Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

puppet-ca (8)

Name

puppet-ca - Local Puppet Certificate Authority management.

Synopsis

puppet ca action

Description

PUPPET-CA(8)                     Puppet manual                    PUPPET-CA(8)



NAME
       puppet-ca - Local Puppet Certificate Authority management.

SYNOPSIS
       puppet ca action

DESCRIPTION
       This provides local management of the Puppet Certificate Authority.

       You  can  use this subcommand to sign outstanding certificate requests,
       list and manage local certificates, and inspect the state of the CA.

OPTIONS
       Note that any setting that's valid in the configuration file is also  a
       valid  long  argument,  although  it  may or may not be relevant to the
       present action. For example, server and run_mode are valid settings, so
       you  can  specify  --server <servername>, or --run_mode <runmode> as an
       argument.

       See  the  configuration  file  documentation  at   https://docs.puppet-
       labs.com/puppet/latest/reference/configuration.html  for  the full list
       of acceptable parameters. A commented list of all configuration options
       can also be generated by running puppet with --genconfig.

       --render-as FORMAT
              The  format  in  which to render output. The most common formats
              are json, s (string), yaml, and console, but other options  such
              as dot are sometimes available.

       --verbose
              Whether to log verbosely.

       --debug
              Whether to log debug information.

ACTIONS
       o   destroy   -   Destroy  named  certificate  or  pending  certificate
           request.: SYNOPSIS

           puppet ca destroy

           DESCRIPTION

           Destroy named certificate or pending certificate request.

       o   fingerprint - Print the DIGEST (defaults to the signing  algorithm)
           fingerprint of a host's certificate.: SYNOPSIS

           puppet ca fingerprint [--digest ALGORITHM]

           DESCRIPTION

           Print the DIGEST (defaults to the signing algorithm) fingerprint of
           a host's certificate.

           OPTIONS --digest ALGORITHM - The hash algorithm to  use  when  dis-
           playing the fingerprint

       o   generate - Generate a certificate for a named client.: SYNOPSIS

           puppet ca generate [--dns-alt-names NAMES]

           DESCRIPTION

           Generate a certificate for a named client.

           OPTIONS --dns-alt-names NAMES - A comma-separated list of alternate
           DNS names for Puppet Server. These are extra hostnames (in addition
           to  its  certname)  that  the server is allowed to use when serving
           agents. Puppet checks this setting when automatically requesting  a
           certificate  for  Puppet  agent or Puppet Server, and when manually
           generating a certificate with puppet cert generate.

           In order to handle agent requests at a given hostname  (like  "pup-
           pet.example.com"),  Puppet  Server  needs a certificate that proves
           it's allowed to use that name; if a server shows a certificate that
           doesn't  include  its  hostname, Puppet agents will refuse to trust
           it. If you use a single hostname for Puppet traffic  but  load-bal-
           ance  it to multiple Puppet Servers, each of those servers needs to
           include the official hostname in its list of extra names.

           Note: The list of alternate names is locked in  when  the  server's
           certificate  is  signed.  If you need to change the list later, you
           can't just change this setting; you also need to:

       o   On the server: Stop Puppet Server.

       o   On the CA server: Revoke and clean the  server's  old  certificate.
           (puppet cert clean <NAME>)

       o   On  the server: Delete the old certificate (and any old certificate
           signing requests) from the ssldir  https://docs.puppetlabs.com/pup-
           pet/latest/reference/dirs_ssldir.html.

       o   On  the  server:  Run  puppet agent -t --ca_server <CA HOSTNAME> to
           request a new certificate

       o   On the CA server: Sign the certificate request, explicitly allowing
           alternate names (puppet cert sign --allow-dns-alt-names <NAME>).

       o   On  the  server:  Run  puppet agent -t --ca_server <CA HOSTNAME> to
           retrieve the cert.

       o   On the server: Start Puppet Server again.



       To see all the alternate names your servers are using, log into your CA
       server  and  run  puppet  cert  list -a, then check the output for (alt
       names: ...). Most agent nodes should NOT have alternate names; the only
       certs that should have them are Puppet Server nodes that you want other
       agents to trust.

       o   list - List certificates and/or certificate requests.: SYNOPSIS

           puppet  ca  list  [--[no-]all]   [--[no-]pending]   [--[no-]signed]
           [--digest ALGORITHM] [--subject PATTERN]

           DESCRIPTION

           This  will  list  the  current certificates and certificate signing
           requests in the Puppet CA. You will also get the  fingerprint,  and
           any certificate verification failure reported.

           OPTIONS --[no-]all - Include all certificates and requests.

           --digest  ALGORITHM - The hash algorithm to use when displaying the
           fingerprint

           --[no-]pending - Include pending certificate signing requests.

           --[no-]signed - Include signed certificates.

           --subject PATTERN - Only include  certificates  or  requests  where
           subject matches PATTERN.

           PATTERN  is  interpreted  as a regular expression, allowing complex
           filtering of the content.

       o   print - Print the full-text version of a host's certificate.:  SYN-
           OPSIS

           puppet ca print

           DESCRIPTION

           Print the full-text version of a host's certificate.

       o   revoke - Add certificate to certificate revocation list.: SYNOPSIS

           puppet ca revoke

           DESCRIPTION

           Add certificate to certificate revocation list.

       o   sign - Sign an outstanding certificate request.: SYNOPSIS

           puppet ca sign [--[no-]allow-dns-alt-names]

           DESCRIPTION

           Sign an outstanding certificate request.

           OPTIONS  --[no-]allow-dns-alt-names  - Whether or not to accept DNS
           alt names in the certificate request

       o   verify - Verify the named certificate against the local CA certifi-
           cate.: SYNOPSIS

           puppet ca verify

           DESCRIPTION

           Verify the named certificate against the local CA certificate.



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



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


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

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



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