Troubleshooting connections between components

If agent nodes can't retrieve configurations, check for communication, certificate, DNS , and NTP issues.

Agents can't reach the primary server

Agent nodes must be able to communicate with the primary server in order to retrieve configurations.

If agents can't reach the primary server, running telnet <PRIMARY_HOSTNAME> 8140 returns the error "Name or service not known."

  1. Verify that the primary server is reachable at a DNS name your agents recognize.
  2. Verify that the pe-puppetserver service is running.

Agents don't have signed certificates

Agent certificates must be signed by the primary server.

If the node's Puppet agent logs have a warning about unverified peer certificates in the current SSL session, the agent has submitted a certificate signing request that hasn't yet been signed.

  1. On the primary server, view a list of pending certificate requests: puppet cert list
  2. Sign a specified node's certificate: puppetserver ca sign <NODE NAME>

Agents aren't using the primary server's valid DNS name

Agents trust the primary server only if they contact it at one of the valid hostnames specified when the primary server was installed.

On the node, if the results of puppet agent --configprint server don't return one of the valid DNS names you chose during installation of the primary server, the node and primary server can't establish communication.

  1. To edit the primary server's hostname on nodes, in /etc/puppetlabs/puppet/puppet.conf, change the server setting to a valid DNS name.
  2. To reset the primary server's valid DNS names, log in as root and run: 
    puppet infrastructure run regenerate_primary_certificate --dns_alt_names=<COMMA-SEPARATED_LIST_OF_DNS_NAMES>

Time is out of sync

The date and time must be in sync on the primary server's and agent nodes.

If time is out of sync on nodes, running date returns incorrect or inconsistent dates.

Get time in sync by setting up NTP. Keep in mind that NTP can behave unreliably on virtual machines.

Node certificates have invalid dates

The date and time must be in sync when certificates are created.

If certificates were signed out of sync, running openssl x509 -text -noout -in $(puppet config print --section master ssldir)/certs/<NODE NAME>.pem returns invalid dates, such as certificates dated in the future.

  1. On the primary server, delete certificates with invalid dates: puppetserver ca clean --certname <NODE CERT NAME>
  2. On nodes with invalid certificates, delete the SSL directory: rm -r $(puppet config print --section master ssldir)
  3. On agent nodes, generate a new certificate request: puppet agent --test
  4. On the primary server, sign the request: puppetserver ca sign <NODE NAME>

A node is re-using a certname

If a node re-uses an old node's certname and the primary server retains the previous node's certificate, the new node is unable to request a new certificate.

  1. On the primary server, clear the node's certificate: puppetserver ca clean --certname <NODE CERT NAME>
  2. On agent node, generate a new certificate request: puppet agent --test
  3. On the primary server, sign the request: puppetserver ca sign <NODE NAME>

Agents can't reach the filebucket server

If the primary server is installed with a certname that doesn't match its hostname, agents can't back up files to the filebucket on the primary server.

If agents log errors like "could not back up," nodes are likely attempting to back up files to the wrong hostname.

On the primary server, edit /etc/puppetlabs/code/environments/production/manifests/site.pp so that filebucket server attribute points to the correct hostname: 
# Define filebucket 'main':
filebucket { 'main':
  server => '<PRIMARY_DNS_NAME>',
  path   => false,
}
Results

Changing the filebucket server attribute on the primary server fixes the error on all agent nodes.

Orchestrator can't connect to PE Bolt server

Debug a faulty connection between the orchestrator and PE Bolt server by setting the bolt_server_loglevel in the puppet_enterprise::profile::bolt_server class and running Puppet, or by manually updating loglevel in /etc/puppetlabs/bolt-server/conf.d/bolt-server.conf. The server logs are located at /var/log/puppetlabs/bolt-server/bolt-server.log.