Subcommands

We've provided several CLI commands to help with debugging and exploring Puppet Server. Most of the commands are the same ones you would use in a Ruby environment -- such as gem, ruby, and irb -- except they run against Puppet Server's JRuby installation and gems instead of your system Ruby.

The following subcommands are provided:

The format for each subcommand is:

puppetserver <subcommand> [<args>]

When running from source, the format is:

lein <subcommand> -c /path/to/puppetserver.conf [--] [<args>]

Note that if you are running from source, you need to separate flag arguments (such as --version or -e) with --, as shown above. Otherwise, those arguments will be applied to Leiningen instead of to Puppet Server. This isn't necessary when running from packages (i.e., puppetserver <subcommand>).

ca

Available actions

CA subcommand usage: puppetserver ca <action> [options].

The available actions:

  • clean: clean files from the CA for certificates

  • delete: remove expired, arbitrary, or all certs from the signed directory

  • generate: create a new certificate signed by the CA

  • setup: generate a root and intermediate signing CA for Puppet Server

  • import: import the CA's key, certs, and CRLs

  • list: list all certificate requests

  • migrate: migrate the contents of the CA directory from its current location to /etc/puppetlabs/puppetserver/ca. Adds a symlink at the old location for backwards compatibility.

  • revoke: revoke a given certificate

  • sign: sign a given certificate

    • Use the --ttl flag with sign subcommand to send the ttl to the CA. The signed certificate's notAfter value is the current time plus the ttl. The values are valid puppet.conf ttl values, for example, 1y = 1 year, 31d = 31 days.

  • prune: remove duplicate entries from the CA CRL

Important: Most of these actions only work if the puppetserver service is running. Exceptions to this requirement are:

  • migrate and prune, which require you to stop the puppetserver service.

  • setup and import, which require you to run the actions only once before you start your puppetserver service, for the very first time.

Syntax

puppetserver ca <action> [options]

Most commands require a target to be specified with the --certname flag. For example:

puppetserver ca sign --certname cert.example.com

The target is a comma separated list of names that act on multiple certificates at one time.

You can supply a custom configuration file to all subcommands using the --config option. This allows you to point the command at a custom puppet.conf, instead of the default one.

Note: These commands are available in Puppet 5, but in order to use them, you must update Puppet Server’s auth.conf to include a rule allowing the primary server’s certname to access the certificate_status and certificate_statuses endpoints. The same applies to upgrading in open source Puppet: if you're upgrading from Puppet 5 to Puppet 6 and are not regenerating your CA, you must allow the primary server’s certname. See Puppet Server Configuration Files: auth.conf for details on how to use auth.conf.

Example:

{
    # Allow the CA CLI to access the certificate_status endpoint
    match-request: {
        path: "/puppet-ca/v1/certificate_status"
        type: path
        method: [get, put, delete]
    }
    allow: server.example.com
    sort-order: 500
    name: "puppetlabs cert status"
},

Signing certs with SANs or auth extensions

With the removal of puppet cert sign, it's possible for Puppet Server’s CA API to sign certificates with subject alternative names or auth extensions, which was previously completely disallowed. This is disabled by default for security reasons, but you can turn it on by setting allow-subject-alt-names or allow-authorization-extensions to true in the certificate-authority section of Puppet Server’s config (usually located in ca.conf). After these have been configured, you can use puppetserver ca sign --certname <name> to sign certificates with these additions.

Note: For more details about the ca subcommand, visit Puppet Server CA commands.

gem

Installs and manages gems that are isolated from system Ruby and are accessible only to Puppet Server. This is a simple wrapper around the standard Ruby gem, so all of the usual arguments and flags should work as expected.

Examples:

$ puppetserver gem install pry --no-ri --no-rdoc
$ lein gem -c /path/to/puppetserver.conf -- install pry --no-ri --no-rdoc

If needed, you also can use the JAVA_ARGS_CLI environment variable to pass along custom arguments to the Java process that the gem command is run within.

Example:

$ JAVA_ARGS_CLI=-Xmx8g puppetserver gem install pry --no-ri --no-rdoc

If you prefer to have the JAVA_ARGS_CLI option persist for multiple command executions, you could set the value in the /etc/sysconfig/puppetserver or /etc/default/puppetserver file, depending upon your OS distribution:

