puppet-epp - Interact directly with the EPP template parser/renderer.
puppet epp action
PUPPET-EPP(8) Puppet manual PUPPET-EPP(8)
NAME
puppet-epp - Interact directly with the EPP template parser/renderer.
SYNOPSIS
puppet epp action
OPTIONS
Note that any setting that's valid in the configuration file is also a
valid long argument, although it may or may not be relevant to the
present action. For example, server and run_mode are valid settings, so
you can specify --server <servername>, or --run_mode <runmode> as an
argument.
See the configuration file documentation at https://pup-
pet.com/docs/puppet/latest/configuration.html for the full list of
acceptable parameters. A commented list of all configuration options
can also be generated by running puppet with --genconfig.
--render-as FORMAT
The format in which to render output. The most common formats
are json, s (string), yaml, and console, but other options such
as dot are sometimes available.
--verbose
Whether to log verbosely.
--debug
Whether to log debug information.
ACTIONS
o dump - Outputs a dump of the internal template parse tree for
debugging: SYNOPSIS
puppet epp dump [--e source] [--[no-]validate] [--format old, pn,
or json] [--pretty] [--[no-]header] [--format old|pn|json]
[--pretty] { -e source | [templates ...] }
DESCRIPTION
The dump action parses and validates the EPP syntax and dumps the
resulting AST model in a human readable (but not necessarily an
easy to understand) format.
The output format can be controlled using the --format old|pn|json
where:
o 'old' is the default, but now deprecated format which is not API.
o 'pn' is the Puppet Extended S-Expression Notation.
o 'json' outputs the same graph as 'pn' but with JSON syntax.
The output will be "pretty printed" when the option --pretty is given
together with --format 'pn' or 'json'. This option has no effect on the
'old' format.
The command accepts one or more templates (.epp) files, or an -e fol-
lowed by the template source text. The given templates can be paths to
template files, or references to templates in modules when given on the
form modulename/template-name.epp. If no arguments are given, the stdin
is read (unless it is attached to a terminal)
If multiple templates are given, they are separated with a header indi-
cating the name of the template. This can be suppressed with the option
--no-header. The option --[no-]header has no effect when a single tem-
plate is dumped.
When debugging the epp parser itself, it may be useful to suppress the
validation step with the --no-validate option to observe what the
parser produced from the given source.
This command ignores the --render-as setting/option.
OPTIONS --e <source> - Dump one epp source expression given on the com-
mand line.
--format <old, pn, or json> - Get result in 'old' (deprecated format),
'pn' (new format), or 'json' (new format in JSON).
--[no-]header - Whether or not to show a file name header between
files.
--pretty - Pretty print output. Only applicable together with --format
pn or json
--[no-]validate - Whether or not to validate the parsed result, if
no-validate only syntax errors are reported.
RETURNS
A dump of the resulting AST model unless there are syntax or validation
errors.
o render - Renders an epp template as text: SYNOPSIS
puppet epp render [--node node_name] [--e source] [--values val-
ues_hash] [--values_file pp_or_yaml_file] [--facts facts_file]
[--[no-]header] -e source | [templates ...]
DESCRIPTION
This action renders one or more EPP templates.
The command accepts one or more templates (.epp files), given the
same way as templates are given to the puppet epp function (a full
path, or a relative reference on the form 'modulename/tem-
plate-name.epp'), or as a relative path.args In case the given path
matches both a modulename/template and a file, the template from
the module is used.
An inline_epp equivalent can also be performed by giving the tem-
plate after an -e, or by piping the EPP source text to the command.
Values to the template can be defined using the Puppet Language on
the command line with --values or in a .pp or .yaml file referenced
with --values_file. If specifying both the result is merged with
--values having higher precedence.
The --values option allows a Puppet Language sequence of expres-
sions to be defined on the command line the same way as it may be
given in a .pp file referenced with --values_file. It may set vari-
able values (that become available in the template), and must pro-
duce either undef or a Hash of values (the hash may be empty). Pro-
ducing undef simulates that the template is called without an argu-
ments hash and thus only references variables in its outer scope.
When a hash is given, a template is limited to seeing only the
global scope. It is thus possible to simulate the different types
of calls to the epp and inline_epp functions, with or without a
given hash. Note that if variables are given, they are always
available in this simulation - to test that the template only ref-
erences variables given as arguments, produce a hash in --values or
the --values_file, do not specify any variables that are not
global, and turn on --strict_variables setting.
If multiple templates are given, the same set of values are given
to each template. If both --values and --value_file are used, the
--values are merged on top of those given in the file.
When multiple templates are rendered, a separating header is output
between the templates showing the name of the template before the
output. The header output can be turned off with --no-header. This
also concatenates the template results without any added newline
separators.
Facts from the node where the command is being run are used by
default.args Facts can be obtained for other nodes if they have
called in, and reported their facts by using the --node <nodename>
flag.
Overriding node facts as well as additional facts can be given in a
.yaml or .json file and referencing it with the --facts option.
(Values can be obtained in yaml format directly from facter, or
from puppet for a given node). Note that it is not possible to sim-
ulate the reserved variable name $facts in any other way.
Note that it is not possible to set variables using the Puppet Lan-
guage that have the same names as facts as this result in an error;
"attempt to redefine a variable" since facts are set first.
Exits with 0 if there were no validation errors. On errors, no ren-
dered output is produced for that template file.
When designing EPP templates, it is strongly recommended to define
all template arguments in the template, and to give them in a hash
when calling epp or inline_epp and to use as few global variables
as possible, preferably only the $facts hash. This makes templates
more free standing and are easier to reuse, and to test.
OPTIONS --e <source> - Render one inline epp template given on the
command line.
--facts <facts_file> - A .yaml or .json file containing a hash of
facts made available in $facts and $trusted
--[no-]header - Whether or not to show a file name header between
rendered results.
--node <node_name> - The name of the node for which facts are
obtained. Defaults to facts for the local node.
--values <values_hash> - A Hash in Puppet DSL form given as argu-
ments to the template being rendered.
--values_file <pp_or_yaml_file> - A .pp or .yaml file that is pro-
cessed to produce a hash of values for the template.
RETURNS
A rendered result of one or more given templates.
o validate - Validate the syntax of one or more EPP templates.: SYN-
OPSIS
puppet epp validate [--[no-]continue_on_error] [template] [template
...]
DESCRIPTION
This action validates EPP syntax without producing any output.
When validating, multiple issues per file are reported up to the
settings of max_error, and max_warnings. The processing stops after
having reported issues for the first encountered file with errors
unless the option --continue_on_error is given.
Files can be given using the modulename/template.epp style to
lookup the template from a module, or be given as a reference to a
file. If the reference to a file can be resolved against a template
in a module, the module version wins - in this case use an absolute
path to reference the template file if the module version is not
wanted.
Exits with 0 if there were no validation errors.
OPTIONS --[no-]continue_on_error - Whether or not to continue after
errors are reported for a template.
RETURNS
Nothing, or encountered syntax errors.
EXAMPLES
render
Render the template in module 'mymodule' called 'mytemplate.epp', and
give it two arguments a and b:
$ puppet epp render mymodule/mytemplate.epp --values '{a => 10, b => 20}'
Render a template using an absolute path:
$ puppet epp render /tmp/testing/mytemplate.epp --values '{a => 10, b => 20}'
Render a template with data from a .pp file:
$ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp
Render a template with data from a .pp file and override one value on
the command line:
$ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp --values '{a=>10}'
Render from STDIN:
$ cat template.epp | puppet epp render --values '{a => 10, b => 20}'
Set variables in a .pp file and render a template that uses variable
references:
# data.pp file
$greeted = 'a global var'
undef
$ puppet epp render -e 'hello <%= $greeted %>' --values_file data.pp
Render a template that outputs a fact:
$ facter --yaml > data.yaml
$ puppet epp render -e '<% $facts[osfamily] %>' --facts data.yaml
validate
Validate the template 'template.epp' in module 'mymodule':
$ puppet epp validate mymodule/template.epp
Validate two arbitrary template files:
$ puppet epp validate mymodule/template1.epp yourmodule/something.epp
Validate a template somewhere in the file system:
$ puppet epp validate /tmp/testing/template1.epp
Validate a template against a file relative to the current directory:
$ puppet epp validate template1.epp
$ puppet epp validate ./template1.epp
Validate from STDIN:
$ cat template.epp | puppet epp validate
Continue on error to see errors for all templates:
$ puppet epp validate mymodule/template1.epp mymodule/template2.epp --continue_on_error
COPYRIGHT AND LICENSE
Copyright 2014 by Puppet Inc. Apache 2 license; see COPYING
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/management/puppet |
+---------------+--------------------------+
|Stability | Volatile |
+---------------+--------------------------+
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from https://github.com/puppetlabs/puppet.
Further information about this software can be found on the open source
community website at http://puppetlabs.com/.
Puppet, Inc. January 2022 PUPPET-EPP(8)