You can install Puppet Enterprise agents on *nix, Windows, and macOS.
The master hosts a package repo used to install agents in your infrastructure.
The PE package management repo is created during installation of the master and serves packages over HTTPS using the same port as the master (8140). This means agents don't require any new ports to be open other than the one they already need to communicate with the master.
After installing agents, you must sign their certificates. For details, see Managing certificate signing requests.
Using the install script
The install script installs and configures the agent on target nodes using installation packages from the PE package management repo.
Detects the operating system on which it's running, sets up an apt, yum, or zipper repo that refers back to the master, and then pulls down and installs the
puppet-agent
packages. If the install script can't find agent packages corresponding to the agent's platform, it fails with an error telling you whichpe_repo
class you need to add to the master.For *nix agents, downloads a tarball of plugins from the master. This feature is controlled by the setting
pe_repo::enable_bulk_pluginsync
, which you can configure in Hiera or in the console. Bulk plugin sync is set totrue
(enabled) by default.Creates a basic
puppet.conf
file.Kicks off a Puppet run.
pe_repo
class requires an internet connection.pe_repo::http_proxy_host
and pe_repo::http_proxy_port
in pe.conf
, Hiera, or in the console, in the pe_repo
class of the PE Master node group. You can customize agent installation by providing as flags to the script any number of these options, in any order:
Option | Example | Result |
---|---|---|
puppet.conf settings |
| The puppet.conf file looks like this: |
CSR attribute settings |
| The installer creates a csr_attributes.yaml file before installing with this content: |
MSI properties (Windows only) |
| The Puppet service runs as pup_adm with a password of secret. |
Puppet service status | *nix: Windows | The Puppet service is stopped and doesn't boot after installation. An initial Puppet run doesn't occur after installation. |
puppet.conf
settings
You can specify any agent configuration option using the install script. Configuration settings are added to puppet.conf
.
server
certname
environment
splay
splaylimit
noop
http_proxy_host
, for example -s agent:http_proxy_host=<PROXY_FQDN>
.See the Configuration Reference for details.
CSR attribute settings
These settings are added to puppet.conf
and included in the custom_attributes
and extension_requests
sections of csr_attributes.yaml
.
You can pass as many parameters as needed. Follow the section:key=value
pattern and leave one space between parameters.
See the csr_attributes.yaml reference for details.
curl -k https://master.example.com:8140/packages/current/install.bash | sudo bash -s agent:certname=<certnameOtherThanFQDN> custom_attributes:challengePassword=<passwordForAutosignerScript> extension_requests:pp_role=<puppetNodeRole>
[Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<PUPPET MASTER FQDN>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 agent:certname=<certnameOtherThanFQDN> custom_attributes:challengePassword=<passwordForAutosignerScript> extension_requests:pp_role=<puppetNodeRole>
MSI properties (Windows)
For Windows, you can set these MSI properties, with or without additional agent configuration settings.
MSI Property | PowerShell flag |
---|---|
INSTALLDIR | -InstallDir |
PUPPET_AGENT_ACCOUNT_USER | -PuppetAgentAccountUser |
PUPPET_AGENT_ACCOUNT_PASSWORD | -PuppetAgentAccountPassword |
PUPPET_AGENT_ACCOUNT_DOMAIN | -PuppetAgentAccountDomain |
[Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<MASTER HOSTNAME>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 -PuppetAgentAccountUser "svcPuppet" -PuppetAgentAccountPassword "[email protected]" agent:splay=true agent:environment=development
Puppet service status
By default, the install script starts the Puppet agent service and kicks off a Puppet run. If you want to manually trigger a Puppet run, or you're using a provisioning system that requires non-default behavior, you can control whether the service is running and enabled.
Option | *nix | Windows | Values |
---|---|---|---|
ensure | --puppet-service-ensure <VALUE> | -PuppetServiceEnsure <VALUE> |
|
enable | --puppet-service-enable <VALUE> | -PuppetServiceEnable <VALUE> |
|
curl -k https://master.example.com:8140/packages/current/install.bash | sudo bash -s -- --puppet-service-ensure stopped
Windows [Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<PUPPET MASTER FQDN>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1 -PuppetServiceEnsure stopped
Install *nix agents
PE has package management tools to help you easily install and configure agents. You can also use standard *nix package management tools.
Install agents from the console
You can use the console to leverage tasks that install *nix or Windows agents on target nodes.
Make sure you have permission to run the appropriate task to install agents on all nodes.
-
*nix targets use the task pe_bootstrap::linux
-
Windows targets use the task pe_bootstrap::windows
Install *nix agents with PE package management
PE provides its own package management to help you install agents in your infrastructure.
<MASTER HOSTNAME>
portion of the installer script—as provided in the following example—refers to the FQDN of the master. The FQDN must be fully resolvable by the machine on which you're installing or upgrading the agent.- If you're installing an agent with a different OS than the master, add the appropriate class for the repo that contains the agent packages.
- SSH into the node where you want to install the agent, and run the installation command appropriate to your environment.
- Curl
curl -k https://<MASTER HOSTNAME>:8140/packages/current/install.bash | sudo bash
Tip: On AIX, which doesn't support the-k
option, use--tlsv1
instead. On other platforms that don't support the-k
option, you must install using a manually transferred certificate. - wget
wget -O - -q --no-check-certificate --secure-protocol=TLSv1 https://<MASTER HOSTNAME>:8140/packages/current/install.bash | sudo bash
-
Solaris 10 (run as root)
export PATH=$PATH:/opt/sfw/bin wget -O - -q --no-check-certificate --secure-protocol=TLSv1 https://<MASTER HOSTNAME>:8140/packages/current/install.bash | bash
- Curl
Install *nix agents with your own package management
If you choose not to use PE package management to install agents, you can use your own package management tools.
Download the appropriate agent tarball.
Agent packages can be found on the master in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/
. This directory contains the platform specific repository file structure for agent packages. For example, if your master is running on CentOS 7, in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/
, there's a directory el-7-x86_64
, which contains the directories with all the packages needed to install an agent.
If your nodes are running an operating system or architecture that is different from the master, download the appropriate agent package, extract the agent packages into the appropriate repo, and then install the agents on your nodes just as you would any other package, for example yum install puppet-agent
.
- Add the agent package to your own package management and distribution system.
- Configure the package manager on your agent node (Yum, Apt) to point to that repo.
- Install the agent using the command appropriate to your environment.
- Yum
sudo yum install puppet-agent
- Apt
sudo apt-get install puppet-agent
- Yum
- Configure the agent as needed:
puppet config set
Install *nix agents using a manually transferred certificate
If you choose not to or can't use curl -k
to trust the master during agent installation, you can manually transfer the master CA certificate to any machines you want to install agents on, and then run the installation script against that cert.
-k
is not supported for AIX 5.3, 6.1, and 7.1. You must replace the -k
flag with -tlsv1
or -1
. Install *nix agents without internet access
If you don't have access to the internet beyond your infrastructure, you can download the appropriate agent tarball from an internet-connected system and then install using the package management solution of your choice.
Download the appropriate agent tarball.
Install *nix agents with PE package management without internet access
Use PE package management to install agents when you don't have internet access beyond your infrastructure.
- On your master, copy the agent tarball to
/opt/puppetlabs/server/data/staging/pe_repo-puppet-agent-<AGENT_VERSION>
, for example/opt/puppetlabs/server/data/staging/pe_repo-puppet-agent-1.10.4
. - Run Puppet:
puppet agent -t
- Follow the steps for Install *nix agents with PE package management.
Install *nix agents with your own package management without internet access
Use your own package management to install agents when you don't have internet access beyond your infrastructure.
- Add the agent package to your own package management and distribution system.
- Disable the PE-hosted repo.
- In the console, click Classification, and in the PE Infrastructure group, select the PE Master group.
- On the Configuration tab, find
pe_repo
class (as well as any class that beginspe_repo::
), and click Remove this class. - Commit changes.
Install *nix agents from compile masters using your own package management without internet access
If your infrastructure relies on compile masters to install agents, you don’t have to copy the agent package to each compile master. Instead, use the console to specify a path to the agent package on your package management server.
- Add the agent package to your own package management and distribution system.
- Set the
base_path
parameter of thepe_repo
class to your package management server.
Install Windows agents
You can install Windows agents with PE package management, with a manually transferred certificate, or with the Windows .msi package.
Install agents from the console
You can use the console to leverage tasks that install *nix or Windows agents on target nodes.
Make sure you have permission to run the appropriate task to install agents on all nodes.
-
*nix targets use the task pe_bootstrap::linux
-
Windows targets use the task pe_bootstrap::windows
Install Windows agents with PE package management
To install a Windows agent with PE package management, you use the pe_repo
class to distribute an installation package to agents. You can use this method with or without internet access.
32-bit systems —
/opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-i386-<AGENT_VERSION>/
64-bit systems —
/opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-x86_64-<AGENT_VERSION>/
You must use PowerShell 2.0 or later to install Windows agents with PE package management.
<MASTER HOSTNAME>
portion of the installer script—as provided in the following example—refers to the FQDN of the master. The FQDN must be fully resolvable by the machine on which you're installing or upgrading the agent.After running the installer, you see the following output, which indicates the agent was successfully installed.
Notice: /Service[puppet]/ensure: ensure changed 'stopped' to 'running'
service { 'puppet':
ensure => 'running',
enable => 'true',
}
Install Windows agents using a manually transferred certificate
If you need to perform a secure installation on Windows nodes, you can manually transfer the master CA certificate to target nodes, and run a specialized installation script against that cert.
Install Windows agents with the .msi package
Use the Windows .msi package if you need to specify agent configuration details during installation, or if you need to install Windows agents locally without internet access.
Download the .msi package.
-
32-bit systems —
/opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-i386-<AGENT_VERSION>/
-
64-bit systems —
/opt/puppetlabs/server/data/packages/public/<PE_VERSION>/windows-x86_64-<AGENT_VERSION>/
Install Windows agents with the installer
Use the MSI installer for a more automated installation process. The installer can configure puppet.conf
, create CSR attributes, and configure the agent to talk to your master.
- Run the installer as administrator.
- When prompted, provide the hostname of your master, for example puppet.
Install
Windows agents using msiexec
from the command line
Install the MSI manually from the the command line if you need to customize puppet.conf
, CSR attributes, or certain agent properties.
msiexec /qn /norestart /i <PACKAGE_NAME>.msi
/l*v install.txt
to log the progress of the installation to a file.MSI properties
If you install Windows agents from the command line using the .msi package, you can optionally specify these properties.
PUPPET_MASTER_SERVER
, PUPPET_CA_SERVER
, PUPPET_AGENT_CERTNAME
, or PUPPET_AGENT_ENVIRONMENT
, the installer replaces the existing value in puppet.conf
and re-uses the value at upgrade unless you specify a new value. Therefore, if you've used these properties once, don't change the setting directly in puppet.conf
; instead, re-run the installer and set a new value at installation.Property | Definition | Setting in pe.conf | Default |
---|---|---|---|
INSTALLDIR
| Location to install Puppet and its dependencies. | n/a |
|
PUPPET_MASTER_SERVER
| Hostname where the master can be reached. |
server
|
puppet
|
PUPPET_CA_SERVER
| Hostname where the CA master can be reached, if you're using multiple masters and only one of them is acting as the CA. |
ca_server
| Value of PUPPET_MASTER_SERVER |
PUPPET_AGENT_CERTNAME
|
Node's certificate name, and the name it uses when requesting catalogs. For best compatibility, limit the value of |
certname
| Value of facter fdqn |
PUPPET_AGENT_ENVIRONMENT
| Node's environment. Note: If a value for the environment variable already exists in puppet.conf , specifying it during installation does not override that value. |
environment
|
production
|
PUPPET_AGENT_STARTUP_MODE
| Whether and how the agent service is allowed to run. Allowed values are:
| n/a |
Automatic
|
PUPPET_AGENT_ACCOUNT_USER
|
Windows user account the agent service uses. This property is useful if the agent needs to access files on UNC shares, because the default The user account must already exist, and may be a local or domain user. The installer allows domain users even if they have not accessed the machine before. The installer grants This property must be combined with | n/a |
LocalSystem
|
PUPPET_AGENT_ACCOUNT_PASSWORD
| Password for the agent's user account. | n/a | No Value |
PUPPET_AGENT_ACCOUNT_DOMAIN
| Domain of the agent's user account. | n/a |
.
|
REINSTALLMODE
| A default MSI property used to control the behavior of file copies during installation. Important: If you need to downgrade agents, use REINSTALLMODE=amus when calling msiexec.exe at the command line to prevent removing files that the application needs. | n/a |
amus as of puppet-agent 1.10.10 and puppet-agent 5.3.4 omus in prior releases |
puppet.acme.com
:msiexec /qn /norestart /i puppet.msi PUPPET_MASTER_SERVER=puppet.acme.com
ExampleCorp\bob
:msiexec /qn /norestart /i puppet-<VERSION>.msi PUPPET_AGENT_ACCOUNT_DOMAIN=ExampleCorp PUPPET_AGENT_ACCOUNT_USER=bob PUPPET_AGENT_ACCOUNT_PASSWORD=password
Windows agent installation details
Windows nodes can fetch configurations from a master and apply manifests locally, and respond to orchestration commands.
The agent runs as a Windows service. By default, the agent fetches and applies configurations every 30 minutes. The agent service can be started and stopped independently using either the service control manager UI or the command line sc.exe
utility.
Puppet is automatically added to the machine's PATH
environment variable, so you can open any command line and run puppet
, facter
and the other batch files that are in the bin
directory of the Puppet installation. Items necessary for the Puppet environment are also added to the shell, but only for the duration of execution of each of the particular commands.
The installer includes Ruby, gems, and Facter. If you have existing copies of these applications, such as Ruby, they aren't affected by the re-distributed version included with Puppet.
Program directory
Unless overridden during installation, PE and its dependencies are installed in Program Files
at \Puppet Labs\Puppet
.
You can locate the Program Files
directory using the PROGRAMFILES
variable or the PROGRAMFILES(X86)
variable.
The program directory contains these subdirectories.
Subdirectory | Contents |
---|---|
bin | scripts for running Puppet and Facter |
facter | Facter source |
hiera | Hiera source |
misc | resources |
puppet | Puppet source |
service | code to run the agent as a service |
sys | Ruby and other tools |
Data directory
PE stores settings, manifests, and generated data — such as logs and catalogs — in the data directory. The data directory contains two subdirectories for the various components:
etc
(the$confdir
): Contains configuration files, manifests, certificates, and other important files.var
(the$vardir
): Contains generated data and logs.
When you run Puppet with elevated privileges as intended, the data directory is located in the COMMON_APPDATA.aspx
folder. This folder is typically located at C:\ProgramData\PuppetLabs\
. Because the common app data directory is a system folder, it is hidden by default.
If you run Puppet without elevated privileges, it uses a .puppet
directory in the current user's home folder as its data directory, which can result in unexpected settings.
Install macOS agents
You can install macOS agents with PE package management, from Finder, or from the command line.
Download the appropriate agent tarball.
To install macOS agents with PE package management, follow the steps to Install *nix agents with PE package management.
Install macOS agents from Finder
You can use Finder to install the agent on your macOS machine.
Install macOS agents from the command line
You can use the command line to install the agent on a macOS machine.
macOS agent installation details
macOS agents include core Puppet functionality, plus platform-specific capabilities like package installation, service management with LaunchD, facts inventory with the System Profiler, and directory services integration.
Install non-root agents
Running agents without root privileges can assist teams using PE to work autonomously.
For example, your infrastructure’s platform might be maintained by one team with root privileges while your infrastructure’s applications are managed by a separate team (or teams) with diminished privileges. If the application team wants to be able to manage its part of the infrastructure independently, they can run Puppet without root privileges.
PE is installed with root privileges, so you need a root user to install and configure non-root access to a master. The root user who performs this installation can then set up non-root users on the master and any nodes running an agent.
Non-root users can perform a reduced set of management tasks, including configuring settings, configuring Facter external facts, running puppet agent --test
, and running Puppet with non-privileged cron jobs or a similar scheduling service. Non-root users can also classify nodes by writing or editing manifests in the directories where they have write privileges.
Install non-root *nix agents
-
The agent can request certificates and apply the catalog from the master when a non-root user runs Puppet:
puppet agent -t
-
The agent service is not running:
service puppet status
-
Non-root users can collect existing facts by running
facter
on the agent, and they can define new, external facts.
Install non-root Windows agents
Non-root user functionality
Non-root users can only use a subset of functionality. Any operation that requires root privileges, such as installing system packages, can't be managed by a non-root agent.
*nix non-root functionality
On *nix systems, as non-root agent you may enforce these resource types:
cron
(only non-root cron jobs can be viewed or set)exec
(cannot run as another user or group)file
(only if the non-root user has read/write privileges)-
notify
-
schedule
-
ssh_key
-
ssh_authorized_key
-
service
-
augeas
-u
flag to set a user with root privileges causes the job to fail, resulting in this error message:
Notice: /Stage[main]/Main/Node[nonrootuser]/Cron[illegal_action]/ensure: created must be privileged to use -u
puppet resource <resource type>
):-
host
-
mount
-
package
Windows non-root functionality
On Windows systems as non-admin user, you may enforce these types :
-
exec
-
file
C:\Windows
unless your user has permission to do so.You may also inspect these resource types (use puppet resource <resource type>
):
-
host
-
package
-
user
-
group
-
service
Managing certificate signing requests
When you install a new PE agent, the agent automatically submits a certificate signing request (CSR) to the master.
Certificate requests can be signed from the console or the command line. If DNS altnames are set up for agent nodes, you must use the command line interface to approve and reject node requests.
After approving a node request, the node doesn’t show up in the console until the next Puppet run, which can take up to 30 minutes. You can manually trigger a Puppet run if you want the node to appear immediately.
To accept or reject CSRs in the console or on the command line, you need the permission Certificate requests: Accept and reject. To manage certificate requests in the console, you also need the permission Console: View.
Managing certificate signing requests in the console
The console displays a list of nodes on the Unsigned certs page that have submitted CSRs. You can approve or deny CSRs individually or in a batch.
If you use the Accept All or Reject All options, processing could take up to two seconds per request.
When using Accept All or Reject All, nodes are processed in batches. If you close the browser window or navigate to another website while processing is in progress, only the current batch is processed.
Managing certificate signing requests on the command line
You can view, approve, and reject node requests using the command line.
$ sudo puppetserver ca list
$ sudo puppetserver ca sign <NAME>
$ sudo puppetserver ca sign (<HOSTNAME> or --all) --allow-dns-alt-names
Configuring agents
You can add additional configuration to agents by editing /etc/puppetlabs/puppet/puppet.conf
directly, or by using the puppet config set
sub-command, which edits puppet.conf
automatically.
For example, to point the agent at a master called master.example.com
, run puppet config set server master.example.com
. This command adds the setting server = puppetmaster.example.com
to the [main]
section of puppet.conf
.
To set the certname for the agent, run /opt/puppetlabs/bin/puppet config set certname agent.example.com
.