puppet-apply

title: puppet-apply(8)

summary: Apply Puppet manifests locally

text:
# puppet-apply(8)

## NAME
puppet-apply - Apply Puppet manifests locally

## SYNOPSIS
Applies a standalone Puppet manifest to the local system.

## USAGE
puppet apply [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose] [-e|--execute] [--detailed-exitcodes] [-L|--loadclasses] [-l|--logdest syslog|eventlog|ABS FILEPATH|console] [--noop] [--catalog catalog] [--write-catalog-summary] file

## DESCRIPTION
This is the standalone puppet execution tool; use it to apply individual manifests.

When provided with a modulepath, via command line or config file, puppet apply can effectively mimic the catalog that would be served by puppet master with access to the same modules, although there are some subtle differences. When combined with scheduling and an automated system for pushing manifests, this can be used to implement a serverless Puppet site.

Most users should use ´puppet agent´ and ´puppet master´ for site-wide manifests.

## OPTIONS
Any setting that´s valid in the configuration file is a valid long argument for puppet apply. For example, ´tags´ is a valid setting, so you can specify ´--tags class,tag´ as an argument.

See the configuration file documentation at https://puppet.com/docs/puppet/latest/configuration.html for the full list of acceptable parameters. You can generate a commented list of all configuration options by running puppet with ´--genconfig´.

- --debug: Enable full debugging.

- --detailed-exitcodes: Provide extra information about the run via exit codes. If enabled, ´puppet apply´ will use the following exit codes:

0: The run succeeded with no changes or failures; the system was already in the desired state.

1: The run failed.

2: The run succeeded, and some resources were changed.

4: The run succeeded, and some resources failed.

6: The run succeeded, and included both changes and failures.

- --help: Print this help message

- --loadclasses: Load any stored classes. ´puppet agent´ caches configured classes (usually at /etc/puppetlabs/puppet/classes.txt), and setting this option causes all of those classes to be set in your puppet manifest.

- --logdest: Where to send log messages. Choose between ´syslog´ (the POSIX syslog service), ´eventlog´ (the Windows Event Log), ´console´, or the path to a log file. Defaults to ´console´. Multiple destinations can be set using a comma separated list (eg: /path/file1,console,/path/file2)"

A path ending with ´.json´ will receive structured output in JSON format. The log file will not have an ending ´]´ automatically written to it due to the appending nature of logging. It must be appended manually to make the content valid JSON.

A path ending with ´.jsonl´ will receive structured output in JSON Lines format.

- --noop: Use ´noop´ mode where Puppet runs in a no-op or dry-run mode. This is useful for seeing what changes Puppet will make without actually executing the changes.

- --execute: Execute a specific piece of Puppet code

- --test: Enable the most common options used for testing. These are ´verbose´, ´detailed-exitcodes´ and ´show_diff´.

- --verbose: Print extra information.

- --catalog: Apply a JSON catalog (such as one generated with ´puppet master --compile´). You can either specify a JSON file or pipe in JSON from standard input.

- --write-catalog-summary After compiling the catalog saves the resource list and classes list to the node in the state directory named classes.txt and resources.txt

## EXAMPLE

```
$ puppet apply -l /tmp/manifest.log manifest.pp
$ puppet apply --modulepath=/root/dev/modules -e "include ntpd::server"
$ puppet apply --catalog catalog.json
```

## AUTHOR
Luke Kanies

## COPYRIGHT
Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-catalog

package: puppet

title: puppet-catalog(8)

summary: Compile, save, view, and convert catalogs\.

text:
# puppet-catalog(8)

## NAME
puppet-catalog - Compile, save, view, and convert catalogs.

## SYNOPSIS
puppet catalog action [--terminus _TERMINUS]

## DESCRIPTION
This subcommand deals with catalogs, which are compiled per-node artifacts generated from a set of Puppet manifests. By default, it interacts with the compiling subsystem and compiles a catalog using the default manifest and certname, but you can change the source of the catalog with the --terminus option. You can also choose to print any catalog in ´dot´ format (for easy graph viewing with OmniGraffle or Graphviz) with ´--render-as dot´.

## 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.

--terminus _TERMINUS

Indirector faces expose indirected subsystems of Puppet. These subsystems are each able to retrieve and alter a specific type of data (with the familiar actions of find, search, save, and destroy) from an arbitrary number of pluggable backends. In Puppet parlance, these backends are called terminuses.

Almost all indirected subsystems have a rest terminus that interacts with the puppet master´s data. Most of them have additional terminuses for various local data models, which are in turn used by the indirected subsystem on the puppet master whenever it receives a remote request.

The terminus for an action is often determined by context, but occasionally needs to be set explicitly. See the "Notes" section of this face´s manpage for more details.

## ACTIONS
apply - Find and apply a catalog.

SYNOPSIS

puppet catalog apply [--terminus _TERMINUS]

DESCRIPTION

Finds and applies a catalog. This action takes no arguments, but the source of the catalog can be managed with the --terminus option.

RETURNS

Nothing. When used from the Ruby API, returns a Puppet::Transaction::Report object.

compile - Compile a catalog.

SYNOPSIS

puppet catalog compile [--terminus _TERMINUS]

DESCRIPTION

Compiles a catalog locally for a node, requiring access to modules, node classifier, etc.

RETURNS

A serialized catalog.

download - Download this node´s catalog from the puppet master server.

SYNOPSIS

puppet catalog download [--terminus _TERMINUS]

DESCRIPTION

Retrieves a catalog from the puppet master and saves it to the local yaml cache. This action always contacts the puppet master and will ignore alternate termini.

The saved catalog can be used in any subsequent catalog action by specifying ´--terminus yaml´ for that action.

RETURNS

Nothing.

NOTES

When used from the Ruby API, this action has a side effect of leaving Puppet::Resource::Catalog.indirection.terminus_class set to yaml. The terminus must be explicitly re-set for subsequent catalog actions.

find - Retrieve the catalog for the node from which the command is run.

SYNOPSIS

puppet catalog find [--terminus _TERMINUS] certname

DESCRIPTION

Retrieve the catalog for the node from which the command is run.

RETURNS

A serialized catalog. When used from the Ruby API, returns a Puppet::Resource::Catalog object.

info - Print the default terminus class for this face.

SYNOPSIS

puppet catalog info [--terminus _TERMINUS]

DESCRIPTION

Prints the default terminus class for this subcommand. Note that different run modes may have different default termini; when in doubt, specify the run mode with the ´--run_mode´ option.

save - API only: create or overwrite an object.

SYNOPSIS

puppet catalog save [--terminus _TERMINUS] key

DESCRIPTION

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.

select - Retrieve a catalog and filter it for resources of a given type.

SYNOPSIS

puppet catalog select [--terminus _TERMINUS] host resource_type

DESCRIPTION

Retrieves a catalog for the specified host, then searches it for all resources of the requested type.

RETURNS

A list of resource references ("Type[title]"). When used from the API, returns an array of Puppet::Resource objects excised from a catalog.

NOTES

By default, this action will retrieve a catalog from Puppet´s compiler subsystem; you must call the action with --terminus rest if you wish to retrieve a catalog from the puppet master.

FORMATTING ISSUES: This action cannot currently render useful yaml; instead, it returns an entire catalog. Use json instead.

## EXAMPLES
apply

Apply the locally cached catalog:

$ puppet catalog apply --terminus yaml

Retrieve a catalog from the master and apply it, in one step:

$ puppet catalog apply --terminus rest

API example:

```
# ...
Puppet::Face[:catalog, ´0.0.1´].download
# (Termini are singletons; catalog.download has a side effect of
# setting the catalog terminus to yaml)
report  = Puppet::Face[:catalog, ´0.0.1´].apply
# ...
```

compile

Compile catalog for node ´mynode´:

$ puppet catalog compile mynode --codedir ...

download

Retrieve and store a catalog:

$ puppet catalog download

API example:

```
Puppet::Face[:plugin, ´0.0.1´].download
Puppet::Face[:facts, ´0.0.1´].upload
Puppet::Face[:catalog, ´0.0.1´].download
# ...
```

select

Ask the puppet master for a list of managed file resources for a node:

$ puppet catalog select --terminus rest somenode.magpie.lan file

## NOTES
This subcommand is an indirector face, which exposes find, search, save, and destroy actions for an indirected subsystem of Puppet. Valid termini for this face include:

- compiler

