You can install PE using express install, which relies on defaults, text install, where you provide a pe.conf file with installation parameters, or using a guided web install. Any of these methods is appropriate for installing infrastructure components on your master.
Download and verify the installation package
PE is distributed in downloadable packages specific to supported operating system versions and architectures. Installation packages include the full installation tarball and a GPG signature (.asc) file used to verify authenticity.
You must have GnuPG installed.
Install using express install
Express installation relies on default settings to install PE, so you don't have to edit a pe.conf file before or during installation. At the end of the installation process, you're prompted to provide a console admininstrator password, which is the only user-required value.
You must restart the shell before you can use PE client tool subcommands.
Install using text install
When you run the installer in text mode, you provide a configuration file (pe.conf) to the installer. The pe.conf file contains values for the parameters needed for installation.
You must restart the shell before you can use PE client tool subcommands.
Text install options
When you run the installer in text mode, you can use the
-c option to specify the full path to
an existing pe.conf file. You can pair
these additional options with the -c
option.
| Option | Definition |
|---|---|
-D
| Display debugging information |
-q
| Run in quiet mode. The installation process isn't displayed. If errors occur during the installation, the command quits with an error message. |
-y
| Run automatically using the
pe.conf file at
/etc/puppetlabs/enterprise/conf.d/. If the file is not
present or is invalid, installation or upgrade fails. |
-V
| Display verbose debugging information. |
-h
| Display help information. |
force
| For upgrades only, bypass PostgreSQL migration
validation. This option must appear last, after the end-of-options
signifier (--), for
example sudo
./puppet-enterprise-installer -c pe.conf -- --force |
Install using web install
Web-based installation uses a web server to guide you through installation.
Review the Web install prerequisites.
Web install prerequisites
Review these prerequisites and tips before beginning a web-based installation.
-
If you've previously installed Puppet or Puppet Enterprise, make sure that the machine you're installing on is free of any artifacts left over from the previous installation.
-
Make sure that DNS is properly configured on the machines you're installing on.
-
All nodes must know their own hostnames, which you can achieve by properly configuring reverse DNS on your local DNS server, or by setting the hostname explicitly. Setting the hostname usually involves the
hostnamecommand and one or more configuration files, but the exact method varies by platform. -
All nodes must be able to reach each other by name, which you can achieve with a local DNS server, or by editing the
/etc/hostsfile on each node to point to the proper IP addresses.
-
-
You can run the installer from a machine that is part of your deployment or from a machine that is outside your deployment.
-
The machine you run the installer from must have the same operating system and architecture as your deployment.
-
The web-based installer does not support sudo configurations with
Defaults targetpworDefaults rootpw. Make sure your/etc/sudoersfile does not contain, or comment out, those lines. -
For Debian users, if you gave the root account a password during installation of Debian, sudo may not have been installed. In this case, you must either install as root, or install sudo on any nodes on which you want to install.
SSH prerequisites
SSH requirements very depending on your installation method.
- Choose Install on this server during installation.
- Have a properly configured SSH agent with agent forwarding enabled.
authorized_keys file for that user account on each infrastructure node, including the machine from which you're running the installer. This requirement applies to root or non-root users.
| Installation method | Requirements | Prerequisites |
|---|---|---|
| Root with a password | The installer requires the username and password for each infrastructure node. | Remote root SSH login must be enabled on each infrastructure node, including the node from which you're running the installer. |
| Non-root with a password | Sudo must be enabled for the non-root user on each infrastructure node. | |
| Root with an SSH key | The installer requires the username, private key path, and key passphrase (as needed) for each infrastructure node. |
|
| Non-root with an SSH key |
|
Web install options
Use this reference when providing values in the web-based installer.
| Setting | Value |
|---|---|
| Puppet master FQDN |
Fully qualified domain name of the server you're installing on. This FQDN is used as the name of the master certificate. This FQDN must be resolvable from the machine on which you're running the installer. To ensure you're using the proper FQDN for the master, run |
| DNS altnames | Comma-separated list of static, valid, DNS altnames so agents can trust the master. Make sure that this static list contains the DNS name or alias you’re be configuring your agents to contact. The default settings include puppet.
|
| SSH username | Username to use when connecting to the master. This user must either be root or have sudo access. The default value is root.
|
| SSH password | Password associated with the SSH username. This password is used only if the user requires a password for sudo access. |
| SSH key file path | Absolute path to the SSH key on the machine you're performing the installation from. This value is used if an SSH password is not specified. Defaults to the root SSH key path. |
| SSH key passphrase | Passphrase for the SSH key, if applicable. |
Configuration parameters and the pe.conf file
A pe.conf file is a HOCON formatted file that declares parameters and values needed to install, upgrade, and configure PE.
You can create or obtain a pe.conf file by:
- Using the example
pe.conffile provided in theconf.ddirectory in the installer tarball.Tip: In most cases, you can use the examplepe.conffile without making any changes. - Selecting the text-mode installation option when prompted by the installer. This option opens your default text editor with the example
pe.conffile, which you can modify as needed. Installation proceeds using thatpe.confafter you quit the editor. - Using the web-based installer to create a
pe.conffile. After you run the web-based installer, you can find the file at/etc/puppetlabs/enterprise/conf.d. You can also download the file by following the link provided on the confirmation page of the web-based installer.
The following are examples of valid paramater and value expressions:
| Type | Value |
|---|---|
| FQDNs |
"puppet_enterprise::puppet_master_host": "master.example.com"
|
| Strings |
"console_admin_password": "mypassword"
|
| Arrays |
[ "puppet", "puppetlb-01.example.com" ]
|
| Booleans |
"puppet_enterprise::profile::orchestrator::run_service": true
Valid Boolean values are Note: Don't use Yes (y), No (n), 1, or 0.
|
| JSON hashes |
"puppet_enterprise::profile::orchestrator::java_args": {"Xmx": "256m", "Xms": "256m"}
|
| Integer |
"puppet_enterprise::profile::console::rbac_session_timeout": "60"
|
Installation parameters
These parameters are required for installation.
%{::trusted.certname} for your master and provide a console administrator password after running the installer. | Parameter | Value | Default |
|---|---|---|
puppet_enterprise::puppet_master_host | The FQDN of the node hosting the master, for example | %{::trusted.certname} |
| The password to log into the console, for example | Specified during installation |
Database configuration parameters
These are the default parameters and values supplied for the PE databases.
| Parameter | Value | Default |
|---|---|---|
puppet_enterprise::activity_database_name | Name for the activity database. | pe-activity |
puppet_enterprise::activity_database_read_user | Activity database user that can perform only read functions. | pe-activity-read |
puppet_enterprise::activity_database_write_user | Activity database user that can perform only read and write functions. | pe-activity-write |
puppet_enterprise::activity_database_super_user | Activity database superuser. | pe-activity |
puppet_enterprise::activity_service_migration_db_user | Activity service database user used for migrations. | pe-activity |
puppet_enterprise::activity_service_regular_db_user | Activity service database user used for normal operations. | pe-activity-write |
puppet_enterprise::classifier_database_name | Name for the classifier database. | pe-classifier |
puppet_enterprise::classifier_database_read_user | Classifier database user that can perform only read functions. | pe-classifier-read |
puppet_enterprise::classifier_database_write_user | Classifier database user that can perform only read and write functions. | pe-classifier-write |
puppet_enterprise::classifier_database_super_user | Classifier database superuser. | pe-classifier |
puppet_enterprise::classifier_service_migration_db_user | Classifier service user used for migrations. | pe-classifier |
puppet_enterprise::classifier_service_regular_db_user | Classifier service user used for normal operations. | pe-classifier-write |
puppet_enterprise::orchestrator_database_name | Name for the orchestrator database. | pe-orchestrator |
puppet_enterprise::orchestrator_database_read_user | Orchestrator database user that can perform only read functions. | pe-orchestrator-read |
puppet_enterprise::orchestrator_database_write_user | Orchestrator database user that can perform only read and write functions. | pe-orchestrator-write |
puppet_enterprise::orchestrator_database_super_user | Orchestrator database superuser. | pe-orchestrator |
puppet_enterprise::orchestrator_service_migration_db_user | Orchestrator service user used for migrations. | pe-orchestrator |
puppet_enterprise::orchestrator_service_regular_db_user | Orchestrator service user used for normal operations. | pe-orchestrator-write |
puppet_enterprise::puppetdb_database_name | Name for the PuppetDB database. | pe-puppetdb |
puppet_enterprise::puppetdb_database_user | PuppetDB database user. | pe-puppetdb |
puppet_enterprise::rbac_database_name | Name for the RBAC database. | pe-rbac |
puppet_enterprise::rbac_database_read_user | RBAC database user that can perform only read functions. | pe-rbac-read |
puppet_enterprise::rbac_database_write_user | RBAC database user that can perform only read and write functions. | pe-rbac-write |
puppet_enterprise::rbac_database_super_user | RBAC database superuser. | pe-rbac |
puppet_enterprise::rbac_service_migration_db_user | RBAC service user used for migrations. | pe-rbac |
puppet_enterprise::rbac_service_regular_db_user | RBAC service user used for normal operations. | pe-rbac-write |
External PostgreSQL parameters
These parameters are required to install an external PostgreSQL instance. Password parameters can be added to standard installations if needed.
| Parameter | Value | Default |
|---|---|---|
puppet_enterprise::database_host | Agent certname of the node hosting the database component. Don't use an alt name for this value. | |
puppet_enterprise::database_port | The port that the database is running on. | 5432 |
puppet_enterprise::database_ssl | true or false. For unmanaged PostgreSQL installations don't use SSL security, set this parameter to false. | true |
puppet_enterprise::database_cert_auth | true or false. Important: For unmanaged PostgreSQL installations don't use SSL security, set this parameter to false. | true |
puppet_enterprise::puppetdb_database_password | Password for the PuppetDB database user. Must be a string, such as "mypassword". | |
puppet_enterprise::classifier_database_password | Password for the classifier database user. Must be a string, such as "mypassword". | |
puppet_enterprise::classifier_service_regular_db_user | Database user the classifier service uses for normal operations. | pe-classifier |
puppet_enterprise::classifier_service_migration_db_user | Database user the classifier service uses for migrations. | pe-classifier |
puppet_enterprise::activity_database_password | Password for the activity database user. Must be a string, such as "mypassword". | |
puppet_enterprise::activity_service_regular_db_user | Database user the activity service uses for normal operations. | "pe-activity" |
puppet_enterprise::activity_service_migration_db_user | Database user the activity service uses for migrations. | pe-activity" |
puppet_enterprise::rbac_database_password | Password for the RBAC database user. Must be a string, such as "mypassword". | |
puppet_enterprise::rbac_service_regular_db_user | Database user the RBAC service uses for normal operations. | "pe-rbac" |
puppet_enterprise::rbac_service_migration_db_user | Database user the RBAC service uses for migrations | "pe-rbac" |
puppet_enterprise::orchestrator_database_password | Password for the orchestrator database user. Must be a string, such as "mypassword". | |
puppet_enterprise::orchestrator_service_regular_db_user | Database user the orchestrator service uses for normal operations. | pe-orchestrator |
puppet_enterprise::orchestrator_service_migration_db_user | Database user the orchestrator service uses for migrations | "pe-orchestrator" |
Master parameters
Use these parameters to configure and tune the master.
| Parameter | Value | Default |
|---|---|---|
pe_install::puppet_master_dnsaltnames | An array of strings that represent the DNS altnames to be added to the SSL certificate generated for the master. | ["puppet"] |
puppet_enterprise::profile::certificate_authority | 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::code_manager_auto_configure | true to automatically configure the Code Manager service, or false. | |
puppet_enterprise::profile::master::r10k_remote | String that represents the Git URL to be passed to the r10k.yaml file, for example "[email protected]:puppet/control.git". The URL can be any URL that's supported by r10k and Git. This parameter is required only if you want r10k configured when PE is installed; it must be specified in conjunction with puppet_enterprise::profile::master::r10k_private_key. | |
puppet_enterprise::profile::master::r10k_private_key | String that represents the local file system path on the master where the SSH private key can be found and used by r10k, for example "/etc/puppetlabs/puppetserver/ssh/id-control_repo.rsa". This parameter is required only if you want r10k configured when PE is installed; it must be specified in conjunction with puppet_enterprise::profile::master::r10k_remote. | |
puppet_enterprise::profile::master::check_for_updates | true to check for updates whenever the pe-puppetserver service restarts, or false. | true |
Console and console-services parameters
Use these parameters to customize the behavior of the console and console-services.
Parameters that begin with puppet_enterprise::profile can be modified from
the console itself.
| Parameter | Value | Default |
|---|---|---|
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 master. |
"600" seconds (10 minutes) |
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. | "10" |
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. | "24" |
puppet_enterprise::profile::console::rbac_session_timeout
|
Integer representing, in minutes, how long a user's session may last. The session length is the same for node classification, RBAC, and the console. |
"60"
|
puppet_enterprise::profile::console::session_maximum_lifetime
|
Integer representing the maximum allowable period that a console session may be valid. May be set to "0" to not expire before the maximum token lifetime. 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::console_ssl_listen_port
|
Integer representing the port that the console is available on. |
"[443]"
|
puppet_enterprise::profile::console::ssl_listen_address
|
Nginx listen address for the console |
"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". |
"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. |
"false"
|
| Parameter | Value | Default |
|---|---|---|
puppet_enterprise::api_port
|
SSL port that the node classifier is served on. |
[4433]
|
puppet_enterprise::console_services::no_longer_reporting_cutoff
|
Length of time, in seconds, before a node is considered unresponsive. |
3600 seconds |
Orchestrator and orchestration services parameters
Use these parameters to configure and tune the orchestrator and orchestration services.
| Parameter | Value | Default |
|---|---|---|
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. |
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. |
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 master, across all orchestrator jobs. | "8" requests |
puppet_enterprise::profile::orchestrator::job_prune_threshold
| Integer representing the days after which job reports should be removed. | "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. | "30" seconds |
puppet_enterprise::profile::orchestrator::run_service
| true to enable orchestration services, or false. |
true
|
puppet_enterprise::profile::orchestrator::task_concurrency
| Integer representing the number of tasks that can run at the same time. | "250" tasks |
puppet_enterprise::profile::orchestrator::use_application_services
| true to enable application management, or false. |
false
|
puppet_enterprise::pxp_agent::ping_interval
| Integer representing the interval, in seconds, between agents' attempts to ping Puppet Communications Protocol brokers. | "120" seconds |
puppet_enterprise::pxp_agent::pxp_logfile
| String representing the path to the Puppet Execution Protocol agent log file. Change as needed. | /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.
| Parameter | Value | Default |
|---|---|---|
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. | 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. |
present
|
puppet_enterprise::puppetdb_port
|
Integer in brackets representing the SSL port that PuppetDB listens on, for example "[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. | |
Java parameters
Use these parameters to configure and tune Java.
| Parameter | Value |
|---|---|
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"}. |