1PUPPET-EPP(8)                    Puppet manual                   PUPPET-EPP(8)
2
3
4

NAME

6       puppet-epp - Interact directly with the EPP template parser/renderer.
7

SYNOPSIS

9       puppet epp action
10

OPTIONS

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
18       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
23       --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
28       --verbose
29              Whether to log verbosely.
30
31       --debug
32              Whether to log debug information.
33

ACTIONS

35dump - Outputs a dump of the internal template parse tree  for  de‐
36           bugging: SYNOPSIS
37
38           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
42           DESCRIPTION
43
44           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
48           The  output format can be controlled using the --format old|pn|json
49           where:
50
51       •   ´old´ is the default, but now deprecated format which is not API.
52
53       •   ´pn´ is the Puppet Extended S-Expression Notation.
54
55       •   ´json´ outputs the same graph as ´pn´ but with JSON syntax.
56
57
58
59       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
63       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
69       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
74       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
78       This command ignores the --render-as setting/option.
79
80       OPTIONS --e <source> - Dump one epp source expression given on the com‐
81       mand line.
82
83       --format <old, pn, or json> - Get result in ´old´ (deprecated  format),
84       ´pn´ (new format), or ´json´ (new format in JSON).
85
86       --[no-]header  -  Whether  or  not  to  show a file name header between
87       files.
88
89       --pretty - Pretty print output. Only applicable together with  --format
90       pn or json
91
92       --[no-]validate  -  Whether  or  not  to validate the parsed result, if
93       no-validate only syntax errors are reported.
94
95       RETURNS
96
97       A dump of the resulting AST model unless there are syntax or validation
98       errors.
99
100render - Renders an epp template as text: SYNOPSIS
101
102           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
106           DESCRIPTION
107
108           This action renders one or more EPP templates.
109
110           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
117           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
120           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
125           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
141           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
145           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
151           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
156           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
162           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
166           Exits with 0 if there were no validation errors. On errors, no ren‐
167           dered output is produced for that template file.
168
169           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
175           OPTIONS --e <source> - Render one inline epp template given on  the
176           command line.
177
178           --facts  <facts_file>  - A .yaml or .json file containing a hash of
179           facts made available in $facts and $trusted
180
181           --[no-]header - Whether or not to show a file name  header  between
182           rendered results.
183
184           --node  <node_name>  - The name of the node for which facts are ob‐
185           tained. Defaults to facts for the local node.
186
187           --values <values_hash> - A Hash in Puppet DSL form given  as  argu‐
188           ments to the template being rendered.
189
190           --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
193           RETURNS
194
195           A rendered result of one or more given templates.
196
197validate - Validate the syntax of one or more EPP templates.:  SYN‐
198           OPSIS
199
200           puppet epp validate [--[no-]continue_on_error] [template] [template
201           ...]
202
203           DESCRIPTION
204
205           This action validates EPP syntax without producing any output.
206
207           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
212           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
219           Exits with 0 if there were no validation errors.
220
221           OPTIONS --[no-]continue_on_error - Whether or not to continue after
222           errors are reported for a template.
223
224           RETURNS
225
226           Nothing, or encountered syntax errors.
227
228
229

EXAMPLES

231       render
232
233       Render  the  template in module ´mymodule´ called ´mytemplate.epp´, and
234       give it two arguments a and b:
235
236
237
238           $ puppet epp render mymodule/mytemplate.epp --values ´{a => 10, b => 20}´
239
240
241
242       Render a template using an absolute path:
243
244
245
246           $ puppet epp render /tmp/testing/mytemplate.epp --values ´{a => 10, b => 20}´
247
248
249
250       Render a template with data from a .pp file:
251
252
253
254           $ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp
255
256
257
258       Render a template with data from a .pp file and override one  value  on
259       the command line:
260
261
262
263           $ puppet epp render /tmp/testing/mytemplate.epp --values_file mydata.pp --values ´{a=>10}´
264
265
266
267       Render from STDIN:
268
269
270
271           $ cat template.epp | puppet epp render --values ´{a => 10, b => 20}´
272
273
274
275       Set  variables  in  a .pp file and render a template that uses variable
276       references:
277
278
279
280           # data.pp file
281           $greeted = ´a global var´
282           undef
283
284           $ puppet epp render -e ´hello <%= $greeted %>´ --values_file data.pp
285
286
287
288       Render a template that outputs a fact:
289
290
291
292           $ facter --yaml > data.yaml
293           $ puppet epp render -e ´<% $facts[osfamily] %>´ --facts data.yaml
294
295
296
297       validate
298
299       Validate the template ´template.epp´ in module ´mymodule´:
300
301
302
303           $ puppet epp validate mymodule/template.epp
304
305
306
307       Validate two arbitrary template files:
308
309
310
311           $ puppet epp validate mymodule/template1.epp yourmodule/something.epp
312
313
314
315       Validate a template somewhere in the file system:
316
317
318
319             $ puppet epp validate /tmp/testing/template1.epp
320
321
322
323       Validate a template against a file relative to the current directory:
324
325
326
327            $ puppet epp validate template1.epp
328            $ puppet epp validate ./template1.epp
329
330
331
332       Validate from STDIN:
333
334
335
336           $ cat template.epp | puppet epp validate
337
338
339
340       Continue on error to see errors for all templates:
341
342
343
344           $ puppet epp validate mymodule/template1.epp mymodule/template2.epp --continue_on_error
345
346
347
349       Copyright 2014 by Puppet Inc. Apache 2 license; see COPYING
350
351
352
353Puppet, Inc.                       May 2022                      PUPPET-EPP(8)
Impressum