puppet 3.8.7 → 4.0.0.rc1

data/man/man8/puppet-epp.8

@@ -0,0 +1,349 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "PUPPET\-EPP" "8" "February 2015" "Puppet Labs, LLC" "Puppet manual"
+.
+.SH "NAME"
+\fBpuppet\-epp\fR \- Interact directly with the EPP template parser/renderer\.
+.
+.SH "SYNOPSIS"
+puppet epp \fIaction\fR
+.
+.SH "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, \fBserver\fR and \fBrun_mode\fR are valid settings, so you can specify \fB\-\-server <servername>\fR, or \fB\-\-run_mode <runmode>\fR as an argument\.
+.
+.P
+See the configuration file documentation at \fIhttp://docs\.puppetlabs\.com/references/stable/configuration\.html\fR for the full list of acceptable parameters\. A commented list of all configuration options can also be generated by running puppet with \fB\-\-genconfig\fR\.
+.
+.TP
+\-\-render\-as FORMAT
+The format in which to render output\. The most common formats are \fBjson\fR, \fBs\fR (string), \fByaml\fR, and \fBconsole\fR, but other options such as \fBdot\fR are sometimes available\.
+.
+.TP
+\-\-verbose
+Whether to log verbosely\.
+.
+.TP
+\-\-debug
+Whether to log debug information\.
+.
+.SH "ACTIONS"
+.
+.TP
+\fBdump\fR \- Outputs a dump of the internal template parse tree for debugging
+\fBSYNOPSIS\fR
+.
+.IP
+puppet epp dump [\-\-e \fIsource\fR] [\-\-[no\-]validate] [\-\-[no\-]header] \-e \fIsource\fR | [\fItemplates\fR \.\.\.]
+.
+.IP
+\fBDESCRIPTION\fR
+.
+.IP
+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 of the dumped tree is intended for epp parser debugging purposes and is not API, and may thus change between versions without deprecation warnings\.
+.
+.IP
+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 \fImodulename\fR/\fItemplate\-name\fR\.epp\. If no arguments are given, the stdin is read (unless it is attached to a terminal)
+.
+.IP
+If multiple templates are given, they are separated with a header indicating the name of the template\. This can be surpressed with the option \-\-no\-header\. The option \-\-[no\-]header has no effect whe a single template is dumped\.
+.
+.IP
+When debugging the epp parser itself, it may be useful to surpress the valiation step with the \fB\-\-no\-validate\fR option to observe what the parser produced from the given source\.
+.
+.IP
+This command ignores the \-\-render\-as setting/option\.
+.
+.IP
+\fBOPTIONS\fR \fI\-\-e <source\fR> \- Dump one epp source expression given on the command line\.
+.
+.IP
+\fI\-\-[no\-]header\fR \- Whether or not to show a file name header between files\.
+.
+.IP
+\fI\-\-[no\-]validate\fR \- Whether or not to validate the parsed result, if no\-validate only syntax errors are reported\.
+.
+.IP
+\fBRETURNS\fR
+.
+.IP
+A dump of the resulting AST model unless there are syntax or validation errors\.
+.
+.TP
+\fBrender\fR \- Renders an epp template as text
+\fBSYNOPSIS\fR
+.
+.IP
+puppet epp render [\-\-e \fIsource\fR] [\-\-values \fIvalues_hash\fR] [\-\-values_file \fIpp_or_yaml_file\fR] [\-\-facts \fIyaml_file\fR] [\-\-[no\-]header] \-e \fIsource\fR | [\fItemplates\fR \.\.\.]
+.
+.IP
+\fBDESCRIPTION\fR
+.
+.IP
+This action renders one or more EPP templates\.
+.
+.IP
+The command accepts one or more templates (\.epp files), given the same way as templates are given to the puppet \fBepp\fR function (a full path, or a relative reference on the form \'\fImodulename\fR/\fItemplate\-name\fR\.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\.
+.
+.IP
+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\.
+.
+.IP
+Values to the template can be defined using the Puppet Language on the command line with \fB\-\-values\fR or in a \.pp or \.yaml file referenced with \fB\-\-values_file\fR\. If specifying both the result is merged with \-\-values having higher precedence\.
+.
+.IP
+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 \fB\-\-values_file\fR\. It may set variable values (that become available in the template), and must produce either \fBundef\fR or a \fBHash\fR of values (the hash may be empty)\. Producing \fBundef\fR 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 \fBepp\fR and \fBinline_epp\fR 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\.
+.
+.IP
+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\.
+.
+.IP
+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 \fB\-\-no\-header\fR\. This also concatenates the template results without any added newline separators\.
+.
+.IP
+Facts for the simulated node can be feed to the rendering process by referencing a \.yaml file with facts using the \-\-facts option\. (Values can be obtained in yaml format directly from \fBfacter\fR, or from puppet for a given node)\. Note that it is not possible to simulate the reserved variable name \fB$facts\fR in any other way\.
+.
+.IP
+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\.
+.
+.IP
+Exits with 0 if there were no validation errors\. On errors, no rendered output is produced for that template file\.
+.
+.IP
+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 \fBepp\fR or \fBinline_epp\fR and to use as few global variables as possible, preferrably only the $facts hash\. This makes templates more free standing and are easier to reuse, and to test\.
+.
+.IP
+\fBOPTIONS\fR \fI\-\-e <source\fR> \- Render one inline epp template given on the command line\.
+.
+.IP
+\fI\-\-facts <yaml_file\fR> \- A \.yaml file containing a hash of facts made available in $facts
+.
+.IP
+\fI\-\-[no\-]header\fR \- Whether or not to show a file name header between rendered results\.
+.
+.IP
+\fI\-\-values <values_hash\fR> \- A Hash in Puppet DSL form given as arguments to the template being rendered\.
+.
+.IP
+\fI\-\-values_file <pp_or_yaml_file\fR> \- A \.pp or \.yaml file that is processed to produce a hash of values for the template\.
+.
+.IP
+\fBRETURNS\fR
+.
+.IP
+A rendered result of one or more given templates\.
+.
+.TP
+\fBvalidate\fR \- Validate the syntax of one or more EPP templates\.
+\fBSYNOPSIS\fR
+.
+.IP
+puppet epp validate [\-\-[no\-]continue_on_error] [\fItemplate\fR] [\fItemplate\fR \.\.\.]
+.
+.IP
+\fBDESCRIPTION\fR
+.
+.IP
+This action validates EPP syntax without producing any output\.
+.
+.IP
+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\.
+.
+.IP
+Files can be given using the \fBmodulename/template\.epp\fR 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\.
+.
+.IP
+Exits with 0 if there were no validation errors\.
+.
+.IP
+\fBOPTIONS\fR \fI\-\-[no\-]continue_on_error\fR \- Whether or not to continue after errors are reported for a template\.
+.
+.IP
+\fBRETURNS\fR
+.
+.IP
+Nothing, or encountered syntax errors\.
+.
+.SH "EXAMPLES"
+\fBrender\fR
+.
+.P
+Render the template in module \'mymodule\' called \'mytemplate\.epp\', and give it two arguments \fBa\fR and \fBb\fR:
+.
+.IP "" 4
+.
+.nf
+
+$ puppet epp render mymodule/mytemplate\.epp \-\-values \'{a => 10, b => 20}\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Render a template using an absolute path:
+.
+.IP "" 4
+.
+.nf
+
+$ puppet epp render /tmp/testing/mytemplate\.epp \-\-values \'{a => 10, b => 20}\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Render a template with data from a \.pp file:
+.
+.IP "" 4
+.
+.nf
+
+$ puppet epp render /tmp/testing/mytemplate\.epp \-\-values_file mydata\.pp
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Render a template with data from a \.pp file and override one value on the command line:
+.
+.IP "" 4
+.
+.nf
+
+$ puppet epp render /tmp/testing/mytemplate\.epp \-\-values_file mydata\.pp \-\-values \'{a=>10}\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Render from STDIN:
+.
+.IP "" 4
+.
+.nf
+
+$ cat template\.epp | puppet epp render \-\-values \'{a => 10, b => 20}\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Set variables in a \.pp file and render a template that uses variable references:
+.
+.IP "" 4
+.
+.nf
+
+# data\.pp file
+$greeted = \'a global var\'
+undef
+
+$ puppet epp render \-e \'hello <%= $greeted %>\' \-\-values_file data\.pp
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Render a template that outputs a fact:
+.
+.IP "" 4
+.
+.nf
+
+$ facter \-\-yaml > data\.yaml
+$ puppet epp render \-e \'<% $facts[osfamily] %>\' \-\-facts data\.yaml
+.
+.fi
+.
+.IP "" 0
+.
+.P
+\fBvalidate\fR
+.
+.P
+Validate the template \'template\.epp\' in module \'mymodule\':
+.
+.IP "" 4
+.
+.nf
+
+$ puppet epp validate mymodule/template\.epp
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Validate two arbitrary template files:
+.
+.IP "" 4
+.
+.nf
+
+$ puppet epp validate mymodule/template1\.epp yourmodule/something\.epp
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Validate a template somewhere in the file system:
+.
+.IP "" 4
+.
+.nf
+
+  $ puppet epp validate /tmp/testing/template1\.epp
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Validate a template against a file relative to the current directory:
+.
+.IP "" 4
+.
+.nf
+
+ $ puppet epp validate template1\.epp
+ $ puppet epp validate \./template1\.epp
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Validate from STDIN:
+.
+.IP "" 4
+.
+.nf
+
+$ cat template\.epp | puppet epp validate
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Continue on error to see errors for all templates:
+.
+.IP "" 4
+.
+.nf
+
+$ puppet epp validate mymodule/template1\.epp mymodule/template2\.epp \-\-continue_on_error
+.
+.fi
+.
+.IP "" 0
+.
+.SH "COPYRIGHT AND LICENSE"
+Copyright 2014 by Puppet Labs Apache 2 license; see COPYING

data/man/man8/puppet-facts.8

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "PUPPET\-FACTS" "8" "January 2013" "Puppet Labs, LLC" "Puppet manual"
+.TH "PUPPET\-FACTS" "8" "February 2015" "Puppet Labs, LLC" "Puppet manual"
 .
 .SH "NAME"
 \fBpuppet\-facts\fR \- Retrieve and store facts\.
@@ -10,13 +10,10 @@
 puppet facts \fIaction\fR [\-\-terminus TERMINUS] [\-\-extra HASH]
 .
 .SH "DESCRIPTION"
-This subcommand manages facts, which are collections of normalized system information used by Puppet\. It can read facts directly from the local system (with the default \fBfacter\fR terminus), look up facts reported by other systems, and submit facts to the puppet master\.
-.
-.P
-When used with the \fBrest\fR terminus, this subcommand is essentially a front\-end to the inventory service REST API\. See the inventory service documentation at \fIhttp://docs\.puppetlabs\.com/guides/inventory_service\.html\fR for more detail\.
+This subcommand manages facts, which are collections of normalized system information used by Puppet\. It can read facts directly from the local system (with the default \fBfacter\fR terminus)\.
 .
 .SH "OPTIONS"
-Note that any configuration parameter 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, \fBserver\fR and \fBrun_mode\fR are valid configuration parameters, so you can specify \fB\-\-server <servername>\fR, or \fB\-\-run_mode <runmode>\fR as an argument\.
+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, \fBserver\fR and \fBrun_mode\fR are valid settings, so you can specify \fB\-\-server <servername>\fR, or \fB\-\-run_mode <runmode>\fR as an argument\.
 .
 .P
 See the configuration file documentation at \fIhttp://docs\.puppetlabs\.com/references/stable/configuration\.html\fR for the full list of acceptable parameters\. A commented list of all configuration options can also be generated by running puppet with \fB\-\-genconfig\fR\.
@@ -50,24 +47,11 @@ The terminus for an action is often determined by context, but occasionally need
 .SH "ACTIONS"
 .
 .TP
-\fBdestroy\fR \- Invalid for this subcommand\.
-\fBSYNOPSIS\fR
-.
-.IP
-puppet facts destroy [\-\-terminus TERMINUS] [\-\-extra HASH] \fIkey\fR
-.
-.IP
-\fBDESCRIPTION\fR
-.
-.IP
-Invalid for this subcommand\.
-.
-.TP
 \fBfind\fR \- Retrieve a node\'s facts\.
 \fBSYNOPSIS\fR
 .
 .IP
-puppet facts find [\-\-terminus TERMINUS] [\-\-extra HASH] \fInode_certname\fR
+puppet facts [\-\-terminus TERMINUS] [\-\-extra HASH] [\fInode_certname\fR]
 .
 .IP
 \fBDESCRIPTION\fR
@@ -116,44 +100,6 @@ puppet facts save [\-\-terminus TERMINUS] [\-\-extra HASH] \fIkey\fR
 .IP
 API only: create or overwrite an object\. As the Faces framework does not currently accept data from STDIN, save actions cannot currently be invoked from the command line\.
 .
-.TP
-\fBsearch\fR \- Invalid for this subcommand\.
-\fBSYNOPSIS\fR
-.
-.IP
-puppet facts search [\-\-terminus TERMINUS] [\-\-extra HASH] \fIquery\fR
-.
-.IP
-\fBDESCRIPTION\fR
-.
-.IP
-Invalid for this subcommand\.
-.
-.TP
-\fBupload\fR \- Upload local facts to the puppet master\.
-\fBSYNOPSIS\fR
-.
-.IP
-puppet facts upload [\-\-terminus TERMINUS] [\-\-extra HASH]
-.
-.IP
-\fBDESCRIPTION\fR
-.
-.IP
-Reads facts from the local system using the \fBfacter\fR terminus, then saves the returned facts using the rest terminus\.
-.
-.IP
-\fBRETURNS\fR
-.
-.IP
-Nothing\.
-.
-.IP
-\fBNOTES\fR
-.
-.IP
-This action requires that the puppet master\'s \fBauth\.conf\fR file allow save access to the \fBfacts\fR REST terminus\. Puppet agent does not use this facility, and it is turned off by default\. See \fIhttp://docs\.puppetlabs\.com/guides/rest_auth_conf\.html\fR for more details\.
-.
 .SH "EXAMPLES"
 \fBfind\fR
 .
@@ -161,57 +107,21 @@ This action requires that the puppet master\'s \fBauth\.conf\fR file allow save
 Get facts from the local system:
 .
 .P
-$ puppet facts find x
-.
-.P
-Ask the puppet master for facts for an arbitrary node:
-.
-.P
-$ puppet facts find somenode\.puppetlabs\.lan \-\-terminus rest
-.
-.P
-Query a DB\-backed inventory directly (bypassing the REST API):
-.
-.P
-$ puppet facts find somenode\.puppetlabs\.lan \-\-terminus inventory_active_record \-\-run_mode master
-.
-.P
-\fBupload\fR
-.
-.P
-Upload facts:
-.
-.P
-$ puppet facts upload
+$ puppet facts find
 .
 .SH "NOTES"
 This subcommand is an indirector face, which exposes \fBfind\fR, \fBsearch\fR, \fBsave\fR, and \fBdestroy\fR actions for an indirected subsystem of Puppet\. Valid termini for this face include:
 .
 .IP "\(bu" 4
-\fBactive_record\fR
-.
-.IP "\(bu" 4
-\fBcouch\fR
-.
-.IP "\(bu" 4
 \fBfacter\fR
 .
 .IP "\(bu" 4
-\fBinventory_active_record\fR
-.
-.IP "\(bu" 4
-\fBinventory_service\fR
-.
-.IP "\(bu" 4
 \fBmemory\fR
 .
 .IP "\(bu" 4
 \fBnetwork_device\fR
 .
 .IP "\(bu" 4
-\fBrest\fR
-.
-.IP "\(bu" 4
 \fBstore_configs\fR
 .
 .IP "\(bu" 4