Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

puppet-epp (8)

Name

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

Synopsis

puppet epp action

Description

PUPPET-EPP(8)                    Puppet 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://docs.puppet-
       labs.com/puppet/latest/reference/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
       o   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:

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

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

       o   '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  fol-
       lowed  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 indi-
       cating the name of the template. This can be suppressed with the option
       --no-header. The option --[no-]header has no effect when a single  tem-
       plate 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 com-
       mand 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.

       o   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/tem-
           plate-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  tem-
           plate 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  expres-
           sions  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 vari-
           able  values (that become available in the template), and must pro-
           duce either undef or a Hash of values (the hash may be empty). Pro-
           ducing undef simulates that the template is called without an argu-
           ments 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 ref-
           erences 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 sim-
           ulate the reserved variable name $facts in any other way.

           Note that it is not possible to set variables using the Puppet Lan-
           guage 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 ren-
           dered 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  argu-
           ments to the template being rendered.

           --values_file  <pp_or_yaml_file> - A .pp or .yaml file that is pro-
           cessed to produce a hash of values for the template.

           RETURNS

           A rendered result of one or more given templates.

       o   validate - Validate the syntax of one or more EPP templates.:  SYN-
           OPSIS

           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



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/management/puppet |
       +---------------+--------------------------+
       |Stability      | Volatile                 |
       +---------------+--------------------------+
NOTES
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was  downloaded  from   https://github.com/puppetlabs/puppet/ar-
       chive/5.5.0.tar.gz

       Further information about this software can be found on the open source
       community website at http://puppetlabs.com/.



Puppet, Inc.                      March 2018                     PUPPET-EPP(8)