Installing PE

To install Puppet Enterprise (PE), you must first set up a standard installation. From there, you can scale up to the large or extra-large installation as your infrastructure grows, or customize your configuration as needed.

A standard PE installation consists of the following components installed on a single node:

The primary server: The central hub of activity. It is where Puppet code is compiled to create agent catalogs and where SSL certificates are verified and signed.
The console: The graphical web user interface. It has configuration and reporting tools.
PuppetDB: The data store for data generated throughout your Puppet infrastructure.

Important: The primary server can only run on a *nix machine. However, Windows machines can be Puppet agents, and you can manage them with your *nix primary server. Furthermore, you can operate your *nix primary server remotely from a Windows machine. To do this, before you install PE on your *nix primary server, you must configure an SSH client (such as PuTTY) with the hostname or IP address and port of the *nix machine that you'll use as your primary server. When you open an SSH session to install PE on the *nix primary server, log in as root or use sudo.

To install a FIPS-enabled PE primary server, install the appropriate FIPS-enabled PE tarball (such as puppet-enterprise-2021.6.0-redhatfips-7-x86_64.tar) on a third-party Supported operating system with FIPS mode enabled. The node must be configured with sufficient available entropy for the installation process to succeed.

Verify the installation package

These steps are only required if your organization requires you to verify authenticity before installing packages. These steps explain how to use GnuPG (GPG) to verify the PE installation tarball.

Before you begin

You must have GnuPG (GPG) installed to be able to sign for the release key. GPG is an open source program you can use to safely encrypt and sign digital communications. You can download GPG from the GnuPG website or use your package management system to install it by running something like: yum install gnupg

Download the tarball appropriate to your operating system and architecture.

Tip: To download packages from the command line, run wget --content-disposition <URL> or curl -JLO <URL>, using the URL for the tarball you want to download.
To import the Puppet public key, run:
```
uri='https://downloads.puppet.com/puppet-gpg-signing-key-20250406.pub'

curl "$uri" | gpg --import
```
Tip: For general information about forming curl commands, go to Using example commands.
To print the key fingerprint, run:
```
gpg --fingerprint 0x4528B6CD9E61EF26
```
This command returns the primary key fingerprint. For example:
```
D681 1ED3 ADEE B844 1AF5 AA8F 4528 B6CD 9E61 EF26
```
Download the GPG SIGNATURE .asc file corresponding to your PE tarball. You can find links to these files on the PE Download page.

To verify the installation package release signature, run:

gpg --verify puppet-enterprise-<VERSION>-<PLATFORM>.tar.gz.asc

Results

The gpg --verify command returns something similar to:

gpg: Signature made <DATE_AND_TIME>
gpg: using RSA key <KEY_ID>
gpg: Good signature from "Puppet, Inc. Release Key (Puppet, Inc. Release Key) <release@puppet.com>"

Tip:

If you receive a warning that a valid key path couldn't be found, this means you don't have a trusted path to one of the signatures on the release key.

If you receive a warning that the key is not certified with a trusted signature, this means you haven't told GPG to trust the imported key. Refer to the GPG documentation for more information.

What to do next

If you received the Good signature message, you can proceed to Install PE.

Install PE

The Puppet Enterprise (PE) installer uses default settings to install PE infrastructure components on a single node. After installing, you can scale or customize your installation as needed.

Before you begin

Review the Hardware requirements for standard installations to make sure your system capacity can handle the standard PE installation.

Log in as root on your target primary server. If you're installing on a system that doesn't allow root login, you must use sudo su - to complete these steps.

Download the tarball appropriate to your operating system and architecture.

Tip: To download packages from the command line, run wget --content-disposition <URL> or curl -JLO <URL>, using the URL for the tarball you want to download.
To unpack the installation tarball, run:
```
tar -xf <TARBALL_FILENAME>
```
From the installer directory, run ./puppet-enterprise-installer and follow the CLI instructions to complete the installation.
Optional: Restart the shell to use client tool commands.

What to do next

