Correct documentation for PuppetDB SSL client configuration

Author: Kevin Paulisse

doc/configuration-puppetdb.md

@@ -24,8 +24,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

examples/octocatalog-diff.cfg.rb

@@ -76,19 +76,33 @@ 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")
       # settings[:puppetdb_ssl_client_password] = 'your-password-here'
 
       ##############################################################################################