- json

- msgpack

- rest

- store_configs

- yaml

## COPYRIGHT AND LICENSE
Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


puppet-config

title: puppet-config(8)

summary: Interact with Puppet\'s settings\.

text:
# puppet-config(8)

## NAME
puppet-config - Interact with Puppet´s settings.

## SYNOPSIS
puppet config action [--section SECTION_NAME]

## DESCRIPTION
This subcommand can inspect and modify settings from Puppet´s ´puppet.conf´ configuration file. For documentation about individual settings, see https://puppet.com/docs/puppet/latest/configuration.html.

## 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.

--section SECTION_NAME

The section of the puppet.conf configuration file to interact with.

The three most commonly used sections are ´main´, ´server´, and ´agent´. ´Main´ is the default, and is used by all Puppet applications. Other sections can override ´main´ values for specific applications --- the ´server´ section affects Puppet Server, and the ´agent´ section affects puppet agent.

Less commonly used is the ´user´ section, which affects puppet apply. Any other section will be treated as the name of a legacy environment (a deprecated feature), and can only include the ´manifest´ and ´modulepath´ settings.

## ACTIONS
delete - Delete a Puppet setting.

SYNOPSIS

puppet config delete [--section SECTION_NAME] setting

DESCRIPTION

Deletes a setting from the specified section. (The default is the section ´main´).

NOTES

By default, this action deletes the configuration setting from the ´main´ configuration domain. Use the ´--section´ flags to delete settings from other configuration domains.

print - Examine Puppet´s current settings.

SYNOPSIS

puppet config print [--section SECTION_NAME] all | setting [setting ...]

DESCRIPTION

Prints the value of a single setting or a list of settings.

This action is a replacement interface to the information available with puppet <subcommand> --configprint.

NOTES

By default, this action reads the general configuration in the ´main´ section. Use the ´--section´ and ´--environment´ flags to examine other configuration domains.

set - Set Puppet´s settings.

SYNOPSIS

puppet config set [--section SECTION_NAME] [setting_name] [setting_value]

DESCRIPTION

Updates values in the puppet.conf configuration file.

NOTES

By default, this action manipulates the configuration in the ´main´ section. Use the ´--section´ flag to manipulate other configuration domains.

## EXAMPLES
delete

Delete the setting ´setting_name´ from the ´main´ configuration domain:

$ puppet config delete setting_name

Delete the setting ´setting_name´ from the ´server´ configuration domain:

$ puppet config delete setting_name --section server

print

Get puppet´s runfile directory:

$ puppet config print rundir

Get a list of important directories from the server´s config:

$ puppet config print all --section server | grep -E "(path|dir)"

set

Set puppet´s runfile directory:

$ puppet config set rundir /var/run/puppetlabs

Set the vardir for only the agent:

$ puppet config set vardir /opt/puppetlabs/puppet/cache --section agent

## COPYRIGHT AND LICENSE
Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


puppet-describe

title: puppet-describe(8)

summary: Display help about resource types

text:
# puppet-describe(8)

## NAME
puppet-describe - Display help about resource types

## SYNOPSIS
Prints help about Puppet resource types, providers, and metaparameters.

## USAGE
puppet describe [-h|--help] [-s|--short] [-p|--providers] [-l|--list] [-m|--meta]

## OPTIONS
--help

Print this help text

--providers

Describe providers in detail for each type

--list

List all types

--meta

List all metaparameters

--short

List only parameters without detail

## EXAMPLE

```
$ puppet describe --list
$ puppet describe file --providers
$ puppet describe user -s -m
```

## AUTHOR
David Lutterkort

## COPYRIGHT
Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-device

title: puppet-device(8)

summary: Manage remote network devices

text:
# puppet-device(8)

## NAME
puppet-device - Manage remote network devices

## SYNOPSIS
Retrieves catalogs from the Puppet master and applies them to remote devices.

This subcommand can be run manually; or periodically using cron, a scheduled task, or a similar tool.

## USAGE
puppet device [-h|--help] [-v|--verbose] [-d|--debug] [-l|--logdest syslog|file|console] [--detailed-exitcodes] [--deviceconfig file] [-w|--waitforcert seconds] [--libdir directory] [-a|--apply file] [-f|--facts] [-r|--resource type [name]] [-t|--target device] [--user=user] [-V|--version]

## DESCRIPTION
Devices require a proxy Puppet agent to request certificates, collect facts, retrieve and apply catalogs, and store reports.

## USAGE NOTES
Devices managed by the puppet-device subcommand on a Puppet agent are configured in device.conf, which is located at $confdir/device.conf by default, and is configurable with the $deviceconfig setting.

The device.conf file is an INI-like file, with one section per device:

[DEVICE_CERTNAME] type TYPE url URL debug

The section name specifies the certname of the device.

The values for the type and url properties are specific to each type of device.

The optional debug property specifies transport-level debugging, and is limited to telnet and ssh transports.

See https://puppet.com/docs/puppet/latest/config_file_device.html for details.

## OPTIONS
Note that any setting that´s valid in the configuration file is also a valid long argument. For example, ´server´ is a valid configuration parameter, so you can specify ´--server servername´ as an argument.

--help, -h

Print this help message

--verbose, -v

Turn on verbose reporting.

--debug, -d

Enable full debugging.

--logdest, -l

Where to send log messages. Choose between ´syslog´ (the POSIX syslog service), ´console´, or the path to a log file. If debugging or verbosity is enabled, this defaults to ´console´. Otherwise, it defaults to ´syslog´. Multiple destinations can be set using a comma separated list (eg: /path/file1,console,/path/file2)"

A path ending with ´.json´ will receive structured output in JSON format. The log file will not have an ending ´]´ automatically written to it due to the appending nature of logging. It must be appended manually to make the content valid JSON.

--detailed-exitcodes

Provide transaction information via exit codes. If this is enabled, an exit code of ´1´ means at least one device had a compile failure, an exit code of ´2´ means at least one device had resource changes, and an exit code of ´4´ means at least one device had resource failures. Exit codes of ´3´, ´5´, ´6´, or ´7´ means that a bitwise combination of the preceding exit codes happened.

--deviceconfig

Path to the device config file for puppet device. Default: $confdir/device.conf

--waitforcert, -w

This option only matters for targets that do not yet have certificates and it is enabled by default, with a value of 120 (seconds). This causes +puppet device+ to poll the server every 2 minutes and ask it to sign a certificate request. This is useful for the initial setup of a target. You can turn off waiting for certificates by specifying a time of 0.

--libdir

Override the per-device libdir with a local directory. Specifying a libdir also disables pluginsync. This is useful for testing.

A path ending with ´.jsonl´ will receive structured output in JSON Lines format.

--apply

Apply a manifest against a remote target. Target must be specified.

--facts

Displays the facts of a remote target. Target must be specified.

--resource

Displays a resource state as Puppet code, roughly equivalent to puppet resource. Can be filtered by title. Requires --target be specified.

--target

Target a specific device/certificate in the device.conf. Doing so will perform a device run against only that device/certificate.

--to_yaml

Output found resources in yaml format, suitable to use with Hiera and create_resources.

--user

The user to run as.

## EXAMPLE

```
  $ puppet device --target remotehost --verbose
```

## AUTHOR
Brice Figureau

## COPYRIGHT
Copyright (c) 2011-2018 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-doc

title: puppet-doc(8)

summary: Generate Puppet references

text:
# puppet-doc(8)

## NAME
puppet-doc - Generate Puppet references

## SYNOPSIS
Generates a reference for all Puppet types. Largely meant for internal Puppet Inc. use. (Deprecated)

## USAGE
puppet doc [-h|--help] [-l|--list] [-r|--reference reference-name]

## DESCRIPTION
This deprecated command generates a Markdown document to stdout describing all installed Puppet types or all allowable arguments to puppet executables. It is largely meant for internal use and is used to generate the reference document available on the Puppet Inc. web site.

For Puppet module documentation (and all other use cases) this command has been superseded by the "puppet-strings" module - see https://github.com/puppetlabs/puppetlabs-strings for more information.

This command (puppet-doc) will be removed once the puppetlabs internal documentation processing pipeline is completely based on puppet-strings.

## OPTIONS
--help

Print this help message

--reference

Build a particular reference. Get a list of references by running ´puppet doc --list´.

## EXAMPLE

```
$ puppet doc -r type > /tmp/type_reference.markdown
```