After completing the standard installation, you can scale or customize your installation, if needed. For information and requirements for large and extra-large installations, go to Supported architectures and System requirements. You can use Configuration parameters and the pe.conf file to customize your installation.

Configuration parameters and the `pe.conf` file

A pe.conf file is a HOCON formatted file that declares parameters and values used to install, upgrade, or configure Puppet Enterprise (PE). A default pe.conf file is available in the conf.d directory in the installer tarball.

Tip: You can use a custom pe.conf file when installing PE by running:

./puppet-enterprise-installer -c
               <PATH_TO_pe.conf>

The following table lists the value types you can use in the pe.conf file, along with examples of each type:


Type	Parameter-value format example
FQDN	`"puppet_enterprise::puppet_master_host": "primary.example.com"`
String	`"console_admin_password": "mypassword"`
Array	`[ "puppet", "puppetlb-01.example.com" ]`
Boolean	`"puppet_enterprise::profile::orchestrator::run_service": true` Restriction: The only valid Boolean values are `true` and `false`. These are not case sensitive, and these are the only values that don't use quotation marks. Don't use `Yes (y)`, `No (n)`, `1`, or `0` for Booleans.
JSON hash	`"puppet_enterprise::profile::orchestrator::java_args": {"Xmx": "256m", "Xms": "256m"}`
Integer	`"puppet_enterprise::profile::console::rbac_session_timeout": "60"`

