Installing Puppet Enterprise: Monolithic
A newer version is available; see the version menu above for details.
The following instructions are for installing a monolithic installation of PE. When you perform a monolithic installation of PE, the master, console, and PuppetDB components are all installed on the same machine. This type of installation is recommended for deployments up to 500 agent nodes.
See the installation overview for instructions on downloading Puppet Enterprise.
Note: The answer file generated by the procedure on this page can be used to perform an installation with an answer file. You can find the installer answer file at
/opt/puppet/share/installer/answerson the machine from which you’re running the installer, but note that these answers are overwritten each time you run the installer.
General Prerequisites and Notes
If you’ve previously installed Puppet or PE, make sure that the machine you’re installing PE on is totally free of any artifacts left over from the previous installation.
Make sure that DNS is properly configured on the machines you’re installing PE on. All nodes must know their own hostnames. This can be done 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, while the exact method varies by platform. In addition, all nodes must be able to reach each other by name. This can be done 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 PE deployment or from a machine that is outside your deployment. If you want to run the installer from a machine that is part of your deployment, we recommend you run it from the same node assigned the console component (in a split install).
The machine you run the installer from must have the same OS/architecture as your PE deployment.
Please ensure that port 3000 is reachable, as the web-based installer uses this port. You can close this port when the installation is complete.
The web-based installer does not support sudo configurations with
Defaults rootpw. Make sure your
/etc/sudoersfile does not contain, or else comment out, those lines.
For Debian Users: If you gave the root account a password during the installation of Debian, sudo may not have been installed. In this case, you will need to either install PE as root, or install sudo on any node(s) on which you want to install PE.
A Note about Passwords: In some cases, during the installation process, you’ll be asked to supply passwords. The
'(single quote) is forbidden in all passwords.
SSH Prerequisites and Notes
Note: If you plan on choosing Install on this server during the installation process, you do not need to take any additional steps to configure SSH.
If you have a properly configured SSH agent with agent forwarding enabled, you don’t need to perform any additional SSH configurations. Your SSH agent will be used by the installer.
If you’re using SSH keys to authenticate across the nodes of your PE installation, the public key for the user account performing the installation must be included in the
authorized_keysfile for that user account on each node that you’re installing a PE component on, including the machine from which you’re running the installer. This applies to root or non-root users.
The web-based installer will prompt for the user account name, the SSH private key location, and the SSH passphrase for each node on which you’re installing a PE component.
Please review the following authentication options:
- Are you installing using root with a password? The installer will ask you to provide the username and password for each node on which you’re installing a PE component.
- Prerequisite: Remote root SSH login must be enabled on each node, including the node from which you’re running the installer.
- Are you installing using a non-root user with a password? The installer will ask you to provide the username and password for each node on which you’re installing a PE component.
- Prerequisite: Sudo must be enabled for the non-root user on which you’re installing a PE component.
- Are you installing using root with an SSH key? The installer will ask you to provide the username, private key path, and key passphrase (as needed) for each node on which you’re installing a PE component.
- Prerequisite: Remote root SSH login must enabled on each node, including the node from which you’re running the installer. And the public root ssh key must be added to
authorized_keyson each node on which you’re installing a PE component.
- Are you installing using a non-root user with an SSH key? The installer will ask you to provide the username, private key path, and key passphrase (as needed) for each node on which you’re installing a PE component.
- Prerequisite: The non-root user SSH key must be added to
authorized_keyson each node on which you’re installing a PE component. And the non-root user must be granted sudo access on each box.
Monolithic Installation: Step 1
- Download and verify the appropriate PE tarball.
- Unpack the tarball. (Run
tar -xf <tarball>. Note that you need about 1 GB of space in
/tmpto untar the installer.)
- From the PE installer directory, run
When prompted, choose “Yes” to install the setup packages. (If you choose “No,” the installer will exit.)
At this point, the PE installer will start a web server and provide a web address:
https://<install platform hostname>:3000. Please ensure that port 3000 is reachable. If necessary, you can close port 3000 when the installation is complete. Also be sure to use
- Copy the address into your browser and continue on to Monolithic Installation: Part 2.
Warning: Leave your terminal connection open until the installation is complete; otherwise, the installation will fail.
Monolithic Installation: Step 2
When prompted, accept the security request in your browser.
The web-based installation uses a default SSL certificate; you’ll have to add a security exception in order to access the web-based installer. This is safe to do.
You’ll be taken to the installer start page.
- On the start page, click Let’s get started.
- Next, you’ll be asked to choose your deployment type. Select Monolithic.
- Choose whether you want to install PE on the server you’re running the installer from or on another server. The choices are Install on this server or Install on another server.
Provide the following information about the Puppet master server:
Note that if you selected Install on this server, you will only be prompted for steps a - b.
a. Puppet master FQDN: provide the fully qualified domain name of the server you’re installing PE on. It will be the name of the Puppet master certificate. This FQDN must be resolvable from the machine on which you’re running the installer.
b. DNS aliases: provide a comma-separated list of static, valid DNS names (default is “puppet”), so agents can trust the master if they contact it. You should make sure that this static list contains the DNS name or alias you’ll be configuring your agents to contact.
c. SSH username: provide the username to use when connecting to the Puppet master. This field defaults to
root. This user must either be root or have sudo access.
d. SSH password: if used, provide the password for the SSH username provided. This password will also be used if the user requires a password for sudo access.
e. SSH key file path: if SSH password is not used, provide the absolute path to the SSH key on the machine you are performing the installation from. Defaults to the root SSH key path.
f. SSH key passphrase: provide if your SSH key is protected with a passphrase.
Provide the following information about database support (PuppetDB and PostgreSQL):
a. Install PostgreSQL on the PuppetDB host for me: (default) PE will install a PostgreSQL instance for the databases. This will use PE-generated default names and usernames for the databases. The passwords can be retrieved from
/etc/puppetlabs/installer/database_info.installwhen the installation is complete.
b. Use an Existing PostgreSQL instance: if you already have a PostgreSQL instance you’d like to use, you’ll need to provide the following database information. Refer to External PostgreSQL Prep Notes for more info.
Important: After installing PE, refer to the SSL for PE and PostgreSQL documentation to enable SSL between PE and your external PostgreSQL instance.
the PostgreSQL server DNS name
the port number used by the PostgreSQL server (default is 5432)
the PuppetDB database name (default is “pe-puppetdb”)
the PuppetDB database user (default is “pe-puppetdb).
the PuppetDB database password
the role-based access control database name (default is “pe-rbac”)
the role-based access control database user (default is “pe-rbac”)
the role-based access control database password
the node classifier database name (default is “pe-classifier”)
the node classifier database user (default is “pe-classifier”)
the node classifier database password
the activity database name (default is “pe-activity”)
the activity database user (default is “pe-activity”)
the activity database password
Provide the following information about the PE console administrator user:
Console superuser password: create a password for the console login; the password must be at least eight characters.
Note: the user name for the console administrator user is admin.
Provide the following information about the PE console mail server:
- SMTP hostname: the console requires access to an SMTP server in order to email account information to users. If necessary, this can be changed after installation.
To add more information about the SMTP host, select Advanced SMTP options. Here you can configure advanced SMTP options for setting the port, username, password, and whether or not to use TLS.
On the confirm plan page, review the information you provided, and, if it looks correct, click Continue.
If you need to make any changes, click Go Back and make whatever changes are required.
- On the validation page, the installer will verify various configuration elements (e.g., if SSH credentials are correct, if there is enough disk space, and if the OS is the same for the various components). If there aren’t any outstanding issues, click Deploy now.
At this point, PE will begin installing your deployment, and you can monitor the installation as it runs by toggling Log View and Summary View (top-right corner of page). If you notice any errors during the installation, check
/var/log/pe-installer/install_log.lastrun.<hostname>.log on the machine from which you are running the installer.
You can find the installer answer file at
/opt/puppet/share/installer/answers on the machine from which you’re running the installer, but note that these answers are overwritten each time you run the installer.
When the installation is complete, the installer script that was running in the terminal will close itself.
External PostgreSQL Prep Notes
If you are using an external PostgreSQL instance that is not managed by PE, make sure you review the following notes.
You must create databases for RBAC, activity service, and the node classifier before installing. The SQL commands to create the databases resemble the following:
CREATE TABLESPACE "pe-puppetdb" LOCATION '/opt/puppetlabs/server/data/postgresql/puppetdb'; CREATE USER "pe-puppetdb" PASSWORD 'password'; CREATE DATABASE "pe-puppetdb" OWNER "pe-puppetdb" TABLESPACE "pe-puppetdb" ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0; CREATE TABLESPACE "pe-activity" LOCATION '/opt/puppetlabs/server/data/postgresql/activity'; CREATE USER "pe-activity" PASSWORD 'password'; CREATE DATABASE "pe-activity" OWNER "pe-activity" TABLESPACE "pe-activity" ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0; CREATE TABLESPACE "pe-classifier" LOCATION '/opt/puppetlabs/server/data/postgresql/classifier'; CREATE USER "pe-classifier" PASSWORD 'password'; CREATE DATABASE "pe-classifier" OWNER "pe-classifier" TABLESPACE "pe-classifier" ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0; CREATE TABLESPACE "pe-rbac" LOCATION '/opt/puppetlabs/server/data/postgresql/rbac'; CREATE USER "pe-rbac" PASSWORD 'password'; CREATE DATABASE "pe-rbac" OWNER "pe-rbac" TABLESPACE "pe-rbac" ENCODING 'utf8' LC_CTYPE 'en_US.utf8' LC_COLLATE 'en_US.utf8' template template0;
You must enable the citext extension on the RBAC database. To do so, install the
postgresql-contribpackage, and then from inside the RBAC database, run the following commands:
sudo -u postgres sh psql pe_rbac -c 'create extension citext' exit
If you are running PostgreSQL 9.3 or above, you should install the
pg_trimextension on the PuppetDB database. This may require the
postgresql-contrib(or equivalent) package depending on your distribution. To install the extension, run the following commands:
sudo -u postgres sh psql puppetdb -c 'create extension pg_trgm' exit
Consult the PostgreSQL documentation for more info.
Port Forwarding to the Installer
If you cannot connect directly to port 3000 on the on the machine you’re running the installer from, we suggest port forwarding (or “tunneling” to) the installer via SSH.
From a Linux machine:
- On the machine from which you’re running the installer, run
ssh -L 3000:localhost:3000 jumphost.exmple.tld
- Run the installer script as indicated in the instructions below.
- When prompted to enter the installer URL, instead navigate to
From a Windows machine:
- Open PuTTY, and select Sessions.
- In the Host Name field, enter the FQDN of the host you want to run the installer from.
- Select Tunnels.
- In the Source Port field, enter
- In the Destination field, enter
- Select Local.
- Click Add.
- Click Open.
When the installer asks you to launch the browser, use
https://localhost:3000, and continue following the installation instructions.
Next: Installing PE Agents