## AUTHOR
Luke Kanies

## COPYRIGHT
Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-epp

title: puppet-epp(8)

summary: Interact directly with the EPP template parser/renderer\.

text:
# 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/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


puppet-facts

title: puppet-facts(8)

summary: Retrieve and store facts\.

text:
# puppet-facts(8)

## NAME
puppet-facts - Retrieve and store facts.

## SYNOPSIS
puppet facts action [--terminus _TERMINUS]

## 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 facter terminus).

## 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.

--terminus _TERMINUS

Indirector faces expose indirected subsystems of Puppet. These subsystems are each able to retrieve and alter a specific type of data (with the familiar actions of find, search, save, and destroy) from an arbitrary number of pluggable backends. In Puppet parlance, these backends are called terminuses.

Almost all indirected subsystems have a rest terminus that interacts with the puppet master´s data. Most of them have additional terminuses for various local data models, which are in turn used by the indirected subsystem on the puppet master whenever it receives a remote request.

The terminus for an action is often determined by context, but occasionally needs to be set explicitly. See the "Notes" section of this face´s manpage for more details.

## ACTIONS
find - Retrieve a node´s facts.

SYNOPSIS

puppet facts find [--terminus _TERMINUS] [node_certname]

DESCRIPTION

Retrieve a node´s facts.

RETURNS

A hash containing some metadata and (under the "values" key) the set of facts for the requested node. When used from the Ruby API: A Puppet::Node::Facts object.

RENDERING ISSUES: Facts cannot currently be rendered as a string; use yaml or json.

NOTES

When using the facter terminus, the host argument is ignored.

info - Print the default terminus class for this face.

SYNOPSIS

puppet facts info [--terminus _TERMINUS]

DESCRIPTION

Prints the default terminus class for this subcommand. Note that different run modes may have different default termini; when in doubt, specify the run mode with the ´--run_mode´ option.

save - API only: create or overwrite an object.

SYNOPSIS

puppet facts save [--terminus _TERMINUS] key

DESCRIPTION

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.

show - Retrieve current node´s facts.

SYNOPSIS

puppet facts [--terminus _TERMINUS] [--config-file path] [--custom-dir path] [--external-dir path] [--no-block] [--no-cache] [--show-legacy] [--value-only] [--timing] [facts]

DESCRIPTION

Reads facts from the local system using facter terminus. A query can be provided to retrieve just a specific fact or a set of facts.

OPTIONS --config-file <path> - The location of the config file for Facter.

--custom-dir <path> - The path to a directory that contains custom facts.

--external-dir <path> - The path to a directory that contains external facts.

--no-block - Disable fact blocking mechanism.

--no-cache - Disable fact caching mechanism.

--show-legacy - Show legacy facts when querying all facts.

--timing - Show how much time it took to resolve each fact.

--value-only - Show only the value when the action is called with a single query

RETURNS

The output of facter with added puppet specific facts.

NOTES

upload - Upload local facts to the puppet master.

SYNOPSIS

puppet facts upload [--terminus _TERMINUS]

DESCRIPTION

Reads facts from the local system using the facter terminus, then saves the returned facts using the rest terminus.

RETURNS

Nothing.

NOTES

This action requires that the Puppet Server´s auth.conf file allow PUT or save access to the /puppet/v3/facts API endpoint.

For details on configuring Puppet Server´s auth.conf, see:

https://puppet.com/docs/puppetserver/latest/config_file_auth.html

## EXAMPLES
find

Get facts from the local system:

$ puppet facts find

show

retrieve facts:

$ puppet facts show os

upload

Upload facts:

$ puppet facts upload

## NOTES
This subcommand is an indirector face, which exposes find, search, save, and destroy actions for an indirected subsystem of Puppet. Valid termini for this face include:

- facter

- json

- memory

- network_device

- rest

- store_configs

- yaml

## COPYRIGHT AND LICENSE
Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


puppet-filebucket

title: puppet-filebucket(8)

text:
# puppet-filebucket(8)

## NAME
puppet-filebucket - Store and retrieve files in a filebucket

## SYNOPSIS
A stand-alone Puppet filebucket client.

## USAGE
puppet filebucket mode [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose] [-l|--local] [-r|--remote] [-s|--server server] [-f|--fromdate date] [-t|--todate date] [-b|--bucket directory] file file ...

Puppet filebucket can operate in three modes, with only one mode per call:

backup: Send one or more files to the specified file bucket. Each sent file is printed with its resulting sha256 sum.

get: Return the text associated with an sha256 sum. The text is printed to stdout, and only one file can be retrieved at a time.

restore: Given a file path and an sha256 sum, store the content associated with the sum into the specified file path. You can specify an entirely new path to this argument; you are not restricted to restoring the content to its original location.

diff: Print a diff in unified format between two checksums in the filebucket or between a checksum and its matching file.

list: List all files in the current local filebucket. Listing remote filebuckets is not allowed.

## DESCRIPTION
This is a stand-alone filebucket client for sending files to a local or central filebucket.

Note that ´filebucket´ defaults to using a network-based filebucket available on the server named ´puppet´. To use this, you´ll have to be running as a user with valid Puppet certificates. Alternatively, you can use your local file bucket by specifying ´--local´, or by specifying ´--bucket´ with a local path.

```
  find /opt/puppetlabs/server/data/puppetserver/bucket -type f -mtime +45 -atime +45 -print0 | xargs -0 rm
```

•

Restrict the directory to a maximum size after which the oldest items are removed.

## OPTIONS
Note that any setting that´s valid in the configuration file is also a valid long argument. For example, ´ssldir´ is a valid setting, so you can specify ´--ssldir directory´ 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´.

--bucket

Specify a local filebucket path. This overrides the default path set in ´$clientbucketdir´.

--debug

Enable full debugging.

--fromdate

(list only) Select bucket files from ´fromdate´.

--help

Print this help message.

--local

Use the local filebucket. This uses the default configuration information and the bucket located at the ´$clientbucketdir´ setting by default. If ´--bucket´ is set, puppet uses that path instead.

--remote

Use a remote filebucket. This uses the default configuration information and the bucket located at the ´$bucketdir´ setting by default.

--server_list

A list of comma separated servers; only the first entry is used for file storage. This setting takes precidence over server.

--server

The server to use for file storage. This setting is only used if server_list is not set.

--todate

(list only) Select bucket files until ´todate´.

--verbose

Print extra information.

--version

Print version information.

## EXAMPLES

```
## Backup a file to the filebucket, then restore it to a temporary directory
$ puppet filebucket backup /etc/passwd
/etc/passwd: 429b225650b912a2ee067b0a4cf1e949
$ puppet filebucket restore /tmp/passwd 429b225650b912a2ee067b0a4cf1e949
## Diff between two files in the filebucket
$ puppet filebucket -l diff d43a6ecaa892a1962398ac9170ea9bf2 7ae322f5791217e031dc60188f4521ef
1a2
> again
## Diff between the file in the filebucket and a local file
$ puppet filebucket -l diff d43a6ecaa892a1962398ac9170ea9bf2 /tmp/testFile
1a2
> again
## Backup a file to the filebucket and observe that it keeps each backup separate
$ puppet filebucket -l list
d43a6ecaa892a1962398ac9170ea9bf2 2015-05-11 09:27:56 /tmp/TestFile
$ echo again >> /tmp/TestFile
$ puppet filebucket -l backup /tmp/TestFile
/tmp/TestFile: 7ae322f5791217e031dc60188f4521ef
$ puppet filebucket -l list
d43a6ecaa892a1962398ac9170ea9bf2 2015-05-11 09:27:56 /tmp/TestFile
7ae322f5791217e031dc60188f4521ef 2015-05-11 09:52:15 /tmp/TestFile
## List files in a filebucket within date ranges
$ puppet filebucket -l -f 2015-01-01 -t 2015-01-11 list
<Empty Output>
$ puppet filebucket -l -f 2015-05-10 list
d43a6ecaa892a1962398ac9170ea9bf2 2015-05-11 09:27:56 /tmp/TestFile
7ae322f5791217e031dc60188f4521ef 2015-05-11 09:52:15 /tmp/TestFile
$ puppet filebucket -l -f "2015-05-11 09:30:00" list
7ae322f5791217e031dc60188f4521ef 2015-05-11 09:52:15 /tmp/TestFile
$ puppet filebucket -l -t "2015-05-11 09:30:00" list
d43a6ecaa892a1962398ac9170ea9bf2 2015-05-11 09:27:56 /tmp/TestFile
## Manage files in a specific local filebucket
$ puppet filebucket -b /tmp/TestBucket backup /tmp/TestFile2
/tmp/TestFile2: d41d8cd98f00b204e9800998ecf8427e
$ puppet filebucket -b /tmp/TestBucket list
d41d8cd98f00b204e9800998ecf8427e 2015-05-11 09:33:22 /tmp/TestFile2
## From a Puppet Server, list files in the server bucketdir
$ puppet filebucket -b $(puppet config print bucketdir --section server) list
d43a6ecaa892a1962398ac9170ea9bf2 2015-05-11 09:27:56 /tmp/TestFile
7ae322f5791217e031dc60188f4521ef 2015-05-11 09:52:15 /tmp/TestFile
```

