User's Guide Appendix

A newer version is available; see the version menu above for details.

This page contains additional miscellaneous information about Puppet Enterprise (PE) 3.0.

Puppet Terminology

For help with Puppet-specific terms and language, visit the glossary

For a complete guide to the Puppet language, visit the reference manual

Release Notes

PE 3.0.1 (8/15/2013)

Complete Upgrade Support

The PE Installer/Upgrader script is now fully functional and can upgrade all PE roles: agent, master, console, cloud provisioner, and database support.

SLES Support

PE 3.0.1 now fully supports all PE roles on nodes running SLES 11 SP1 or higher.

Improvements to Cloud Provisioner

Integration with PE has been improved and installation of the cloud provisioner role now properly includes all dependencies. In addition, issues with puppet node_vmware list have been addressed and the command should now correctly list directory structures.

Security Fixes

CVE-2013-4761 resource_type Remote Code Execution Vulnerability.

The resource_type service could be used to load arbitrary Ruby files if auth_conf was edited to allow the behavior.

CVE-2013-4073 Ruby SSL Vulnerability.

A vulnerability in Ruby’s SSL client could allow an attacker to spoof SSL servers via a valid, trusted certificate.

CVE-2013-4762 Logout Link Did Not Destroy Server Session.

The “logout” link in Puppet Enterprise did not invalidate the old session, potentially allowing an attacker to hijack a user’s session and gain access to sensitive data.

CVE-2013-4955 Phishing Through URL Redirection Vulnerability.

The PE login page could be manipulated into redirecting to a third-party website, allowing an attacker to redirect to a phishing site under their control.

CVE-2013-4956 Puppet Module Permissions Vulnerability.

The Puppet Module Tool (PMT) incorrectly transferred a module’s original permissions.

CVE-2013-4958 Lack of Session Timeout.

A lack of session timeout in Puppet Enterprise meant that an attacker could seize a machine and perform any actions the user was authorized to perform.

CVE-2013-4959 Sensitive Data Browser Caching.

Pages in PE’s console that display sensitive data were caching that data incorrectly. This meant an attacker with access to the user’s machine could access the data in Temporary Internet Files.

CVE-2013-4961 Software Version Numbers Were Revealed.

HTTP response headers generated by the web server revealed software version numbers for Apache and Phusion Passenger. These could be used to craft attacks based on published vulnerabilities.

CVE-2013-4962 Lack of Re-authentication for Sensitive Transactions.

PE’s password reset page did not require the user to re-authenticate, allowing an attacker to potentially gain access to sensitive transactions.

CVE-2013-4963 Cross-Site Request Forgery Vulnerability.

Several pages in the PE console were vulnerable to CSRF, which could allow an attacker to manipulate a user’s browser in a malicious manner.

CVE-2013-4964 Session Cookies Not Set With Secure Flag.

The PE console uses a cookie to control access to the application. An incorrectly set security flag could allow an attacker to hijack a user’s session and access any functions or services available to the user.

CVE-2013-4967 External Node Classifiers Allowed Clear Text Database Password Query.

A vulnerability in the PE console’s handling of database password could allow an attacker to access the password in clear text.

CVE-2013-4968 Site Lacked Clickjacking Defense.

The PE console was vulnerable to UI redress attack (aka, “clickjacking”), which could allow an attacker to redirect the user to another page or application and possibly trick them into entering sensitive data. Further, live management was vulnerable to cross-site scripting (XSS), allowing an attacker to potentially inject malicious scripts that could be used to access sensitive data.

PE 3.0.0

Delayed Support for Complete Upgrades and SLES

  • Full functionality for upgrades is not yet complete in 3.0. Upgrading is not yet supported for master, console and database roles, but is fully supported for agents. Visit the upgrading page for complete instructions on how to migrate a 2.8 deployment to PE 3.0 now. Full upgrade support will be included in the next release of PE 3.0, no later than August 15, 2013.
  • Support for nodes running the SLES operating system is not yet completed. It will be included in the next release of PE 3.0, no later than August 15, 2013.

Package and Component Upgrades

