Installing client tools

PE client tools are a set of command line tools that let you access Puppet Enterprise services from a workstation that might or might not be managed by Puppet.

The pe-client-tools package is included in the PE installation tarball. When you install, the client tools are automatically installed on the same node as the primary server. When you upgrade, client tools are automatically updated on infrastructure nodes and managed nodes, but on unmanaged nodes, you must re-install the version of client tools that matches the PE version you upgraded to.

Client tools versions align with PE versions. For example, if you're running PE 2023.0, use the 2023.0 client tools. In some cases, we might issue patch releases ("x.y.z") for PE or the client tools. You don't need to match complete patch numbers between PE and the client tools; only the "x.y" numbers need to match.
Note: To see the version of client tools installed on your system, use the command appropriate for your package manager or operating system. For example, on Red Hat: rpm -q pe-client-tools.

The package includes client tools for these services:

  • Orchestrator — Allow you to control the rollout of changes in your infrastructure, and provides the interface to the orchestration service. Tools include puppet job and puppet task.
  • Puppet access — Authenticates you to the PE RBAC token-based authentication service so that you can use other capabilities and APIs.
  • Code Manager — Provides the interface for the Code Manager and file sync services. Tools include puppet-code.
  • PuppetDB CLI — Enables certain operations with PuppetDB, such as building queries and handling exports.

Because you can safely run these tools remotely, you no longer need to SSH into the primary server to execute commands. Your permissions to see information and to take action are controlled by PE role-based access control. Your activity is logged under your username rather than under root or the pe-puppet user.

Supported PE client tools operating systems

The PE client tools package can be installed on the following platforms.

Operating system Versions Arch
Amazon Linux 2 x86_64
CentOS 6, 7 x86_64
macOS 10.15, 11, 12
  • 10.15: x86_64
  • 11: x86_64
  • 12: x86_64, M1, M2
Microsoft Windows 10, 11
  • 10: x86, x64
  • 11: x64
Microsoft Windows Server 2012, 2012 R2, 2012 R2 core, 2016, 2016 core, 2019, 2019 core, 2022 x64
Oracle Linux 6, 7, 8, 9 x86_64
Red Hat Enterprise Linux 6, 7, 8, 9 x86_64
Scientific Linux 6, 7, 8, 9 x86_64
SUSE Linux Enterprise Server 12, 15 x86_64
Ubuntu 18.04, 20.04, 22.04 amd64

Install PE client tools on a managed workstation

To use the client tools on a system other than the primary server, where they're installed by default, you can install the tools on a controller node.

Before you begin
Controller nodes must be running the same OS as your primary server and must have an agent installed.
  1. In the console, create a controller classification group, for example PE Controller, and ensure that its Parent name is set to All Nodes.
  2. Select the controller group and add the puppet_enterprise::profile::controller class.
  3. Pin the node that you want to be a controller to the controller group.
    1. In the controller group, on the Rules tab, in the Certname field, enter the certname of the node.
    2. Click Pin node and commit changes.
  4. Run Puppet on the controller machine.

Install PE client tools on an unmanaged workstation

You can install the pe-client-tools package on any workstation running a supported OS. The workstation OS does not need to match the primary server OS.

Before you begin
Review prerequisites for timekeeping, name resolution, and firewall configuration, and ensure that these ports are available on the workstation.
  • 8143 — The orchestrator client uses this port to communicate with orchestration services running on the primary server.
  • 4433 — The Puppet access client uses this port to communicate with the RBAC service running on the primary server.
  • 8170 — If you use the Code Manager service, it requires this port.

Install PE client tools on an unmanaged Linux workstation

  1. On the workstation, create the directory /etc/puppetlabs/puppet/ssl/certs.
  2. On the primary server, navigate to /etc/puppetlabs/puppet/ssl/certs/ and copy ca.pem to the directory you created on the workstation.
  3. On the workstation, make sure file permissions are correct: chmod 444 /etc/puppetlabs/puppet/ssl/certs/ca.pem
  4. Verify that the checksum of ca.pem on the workstation matches the checksum of the same file on the primary server.
  5. Download the pe-client-tools package for the platform appropriate to your workstation.
  6. Use your workstation's package management tools to install the pe-client-tools.
    For example,on RHEL platforms: rpm -Uvh pe-client-tools-<VERSION-and-PLATFORM>.rpm

Install PE client tools on an unmanaged Windows workstation

You can install the client tools on a Windows workstation using the setup wizard or the command line.

To start using the client tools on your Windows workstation, open the PE ClientTools Console from the Start menu.

  1. On the workstation, create the directory C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs.

    For example: mkdir C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs

  2. On the primary server, navigate to /etc/puppetlabs/puppet/ssl/certs/ and copy ca.pem to the directory you created on the workstation.
  3. On the workstation, make sure the file permissions are set to read-only for C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\ca.pem.
  4. Verify that the checksum of ca.pem on the workstation matches the checksum of the same file on the primary server.
  5. Install the client tools using guided setup or the command line.
    • Guided setup

      1. Download the Windows pe-client-tools-package.

      2. Double-click the pe-client-tools .msi file.

      3. Follow prompts to accept the license agreement and select the installation location.

      4. Click Install.

    • Command line

      1. Download the Windows pe-client-tools-package.

      2. From the command line, run the installer: 
        msiexec /i <PATH TO PE-CLIENT-TOOLS.MSI> TARGETDIR="<INSTALLATION DIRECTORY>"
        TARGETDIR is optional.

Install PE client tools on an unmanaged macOS workstation

You can install the client tools on a macOS workstation using Finder or the command line.

  1. On the workstation, create the directory /etc/puppetlabs/puppet/ssl/certs.
  2. On the primary server, navigate to /etc/puppetlabs/puppet/ssl/certs/ and copy ca.pem to the directory you created on the workstation.
  3. On the workstation, make sure file permissions are correct: chmod 444 /etc/puppetlabs/puppet/ssl/certs/ca.pem
  4. Verify that the checksum of ca.pem on the workstation matches the checksum of the same file on the primary server.
  5. Install the client tools using Finder or the command line.
    • Finder

      1. Download the macOS pe-client-tools-package.

      2. Open the pe-client-tools .dmg and click the installer .pkg.

      3. Follow the prompts to install the client tools.

    • Command line

      1. Download the macOS pe-client-tools-package.

      2. Mount the disk image: sudo hdiutil mount <DMGFILE>.

        A line appears ending with /Volumes/puppet-agent-VERSION. This directory location is the mount point for the virtual volume created from the disk image.

      3. Run cd /Volumes/pe-client-tools-VERSION.
      4. Run sudo installer -pkg pe-client-tools-<VERSION>-installer.pkg -target /.
      5. Run cd ~ and then run sudo umount /Volumes/pe-client-tools-VERSION.

Configuring and using PE client tools

Use configuration files to customize how client tools communicate with the primary server.

For each client tool, you can create config files for individual machines (global) or for individual users. Configuration files are structured as JSON.

Save configuration files to these locations:
  • Global:
    • *nix — /etc/puppetlabs/client-tools/
    • Windows —%ProgramData%\puppetlabs\client-tools
  • User:
    • *nix — ~/.puppetlabs/client-tools/
    • Windows —%USERPROFILE%\.puppetlabs\client-tools

On managed client nodes where the operating system and architecture match the primary server, you can have PE manage Puppet code and orchestrator global configuration files using the puppet_enterprise::profile::controller class.

For example configuration files and details about using the various client tools, go to the documentation for each service:
Client tool Documentation
Orchestrator
Puppet access Token-based authentication
Puppet code Triggering Code Manager on the command line
PuppetDB PuppetDB CLI