Important: With the exception of Booleans, always use double quotes (") around parameter values.

Installation parameters

These parameters must be present in the pe.conf file to install Puppet Enterprise (PE).

puppet_enterprise::puppet_master_host: Specify the FQDN of the node hosting your PE primary server, such as primary.example.com.; Default: %{::trusted.certname}; Tip: To simplify installation, keep the default value and then provide a console administrator password after you run the installer.

Database configuration parameters

These parameters and values are supplied for Puppet Enterprise (PE) databases.

CAUTION: Don't change these parameters. This list is provided only for reference purposes.

puppet_enterprise::activity_database_name: The activity database name.; Default: pe-activity
puppet_enterprise::activity_database_read_user: An activity database user that can perform only read functions.; Default: pe-activity-read
puppet_enterprise::activity_database_write_user: An cctivity database user that can perform only read and write functions.; Default: pe-activity-write
puppet_enterprise::activity_database_super_user: The activity database superuser.; Default: pe-activity
puppet_enterprise::activity_service_migration_db_user: An activity service database user used for migrations.; Default: pe-activity
puppet_enterprise::activity_service_regular_db_user: An activity service database user used for normal operations.; Default: pe-activity-write
puppet_enterprise::classifier_database_name: The classifier database name.; Default: pe-classifier
puppet_enterprise::classifier_database_read_user: A classifier database user that can perform only read functions.; Default: pe-classifier-read
puppet_enterprise::classifier_database_write_user: A classifier database user that can perform only read and write functions.; Default: pe-classifier-write
puppet_enterprise::classifier_database_super_user: The classifier database superuser.; pe-classifier
puppet_enterprise::classifier_service_migration_db_user: A classifier service user used for migrations.; Default: pe-classifier
puppet_enterprise::classifier_service_regular_db_user: A classifier service user used for normal operations.; Default: pe-classifier-write
puppet_enterprise::orchestrator_database_name: The orchestrator database name.; Default: pe-orchestrator
puppet_enterprise::orchestrator_database_read_user: An orchestrator database user that can perform only read functions.; Default: pe-orchestrator-read
puppet_enterprise::orchestrator_database_write_user: An orchestrator database user that can perform only read and write functions.; Default: pe-orchestrator-write
puppet_enterprise::orchestrator_database_super_user: The orchestrator database superuser.; Default: pe-orchestrator
puppet_enterprise::orchestrator_service_migration_db_user: An orchestrator service user used for migrations.; Default: pe-orchestrator
puppet_enterprise::orchestrator_service_regular_db_user: An orchestrator service user used for normal operations.; Default: pe-orchestrator-write
puppet_enterprise::puppetdb_database_name: The PuppetDB database name.; Default: pe-puppetdb
puppet_enterprise::rbac_database_name: The role-based access control (RBAC) database name.; Default: pe-rbac
puppet_enterprise::rbac_database_read_user: An RBAC database user that can perform only read functions.; Default: pe-rbac-read
puppet_enterprise::rbac_database_write_user: An RBAC database user that can perform only read and write functions.; Default: pe-rbac-write
puppet_enterprise::rbac_database_super_user: The RBAC database superuser.; Default: pe-rbac
puppet_enterprise::rbac_service_migration_db_user: An RBAC service user used for migrations.; pe-rbac
puppet_enterprise::rbac_service_regular_db_user: An RBAC service user used for normal operations.; Default: pe-rbac-write

External PostgreSQL parameters

These parameters are required to install an external PostgreSQL instance. If necessary, you can add password parameters to standard installations.

puppet_enterprise::database_host: The agent certname of the node hosting the database component.; Important: Don't use an alt name for the database_host value.
puppet_enterprise::database_port: The port that the database is running on.; Default: 5432
puppet_enterprise::database_ssl: A Boolean indicating whether SSL authentication is used.; Default: true; Important: Don't use SSL security for unmanaged PostgreSQL installations. Make sure you set database_ssl to false.
puppet_enterprise::database_cert_auth: A Boolean indicating whether certificate authentication is used.; Default: true; Important: Don't use SSL security for unmanaged PostgreSQL installations. Make sure you set database_cert_auth to false.
puppet_enterprise::puppetdb_database_password: Specify a password, as a string, for the PuppetDB database user.; For example: mypassword
puppet_enterprise::classifier_database_password: Specify a password, as a string, for the classifier database user.; For example: mypassword
puppet_enterprise::classifier_service_regular_db_user: A database user the classifier service can use for normal operations.; Default: pe-classifier
puppet_enterprise::classifier_service_migration_db_user: A database user the classifier service can use for migrations.; Default: pe-classifier
puppet_enterprise::activity_database_password: Specify a password, as a string, for the activity database user.; For example: mypassword
puppet_enterprise::activity_service_regular_db_user: A database user the activity service can use for normal operations.; Default: pe-activity
puppet_enterprise::activity_service_migration_db_user: A database user the activity service can use for migrations.; Default: pe-activity
puppet_enterprise::rbac_database_password: Specify a password, as a string, for the RBAC database user.; For example: mypassword
puppet_enterprise::rbac_service_regular_db_user: A database user the RBAC service can use for normal operations.; Default: pe-rbac
puppet_enterprise::rbac_service_migration_db_user: A database user the RBAC service can use for migrations.; Default: pe-rbac
puppet_enterprise::orchestrator_database_password: Specify a password, as a string, for the orchestrator database user.; For example: mypassword
puppet_enterprise::orchestrator_service_regular_db_user: A database user the orchestrator service can use for normal operations.; Default: pe-orchestrator
puppet_enterprise::orchestrator_service_migration_db_user: A database user the orchestrator service can use for migrations.; Default: pe-orchestrator

Primary server parameters

Use these parameters to configure and tune the primary server.

pe_install::puppet_master_dnsaltnames: An array of strings representing DNS altnames to add to the primary server's SSL certificate.; Default: ["puppet"]
pe_install::install::classification::pe_node_group_environment: A string indicating the environment that infrastructure nodes are running in.; Specify this parameter if you moved your primary server and other infrastructure nodes from the default production environment after install. With non-default environments, this setting ensures that your configuration settings are backed up.; Default: production
puppet_enterprise::ip_version: Accepts either 4 or 6 to specify a preference for IPv4 or IPv6, but this does not restrict the non-preferred option.; The default is 4 (prefer IPv4). You can set it to 6 if you prefer IPv6.
puppet_enterprise::ipv6_only: You can set this to true to force NGINX to listen only on IPv6.; The default is false, which allows both IPv4 and IPv6.
puppet_enterprise::master::recover_configuration::pe_environment: A string indicating the environment that infrastructure nodes are running in.; Specify this parameter if you moved your primary server and other infrastructure nodes from the default production environment after installation. With non-default environments, this setting ensures that your configuration settings are backed up.; Default: production
puppet_enterprise::profile::certificate_authority: An array of additional certificates to be allowed access to the /certificate_statusAPI endpoint. This list is added to the base certificate list.
puppet_enterprise::profile::master::check_for_updates: A Boolean indicating whether to check for updates when the pe-puppetserver service restarts.; The default is true (check for updates). You can set it to false to not check for updates.
puppet_enterprise::profile::master::code_manager_auto_configure: Set to true to automatically configure the Code Manager service; otherwise, set it to false.
puppet_enterprise::profile::master::r10k_remote: A string representing the Git URL to be passed to the r10k.yaml file, for example: git@your.git.server.com:puppet/control.git; The URL can be any URL supported by r10k and Git.; This parameter is only required if you want r10k configured when you install PE, and you must also specify puppet_enterprise::profile::master::r10k_private_key.
puppet_enterprise::profile::master::r10k_private_key: A string representing the local file path on the primary server where the SSH private key can be found and used by r10k, for example: /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519; This parameter is only required if you want r10k configured when you install PE, and you must also specify puppet_enterprise::profile::master::r10k_remote.

Console and console-services parameters

Use these parameters to customize the behavior of the console and console-services in the PE Console node group. Parameters that begin with puppet_enterprise::profile can be modified from the console itself.

puppet_enterprise::profile::console::classifier_synchronization_period: Integer representing, in seconds, the classifier synchronization period, which controls how long it takes the node classifier to retrieve classes from the primary server.; Default: 600 (seconds).
puppet_enterprise::profile::console::rbac_failed_attempts_lockout: Integer specifying how many failed login attempts are allowed on an account before that account is revoked.; Default: 10 (attempts).
puppet_enterprise::profile::console::rbac_password_reset_expiration: Integer representing, in hours, how long a user's generated token is valid for. An administrator generates this token for a user so that they can reset their password.; Default: 24 (hours).
puppet_enterprise::profile::console::rbac_session_timeout: Integer representing, in minutes, how long a user's session can last. The session length is the same for node classification, RBAC, and the console.; Default: 60 (minutes).
puppet_enterprise::profile::console::session_maximum_lifetime: Integer representing the maximum allowable period that a console session can be valid. To not expire before the maximum token lifetime, set to '0'.; Supported units are "s" (seconds), "m" (minutes), "h" (hours), "d" (days), "y" (years). Units are specified as a single letter following an integer, for example "1d"(1 day). If no units are specified, the integer is treated as seconds.
puppet_enterprise::profile::console::rbac_token_auth_lifetime: A value representing the default authentication lifetime for a token. It cannot exceed the rbac_token_maximum_lifetime. This is represented as a numeric value followed by "y" (years), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds). The default is "1h".
puppet_enterprise::profile::console::rbac_token_maximum_lifetime: A value representing the maximum allowable lifetime for all tokens. This is represented as a numeric value followed by "y" (years), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds). The default is "10y".
puppet_enterprise::profile::console::console_ssl_listen_port: Integer representing the port that the console is available on.; Default: 443
puppet_enterprise::profile::console::ssl_listen_address: Nginx listen address for the console.; Default: "0.0.0.0"
puppet_enterprise::profile::console::classifier_prune_threshold: Integer representing the number of days to wait before pruning the size of the classifier database. If you set the value to 0, the node classifier service is never pruned.
puppet_enterprise::profile::console::classifier_node_check_in_storage: true to store an explanation of how nodes match each group they're classified into, or false.; Default: false
puppet_enterprise::profile::console::display_local_time: "true" to display timestamps in local time, with hover text showing UTC time, or "false" to show timestamps in UTC time.; Default: "false"
puppet_enterprise::profile::console::disclaimer_content_path: Specifies the location of the disclaimer.txt file, which contains the disclaimer content that appears on the console login page.; Default: /etc/puppetlabs/console-services