Many of the constituent components of Puppet Enterprise have been upgraded. Namely:

  • Ruby 1.9.3
  • Augeas 1.0.0
  • Puppet 3.2.2
  • Facter 1.7.1
  • Hiera 1.2.1
  • MCollective 2.2.4
  • Passenger 4.0
  • Dashboard 2.0
  • Java 1.7
  • PostgreSQL 9.2.4

Removal of Cloning

The live management cloning tool is deprecated and has been removed in PE 3.0. We are continuing to improve resource inspection and interactive orchestration commands in the console. In general, we recommend managing resources with Puppet manifests instead of one-off commands.

If you are using cloning, you can achieve a similar workflow by using puppet resource or the puppetral plugin’s find action to learn the details of resources on individual host. Then, you can use that info to write or append to a manifest.

Removal of Compliance

The compliance workflow tools, including File Search, are deprecated, and have been removed in Puppet Enterprise 3.0. We are continuing to invest in flexible ways to help you predict, detect, and control change, and our next-generation tools will not use manually maintained baselines as a foundation.

If you are using the compliance workflow tools today, you can achieve a similar workflow by using Puppet’s noop features to detect changes. We’ve created an example page that shows this alternate workflow in greater detail.

While the compliance app has been removed, none of the associated data will be removed when upgrading the console and master. To remove all database tables used by the compliance app, run the following rake task on the master node: /opt/puppet/bin/rake -s -f /opt/puppet/share/puppet-dashboard/Rakefile db:drop_compliance_tables RAILS_ENV=production.

Related to the removal of compliance, the File Search section of the console has been removed. This section was able to display file contents when given an MD5 checksum, but was no longer relevant once compliance was removed.

Puppet Agent Service Rename

Previously, the puppet agent service was known by several names, depending on platform (e.g. puppetagent on Solaris, pe-puppet-agent on Debian/Ubuntu, etc.). As of PE 3, it is called pe-puppet on all platforms.

Change to Orchestration Engine’s Authentication Backend

In previous versions, the orchestration engine (MCollective) used either the psk or aespe security plugin. As of PE 3, it uses the more secure and reliable ssl security plugin. If you have integrated external applications with the orchestration engine, you will need to re-configure their security credentials.

Change to Built-in Orchestration Actions

The output format and available actions of the puppetral orchestration plugin have changed — the create action has been removed, and the output format is now an array of hashes. If you have built applications that integrate with the puppetral plugin, you’ll need to update them.

Known Issues

As we discover them, this page will be updated with known issues in Puppet Enterprise 3.0 and earlier. Fixed issues will be removed from this list and noted above in the release notes. If you find new problems yourself, please file bugs in Puppet here and bugs specific to Puppet Enterprise here.

To find out which of these issues may affect you, run /opt/puppet/bin/puppet --version, the output of which will look something like 3.2.2 (Puppet Enterprise 3.0). To upgrade to a newer version of Puppet Enterprise, see the chapter on upgrading.

The following issues affect the currently shipped version of PE and all prior releases in the 2.x.x series, unless otherwise stated.

Puppet Agent on Windows Requires --onetime

On Windows systems, puppet agent runs started locally from the command line require either the --onetime or --test option to be set. This is due to Puppet bug PUP-1275.

This issue only affects PE 3.0 and later.

PostgreSQL Buffer Memory Issue Can Cause PE Install to Fail on Machines with Large Amounts of RAM

In some cases, when installing PE on machines with large amounts of RAM, the PostgreSQL database will use more shared buffer memory than is available and will not be able to start. This will prevent PE from installing correctly. For more information and a suggested workaround, refer to Troubleshooting the Console and Database.

MCollective server.cfg File May Have Wrong Owner Permissions on Windows Agents

In some cases, server.cfg, managed by the pe-mcollective module, may have file owner permissions set to “Administrator” instead of “Administrators”, which will prevent MCollective from functioning correctly. If this happens, you will need to manually change the file permissions for this file.

On Windows 2008 and 7 agents, you can locate this file at C:\PROGRAMDATA\PuppetLabs\mcollective\etc\server.cfg.

On Windows 2003 agents, you can locate this file at C:\Documents and Settings\All Users\My Application Data\mcollective\etc\server.cfg.

BEAST Attack Mitigation

