Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Installing Grey arrow pointing right Installing agents Grey arrow pointing right Install *nix agents Grey arrow pointing right

Install *nix agents

Sections

You can install agents on *nix nodes with the install script, from the Puppet Enterprise (PE) console, with PE package management, your own package management, with or without internet access, and more.

We recommend you Install agents with the install script or Install agents from the console whenever possible, and we've described other cases here for your reference. For non-root agents, refer to Install non-root *nix agents.

You must enable TLSv1 to install agents on these platforms:
  • AIX
  • Solaris 11

Install *nix agents with PE package management

Puppet Enterprise (PE) provides its own package management to help you install agents on *nix and macOS nodes. You can use this process with or without internet access.

Before you begin

If you're installing an agent with a different OS than your primary server, you must declare the corresponding pe_repo class on the primary server, such as pe_repo::platform::el_8_x86_64. You can declare these classes in the console at Node Groups > PE Master > Classes.

If the primary server does not have internet access, download the appropriate agent tarball, and copy the agent tarball to this location on the primary server:
/opt/puppetlabs/server/data/staging/pe_repo-puppet-agent-<AGENT_VERSION>Copied!
For example, the directory for agent version 8.11.0 is:
/opt/puppetlabs/server/data/staging/pe_repo-puppet-agent-8.11.0/Copied!
Client URL (curl) and World Wide Web Get (Wget) commands can be used to download PE repo tarballs from PE’s private repository. These commands modify the standard agent install script for specific platforms or air-gapped environments. If you do not have a specific need for these commands, follow the procedure in Install agents with the install script.

Authentication credentials

Because Puppet Enterprise agent packages are stored in a private repository, you must authenticate to access and download the packages.

Use the string literal license-id as your username and use your PE License ID as the password. You can find your PE License ID in your PE license file or in the PE console by selecting License from the navigation bar.
Note: If your PE License ID is not present in your license, please Contact our sales team.

Authentication procedures

You can use either of the following procedures to authenticate:

  • Create and configure a .netrc file
  • Export credentials to environment variables
Create and configure a .netrc file

A .netrc file is a configuration file used by many command-line tools and programs, including curl, FTP, and Git. The primary purpose of the file is to store login credentials.

Complete the following steps to create and configure a .netrc file:
  1. Create a file named .netrc by running the following commands:
    touch ~/.netrc  
chmod 600 ~/.netrc Copied!
  2. Edit the file to add your credentials, where license-id is a string literal and <PE_License_ID> is your PE License ID: 
    machine artifacts-puppetcore.puppet.com   
  login license-id  
  password <PE_License_ID>Copied!
  3. Run a command with the --netrc option so that the credentials stored in the .netrc  file are used for authentication, as shown in the following example: 
curl --netrc 'https://artifacts-puppetcore.puppet.com/v1/download?version=8.11.0&type=perepo&os_name=el&os_version=9&os_arch=x86_64' -J -OCopied!
Export credentials to environment variables

You can directly curl the endpoints with credentials by completing the following steps:

  1. Export the credentials, where license-id is a string literal and  <PE_License_ID> is your PE License ID: 
    export USERNAME=license-id 
export PASSWORD=<PE_License_ID>Copied!
  2. Call the credentials from the URL, as shown in the following example: 
    curl -u $USERNAME:$PASSWORD 'https://artifacts-puppetcore.puppet.com/v1/download?version=8.11.0&type=perepo&os_name=el&os_version=9&os_arch=x86_64' -J -OCopied!
Request parameters

The following request parameters are accepted by the artifact download endpoint.

Note: To directly copy URLs and download agent and agent repo, see puppet releases.
Name Type Default Example Description
version String None 8.11.0 The package version.
os_name String None amazon The name of the operating system. For a list of valid names, see operating systems.
os_version String None 2023 The operating system version. For a list of valid versions, see operating systems.
os_arch String None aarch64 The operating system architecture. For a list of valid architectures, see operating systems.
Operating system names, versions, and architectures

The following table lists currently valid values for the os_name, os_version, and os_arch parameters.

To specify an operating system, use the values in the Name column. The Full name column is for informational purposes only.
Name Full name Version Architecture
aix AIX 7.2 architecture ppc
amazon Amazon Linux 2, 2023, and so on x86_64, aarch64
debian Debian 10, 11, and so on amd64, arm64
el Red Hat Enterprise Linux 7, 8, and so on x86_64, aarch64, ppc64le
fedora Fedora Linux 40 and so on x86_64
osx macOS 14 and so on x86_64, arm64
redhatfips Redhat (FIPS) 7, 8, 9 x86_64
sles SUSE Linux Enterprise Server 12, 15 x86_64

