Skip to content

Latest commit

 

History

History
75 lines (51 loc) · 4.07 KB

external_ca_configuration.markdown

File metadata and controls

75 lines (51 loc) · 4.07 KB
Raw
layout title canonical
default
Puppet Server: External CA Configuration
/puppetserver/latest/external_ca_configuration.html

Puppet Server supports the ability to configure certificates from an existing external CA. This is similar to Ruby Puppet master functionality under a Rack-enabled web server like Apache with Passenger. Much of the existing documentation on External CA Support for the Ruby Puppet Master still applies to using an external CA with Puppet Server. However, there are some configuration differences with Puppet Server, which we've detailed on this page.

Client DN Authentication

Puppet Server is hosted by a Jetty web server; therefore, Rack-enabled web server configuration is irrelevant. For client authentication purposes, Puppet Server can extract the distinguished name (DN) from a client certificate provided during SSL negotiation with the Jetty web server. This means the web server no longer needs to be configured to use an X-Client-DN request header for client authentication.

That said, the use of an X-Client-DN request header is still supported for cases where SSL termination of client requests needs to be done on an external server. See External SSL Termination with Puppet Server for details.

Disabling the Internal Puppet CA Service

Note: If you're upgrading from Puppet Server 2.4.x or earlier to Puppet Server 2.5 or newer, read and act on the bootstrap upgrade notes before upgrading.

If you are using certs from an external CA, you'll need to disable the internal Puppet CA service. However, the ca setting from the puppet.conf file isn't honored by Puppet Server. To disable the service, modify the /etc/puppetlabs/puppetserver/services.d/ca.cfg file.

To disable the Puppet CA service in the ca.cfg file, comment out the line following "To enable the CA service..." and uncomment the line following "To disable the CA service...", as so:

# To enable the CA service, leave the following line uncommented
# puppetlabs.services.ca.certificate-authority-service/certificate-authority-service
# To disable the CA service, comment out the above line and uncomment the line below
puppetlabs.services.ca.certificate-authority-disabled-service/certificate-authority-disabled-service

For more information, see Service Bootstrapping.

Web Server Configuration

The webserver.conf file for Puppet Server performs a function similar to that of VirtualHost configuration for a Ruby Puppet master running on an Apache server. Several ssl- settings should be added to the webserver.conf file to enable the web server to use the correct SSL configuration:

  • ssl-cert: The value of puppet master --configprint hostcert. Equivalent to the 'SSLCertificateFile' Apache config setting.
  • ssl-key: The value of puppet master --configprint hostprivkey. Equivalent to the 'SSLCertificateKeyFile' Apache config setting.
  • ssl-ca-cert: The value of puppet master --configprint localcacert. Equivalent to the 'SSLCACertificateFile' Apache config setting.
  • ssl-cert-chain: Equivalent to the 'SSLCertificateChainFile' Apache config setting. Optional.
  • ssl-crl-path: The path to the CRL file to use. Optional.

An example webserver.conf file might look something like this:

webserver: {

  client-auth : want
  ssl-host    : 0.0.0.0
  ssl-port    : 8140

  ssl-cert    : /path/to/master.pem

  ssl-key     : /path/to/master.key

  ssl-ca-cert : /path/to/ca_bundle.pem

  ssl-cert-chain : /path/to/ca_bundle.pem

  ssl-crl-path : /etc/puppetlabs/puppet/ssl/crl.pem
}

For more information on these settings, see Configuring the Web Server Service.

Restart Required

After the above changes are made to Puppet Server's configuration files, you'll have to restart the Puppet Server service for the new settings to take effect.