Most commands on Unix-like operating systems provide a manual or man page. The man page provides information on the available options and general guidance on using the command. Puppet initially chose not to follow this standard and instead used the help argument when calling the puppet command to specify documentation. Recent versions of Puppet have included manual pages for specific subcommands of the Puppet command-line tool. To access an individual manual page, type man puppet-[subcommand]. For example, to access the manual page on using puppet help, use man puppet-help. You can also access the same manual page using puppet man help.
The available help topics for a recent edition of Puppet are shown in the following screenshot:
For more information about a specific command, issue the command after puppet help. For example, for more information on puppet config, use puppet help config. This is demonstrated in the following code:
t@mylaptop ~ $ puppet help config USAGE: puppet config<action> [--section SECTION_NAME] This subcommand can inspect and modify settings from Puppet's 'puppet.conf' configuration file. For documentation about individual settings, see http://docs.puppetlabs.com/references/latest/configuration.html. OPTIONS: --render-as FORMAT - The rendering format to use. --verbose - Whether to log verbosely. --debug - Whether to log debug information. --section SECTION_NAME - The section of the configuration file to interact with. ACTIONS: print Examine Puppet's current settings. setSet Puppet's settings. See 'puppet man config' or 'man puppet-config' for full help.
You can also add subcommands to have even more specific information returned by the command, as follows:
t@mylaptop ~ $ puppet help config print USAGE: puppet config print [--section SECTION_NAME] (all | <setting> [<setting> ...] Prints the value of a single setting or a list of settings. OPTIONS: --render-as FORMAT - The rendering format to use. --verbose - Whether to log verbosely. --debug - Whether to log debug information. --section SECTION_NAME - The section of the configuration file to interact with. See 'puppet man config' or 'man puppet-config' for full help.
The output of puppet help shows all the available arguments for the Puppet command-line utility. We will now see the usefulness of a selection of these arguments.
Using
puppet resource can be a valuable troubleshooting tool. When you are diagnosing a problem, puppet resource can be used to inspect a node and verify how Puppet sees the state of a resource. For example, if we had a Linux node running an SSH daemon (sshd), we could ask Puppet about the state of the sshd service using puppet resource, as follows:
t@mylaptop ~ $ sudo puppet resource service sshd service { 'sshd': ensure => 'running', enable => 'true', }
As you can see, Puppet returned the current status of the service in Puppet code. By using puppet resource, we can query the node for any resource type that is known to Puppet. For instance, we can do this to view the status of the bind package of a node, as follows:
t@mylaptop ~ $ sudo puppet resource package bind package { 'bind': ensure => 'absent', }
We can also inspect the settings for a file, as follows:
t@mylaptop ~ $ sudo puppet resource file /etc/resolv.conf file { '/etc/resolv.conf': ensure => 'file', content => '{md5}463bd26e077bc01a9368378737ef5bf0', ctime => '2015-03-02 21:04:21 -0800', group => '0', mode => '644', mtime => '2015-03-02 21:04:21 -0800', owner => '0', selrange => 's0', selrole => 'object_r', seltype => 'net_conf_t', seluser => 'system_u', type => 'file', }
When troubleshooting, it can often be useful to apply a small chunk of code rather than a whole catalog. By using puppet apply, you can specify a manifest file, which can be applied directly to a node. For example, to create a file named /tmp/trouble on the local node with the content Hello, Troubleshooter!, create the following manifest file named trouble.pp:
file {'/tmp/trouble':
content => "Hello, Troubleshooter!\n"
}When we run puppet apply on this manifest, Puppet will create the /tmp/trouble file as expected:
t@mylaptop ~ $ puppet apply trouble.pp Notice: Compiled catalog for mylaptop in environment production in 0.21 seconds Notice: /Stage[main]/Main/File[/tmp/trouble]/ensure: defined content as '{md5}7b6223913adac8607e89a7c2f11744d0' Notice: Finished catalog run in 0.03 seconds t@mylaptop ~ $ cat /tmp/trouble Hello, Troubleshooter!
When troubleshooting, it can be useful to add the --debug option when running puppet apply. Puppet will print information about how facts were compiled for the node, in addition to debugging information related to the application of resources.
The command-line utility can also be used to verify the syntax of your manifests. This can be useful when trying to find an issue with the compilation of your catalog. You can verify individual files by adding them as arguments to the command. For instance, the following manifest has a syntax error:
file {'bad':
ensure => 'directory',
path => '/tmp/bad'
owner => 'root',
}We can verify this with puppet parser validate, which shows the following error:
t@mylaptop ~/trouble/01 $ puppet parser validate bad.pp Error: Could not parse for environment production: Syntax error at 'owner'; expected '}' at /home/thomas/trouble/01/bad.pp:4
As you can see, there should be a comma after '/tmp/bad' since there is another attribute specified for the file resource.
I find myself using this command often enough to use the ppv alias for puppet parser validate.