solaris

Solaris 11 11: x86_64, SPARC
ubuntu Ubuntu 22.04 and so on amd64, arm64
windows Microsoft Windows Ignored x86, x64
windowsfips Windows (FIPS) Ignored x64
Example
A download link for Ubuntu Linux 22.04 would be similar to the following example, where:
  • <username> is a string literal, license-id
  • <password> is the PE License ID
Content disposition

Content disposition is enabled for these packages and can be used while downloading packages to store them with their default name. Use –J –O only with curl. For wget, use the following structure: 

wget --content-disposition <URL>Copied!
Note: The <PRIMARY_HOSTNAME> portion of the installer script—as provided in the following example—refers to the FQDN of the primary server. The FQDN must be fully resolvable by the machine on which you're installing or upgrading the agent.
  1. SSH into the node where you want to install the agent and run the command appropriate to your environment:
    Choose from:
    • curl: 
      uri='https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash' 
curl -k "$uri" | sudo bash Copied!
    • wget: 
      wget -O - -q --no-check-certificate https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash | sudo bash Copied!
    • Solaris
      sudo export PATH=$PATH:/opt/sfw/bin
wget -O - -q --no-check-certificate --secure-protocol=TLSv1 https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash | bash Copied!
  2. Run puppet agent -t to add the node to the node inventory and generate the CSR.
  3. Accept the CSR as explained in Managing certificate signing requests.

Install *nix agents with your own package management

You can use your own package management tools, instead of Puppet Enterprise (PE) package management, to install agents. You can use this method with or without internet access.

Before you begin

Download the appropriate agent tarball.

  1. Add the agent package to your own package management and distribution system.
  2. Configure the package manager on your agent node (such as YUM or APT) to point to that repo.
  3. Install the agent using the command appropriate to your environment:
    • YUM:
      sudo yum install puppet-agentCopied!
    • APT:
      sudo apt-get install puppet-agentCopied!
    In offline environments, you might need to disable the PE-hosted package management repo if the installer gets stuck trying to connect to the primary server. To do this, in the PE console, go to Node groups > PE Infrastructure > PE Master. On the Classes tab, find the pe_repo::platform class corresponding with your node's platform, click Remove this class, and commit changes.
  4. Run puppet agent -t to add the node to the node inventory and generate the CSR.
  5. Accept the CSR as explained in Managing certificate signing requests.

Install *nix agents using a manually-transferred certificate

If you can't, or don't, use -k or --insecure to trust the primary server during agent installation, you can manually copy the primary server CA certificate to any *nix machines you want to install agents on, and then run a variation of the agent install script against that cert.

For general information about forming curl commands and authentication in commands, go to Using example commands.
  1. On the machine where you want to install the agent, create this directory: /etc/puppetlabs/puppet/ssl/certs
  2. On the primary server, navigate to /etc/puppetlabs/puppet/ssl/certs/ and copy ca.pem to the certs directory you created on the agent node.
  3. On the agent node, verify file permissions by running: 
    chmod 444 /etc/puppetlabs/puppet/ssl/certs/ca.pemCopied!
  4. Run the agent install script command, using the --cacert flag to point to the cert, such as: 
    cacert='/etc/puppetlabs/puppet/ssl/certs/ca.pem'
uri='https://<PRIMARY_HOSTNAME>:8140/packages/current/install.bash'

curl --cacert "$cacert" "$uri" | sudo bashCopied!
    For more information about the agent install script, go to Install agents with the install script.
  5. Run puppet agent -t to add the node to the node inventory and generate the CSR.
  6. Accept the CSR as explained in Managing certificate signing requests.

Install *nix agents from compilers using your own package management

If your infrastructure relies on compilers to install agents, you don’t have to copy the agent package to each compiler. Instead, you can use the console to specify a path to the agent package on your package management server.

Before you begin

Download the appropriate agent tarball.

  1. Add the agent package to your own package management and distribution system.
  2. Set the base_path parameter of the pe_repo class to point to your package management server.
    1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Master group.
    2. On the Classes tab, find the pe_repo class, and set the base_path parameter to your package management server's FQDN.
    3. Click Add parameter and commit changes.
  3. Follow the steps to Install *nix agents with your own package management.
Was this page helpful?