A known weakness in Apache HTTPD leaves it vulnerable to a man-in-the-middle attack known as the BEAST (Browser Exploit Against SSL/TLS) attack. The vulnerability exists because Apache HTTPD uses a FIPS compliant cipher suite that can be cracked via a brute force attack that can discover the decryption key. If FIPS compliance is not required for your infrastructure, we recommend you mitigate vulnerability to the BEAST attack by using a cipher suite that includes stronger ciphers. This can be done as follows:

In /etc/puppetlabs/httpd/conf.d/puppetdashboard.conf, edit the SSLCipherSuite and SSLProtocol options to:

SSLCipherSuite ALL:!ADH:+RC4+RSA:+HIGH:+AES+256:+CBC3:-LOW:-SSLv2:-EXP
SSLProtocol ALL -SSLv2

This will set the order of ciphers to:

KRB5-RC4-MD5            SSLv3 Kx=KRB5     Au=KRB5 Enc=RC4(128)  Mac=MD5
KRB5-RC4-SHA            SSLv3 Kx=KRB5     Au=KRB5 Enc=RC4(128)  Mac=SHA1
RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
RC4-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5
DHE-RSA-AES256-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(256)  Mac=SHA1
DHE-DSS-AES256-SHA      SSLv3 Kx=DH       Au=DSS  Enc=AES(256)  Mac=SHA1
AES256-SHA              SSLv3 Kx=RSA      Au=RSA  Enc=AES(256)  Mac=SHA1
DHE-RSA-AES128-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(128)  Mac=SHA1
DHE-DSS-AES128-SHA      SSLv3 Kx=DH       Au=DSS  Enc=AES(128)  Mac=SHA1
AES128-SHA              SSLv3 Kx=RSA      Au=RSA  Enc=AES(128)  Mac=SHA1
KRB5-DES-CBC3-MD5       SSLv3 Kx=KRB5     Au=KRB5 Enc=3DES(168) Mac=MD5
KRB5-DES-CBC3-SHA       SSLv3 Kx=KRB5     Au=KRB5 Enc=3DES(168) Mac=SHA1
EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
EDH-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
DES-CBC3-SHA            SSLv3 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=SHA1

Note that unless your system contains OpenSSL v1.0.1d (the version that correctly supports TLS1.1 1and 1.2), prioritizing RC4 may leave you vulnerable to other types of attacks.

PostgreSQL Module Conflict

For PE versions 3.0.x, the Puppet Labs PostgreSQL module (included in the PE tarball) is used to manage PuppetDB. However, using your own PostgreSQL module in addition to the Puppet Labs PostgreSQL module will impact the operation of PuppetDB. This issue will be fixed in PE 3.2, but you can also contact the PE customer support portal to discuss potential workarounds.

db:raw:optimize Rake Task does not Work in PE 3.0.0

To re-index and vacuum the console database, you can use the following PostgreSQL commands:

su - pe-postgres -s /bin/bash -c "reindexdb console"; su - pe-postgres -s /bin/bash -c "vacuumdb --full --verbose console"

The default mode of the db:raw:optimize rake task runs re-index and vacuum in the same command. This task is fixed in PE 3.0.1.

Installation of Database Support Role Fails During PE Install if PostgreSQL is Already Installed

Installation of the Database Support role can fail if your system already has PostgreSQL client tools installed. This is fixed in PE 3.0.1 and later. For PE 3.0 users, the workaround is to uninstall PE, remove the previously installed PostgreSQL packages and configs, and then reinstall PE.

PE Install Fails if Port 8080 or 8081 is in Use

PuppetDB requires access to port 8080 and 8081. The installer will check to make sure these ports are available and if they are not, the install will fail with an error message. To fix this, either disable the service currently using 8080/8081 or install the database role on a different node that has port 8080 available. A slightly more complicated workaround is to temporaily disable the service running on 8080/8081, complete the PE installation and then add a class parameter for puppetDB that makes it use a different, available port. Note that you will still need to temporarily disable the service using the ports even if you implement this class parameter workaround.

Puppet Code Issues with UTF-8 Encoding

