1PUPPET-EPP(8) Puppet manual PUPPET-EPP(8)
2
6 puppet-epp - Interact directly with the EPP template parser/renderer.
7
9 puppet epp action
10
12 Note that any setting that´s valid in the configuration file is also a
13 valid long argument, although it may or may not be relevant to the
14 present action. For example, server and run_mode are valid settings, so
15 you can specify --server <servername>, or --run_mode <runmode> as an
16 argument.
17 See the configuration file documentation at https://pup‐
19 pet.com/docs/puppet/latest/configuration.html for the full list of ac‐
20 ceptable parameters. A commented list of all configuration options can
21 also be generated by running puppet with --genconfig.
22 --render-as FORMAT
24 The format in which to render output. The most common formats
25 are json, s (string), yaml, and console, but other options such
26 as dot are sometimes available.
27 --verbose
29 Whether to log verbosely.
30 --debug
32 Whether to log debug information.
33
35 • dump - Outputs a dump of the internal template parse tree for de‐
36 bugging: SYNOPSIS
37 puppet epp dump [--e source] [--[no-]validate] [--format old, pn,
39 or json] [--pretty] [--[no-]header] [--format old|pn|json]
40 [--pretty] { -e source | [templates ...] }
41 DESCRIPTION
43 The dump action parses and validates the EPP syntax and dumps the
45 resulting AST model in a human readable (but not necessarily an
46 easy to understand) format.
47 The output format can be controlled using the --format old|pn|json
49 where:
50 • ´old´ is the default, but now deprecated format which is not API.
52 • ´pn´ is the Puppet Extended S-Expression Notation.
54 • ´json´ outputs the same graph as ´pn´ but with JSON syntax.
56 The output will be "pretty printed" when the option --pretty is given
60 together with --format ´pn´ or ´json´. This option has no effect on the
61 ´old´ format.
62 The command accepts one or more templates (.epp) files, or an -e fol‐
64 lowed by the template source text. The given templates can be paths to
65 template files, or references to templates in modules when given on the
66 form modulename/template-name.epp. If no arguments are given, the stdin
67 is read (unless it is attached to a terminal)
68 If multiple templates are given, they are separated with a header indi‐
70 cating the name of the template. This can be suppressed with the option
71 --no-header. The option --[no-]header has no effect when a single tem‐
72 plate is dumped.
73 When debugging the epp parser itself, it may be useful to suppress the
75 validation step with the --no-validate option to observe what the
76 parser produced from the given source.
77 This command ignores the --render-as setting/option.
79 OPTIONS --e <source> - Dump one epp source expression given on the com‐
81 mand line.
82 --format <old, pn, or json> - Get result in ´old´ (deprecated format),
84 ´pn´ (new format), or ´json´ (new format in JSON).
85 --[no-]header - Whether or not to show a file name header between
87 files.
88 --pretty - Pretty print output. Only applicable together with --format
90 pn or json
91 --[no-]validate - Whether or not to validate the parsed result, if
93 no-validate only syntax errors are reported.
94 RETURNS
96 A dump of the resulting AST model unless there are syntax or validation
98 errors.
99 • render - Renders an epp template as text: SYNOPSIS
101 puppet epp render [--node node_name] [--e source] [--values val‐
103 ues_hash] [--values_file pp_or_yaml_file] [--facts facts_file]
104 [--[no-]header] -e source | [templates ...]
105 DESCRIPTION
107 This action renders one or more EPP templates.
109 The command accepts one or more templates (.epp files), given the
111 same way as templates are given to the puppet epp function (a full
112 path, or a relative reference on the form ´modulename/tem‐
113 plate-name.epp´), or as a relative path.args In case the given path
114 matches both a modulename/template and a file, the template from
115 the module is used.
116 An inline_epp equivalent can also be performed by giving the tem‐
118 plate after an -e, or by piping the EPP source text to the command.
119 Values to the template can be defined using the Puppet Language on
121 the command line with --values or in a .pp or .yaml file referenced
122 with --values_file. If specifying both the result is merged with
123 --values having higher precedence.
124 The --values option allows a Puppet Language sequence of expres‐
126 sions to be defined on the command line the same way as it may be
127 given in a .pp file referenced with --values_file. It may set vari‐
128 able values (that become available in the template), and must pro‐
129 duce either undef or a Hash of values (the hash may be empty). Pro‐
130 ducing undef simulates that the template is called without an argu‐
131 ments hash and thus only references variables in its outer scope.
132 When a hash is given, a template is limited to seeing only the
133 global scope. It is thus possible to simulate the different types
134 of calls to the epp and inline_epp functions, with or without a
135 given hash. Note that if variables are given, they are always
136 available in this simulation - to test that the template only ref‐
137 erences variables given as arguments, produce a hash in --values or
138 the --values_file, do not specify any variables that are not
139 global, and turn on --strict_variables setting.
140 If multiple templates are given, the same set of values are given
142 to each template. If both --values and --value_file are used, the
143 --values are merged on top of those given in the file.
144 When multiple templates are rendered, a separating header is output
146 between the templates showing the name of the template before the
147 output. The header output can be turned off with --no-header. This
148 also concatenates the template results without any added newline
149 separators.
150 Facts from the node where the command is being run are used by de‐
152 fault.args Facts can be obtained for other nodes if they have
153 called in, and reported their facts by using the --node <nodename>
154 flag.
155 Overriding node facts as well as additional facts can be given in a
157 .yaml or .json file and referencing it with the --facts option.
158 (Values can be obtained in yaml format directly from facter, or
159 from puppet for a given node). Note that it is not possible to sim‐
160 ulate the reserved variable name $facts in any other way.
161 Note that it is not possible to set variables using the Puppet Lan‐
163 guage that have the same names as facts as this result in an error;
164 "attempt to redefine a variable" since facts are set first.
165 Exits with 0 if there were no validation errors. On errors, no ren‐
167 dered output is produced for that template file.
168 When designing EPP templates, it is strongly recommended to define
170 all template arguments in the template, and to give them in a hash
171 when calling epp or inline_epp and to use as few global variables
172 as possible, preferably only the $facts hash. This makes templates
173 more free standing and are easier to reuse, and to test.
174 OPTIONS --e <source> - Render one inline epp template given on the
176 command line.
177 --facts <facts_file> - A .yaml or .json file containing a hash of
179 facts made available in $facts and $trusted
180 --[no-]header - Whether or not to show a file name header between
182 rendered results.
183 --node <node_name> - The name of the node for which facts are ob‐
185 tained. Defaults to facts for the local node.
186 --values <values_hash> - A Hash in Puppet DSL form given as argu‐
188 ments to the template being rendered.
189 --values_file <pp_or_yaml_file> - A .pp or .yaml file that is pro‐
191 cessed to produce a hash of values for the template.
192 RETURNS
194 A rendered result of one or more given templates.
196 • validate - Validate the syntax of one or more EPP templates.: SYN‐
198 OPSIS
199 puppet epp validate [--[no-]continue_on_error] [template] [template
201 ...]
202 DESCRIPTION
204 This action validates EPP syntax without producing any output.
206 When validating, multiple issues per file are reported up to the
208 settings of max_error, and max_warnings. The processing stops after
209 having reported issues for the first encountered file with errors
210 unless the option --continue_on_error is given.
211 Files can be given using the modulename/template.epp style to
213 lookup the template from a module, or be given as a reference to a
214 file. If the reference to a file can be resolved against a template
215 in a module, the module version wins - in this case use an absolute
216 path to reference the template file if the module version is not
217 wanted.
218 Exits with 0 if there were no validation errors.
220 OPTIONS --[no-]continue_on_error - Whether or not to continue after
222 errors are reported for a template.
223 RETURNS
225 Nothing, or encountered syntax errors.
227
231 render
232 Render the template in module ´mymodule´ called ´mytemplate.epp´, and
234 give it two arguments a and b:
235 $ puppet epp render mymodule/mytemplate.epp --values ´{a => 10, b => 20}´
239 Render a template using an absolute path:
243 $ puppet epp render /tmp/testing/mytemplate.epp --values ´{a => 10, b => 20}´
247 Render a template with data from a .pp file:
251 $ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp
255 Render a template with data from a .pp file and override one value on
259 the command line:
260 $ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp --values ´{a=>10}´
264 Render from STDIN:
268 $ cat template.epp | puppet epp render --values ´{a => 10, b => 20}´
272 Set variables in a .pp file and render a template that uses variable
276 references:
277 # data.pp file
281 $greeted = ´a global var´
282 undef
283 $ puppet epp render -e ´hello <%= $greeted %>´ --values_file data.pp
285 Render a template that outputs a fact:
289 $ facter --yaml > data.yaml
293 $ puppet epp render -e ´<% $facts[osfamily] %>´ --facts data.yaml
294 validate
298 Validate the template ´template.epp´ in module ´mymodule´:
300 $ puppet epp validate mymodule/template.epp
304 Validate two arbitrary template files:
308 $ puppet epp validate mymodule/template1.epp yourmodule/something.epp
312 Validate a template somewhere in the file system:
316 $ puppet epp validate /tmp/testing/template1.epp
320 Validate a template against a file relative to the current directory:
324 $ puppet epp validate template1.epp
328 $ puppet epp validate ./template1.epp
329 Validate from STDIN:
333 $ cat template.epp | puppet epp validate
337 Continue on error to see errors for all templates:
341 $ puppet epp validate mymodule/template1.epp mymodule/template2.epp --continue_on_error
345
349 Copyright 2014 by Puppet Inc. Apache 2 license; see COPYING
350Puppet, Inc. October 2021 PUPPET-EPP(8)