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.
For help with Puppet-specific terms and language, visit the glossary
For a complete guide to the Puppet language, visit the reference manual
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.
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.
resource_type service could be used to load arbitrary Ruby files if auth_conf was edited to allow the behavior.
A vulnerability in Ruby’s SSL client could allow an attacker to spoof SSL servers via a valid, trusted certificate.
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.
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.
The Puppet Module Tool (PMT) incorrectly transferred a module’s original permissions.
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.
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.
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.
PE’s password reset page did not require the user to re-authenticate, allowing an attacker to potentially gain access to sensitive transactions.
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.
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.
A vulnerability in the PE console’s handling of database password could allow an attacker to access the password in clear text.
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.
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.
Removal of “File Search”
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
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.
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
On Windows systems, puppet agent runs started locally from the command line require either the
--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.
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
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:
/etc/puppetlabs/httpd/conf.d/puppetdashboard.conf, edit the
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 127.0.1.1. 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-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
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: “<node.name> 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:
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
Due to an upstream bug in Apache, the
pe-httpd service on the puppet master must be restarted after revoking any node’s certificate.
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
$ sudo gem install ronn