PE 3 uses an updated version of Ruby, 1.9 that is much stricter about character encodings than the version of Ruby used in PE 2.8. As a result, puppet code that contains UTF-8 characters such as accents or other non-ASCII characters can fail or act unpredictably. There are a number of ways UTF-8 characters can make it into puppet code, including, but not limited to, downloading a Forge module where some piece of metadata (e.g., author’s name) contains UTF-8 characters. With apologies to our international customers, the current solution is to strictly limit puppet code to the ASCII character set only, including any code comments or metadata. Puppet Labs is working on cleaning up character encoding issues in Puppet and the various libraries it interfaces with.

Readline Version Issues on AIX Agents

  • As with PE 2.8.2, on AIX 5.3, puppet agents depend on readline-4-3.2 being installed. You can check the installed version of readline by running rpm -q readline. If you need to install it, you can download it from IBM. Install it before installing the puppet agent.

  • On AIX 6.1 and 7.1, the default version of readline, 4-3.2, is insufficient. You need to replace it before upgrading or installing by running

       rpm -e --nodeps readline
      rpm -Uvh readline-6.1-1.aix6.1.ppc.rpm

If you see an error message after running this, you can disregard it. Readline-6 should be successfully installed and you can proceed with the installation or upgrade (you can verify the installation with rpm -q readline).

Debian/Ubuntu Local Hostname Issue

On some versions of Debian/Ubuntu, the default /etc/hosts file contains an entry for the machine’s hostname with a local IP address of This can cause issues for PuppetDB and PostgreSQL, because binding a service to the hostname will cause it to resolve to the local-only IP address rather than its public IP. As a result, nodes (including the console) will fail to connect to PuppetDB and PostgreSQL.

To fix this, add an entry to /etc/hosts that resolves the machine’s FQDN to its public IP address. This should be done prior to installing PE. However, if PE has already been installed, restarting the pe-puppetdb and pe-postgresql services after adding the entry to the hosts file should fix things.

Console_auth Fails After PostgreSQL Restart

RubyCAS server, the component which provides console log-in services will not automatically reconnect if it loses connection to its database, which can result in a 500 Internal Server Error when attempting to log in or out. The issue can be resolved by restarting Apache on the console’s node with service pe-httpd restart.

Inconsistent Counts When Comparing Service Resources in Live Management

In the Browse Resources tab, comparing a service across a mixture of RedHat-based and Debian-based nodes will give different numbers in the list view and the detail view.

Bad Data in Facter’s architecture Fact

On AIX agents, a bug causes facter to return the system’s model number (e.g., IBM 3271) instead of the processor’s architecture (e.g. Power6). There is no known workaround.

Augeas File Access Issue

On AIX agents, the Augeas lens is unable to access or modify etc/services. There is no known workaround.

After Upgrading, Nodes Report a “Not a PE Agent” Error

When doing the first puppet run after upgrading using the “upgrader” script included in PE tarballs, agents are reporting an error: “<> is not a Puppet Enterprise agent.” This was caused by a bug in the upgrader that has since been fixed. If you downloaded a tarball prior to November 28, 2012, simply download the tarball again to get the fixed upgrader. If you prefer, you can download the latest upgrader module from the Forge. Alternatively, you can fix it by changing /etc/puppetlabs/facter/facts.d/is_pe.txt to contain: is_pe=true.

EC2/Dual-homed Systems Report Incorrect URIs for the Console.

During installation, the PE installer attempts to automatically determine the URI where the console can be reached. On EC2 (and likely all other dual-homed systems), the installer incorrectly selects the internal, non-routable URI. Instead, you should manually enter the correct, external facing URI of the system hosting the console.

Answer file required for some SMTP servers.d

Any SMTP server that requires authentication, TLS, or runs over any port other than 25 needs to be explicitly added to an answers file. See the advanced configuration page for details.

pe-httpd Must Be Restarted After Revoking Certificates

(Issue #8421)

Due to an upstream bug in Apache, the pe-httpd service on the puppet master must be restarted after revoking any node’s certificate.

After using puppet cert revoke or puppet cert clean to revoke a certificate, restart the service by running:

$ sudo /etc/init.d/pe-httpd restart

Dynamic Man Pages are Incorrectly Formatted

Man pages generated with the puppet man subcommand are not formatted as proper man pages, and are instead displayed as Markdown source text. This is a purely cosmetic issue, and the pages are still fully readable.

To improve the display of Puppet man pages, you can use your system gem command to install the ronn gem:

$ sudo gem install ronn

↑ Back to top