## AUTHOR
Luke Kanies

## COPYRIGHT
Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-generate

title: puppet-generate(8)

summary: Generates Puppet code from Ruby definitions\.

text:
# puppet-generate(8)

## NAME
puppet-generate - Generates Puppet code from Ruby definitions.

## SYNOPSIS
puppet generate 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
types - Generates Puppet code for custom types

SYNOPSIS

puppet generate types [--format format] [--force]

DESCRIPTION

Generates definitions for custom resource types using Puppet code.

Types defined in Puppet code can be used to isolate custom type definitions between different environments.

OPTIONS --force - Forces the generation of output files (skips up-to-date checks).

--format <format> - The generation output format to use. Supported formats: pcore.

## EXAMPLES
types

Generate Puppet type definitions for all custom resource types in the current environment:

```
$ puppet generate types
```

Generate Puppet type definitions for all custom resource types in the specified environment:

```
$ puppet generate types --environment development
```

## COPYRIGHT AND LICENSE
Copyright 2016 by Puppet Inc. Apache 2 license; see COPYING


puppet-help

title: puppet-help(8)

summary: Display Puppet help\.

text:
# puppet-help(8)

## NAME
puppet-help - Display Puppet help.

## SYNOPSIS
puppet help 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
help - Display help about Puppet subcommands and their actions.

SYNOPSIS

puppet help [--version VERSION] [--ronn] [subcommand] [action]

DESCRIPTION

Display help about Puppet subcommands and their actions.

OPTIONS --ronn - Whether to render the help text in ronn format.

--version VERSION - The version of the subcommand for which to show help.

RETURNS

Short help text for the specified subcommand or action.

## EXAMPLES
help

Get help for an action:

$ puppet help

## COPYRIGHT AND LICENSE
Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


puppet-lookup

title: puppet-lookup(8)

summary: Interactive Hiera lookup

text:
# puppet-lookup(8)

## NAME
puppet-lookup - Interactive Hiera lookup

## SYNOPSIS
Does Hiera lookups from the command line.

Since this command needs access to your Hiera data, make sure to run it on a node that has a copy of that data. This usually means logging into a Puppet Server node and running ´puppet lookup´ with sudo.

The most common version of this command is:

´puppet lookup KEY --node NAME --environment ENV --explain´

## USAGE
puppet lookup [--help] [--type TYPESTRING] [--merge first|unique|hash|deep] [--knock-out-prefix PREFIX-STRING] [--sort-merged-arrays] [--merge-hash-arrays] [--explain] [--environment ENV] [--default VALUE] [--node NODE-NAME] [--facts FILE] [--compile] [--render-as s|json|yaml|binary|msgpack] keys

## DESCRIPTION
The lookup command is a CLI for Puppet´s ´lookup()´ function. It searches your Hiera data and returns a value for the requested lookup key, so you can test and explore your data. It is a modern replacement for the ´hiera´ command. Lookup uses the setting for global hiera.yaml from puppet´s config, and the environment to find the environment level hiera.yaml as well as the resulting modulepath for the environment (for hiera.yaml files in modules). Hiera usually relies on a node´s facts to locate the relevant data sources. By default, ´puppet lookup´ uses facts from the node you run the command on, but you can get data for any other node with the ´--node NAME´ option. If possible, the lookup command will use the requested node´s real stored facts from PuppetDB; if PuppetDB isn´t configured or you want to provide arbitrary fact values, you can pass alternate facts as a JSON or YAML file with ´--facts FILE´.

If you´re debugging your Hiera data and want to see where values are coming from, use the ´--explain´ option.

If ´--explain´ isn´t specified, lookup exits with 0 if a value was found and 1 otherwise. With ´--explain´, lookup always exits with 0 unless there is a major error.

You can provide multiple lookup keys to this command, but it only returns a value for the first found key, omitting the rest.

For more details about how Hiera works, see the Hiera documentation: https://puppet.com/docs/puppet/latest/hiera_intro.html

## OPTIONS

- --help: Print this help message.

- --explain Explain the details of how the lookup was performed and where the final value came from (or the reason no value was found).

- --node NODE-NAME Specify which node to look up data for; defaults to the node where the command is run. Since Hiera´s purpose is to provide different values for different nodes (usually based on their facts), you´ll usually want to use some specific node´s facts to explore your data. If the node where you´re running this command is configured to talk to PuppetDB, the command will use the requested node´s most recent facts. Otherwise, you can override facts with the ´--facts´ option.

- --facts FILE Specify a .json or .yaml file of key => value mappings to override the facts for this lookup. Any facts not specified in this file maintain their original value.

- --environment ENV Like with most Puppet commands, you can specify an environment on the command line. This is important for lookup because different environments can have different Hiera data. This environment will be always be the one used regardless of any other factors.

- --merge first|unique|hash|deep: Specify the merge behavior, overriding any merge behavior from the data´s lookup_options. ´first´ returns the first value found. ´unique´ appends everything to a merged, deduplicated array. ´hash´ performs a simple hash merge by overwriting keys of lower lookup priority. ´deep´ performs a deep merge on values of Array and Hash type. There are additional options that can be used with ´deep´.

- --knock-out-prefix PREFIX-STRING Can be used with the ´deep´ merge strategy. Specifies a prefix to indicate a value should be removed from the final result.

- --sort-merged-arrays Can be used with the ´deep´ merge strategy. When this flag is used, all merged arrays are sorted.

- --merge-hash-arrays Can be used with the ´deep´ merge strategy. When this flag is used, hashes WITHIN arrays are deep-merged with their counterparts by position.

- --explain-options Explain whether a lookup_options hash affects this lookup, and how that hash was assembled. (lookup_options is how Hiera configures merge behavior in data.)

- --default VALUE A value to return if Hiera can´t find a value in data. For emulating calls to the ´lookup()´ function that include a default.

- --type TYPESTRING: Assert that the value has the specified type. For emulating calls to the ´lookup()´ function that include a data type.

- --compile Perform a full catalog compilation prior to the lookup. If your hierarchy and data only use the $facts, $trusted, and $server_facts variables, you don´t need this option; however, if your Hiera configuration uses arbitrary variables set by a Puppet manifest, you might need this option to get accurate data. No catalog compilation takes place unless this flag is given.

- --render-as s|json|yaml|binary|msgpack Specify the output format of the results; "s" means plain text. The default when producing a value is yaml and the default when producing an explanation is s.

## EXAMPLE
To look up ´key_name´ using the Puppet Server node´s facts: $ puppet lookup key_name

To look up ´key_name´ using the Puppet Server node´s arbitrary variables from a manifest, and classify the node if applicable: $ puppet lookup key_name --compile

To look up ´key_name´ using the Puppet Server node´s facts, overridden by facts given in a file: $ puppet lookup key_name --facts fact_file.yaml

To look up ´key_name´ with agent.local´s facts: $ puppet lookup --node agent.local key_name

To get the first value found for ´key_name_one´ and ´key_name_two´ with agent.local´s facts while merging values and knocking out the prefix ´foo´ while merging: $ puppet lookup --node agent.local --merge deep --knock-out-prefix foo key_name_one key_name_two

To lookup ´key_name´ with agent.local´s facts, and return a default value of ´bar´ if nothing was found: $ puppet lookup --node agent.local --default bar key_name

To see an explanation of how the value for ´key_name´ would be found, using agent.local´s facts: $ puppet lookup --node agent.local --explain key_name

## COPYRIGHT
Copyright (c) 2015 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-module

title: puppet-module(8)

