When setting up a Puppet master, one common configuration hurdle involves properly defining multiple DNS names for the server's certificate. The error message you're seeing:
err: Could not retrieve catalog from remote server: hostname was not match with the server certificate
typically occurs when the agent tries to connect to a server name that isn't listed in the certificate's Subject Alternative Names (SANs).
The proper format for certdnsnames in puppet.conf is a colon-separated list (not semicolons or commas). Here's the correct way:
[master]
certname = myname.mydomain.com
ca_server = myname.mydomain.com
certdnsnames = puppet:puppet.local:myname.dyndns.org:hivemind.local
Here's the complete process to properly configure multiple DNS names:
- First, clean up any existing certificates:
puppet cert clean myname.mydomain.com - Update your puppet.conf with proper certdnsnames:
[master] certname = puppetmaster.company.com dns_alt_names = puppet:puppetmaster:puppet.company.com:puppet.local - Regenerate certificates:
puppet cert generate puppetmaster.company.com --dns_alt_names=puppet,puppetmaster,puppet.company.com,puppet.local - Restart the Puppet master service
To verify your certificate contains all the proper DNS names:
openssl x509 -in /var/lib/puppet/ssl/certs/myname.mydomain.com.pem -text -noout | grep DNS
You should see output like:
DNS:puppet, DNS:puppet.local, DNS:myname.dyndns.org, DNS:hivemind.local
- Certificate caching: Puppet agents cache certificates. After changing DNS names, you may need to clear the agent's SSL directory.
- Order matters: The certdnsnames must be set before generating the certificate. Changes afterward require regenerating the certificate.
- Version differences: Older Puppet versions (pre-4.0) used slightly different syntax. For modern versions (5+), use dns_alt_names instead of certdnsnames.
For complex environments with internal and external DNS names:
[master]
certname = puppet-master-01.internal.example.com
dns_alt_names = puppet:puppet.example.com:puppet-master-01:puppet-master-01.internal.example.com:puppet-master-01.aws.example.com
This configuration allows agents to connect using various names while maintaining certificate validation.
When working with Puppet's certificate system, I recently encountered a frustrating scenario where my agents couldn't verify the master's identity despite having multiple DNS names configured. Here's what I learned about proper certdnsnames implementation.
The working format in puppet.conf should use colons as separators:
[master]
certname = master.example.com
dns_alt_names = puppet,puppet.local,master.dyndns.org,hivemind.local
Key points to note:
- Use commas between alternative names, no semicolons
- The 'dns_alt_names' parameter is preferred over 'certdnsnames' in newer versions
- No need for prefixing with 'puppet:' unless you're dealing with very old versions
If you're modifying DNS names after initial setup, you'll need to:
# Clean existing certs
puppetserver ca clean --certname master.example.com
# Regenerate with new alt names
puppet master --no-daemonize --verbose --dns_alt_names=puppet,puppet.local
# Verify the cert contains all names
puppet cert print master.example.com | grep DNS
For a multi-environment setup with internal and external DNS:
[master]
certname = puppet-prod-01.aws.internal
dns_alt_names = puppet,puppet.prod.company.com,puppet.aws.internal,puppet.prod
This allows agents to connect via:
puppet agent --server puppet.prod.company.com --test
# or
puppet agent --server puppet.aws.internal --test
Common pitfalls and solutions:
- Certificate mismatch: Always verify with
openssl x509 -in /etc/puppetlabs/puppet/ssl/certs/ca.pem -text - Agent configuration: Ensure agents use
server =value that matches one of the alt names - Firewall issues: Remember Puppet uses port 8140 by default
For dynamic environments, you might consider:
dns_alt_names = puppet,*.region.company.com,puppet.*.internal
Note that wildcard certificates have their own security considerations and may require custom CA configuration.