Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

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://pup-
       pet.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
       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.  These  can  be
           either  IP  or  DNS,  and the type should be specified and followed
           with a colon. Untyped inputs will default to DNS.

           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>) (Note puppet cert clean is deprecated
           and will be replaced with puppetserver ca clean in Puppet 6.)

       o   On the server: Delete the old certificate (and any old  certificate
           signing  requests)  from  the  ssldir  https://puppet.com/docs/pup-
           pet/latest/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>).
           (Note puppet cert sign is deprecated and will be replaced with pup-
           petserver ca sign in Puppet 6.)

       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
       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       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.

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



Puppet, Inc.                       July 2020                      PUPPET-CA(8)