summary: Creates, installs and searches for modules on the Puppet Forge\.

text:
# puppet-module(8)

## NAME
puppet-module - Creates, installs and searches for modules on the Puppet Forge.

## SYNOPSIS
puppet module action [--environment production ] [--modulepath ]

## DESCRIPTION
This subcommand can find, install, and manage modules from the Puppet Forge, a repository of user-contributed Puppet code. It can also generate empty modules, and prepare locally developed modules for release on the Forge.

## 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.

--environment production

The environment in which Puppet is running. For clients, such as puppet agent, this determines the environment itself, which Puppet uses to find modules and much more. For servers, such as puppet server, this provides the default environment for nodes that Puppet knows nothing about.

When defining an environment in the [agent] section, this refers to the environment that the agent requests from the primary server. The environment doesn´t have to exist on the local filesystem because the agent fetches it from the primary server. This definition is used when running puppet agent.

When defined in the [user] section, the environment refers to the path that Puppet uses to search for code and modules related to its execution. This requires the environment to exist locally on the filesystem where puppet is being executed. Puppet subcommands, including puppet module and puppet apply, use this definition.

Given that the context and effects vary depending on the config section https://puppet.com/docs/puppet/latest/config_file_main.html#config-sections in which the environment setting is defined, do not set it globally.

--modulepath

The search path for modules, as a list of directories separated by the system path separator character. (The POSIX path separator is ´:´, and the Windows path separator is ´;´.)

Setting a global value for modulepath in puppet.conf is not allowed (but it can be overridden from the commandline). Please use directory environments instead. If you need to use something other than the default modulepath of <ACTIVE ENVIRONMENT´S MODULES DIR>:$basemodulepath, you can set modulepath in environment.conf. For more info, see https://puppet.com/docs/puppet/latest/environments_about.html

## ACTIONS
changes - Show modified files of an installed module.

SYNOPSIS

puppet module changes path

DESCRIPTION

Shows any files in a module that have been modified since it was installed. This action compares the files on disk to the md5 checksums included in the module´s checksums.json or, if that is missing, in metadata.json.

RETURNS

Array of strings representing paths of modified files.

install - Install a module from the Puppet Forge or a release archive.

SYNOPSIS

puppet module install [--force | -f] [--target-dir DIR | -i DIR] [--ignore-dependencies] [--version VER | -v VER] name

DESCRIPTION

Installs a module from the Puppet Forge or from a release archive file. Note: Module install uses MD5 checksums, which are prohibited on FIPS enabled systems.

The specified module will be installed into the directory specified with the --target-dir option, which defaults to the first directory in the modulepath.

OPTIONS --force | -f - Force overwrite of existing module, if any. Implies --ignore-dependencies.

--ignore-dependencies - Do not attempt to install dependencies. Implied by --force.

--target-dir DIR | -i DIR - The directory into which modules are installed; defaults to the first directory in the modulepath.

Specifying this option will change the installation directory, and will use the existing modulepath when checking for dependencies. If you wish to check a different set of directories for dependencies, you must also use the --environment or --modulepath options.

--version VER | -v VER - Module version to install; can be an exact version or a requirement string, eg ´>= 1.0.3´. Defaults to latest version.

RETURNS

Pathname object representing the path to the installed module.

list - List installed modules

SYNOPSIS

puppet module list [--tree]

DESCRIPTION

Lists the installed puppet modules. By default, this action scans the modulepath from puppet.conf´s [main] block; use the --modulepath option to change which directories are scanned.

The output of this action includes information from the module´s metadata, including version numbers and unmet module dependencies.

OPTIONS --tree - Whether to show dependencies as a tree view

RETURNS

hash of paths to module objects

uninstall - Uninstall a puppet module.

SYNOPSIS

puppet module uninstall [--force | -f] [--ignore-changes | -c] [--version=] name

DESCRIPTION

Uninstalls a puppet module from the modulepath (or a specific target directory). Note: Module uninstall uses MD5 checksums, which are prohibited on FIPS enabled systems.

OPTIONS --force | -f - Force the uninstall of an installed module even if there are local changes or the possibility of causing broken dependencies.

--ignore-changes | -c - Uninstall an installed module even if there are local changes to it. (Implied by --force.)

--version= - The version of the module to uninstall. When using this option, a module matching the specified version must be installed or else an error is raised.

RETURNS

Hash of module objects representing uninstalled modules and related errors.

upgrade - Upgrade a puppet module.

SYNOPSIS

puppet module upgrade [--force | -f] [--ignore-dependencies] [--ignore-changes | -c] [--version=] name

DESCRIPTION

Upgrades a puppet module. Note: Module upgrade uses MD5 checksums, which are prohibited on FIPS enabled systems.

OPTIONS --force | -f - Force the upgrade of an installed module even if there are local changes or the possibility of causing broken dependencies. Implies --ignore-dependencies.

--ignore-changes | -c - Upgrade an installed module even if there are local changes to it. (Implied by --force.)

--ignore-dependencies - Do not attempt to install dependencies. Implied by --force.

--version= - The version of the module to upgrade to.

RETURNS

Hash

## EXAMPLES
changes

Show modified files of an installed module:

$ puppet module changes /etc/puppetlabs/code/modules/vcsrepo/ warning: 1 files modified lib/puppet/provider/vcsrepo.rb

install

Install a module:

$ puppet module install puppetlabs-vcsrepo Preparing to install into /etc/puppetlabs/code/modules ... Downloading from https://forgeapi.puppet.com ... Installing -- do not interrupt ... /etc/puppetlabs/code/modules └── puppetlabs-vcsrepo (v0.0.4)

Install a module to a specific environment:

$ puppet module install puppetlabs-vcsrepo --environment development Preparing to install into /etc/puppetlabs/code/environments/development/modules ... Downloading from https://forgeapi.puppet.com ... Installing -- do not interrupt ... /etc/puppetlabs/code/environments/development/modules └── puppetlabs-vcsrepo (v0.0.4)

Install a specific module version:

$ puppet module install puppetlabs-vcsrepo -v 0.0.4 Preparing to install into /etc/puppetlabs/modules ... Downloading from https://forgeapi.puppet.com ... Installing -- do not interrupt ... /etc/puppetlabs/code/modules └── puppetlabs-vcsrepo (v0.0.4)

Install a module into a specific directory:

$ puppet module install puppetlabs-vcsrepo --target-dir=/opt/puppetlabs/puppet/modules Preparing to install into /opt/puppetlabs/puppet/modules ... Downloading from https://forgeapi.puppet.com ... Installing -- do not interrupt ... /opt/puppetlabs/puppet/modules └── puppetlabs-vcsrepo (v0.0.4)

Install a module into a specific directory and check for dependencies in other directories:

$ puppet module install puppetlabs-vcsrepo --target-dir=/opt/puppetlabs/puppet/modules --modulepath /etc/puppetlabs/code/modules Preparing to install into /opt/puppetlabs/puppet/modules ... Downloading from https://forgeapi.puppet.com ... Installing -- do not interrupt ... /opt/puppetlabs/puppet/modules └── puppetlabs-vcsrepo (v0.0.4)

Install a module from a release archive:

$ puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz Preparing to install into /etc/puppetlabs/code/modules ... Downloading from https://forgeapi.puppet.com ... Installing -- do not interrupt ... /etc/puppetlabs/code/modules └── puppetlabs-vcsrepo (v0.0.4)

Install a module from a release archive and ignore dependencies:

$ puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz --ignore-dependencies Preparing to install into /etc/puppetlabs/code/modules ... Installing -- do not interrupt ... /etc/puppetlabs/code/modules └── puppetlabs-vcsrepo (v0.0.4)

list

List installed modules:

$ puppet module list /etc/puppetlabs/code/modules ├── bodepd-create_resources (v0.0.1) ├── puppetlabs-bacula (v0.0.2) ├── puppetlabs-mysql (v0.0.1) ├── puppetlabs-sqlite (v0.0.1) └── puppetlabs-stdlib (v2.2.1) /opt/puppetlabs/puppet/modules (no modules installed)

List installed modules in a tree view:

$ puppet module list --tree /etc/puppetlabs/code/modules └─┬ puppetlabs-bacula (v0.0.2) ├── puppetlabs-stdlib (v2.2.1) ├─┬ puppetlabs-mysql (v0.0.1) │ └── bodepd-create_resources (v0.0.1) └── puppetlabs-sqlite (v0.0.1) /opt/puppetlabs/puppet/modules (no modules installed)

