Skip to content

Update documentation and examples for puppetdb SSL settings #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kpaulisse merged 3 commits into from
Nov 1, 2016
Merged

Update documentation and examples for puppetdb SSL settings #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9f2da4b
Correct documentation for PuppetDB SSL client configuration
Oct 31, 2016
f739ac5
Clarify the optional-ness of the SSL client password in the example
Oct 31, 2016
cd4c576
Add SSL certificate whitelist link to Puppet documentation
Oct 31, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions doc/configuration-puppetdb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ For this to work, you will need to configure or provide information about your P

- **SSL Authentication Information**: Whether your PuppetDB instance requires clients to authenticate via SSL certificates. Unless you have made a special effort to configure your PuppetDB instance not to require client certificates, it is likely that client certificate authentication is required.

NOTE: In certain situations, you may need to define or alter the `certificate-whitelist` setting in your PuppetDB configuration to whitelist the certificate used by octocatalog-diff. Please see [Configuring PuppetDB](https://docs.puppet.com/puppetdb/latest/configure.html#certificate-whitelist) in the Puppet documentation for additional information.

## Supplying necessary information via configuration files

The following settings can be used in a [configuration file](/doc/configuration.md).
Expand All @@ -24,8 +26,9 @@ The following settings can be used in a [configuration file](/doc/configuration.
| --- | --- |
| `settings[:puppetdb_url]` | PuppetDB URL settings. If this is a string, it will set a single PuppetDB URL. If it is an array, it will set multiple URLs, which will be tried in a random order until one responds. |
| `settings[:puppetdb_ssl_ca]` | Path to the certificate of the CA that signed PuppetDB's certificate. This file is typically found in `/etc/puppetlabs/puppetdb/ssl/ca.pem` on your PuppetDB server. This file should contain only the public certificate, so it is safe to distribute to developer workstations or CI environments. |
| `settings[:puppetdb_ssl_client_cert]` | Path to the certificate of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the certificate from your PuppetDB server itself. |
| `settings[:puppetdb_ssl_client_key]` | Path to the private key of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the private key from your PuppetDB server itself. |
| `settings[:puppetdb_ssl_client_cert]` | TEXT of the certificate of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the certificate from your PuppetDB server itself. Note: This variable needs to be set to the TEXT of the certificate, and not the file path. This means you will likely want to use `File.read(...)` if you are configuring this to be read from a file. |
| `settings[:puppetdb_ssl_client_key]` | Path to the private key of the client SSL keypair. You should generate a keypair specifically for this client (or if you are running this on a machine managed by Puppet, you may be able to use the keypair for the client machine). You should **NOT** copy the private key from your PuppetDB server itself. Note: This variable needs to be set to the TEXT of the key, and not the file path. This means you will likely want to use `File.read(...)` if you are configuring this to be read from a file. |
| `settings[:puppetdb_ssl_client_pem]` | Concatenation of the text of `puppetdb_ssl_client_key` and `puppetdb_ssl_client_cert` as previously described. This is a good alternative if your certificate chain is complex and it's easier just to put everything in a single place. Note: this option is second in precedence; if `settings[:puppetdb_ssl_client_cert]` and `settings[:puppetdb_ssl_client_key]` are both set, this will be ignored. |
| `settings[:puppetdb_ssl_client_password]` | Plain text string containing the password to unlock the private key. For keys generated by the Puppet Master CA, this is not required and should be left undefined. |

## Supplying necessary information via the command line
Expand Down
23 changes: 20 additions & 3 deletions examples/octocatalog-diff.cfg.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,19 +76,36 @@ def self.config
# puppetdb_ssl_client_key
# puppetdb_ssl_client_password
# puppetdb_ssl_client_cert
# puppetdb_ssl_client_pem
#
# This sets up SSL authentication for PuppetDB.
#
# For SSL authentication, the key and certificate used for SSL client authentication.
# Don't set these if your PuppetDB is unauthenticated. The provided example may work if you
# run octocatalog-diff on a machine managed by Puppet, and your PuppetDB authenticates
# clients with that same CA. Otherwise, just provide the actual path to the key and the
# clients with that same CA. Otherwise, fill in the actual path to the key and the
# certificate in the relevant settings. If the key is password protected, set
# :puppetdb_ssl_client_password to the text of the password.
#
# You can configure this in one of two ways:
# 1. Set `puppetdb_ssl_client_key` and `puppetdb_ssl_client_cert` individually.
# 2. Set `puppetdb_ssl_client_pem` to the concatenation of the key and the certificate.
#
# VERY IMPORTANT: settings[:puppetdb_ssl_client_key], settings[:puppetdb_ssl_client_cert], and
# settings[:puppetdb_ssl_client_pem] need to be set to the TEXT OF THE CERTIFICATE/KEY, not
# just the file name of the certificate. You'll probably need to use something like this:
# settings[:puppetdb_ssl_client_WHATEVER] = File.read("...")
#
# More: https://github.com/github/octocatalog-diff/blob/master/doc/configuration-puppetdb.md
##############################################################################################

# require 'socket'
# fqdn = Socket.gethostbyname(Socket.gethostname).first
# settings[:puppetdb_ssl_client_key] = "/etc/puppetlabs/puppet/ssl/private_keys/#{fqdn}.pem"
# settings[:puppetdb_ssl_client_cert] = "/etc/puppetlabs/puppet/ssl/certs/#{fqdn}.pem"
# settings[:puppetdb_ssl_client_key] = File.read("/etc/puppetlabs/puppet/ssl/private_keys/#{fqdn}.pem")
# settings[:puppetdb_ssl_client_cert] = File.read("/etc/puppetlabs/puppet/ssl/certs/#{fqdn}.pem")

# For keys generated by Puppet, passwords are not needed so the next setting can be left commented.
# If you generated your own key outside of Puppet and it has a password, specify it here.
# settings[:puppetdb_ssl_client_password] = 'your-password-here'

##############################################################################################
Expand Down