When using the Puppet Enterprise Marketplace Image, you might encounter some problems that this troubleshooting section can address.

For additional troubleshooting information, see troubleshooting in the supported PE version topic.

EC2 security group isn't configured correctly

This image requires a specific network configuration to allow managed agent nodes to access services on the Puppet master. For more information, see the AWS configuration instructions and the JSON-formatted example EC2 security group policy.

Configuration error appears in a PAYG instance’s message of the day

If your pay-as-you-go (PAYG) EC2 instance is not properly configured to access the AWS metered billing service on launch, the instance will add an error message to the server message of the day (/etc/motd) and display it when you log in. Puppet Enterprise will remain in a partially-configured and non-functional state.

Correct the misconfiguration and launch a new EC2 instance.

After 60 days, the puppetadmin user account stops working

The default puppetadmin user’s password expires 60 days after the image is created. If you fail to reset the password, the account expires.

To prevent the password from expiring, run chage -E -1 puppetadmin on the Puppet master.

PE console password hasn't been set, or I don't have the password

Access to the PE console is disabled until you set the console password.

Run the included script described in the "Launching the image" section to set or reset the password.

Agents can't connect because PE configuration isn't yet complete

When first booting the EC2 instance, PE configuration must complete before you can connect and manage agents.

Run the script described in the "Launching the image" section to confirm when configuration has finished.

SSH username or credentials don't work when connecting to the EC2 instance

This image uses cloud-init to provision an SSH key for the puppetadmin user. AWS Marketplace policy requires root SSH access to be disabled, so users must specify an EC2 key pair when launching the EC2 instance and connect with the matching private key.

For example, you can run:

aws ec2 run-instance --key-name <EC2-KEYPAIR-NAME> …
ssh -i ~/.ssh/<EC2-KEYPAIR-PRIVATE>.pem puppetadmin@<EC2-PUBLIC-HOSTNAME>

Learn more about cloud-init.

EC2 hostname or IP address (private vs. public address) is wrong

To communicate from managed nodes to the master, this PE installation and security group settings are configured to use the private (internal) EC2 hostname.

To get the local hostname on the Puppet master, use Facter by running:

$ facter ec2_metadata.local-hostname


Or retrieve the EC2 instance's metadata by running:

$ curl


To access the PE console from outside EC2, use the Puppet master's public EC2 hostname:

$ facter ec2_metadata.public-hostname


$ curl


Then use your web browser to connect to https://ec2-… See the certificates and DNS configuration section for more information about EC2 hostnames and the default DNS configuration.

Puppet agent run won't work when initiated by a non-root user

An agent run initiated by puppetadmin or any other non-root user will fail when attempting to access certificates, packages, and services.

Always start manual Puppet agent runs with super-user privileges:

sudo /usr/local/bin/puppet agent -t

Other issues

Refer to PE documentation when troubleshooting any of the following Puppet or PE features.

  • Connections

  • Code Manager

  • Databases

  • Puppet core

  • MCollective

  • Windows

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.