List installed modules from a specified environment:

$ puppet module list --environment production /etc/puppetlabs/code/modules ├── bodepd-create_resources (v0.0.1) ├── puppetlabs-bacula (v0.0.2) ├── puppetlabs-mysql (v0.0.1) ├── puppetlabs-sqlite (v0.0.1) └── puppetlabs-stdlib (v2.2.1) /opt/puppetlabs/puppet/modules (no modules installed)

List installed modules from a specified modulepath:

$ puppet module list --modulepath /opt/puppetlabs/puppet/modules /opt/puppetlabs/puppet/modules (no modules installed)

uninstall

Uninstall a module:

$ puppet module uninstall puppetlabs-ssh Removed /etc/puppetlabs/code/modules/ssh (v1.0.0)

Uninstall a module from a specific directory:

$ puppet module uninstall puppetlabs-ssh --modulepath /opt/puppetlabs/puppet/modules Removed /opt/puppetlabs/puppet/modules/ssh (v1.0.0)

Uninstall a module from a specific environment:

$ puppet module uninstall puppetlabs-ssh --environment development Removed /etc/puppetlabs/code/environments/development/modules/ssh (v1.0.0)

Uninstall a specific version of a module:

$ puppet module uninstall puppetlabs-ssh --version 2.0.0 Removed /etc/puppetlabs/code/modules/ssh (v2.0.0)

upgrade

upgrade an installed module to the latest version

$ puppet module upgrade puppetlabs-apache /etc/puppetlabs/puppet/modules └── puppetlabs-apache (v1.0.0 -> v2.4.0)

upgrade an installed module to a specific version

$ puppet module upgrade puppetlabs-apache --version 2.1.0 /etc/puppetlabs/puppet/modules └── puppetlabs-apache (v1.0.0 -> v2.1.0)

upgrade an installed module for a specific environment

$ puppet module upgrade puppetlabs-apache --environment test /etc/puppetlabs/code/environments/test/modules └── puppetlabs-apache (v1.0.0 -> v2.4.0)

## COPYRIGHT AND LICENSE
Copyright 2012 by Puppet Inc. Apache 2 license; see COPYING


puppet-node

title: puppet-node(8)

summary: View and manage node definitions\.

text:
# puppet-node(8)

## NAME
puppet-node - View and manage node definitions.

## SYNOPSIS
puppet node action [--terminus _TERMINUS]

## DESCRIPTION
This subcommand interacts with node objects, which are used by Puppet to build a catalog. A node object consists of the node´s facts, environment, node parameters (exposed in the parser as top-scope variables), and classes.

## 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.

--terminus _TERMINUS

Indirector faces expose indirected subsystems of Puppet. These subsystems are each able to retrieve and alter a specific type of data (with the familiar actions of find, search, save, and destroy) from an arbitrary number of pluggable backends. In Puppet parlance, these backends are called terminuses.

Almost all indirected subsystems have a rest terminus that interacts with the puppet master´s data. Most of them have additional terminuses for various local data models, which are in turn used by the indirected subsystem on the puppet master whenever it receives a remote request.

The terminus for an action is often determined by context, but occasionally needs to be set explicitly. See the "Notes" section of this face´s manpage for more details.

## ACTIONS
clean - Clean up signed certs, cached facts, node objects, and reports for a node stored by the puppetmaster

SYNOPSIS

puppet node clean [--terminus _TERMINUS] host1 [host2 ...]

DESCRIPTION

Cleans up the following information a puppet master knows about a node:

Signed certificates - ($vardir/ssl/ca/signed/node.domain.pem)

Cached facts - ($vardir/yaml/facts/node.domain.yaml)

Cached node objects - ($vardir/yaml/node/node.domain.yaml)

Reports - ($vardir/reports/node.domain)

NOTE: this action now cleans up certs via Puppet Server´s CA API. A running server is required for certs to be cleaned.

find - Retrieve a node object.

SYNOPSIS

puppet node find [--terminus _TERMINUS] host

DESCRIPTION

Retrieve a node object.

RETURNS

A hash containing the node´s classes, environment, expiration, name, parameters (its facts, combined with any ENC-set parameters), and time. When used from the Ruby API: a Puppet::Node object.

RENDERING ISSUES: Rendering as string and json are currently broken; node objects can only be rendered as yaml.

info - Print the default terminus class for this face.

SYNOPSIS

puppet node info [--terminus _TERMINUS]

DESCRIPTION

Prints the default terminus class for this subcommand. Note that different run modes may have different default termini; when in doubt, specify the run mode with the ´--run_mode´ option.

## EXAMPLES
find

Retrieve an "empty" (no classes, no ENC-imposed parameters, and an environment of "production") node:

$ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml

Retrieve a node using the Puppet Server´s configured ENC:

$ puppet node find somenode.puppetlabs.lan --terminus exec --run_mode server --render-as yaml

Retrieve the same node from the Puppet Server:

$ puppet node find somenode.puppetlabs.lan --terminus rest --render-as yaml

## NOTES
This subcommand is an indirector face, which exposes find, search, save, and destroy actions for an indirected subsystem of Puppet. Valid termini for this face include:

- exec

- json

- memory

- msgpack

- plain

- rest

- store_configs

- yaml

## COPYRIGHT AND LICENSE
Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


puppet-parser

title: puppet-parser(8)

summary: Interact directly with the parser\.

text:
# puppet-parser(8)

## NAME
puppet-parser - Interact directly with the parser.

## SYNOPSIS
puppet parser 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 parse tree for debugging: SYNOPSIS

puppet parser dump [--e source] [--[no-]validate] [--format old, pn, or json] [--pretty] [--format old|pn|json] [--pretty] { -e source | [templates ...] }

DESCRIPTION

This action parses and validates the Puppet DSL syntax without compiling a catalog or syncing any resources.

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 manifests (.pp) files, or an -e followed by the puppet source text. If no arguments are given, the stdin is read (unless it is attached to a terminal)

The output format of the dumped tree is intended for debugging purposes and is not API, it may change from time to time.

OPTIONS --e <source> - dump one 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).

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

•

validate - Validate the syntax of one or more Puppet manifests.: SYNOPSIS

puppet parser validate [manifest] [manifest ...]

DESCRIPTION

This action validates Puppet DSL syntax without compiling a catalog or syncing any resources. If no manifest files are provided, it will validate the default site manifest.

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.

RETURNS

Nothing, or the first syntax error encountered.

## EXAMPLES
validate

Validate the default site manifest at /etc/puppetlabs/puppet/manifests/site.pp:

$ puppet parser validate

Validate two arbitrary manifest files:

$ puppet parser validate init.pp vhost.pp

Validate from STDIN:

$ cat init.pp | puppet parser validate

## COPYRIGHT AND LICENSE
Copyright 2014 by Puppet Inc. Apache 2 license; see COPYING


puppet-plugin

title: puppet-plugin(8)

summary: Interact with the Puppet plugin system\.

text:
# puppet-plugin(8)

## NAME
puppet-plugin - Interact with the Puppet plugin system.

## SYNOPSIS
puppet plugin action

## DESCRIPTION
This subcommand provides network access to the puppet master´s store of plugins.

The puppet master serves Ruby code collected from the lib directories of its modules. These plugins can be used on agent nodes to extend Facter and implement custom types and providers. Plugins are normally downloaded by puppet agent during the course of a run.

## 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
download - Download plugins from the puppet master.

SYNOPSIS

puppet plugin download

DESCRIPTION

Downloads plugins from the configured puppet master. Any plugins downloaded in this way will be used in all subsequent Puppet activity. This action modifies files on disk.

RETURNS

A list of the files downloaded, or a confirmation that no files were downloaded. When used from the Ruby API, this action returns an array of the files downloaded, which will be empty if none were retrieved.

## EXAMPLES
download

Retrieve plugins from the puppet master:

$ puppet plugin download

Retrieve plugins from the puppet master (API example):

$ Puppet::Face[:plugin, ´0.0.1´].download

## COPYRIGHT AND LICENSE
Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


puppet-report

title: puppet-report(8)

summary: Create, display, and submit reports\.

text:
# puppet-report(8)

## NAME
puppet-report - Create, display, and submit reports.

## SYNOPSIS
puppet report action [--terminus _TERMINUS]

## 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.

--terminus _TERMINUS