JAVA_ARGS_CLI=-Xmx8g

With the value specified in the sysconfig or defaults file, subsequent commands would use the JAVA_ARGS_CLI variable automatically:

$ puppetserver gem install pry --no-ri --no-rdoc
// Would run 'gem' with a maximum Java heap of 8g

For more information, see Puppet Server and Gems.

ruby

Runs code in Puppet Server's JRuby interpreter. This is a simple wrapper around the standard Ruby ruby, so all of the usual arguments and flags should work as expected.

Useful when experimenting with gems installed via puppetserver gem and the Puppet and Puppet Server Ruby source code.

Examples:

$ puppetserver ruby -e "require 'puppet'; puts Puppet[:certname]"
$ lein ruby -c /path/to/puppetserver.conf -- -e "require 'puppet'; puts Puppet[:certname]"

If needed, you also can use the JAVA_ARGS_CLI environment variable to pass along custom arguments to the Java process that the ruby command is run within.

Example:

$ JAVA_ARGS_CLI=-Xmx8g puppetserver ruby -e "require 'puppet'; puts Puppet[:certname]"

If you prefer to have the JAVA_ARGS_CLI option persist for multiple command executions, you could set the value in the /etc/sysconfig/puppetserver or /etc/default/puppetserver file, depending upon your OS distribution:

JAVA_ARGS_CLI=-Xmx8g

With the value specified in the sysconfig or defaults file, subsequent commands would use the JAVA_ARGS_CLI variable automatically:

$ puppetserver ruby -e "require 'puppet'; puts Puppet[:certname]"
// Would run 'ruby' with a maximum Java heap of 8g

irb

Starts an interactive REPL for the JRuby that Puppet Server uses. This is a simple wrapper around the standard Ruby irb, so all of the usual arguments and flags should work as expected.

Like the ruby subcommand, this is useful for experimenting in an interactive environment with any installed gems (via puppetserver gem) and the Puppet and Puppet Server Ruby source code.

Examples:

$ puppetserver irb
irb(main):001:0> require 'puppet'
=> true
irb(main):002:0> puts Puppet[:certname]
centos6-64.localdomain
=> nil
$ lein irb -c /path/to/puppetserver.conf -- --version
irb 0.9.6(09/06/30)

If needed, you also can use the JAVA_ARGS_CLI environment variable to pass along custom arguments to the Java process that the irb command is run within.

Example:

$ JAVA_ARGS_CLI=-Xmx8g puppetserver irb

If you prefer to have the JAVA_ARGS_CLI option persist for multiple command executions, you could set the value in the /etc/sysconfig/puppetserver or /etc/default/puppetserver file, depending upon your OS distribution:

JAVA_ARGS_CLI=-Xmx8g

With the value specified in the sysconfig or defaults file, subsequent commands would use the JAVA_ARGS_CLI variable automatically:

$ puppetserver irb
// Would run 'irb' with a maximum Java heap of 8g

foreground

Starts the Puppet Server, but doesn't background it; similar to starting the service and then tailing the log.

Accepts an optional --debug argument to raise the logging level to DEBUG.

Examples:

$ puppetserver foreground --debug
2014-10-25 18:04:22,158 DEBUG [main] [p.t.logging] Debug logging enabled
2014-10-25 18:04:22,160 DEBUG [main] [p.t.bootstrap] Loading bootstrap config from specified path: '/etc/puppetserver/bootstrap.cfg'
2014-10-25 18:04:26,097 INFO  [main] [p.s.j.jruby-puppet-service] Initializing the JRuby service
2014-10-25 18:04:26,101 INFO  [main] [p.t.s.w.jetty9-service] Initializing web server(s).
2014-10-25 18:04:26,149 DEBUG [clojure-agent-send-pool-0] [p.s.j.jruby-puppet-agents] Initializing JRubyPuppet instances with the following settings:

prune

You can use this subcommand to remove files older than a specified age from either the report directory or the bucket directory ($reportdir or $bucketdir).

Default is 14 days.

Usage:

puppetserver prune <reportdir|bucketdir> [<ttl>]
  bucketdir|reportdir  work on either bucketdir or reportdir
  <ttl>                delete data older than this amount of time (default: 14d)