Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Installing Grey arrow pointing right Installing agents Grey arrow pointing right Install macOS agents Grey arrow pointing right

Install macOS agents

Sections

On macOS, agents have core Puppet functionality and platform-specific capabilities like package installation, LaunchD service management, System Profiler facts inventory, and directory services integration. You can install agents on macOS nodes with the install script, from the Puppet Enterprise (PE) console, from Finder, and more.

We recommend you Install agents with the install script or Install agents from the console whenever possible. If you want to install macOS agents with PE package management, follow the steps to Install *nix agents with PE package management. If you want to install agents from Finder or the macOS command line, follow the steps below.

Install macOS agents from Finder

You can use Finder to install agents on macOS nodes. Client URL (curl) and World Wide Web Get (Wget) commands can be used to download PE repo tarballs from PE’s private repository.

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 in 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.
os_version String None 2023 The operating system version.
os_arch String None aarch64 The operating system architecture.
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 macOS 14 would be similar to the following example, where:
  • <username> is a string literal, license-id
  • <password> is the PE License ID 
    curl -J -O -u <username>:<password> "https://artifacts-puppetcore.puppet.com/v1/download?version=8.11.0&os_name=osx&os_version=14&os_arch=x86_64"Copied!
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!
  1. Download the appropriate agent tarball.
  2. Open the agent package .dmg and click the installer .pkg.
  3. Follow installer dialog prompts. You must provide the primary server's hostname and the agent's certname.
    Note: For macOS agents, the certname is derived from the machine's name. For best compatibility, make sure the node's name doesn't include capital letters (for example, My-Example-Mac must be my-example-mac). If you don’t want to change the computer’s name, enter the agent certname in all lowercase letters when prompted by the installer.
  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 macOS agents from the command line

You can use the command line to install agents on macOS nodes.

  1. Download the appropriate agent tarball.
  2. SSH into the target node as root or sudo.
  3. To mount the disk image, run: sudo hdiutil mount <DMGFILE>
  4. Locate a line ending with /Volumes/puppet-agent-<VERSION>. This directory location is the mount point for the virtual volume created from the disk image.
  5. Change to the mount point directory, such as with: cd /Volumes/puppet-agent-<VERSION>
  6. To install the agent package, run: sudo installer -pkg puppet-agent-installer.pkg -target /
  7. To verify the installation, run: /opt/puppetlabs/bin/puppet --version
  8. To set the primary server's hostname in the node's puppet.conf file, run: /opt/puppetlabs/bin/puppet config set server <PRIMARY_HOSTNAME>
    Go to Customize the install script for more information about cpuppet.conf.
  9. To set the agent's certname in the node's puppet.conf file, run: /opt/puppetlabs/bin/puppet config set certname <AGENT_CERTNAME>
    For macOS agents, the certname is derived from the machine's name. For best compatibility, make sure the node's name doesn't include capital letters (for example, My-Example-Mac must be my-example-mac). If you don’t want to change the computer’s name, enter the agent certname in all lowercase letters.
  10. Run puppet agent -t to add the node to the node inventory and generate the CSR.
  11. Accept the CSR as explained in Managing certificate signing requests.
Was this page helpful?