Indirector faces expose indirected subsystems of Puppet. These subsystems are each able to retrieve and alter a specific type of data (with the familiar actions of find, search, save, and destroy) from an arbitrary number of pluggable backends. In Puppet parlance, these backends are called terminuses.

Almost all indirected subsystems have a rest terminus that interacts with the puppet master´s data. Most of them have additional terminuses for various local data models, which are in turn used by the indirected subsystem on the puppet master whenever it receives a remote request.

The terminus for an action is often determined by context, but occasionally needs to be set explicitly. See the "Notes" section of this face´s manpage for more details.

## ACTIONS
info - Print the default terminus class for this face.

SYNOPSIS

puppet report info [--terminus _TERMINUS]

DESCRIPTION

Prints the default terminus class for this subcommand. Note that different run modes may have different default termini; when in doubt, specify the run mode with the ´--run_mode´ option.

save - API only: submit a report.

SYNOPSIS

puppet report save [--terminus _TERMINUS] report

DESCRIPTION

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.

RETURNS

Nothing.

submit - API only: submit a report with error handling.

SYNOPSIS

puppet report submit [--terminus _TERMINUS] report

DESCRIPTION

API only: Submits a report to the puppet master. This action is essentially a shortcut and wrapper for the save action with the rest terminus, and provides additional details in the event of a failure.

## EXAMPLES
save

From the implementation of puppet report submit (API example):

begin Puppet::Transaction::Report.indirection.terminus_class = :rest Puppet::Face[:report, "0.0.1"].save(report) Puppet.notice "Uploaded report for #{report.name}" rescue => detail Puppet.log_exception(detail, "Could not send report: #{detail}") end

submit

API example:report = Puppet::Face[:catalog, ´0.0.1´].apply Puppet::Face[:report, ´0.0.1´].submit(report) return report

## NOTES
This subcommand is an indirector face, which exposes find, search, save, and destroy actions for an indirected subsystem of Puppet. Valid termini for this face include:

- json

- msgpack

- processor

- rest

- yaml

## COPYRIGHT AND LICENSE
Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


puppet-resource

title: puppet-resource(8)

summary: The resource abstraction layer shell

text:
# puppet-resource(8)

## NAME
puppet-resource - The resource abstraction layer shell

## SYNOPSIS
Uses the Puppet RAL to directly interact with the system.

## USAGE
puppet resource [-h|--help] [-d|--debug] [-v|--verbose] [-e|--edit] [-p|--param parameter] [-t|--types] [-y|--to_yaml] type [name] [attribute=value ...]

## DESCRIPTION
This command provides simple facilities for converting current system state into Puppet code, along with some ability to modify the current state using Puppet´s RAL.

By default, you must at least provide a type to list, in which case puppet resource will tell you everything it knows about all resources of that type. You can optionally specify an instance name, and puppet resource will only describe that single instance.

If given a type, a name, and a series of attribute=value pairs, puppet resource will modify the state of the specified resource. Alternately, if given a type, a name, and the ´--edit´ flag, puppet resource will write its output to a file, open that file in an editor, and then apply the saved file as a Puppet transaction.

## OPTIONS
Note that any setting that´s valid in the configuration file is also a valid long argument. For example, ´ssldir´ is a valid setting, so you can specify ´--ssldir directory´ 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´.

--debug

Enable full debugging.

--edit

Write the results of the query to a file, open the file in an editor, and read the file back in as an executable Puppet manifest.

--help

Print this help message.

--param

Add more parameters to be outputted from queries.

--types

List all available types.

--verbose

Print extra information.

--to_yaml

Output found resources in yaml format, suitable to use with Hiera and create_resources.

## EXAMPLE
This example uses puppet resource to return a Puppet configuration for the user luke:

```
$ puppet resource user luke
user { ´luke´:

 home => ´/home/luke´,

 uid => ´100´,

 ensure => ´present´,

 comment => ´Luke Kanies,,,´,

 gid => ´1000´,

 shell => ´/bin/bash´,

 groups => [´sysadmin´,´audio´,´video´,´puppet´]
}
```

## AUTHOR
Luke Kanies

## COPYRIGHT
Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-script

title: puppet-script(8)

text:
# puppet-script(8)

## NAME
puppet-script - Run a puppet manifests as a script without compiling a catalog

## SYNOPSIS
Runs a puppet language script without compiling a catalog.

## USAGE
puppet script [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose] [-e|--execute] [-l|--logdest syslog|eventlog|FILE|console] [--noop] file

## DESCRIPTION
This is a standalone puppet script runner tool; use it to run puppet code without compiling a catalog.

When provided with a modulepath, via command line or config file, puppet script can load functions, types, tasks and plans from modules.

## OPTIONS
Note that any setting that´s valid in the configuration file is also a valid long argument. For example, ´environment´ is a valid setting, so you can specify ´--environment mytest´ 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´.

--debug

Enable full debugging.

--help

Print this help message

--logdest

Where to send log messages. Choose between ´syslog´ (the POSIX syslog service), ´eventlog´ (the Windows Event Log), ´console´, or the path to a log file. Defaults to ´console´. Multiple destinations can be set using a comma separated list (eg: /path/file1,console,/path/file2)"

A path ending with ´.json´ will receive structured output in JSON format. The log file will not have an ending ´]´ automatically written to it due to the appending nature of logging. It must be appended manually to make the content valid JSON.

A path ending with ´.jsonl´ will receive structured output in JSON Lines format.

--noop

Use ´noop´ mode where Puppet runs in a no-op or dry-run mode. This is useful for seeing what changes Puppet will make without actually executing the changes. Applies to tasks only.

--execute

Execute a specific piece of Puppet code

--verbose

Print extra information.

## EXAMPLE

```
$ puppet script -l /tmp/manifest.log manifest.pp
$ puppet script --modulepath=/root/dev/modules -e ´notice("hello world")´
```

## AUTHOR
Henrik Lindberg

## COPYRIGHT
Copyright (c) 2017 Puppet Inc., LLC Licensed under the Apache 2.0 License


puppet-ssl

title: puppet-ssl(8)

text:
# puppet-ssl(8)

## NAME
puppet-ssl - Manage SSL keys and certificates for puppet SSL clients

## SYNOPSIS
Manage SSL keys and certificates for SSL clients needing to communicate with a puppet infrastructure.

## USAGE
puppet ssl action [-h|--help] [-v|--verbose] [-d|--debug] [--localca] [--target CERTNAME]

## OPTIONS

- --help: Print this help message.

- --verbose: Print extra information.

- --debug: Enable full debugging.

- --localca Also clean the local CA certificate and CRL.

- --target CERTNAME Clean the specified device certificate instead of this host´s certificate.

## ACTIONS
bootstrap

Perform all of the steps necessary to request and download a client certificate. If autosigning is disabled, then puppet will wait every waitforcert seconds for its certificate to be signed. To only attempt once and never wait, specify a time of 0. Since waitforcert is a Puppet setting, it can be specified as a time interval, such as 30s, 5m, 1h.

submit_request

Generate a certificate signing request (CSR) and submit it to the CA. If a private and public key pair already exist, they will be used to generate the CSR. Otherwise a new key pair will be generated. If a CSR has already been submitted with the given certname, then the operation will fail.

generate_request

Generate a certificate signing request (CSR). If a private and public key pair already exist, they will be used to generate the CSR. Otherwise a new key pair will be generated.

download_cert

Download a certificate for this host. If the current private key matches the downloaded certificate, then the certificate will be saved and used for subsequent requests. If there is already an existing certificate, it will be overwritten.

verify

Verify the private key and certificate are present and match, verify the certificate is issued by a trusted CA, and check revocation status.

clean

Remove the private key and certificate related files for this host. If --localca is specified, then also remove this host´s local copy of the CA certificate(s) and CRL bundle. if --target CERTNAME is specified, then remove the files for the specified device on this host instead of this host.

show

Print the full-text version of this host´s certificate.


pmxcfs

package: pve-cluster

title: pmxcfs(8)

summary: Proxmox Cluster File System

text:
# pmxcfs(8)

## NAME
pmxcfs - Proxmox Cluster File System

## SYNOPSIS
pmxcfs [OPTIONS]

Help Options:

-h, --help

Show help options

Application Options:

-d, --debug

Turn on debug messages

-f, --foreground

Do not daemonize server

-l, --local

Force local mode (ignore corosync.conf, force quorum)

