home | help 
PUPPET-EPP(8)			 OpenVox 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://puppet.com/docs/pup-
     pet/latest/configuration.html for the full list of acceptable parameters. A
     commented	list  of all configuration options can also be generated by run-
     ning 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  debug-
	 ging: 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  re-
	 sulting  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:

     *	 'old' is the default, but now deprecated format which is not API.

     *	 'pn' is the Puppet Extended S-Expression Notation.

     *	 'json' outputs the same graph as 'pn' but with JSON syntax.

     The  output  will be "pretty printed" when the option --pretty is given to-
     gether 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	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 module-
     name/template-name.epp. If no arguments are given, the stdin is  read  (un-
     less it is attached to a terminal)

     If  multiple templates are given, they are separated with a header indicat-
     ing the name of the template.  This  can  be  suppressed  with  the  option
     --no-header.  The option --[no-]header has no effect when a single template
     is dumped.

     When debugging the epp parser itself, it may be useful to suppress the val-
     idation step with the --no-validate option to observe what the parser  pro-
     duced 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.

     --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-vali-
     date only syntax errors are reported.

     RETURNS

     A dump of the resulting AST model unless there are syntax or validation er-
     rors.

     *	 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/template-name.epp'), or as
	 a  relative  path.args  In  case  the given path matches both a module-
	 name/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	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 expressions 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 refer-
	 ences 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  simu-
	 late  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 references variables given as arguments, produce a hash in  --val-
	 ues  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 be-
	 tween the templates showing the name of the template before the output.
	 The  header  output  can be turned off with --no-header. This also con-
	 catenates the template results without any added newline separators.

	 Facts from the node where the command is being  run  are  used  by  de-
	 fault.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 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 possi-
	 ble, 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 com-
	 mand 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 ren-
	 dered 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  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] [template
	 ...]

	 DESCRIPTION

	 This action validates EPP syntax without producing any output.

	 When validating, multiple issues per file are reported up to  the  set-
	 tings 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  refer-
	 ence 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 er-
	 rors 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 refer-
     ences:

	 # 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., Vox Pupuli Apache 2 license; see COPYING

Vox Pupuli			  January 2025			   PUPPET-EPP(8)
home | help