Provided by: puppet-agent_7.23.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