This service is usually started and managed using systemd toolset. The service is called pve-cluster.

```
systemctl start pve-cluster
```

```
systemctl stop pve-cluster
```

```
systemctl status pve-cluster
```

## DESCRIPTION
The Proxmox Cluster file system (“pmxcfs”) is a database-driven file system for storing configuration files, replicated in real time to all cluster nodes using corosync. We use this to store all Proxmox VE related configuration files.

Although the file system stores all data inside a persistent database on disk, a copy of the data resides in RAM. This imposes restrictions on the maximum size, which is currently 128 MiB. This is still enough to store the configuration of several thousand virtual machines.

This system provides the following advantages:

•Seamless replication of all configuration to all nodes in real time

•Provides strong consistency checks to avoid duplicate VM IDs

•Read-only when a node loses quorum

•Automatic updates of the corosync cluster configuration to all nodes

•Includes a distributed locking mechanism

## POSIX COMPATIBILITY
The file system is based on FUSE, so the behavior is POSIX like. But some feature are simply not implemented, because we do not need them:

•You can just generate normal files and directories, but no symbolic links, ...

•You can’t rename non-empty directories (because this makes it easier to guarantee that VMIDs are unique).

•You can’t change file permissions (permissions are based on paths)

•O_EXCL creates were not atomic (like old NFS)

•O_TRUNC creates are not atomic (FUSE restriction)

## FILE ACCESS RIGHTS
All files and directories are owned by user root and have group www-data. Only root has write permissions, but group www-data can read most files. Files below the following paths are only accessible by root:

```
/etc/pve/priv/
/etc/pve/nodes/${NAME}/priv/
```

## TECHNOLOGY
We use the Corosync Cluster Engine[1] for cluster communication, and SQlite[2] for the database file. The file system is implemented in user space using FUSE[3].

## FILE SYSTEM LAYOUT
The file system is mounted at:

```
/etc/pve
```

### Files
authkey.pub

Public key used by the ticket system

ceph.conf

Ceph configuration file (note: /etc/ceph/ceph.conf is a symbolic link to this)

corosync.conf

Corosync cluster configuration file (prior to Proxmox VE 4.x, this file was called cluster.conf)

datacenter.cfg

Proxmox VE datacenter-wide configuration (keyboard layout, proxy, ...)

domains.cfg

Proxmox VE authentication domains

firewall/cluster.fw

Firewall configuration applied to all nodes

firewall/<NAME>.fw

Firewall configuration for individual nodes

firewall/<VMID>.fw

Firewall configuration for VMs and containers

ha/crm_commands

Displays HA operations that are currently being carried out by the CRM

ha/manager_status

JSON-formatted information regarding HA services on the cluster

ha/resources.cfg

Resources managed by high availability, and their current state

ha/rules.cfg

Rules putting constraints on the HA manager’s scheduling of HA resources

nodes/<NAME>/config

Node-specific configuration

nodes/<NAME>/lxc/<VMID>.conf

VM configuration data for LXC containers

nodes/<NAME>/openvz/

Prior to Proxmox VE 4.0, used for container configuration data (deprecated, removed soon)

nodes/<NAME>/pve-ssl.key

Private SSL key for pve-ssl.pem

nodes/<NAME>/pve-ssl.pem

Public SSL certificate for web server (signed by cluster CA)

nodes/<NAME>/pveproxy-ssl.key

Private SSL key for pveproxy-ssl.pem (optional)

nodes/<NAME>/pveproxy-ssl.pem

Public SSL certificate (chain) for web server (optional override for pve-ssl.pem)

nodes/<NAME>/qemu-server/<VMID>.conf

VM configuration data for KVM VMs

priv/authkey.key

Private key used by ticket system

priv/authorized_keys

SSH keys of cluster members for authentication

priv/ceph*

Ceph authentication keys and associated capabilities

priv/known_hosts

SSH keys of the cluster members for verification

priv/lock/*

Lock files used by various services to ensure safe cluster-wide operations

priv/pve-root-ca.key

Private key of cluster CA

priv/shadow.cfg

Shadow password file for PVE Realm users

priv/storage/<STORAGE-ID>.pw

Contains the password of a storage in plain text

priv/tfa.cfg

Base64-encoded two-factor authentication configuration

priv/token.cfg

API token secrets of all tokens

pve-root-ca.pem

Public certificate of cluster CA

pve-www.key

Private key used for generating CSRF tokens

sdn/*

Shared configuration files for Software Defined Networking (SDN)

status.cfg

Proxmox VE external metrics server configuration

storage.cfg

Proxmox VE storage configuration

user.cfg

Proxmox VE access control configuration (users/groups/...)

virtual-guest/cpu-models.conf

For storing custom CPU models

vzdump.cron

Cluster-wide vzdump backup-job schedule

### Symbolic links
Certain directories within the cluster file system use symbolic links, in order to point to a node’s own configuration files. Thus, the files pointed to in the table below refer to different files on each node of the cluster.

local

nodes/<LOCAL_HOST_NAME>

lxc

nodes/<LOCAL_HOST_NAME>/lxc/

openvz

nodes/<LOCAL_HOST_NAME>/openvz/ (deprecated, removed soon)

qemu-server

nodes/<LOCAL_HOST_NAME>/qemu-server/

### Special status files for debugging (JSON)
.version

File versions (to detect file modifications)

.members

Info about cluster members

.vmlist

List of all VMs

.clusterlog

Cluster log (last 50 entries)

.rrd

RRD data (most recent entries)

### Enable/Disable debugging
You can enable verbose syslog messages with:

```
echo "1" >/etc/pve/.debug
```

And disable verbose syslog messages with:

```
echo "0" >/etc/pve/.debug
```

## RECOVERY
If you have major problems with your Proxmox VE host, for example hardware issues, it could be helpful to copy the pmxcfs database file /var/lib/pve-cluster/config.db, and move it to a new Proxmox VE host. On the new host (with nothing running), you need to stop the pve-cluster service and replace the config.db file (required permissions 0600). Following this, adapt /etc/hostname and /etc/hosts according to the lost Proxmox VE host, then reboot and check (and don’t forget your VM/CT data).

### Remove Cluster Configuration
The recommended way is to reinstall the node after you remove it from your cluster. This ensures that all secret cluster/ssh keys and any shared configuration data is destroyed.

In some cases, you might prefer to put a node back to local mode without reinstalling, which is described in Separate A Node Without Reinstalling (man pvecm(1))

### Recovering/Moving Guests from Failed Nodes
For the guest configuration files in nodes/<NAME>/qemu-server/ (VMs) and nodes/<NAME>/lxc/ (containers), Proxmox VE sees the containing node <NAME> as the owner of the respective guest. This concept enables the usage of local locks instead of expensive cluster-wide locks for preventing concurrent guest configuration changes.

As a consequence, if the owning node of a guest fails (for example, due to a power outage, fencing event, etc.), a regular migration is not possible (even if all the disks are located on shared storage), because such a local lock on the (offline) owning node is unobtainable. This is not a problem for HA-managed guests, as Proxmox VE’s High Availability stack includes the necessary (cluster-wide) locking and watchdog functionality to ensure correct and automatic recovery of guests from fenced nodes.

If a non-HA-managed guest has only shared disks (and no other local resources which are only available on the failed node), a manual recovery is possible by simply moving the guest configuration file from the failed node’s directory in /etc/pve/ to an online node’s directory (which changes the logical owner or location of the guest).

For example, recovering the VM with ID 100 from an offline node1 to another node node2 works by running the following command as root on any member node of the cluster:

```
mv /etc/pve/nodes/node1/qemu-server/100.conf /etc/pve/nodes/node2/qemu-server/
```

Warning Before manually recovering a guest like this, make absolutely sure that the failed source node is really powered off/fenced. Otherwise Proxmox VE’s locking principles are violated by the mv command, which can have unexpected consequences.

Warning Guests with local disks (or other local resources which are only available on the offline node) are not recoverable like this. Either wait for the failed node to rejoin the cluster or restore such guests from backups.

## COPYRIGHT AND DISCLAIMER
Copyright © 2007-2022 Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/

## AUTHOR
Proxmox Server Solutions Gmbh

www.proxmox.com

## NOTES
1.

Corosync Cluster Engine

https://www.corosync.org

2.

SQlite

https://www.sqlite.org

3.

FUSE

https://github.com/libfuse/libfuse