Provided by: puppet-agent_8.4.0-1_all bug

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/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

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:

       •   ´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  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 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 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 indicating 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  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 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-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   [--node   node_name]   [--e   source]  [--values  values_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 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 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
           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 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_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 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, 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 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 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