Modify these configuration parameters in Hiera or pe.conf, not the console:

puppet_enterprise::api_port: SSL port that the node classifier is served on.; Default: 4433
puppet_enterprise::console_services::no_longer_reporting_cutoff: Length of time, in seconds, before a node is considered unresponsive.; Default: 3600 (seconds)

console_admin_password: The password to log into the console, for example "myconsolepassword".; Default: Specified during installation.

Orchestrator and orchestration services parameters

Use these parameters to configure and tune the orchestrator and orchestration services.

puppet_enterprise::profile::agent::pxp_enabled: true to enable the Puppet Execution Protocol service, which is required to use the orchestrator and run Puppet from the console, or false.; Default: true
puppet_enterprise::profile::bolt_server::concurrency: An integer that determines the maximum number of concurrent requests orchestrator can make to bolt-server.
CAUTION: Do not set a concurrency limit that is higher than the bolt-server limit. This can cause timeouts that lead to failed task runs.; Default: The default value is set to the current value stored for bolt-server.
puppet_enterprise::profile::orchestrator::global_concurrent_compiles: Integer representing how many concurrent compile requests can be outstanding to the primary server, across all orchestrator jobs.; Default: 8 requests
puppet_enterprise::profile::orchestrator::job_prune_threshold: Integer representing the number of days to keep job reports. After this threshold, job reports are removed.; Default: 30 days
puppet_enterprise::profile::orchestrator::pcp_timeout: Integer representing the length of time, in seconds, before timeout when agents attempt to connect to the Puppet Communications Protocol broker in a Puppet run triggered by the orchestrator.; Default: 30 seconds
puppet_enterprise::profile::orchestrator::run_service: true to enable orchestration services, or false.; Default: true
puppet_enterprise::profile::orchestrator::task_concurrency: Integer representing the number of tasks that can run at the same time.; Default: 250 tasks
puppet_enterprise::pxp_agent::ping_interval: Integer representing the interval, in seconds, between agents' attempts to ping Puppet Communications Protocol brokers.; Default: 120 seconds
puppet_enterprise::pxp_agent::pxp_logfile: String representing the path to the Puppet Execution Protocol agent log file. Change as needed.; Default: /var/log/puppetlabs/pxp-agent/pxp-agent.log (*nix) or C:/ProgramData/PuppetLabs/pxp-agent/var/log/pxp-agent.log (Windows)

