PUPPET-EPP(8) Puppet manual PUPPET-EPP(8)NAMEpuppet-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 http://docs.puppet‐
labs.com/references/stable/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
dump - Outputs a dump of the internal template parse tree for debugging
SYNOPSIS
puppet epp dump [--e source] [--[no-]validate] [--[no-]header]
-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 of the dumped
tree is intended for epp parser debugging purposes and is not
API, and may thus change between versions without deprecation
warnings.
The command accepts one or more templates (.epp) files, or an -e
followed 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 argu‐
ments are given, the stdin is read (unless it is attached to a
terminal)
If multiple templates are given, they are separated with a
header indicating the name of the template. This can be sur‐
pressed with the option --no-header. The option --[no-]header
has no effect whe a single template is dumped.
When debugging the epp parser itself, it may be useful to sur‐
press the valiation 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 command line.
--[no-]header - Whether or not to show a file name header
between files.
--[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.
render - Renders an epp template as text
SYNOPSIS
puppet epp render [--e source] [--values values_hash] [--val‐
ues_file pp_or_yaml_file] [--facts yaml_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 ´module‐
name/template-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
template 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 ref‐
erenced 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
variable values (that become available in the template), and
must produce either undef or a Hash of values (the hash may be
empty). Producing undef simulates that the template is called
without an arguments 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 func‐
tions, 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 references 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_vari‐
ables 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 for the simulated node can be feed to the rendering
process by referencing a .yaml file with facts using 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 simulate the reserved variable name $facts in any
other way.
Note that it is not possible to set variables using the Puppet
Language 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
rendered 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, preferrably 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 <yaml_file> - A .yaml file containing a hash of facts
made available in $facts
--[no-]header - Whether or not to show a file name header
between rendered results.
--values <values_hash> - A Hash in Puppet DSL form given as
arguments to the template being rendered.
--values_file <pp_or_yaml_file> - A .pp or .yaml file that is
processed to produce a hash of values for the template.
RETURNS
A rendered result of one or more given templates.
validate - Validate the syntax of one or more EPP templates.
SYNOPSIS
puppet epp validate [--[no-]continue_on_error] [template] [tem‐
plate ...]
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 Labs Apache 2 license; see COPYING
Puppet Labs, LLC May 2015 PUPPET-EPP(8)
