When Puppet agents attempt to communicate with the puppetmaster, they perform SSL certificate verification where the agent verifies:

1. The server's certificate is signed by a trusted CA
2. The certificate's CN (Common Name) matches the expected hostname
3. The certificate hasn't expired

The critical files involved in the verification process are located in /etc/puppet/ssl/:

ls -l /etc/puppet/ssl/certs/
ls -l /etc/puppet/ssl/private_keys/
ls -l /etc/puppet/ssl/public_keys/

To inspect the certificate details:

openssl x509 -in /etc/puppet/ssl/certs/web1.xxx.xxx.net.pem -text -noout

1. Incorrect certname configuration in puppet.conf:

[main]
certname = web1.xxx.xxx.net
server = puppetmaster.xxx.xxx.net

2. DNS resolution issues - Verify with:

hostname -f
dig puppetmaster.xxx.xxx.net

First, clean up existing certificates:

puppet cert clean web1.xxx.xxx.net
rm -rf /etc/puppet/ssl/{certs,private_keys,public_keys}/web1.xxx.xxx.net.pem

Then regenerate certificates with proper SANs:

puppet agent --test --certname web1.xxx.xxx.net \
--dns_alt_names=web1,puppet,puppet.xxx.xxx.net

Check certificate trust chain:

openssl verify -CAfile /etc/puppet/ssl/certs/ca.pem \
/etc/puppet/ssl/certs/web1.xxx.xxx.net.pem

Test the SSL connection:

openssl s_client -connect puppetmaster:8140 \
-CAfile /etc/puppet/ssl/certs/ca.pem \
-cert /etc/puppet/ssl/certs/web1.xxx.xxx.net.pem \
-key /etc/puppet/ssl/private_keys/web1.xxx.xxx.net.pem

For complex environments, consider these puppet.conf settings:

[master]
certname = puppetmaster.xxx.xxx.net
dns_alt_names = puppet,puppetmaster,puppetmaster.xxx.xxx.net

[agent]
certname = web1.xxx.xxx.net
use_srv_records = true
srv_domain = xxx.xxx.net

---

When Puppet agent attempts to communicate with the master, it performs strict certificate validation. The error occurs when the agent detects a discrepancy between:

• The FQDN in the server's certificate (CN=web1.xxx.xxx.net)
• The actual hostname used in the connection

# Verify the certificate's CN matches exactly:
openssl x509 -in /etc/puppet/ssl/certs/web1.xxx.xxx.net.pem -text | grep "CN ="

# Check the agent's reported certname:
puppet config print certname --section agent

# Validate DNS resolution:
host web1.xxx.xxx.net
ping -c 1 web1.xxx.xxx.net

Edit /etc/puppet/puppet.conf with these essential settings:

[main]
    certname = web1.xxx.xxx.net
    server = web1.xxx.xxx.net
    use_srv_records = false

[agent]
    report = true
    pluginsync = true
    certname = web1.xxx.xxx.net

When troubleshooting SSL issues, a complete certificate reset often helps:

# On agent:
puppet ssl clean
rm -rf /etc/puppet/ssl

# On master:
puppet cert clean web1.xxx.xxx.net

# Then restart the process:
puppet agent -t --waitforcert 60

For development environments where strict SSL isn't required:

[agent]
    ssl_verify_mode = none

Warning: Never use this in production environments.

Verify these network configurations:

• Firewall rules allowing TCP 8140
• Correct /etc/hosts entries
• Consistent time synchronization (NTP)

# Example hosts file entry:
127.0.1.1 web1.xxx.xxx.net web1

Enable verbose logging for detailed troubleshooting:

puppet agent -t --debug --verbose --no-daemonize

Key things to monitor in logs:

1. Certificate paths being used
2. DNS resolution attempts
3. Actual connection endpoints