[SERVER-2347] (DOCS) 'service puppetserver ca generate' typo Created: 2018/10/07  Updated: 2018/10/29  Resolved: 2018/10/08

Status: Closed
Project: Puppet Server
Component/s: None
Affects Version/s: SERVER 6.0.0
Fix Version/s: SERVER 6.0.2

Type: Task Priority: Normal
Reporter: Lucy Wyman Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Template:
Team: Froyo
QA Risk Assessment: Needs Assessment

 Description   

Hello! There seems to be a typo in this doc https://puppet.com/docs/puppetserver/6.0/install_from_packages.html#quick-start - one command says to run service puppetserver ca generate, when I think it should read puppetserver ca generate.



 Comments   
Comment by Rob Thomas [ 2018/10/07 ]

After uninstalling and reinstalling several times, trying to fix this, it appears as if the certificate is auto-generated. However, I'm not sure if that was just left over from a previous attempt.

It would be nice if someone who actually knew a bit more about this could go through the installation instructions and fix any errors.

Comment by Maggie Dreyer [ 2018/10/08 ]

Yeah those docs are definitely a bit funky on several levels, I'll get that cleaned up. Thanks for pointing this out!

I think the main issue here is that the command for setting up the intermediate CA is puppetserver ca setup (it was briefly called generate before release, which may have caused the confusion when these were written). Starting Puppet Server will also generate CA files if none yet exist, but with the old self-signed root architecture, which exists only for backwards compatibility and is not recommended for use on new installs. That may have been what you saw.

For more details on the intermediate CA, see https://puppet.com/docs/puppetserver/6.0/intermediate_ca.html, and for more information on the puppetserver ca command line tool, see https://puppet.com/docs/puppetserver/6.0/subcommands.html#ca.

Comment by Maggie Dreyer [ 2018/10/08 ]

Michelle Fredette do changes like this get picked up automatically each time the docs get built?

Comment by Rob Thomas [ 2018/10/08 ]

Thanks Maggie Dreyer - I'll be waiting with baited breath for the updated docs.   The only thing that SLIGHTLY concerned me is that how did it know what the correct FQDN was? 

I am lucky enough that I was able to provide a valid RDNS, so when the machine did a lookup of itself, it was able to get the correct CN, but I'm sure other people won't be as lucky.  Is there any chance you can document how to regenerate the puppet master cert with the 'correct' CN on its certificate? That's actually what sent me down this spiral, because it seemed un-intuitive that puppet would just guess what the cert should be.

Comment by Maggie Dreyer [ 2018/10/08 ]

So if you are generating the master cert as part of generating the whole CA (e.g. with the setup command), it will use the certname setting from puppet.conf. The default value for this is the FQDN as detected by Facter. The code in the puppetserver CLI gem that supplies this default is here: https://github.com/puppetlabs/puppetserver-ca-cli/blob/master/lib/puppetserver/ca/config/puppet.rb#L76-L86. This is the same behavior that puppetserver has always used for generating the master cert. So if you want something other than the FQDN detected by Facter, you should configure certname in the master section in puppet.conf.

If you are trying to regenerate your master cert without regenerating the CA, you should stop puppetserver, and use puppetserver ca generate --ca-client --certname <name> --subject-alt-names <SANs>. This command will create a certificate with the right auth extensions to contact Puppet Server's CA API, required for using the puppetserver ca CLI. It requires you to specify both the certname and any subject alt names manually. Depending on why you are regenerating the cert, one good way to do this is to inspect the values from the old master cert (assuming you still have it) and supply those before deleting the old cert. If you are regenerating the cert because they were wrong the first time, it would be a good idea to also configure your desired values in the master section of puppet.conf. If you have already configured them, and are regenerating because something bad happened to your old master cert (accidental deletion, it got corrupted or compromised), you can use puppet config print certname --section master and puppet config print dns_alt_names --section master (the FQDN will always be added to whatever the latter returns) to retrieve the configured values.

Does this clear things up? Do you have any further questions?

I have a note to update the docs at https://puppet.com/docs/puppet/6.0/ssl_regenerate_certificates.html for Puppet 6 (they still reference the old puppet cert CLI, as well as several other deprecated workflows). Do you think some of this more detailed info should also get added there, or was this more than you needed? (Note: the old process was "simpler" because it was frighteningly magical. In what world should running `puppet cert list` regenerate your whole CA??)

Comment by Michelle Fredette [ 2018/10/08 ]

It appears that these changes are in the docs Maggie Dreyer - but I'll kick off the build to be sure.

Comment by Maggie Dreyer [ 2018/10/08 ]

Thanks, I just noticed a formatting error now that they've been published, I put up https://github.com/puppetlabs/puppetserver/pull/1842 to fix it. It should be fine for that to go out whenever, it's minor.

Generated at Thu Jan 23 01:36:55 PST 2020 using JIRA 7.7.1#77002-sha1:e75ca93d5574d9409c0630b81c894d9065296414.