PuppetDB parameters

Use these parameters to configure and tune PuppetDB.

puppet_enterprise::puppetdb::command_processing_threads: Integer representing how many command processing threads PuppetDB uses to sort incoming data. Each thread can process a single command at a time.; Default: Half the number of cores in your system, for example 8.
puppet_enterprise::profile::master::puppetdb_report_processor_ensure: present to generate agent run reports and submit them to PuppetDB, or absent; Default: present
puppet_enterprise::puppetdb_port: Integer in brackets representing the SSL port that PuppetDB listens on.; Default: 8081
puppet_enterprise::profile::puppetdb::node_purge_ttl: “Time-to-live” value before deactivated or expired nodes are deleted, along with all facts, catalogs, and reports for the node. For example, a value of "14d" sets the time-to-live to 14 days.; Default: "14d"

Java parameters

Use these parameters to configure and tune Java.

puppet_enterprise::profile::master::java_args: JVM (Java Virtual Machine) memory, specified as a JSON hash, that is allocated to the Puppet Server service, for example {"Xmx": "4096m", "Xms": "4096m"}.
puppet_enterprise::profile::puppetdb::java_args: JVM memory, specified as a JSON hash, that is allocated to the PuppetDB service, for example {"Xmx": "512m", "Xms": "512m"}.
puppet_enterprise::profile::console::java_args: JVM memory, specified as a JSON hash, that is allocated to console services, for example {"Xmx": "512m", "Xms": "512m"}.
puppet_enterprise::profile::orchestrator::java_args: JVM memory, set as a JSON hash, that is allocated to orchestration services, for example, {"Xmx": "256m", "Xms": "256m"}.