Puppet Enterprise 2017.3

PE client tools are a set of command line tools that let you access Puppet Enterprise services from a workstation that may or may 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 master.

Client tools versions align with PE versions. For example, if you're running PE 2017.3, you should use the 2017.3 client tools. In some cases, we may issue patch releases ("x.y.z") for PE or the client tools. You don't need to match patch numbers between PE and the client tools. Only the "x.y" numbers need to match.

Important: When you upgrade PE to a new "x.y" version, install the appropriate "x.y" version of 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-app.
  • 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 master 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 these platforms.

Operating system Version(s) Arch
Red Hat Enterprise Linux6, 7 x86_64
CentOS6, 7 x86_64
Oracle Linux 6, 7 x86_64
Scientific Linux6, 7 x86_64
SUSE Linux Enterprise Server11, 12 x86_64
Ubuntu14.04. 16.04 x86_64
Windows (Consumer OS) 7, 8.1, 10 x86_64
Windows Server (Server OS) 2012, 2012r2, and 2012r2 core x86_64
Mac OS X10.10, 10.11 x86_64

Install PE client tools on a managed workstation

To use the client tools on a system other than the master, 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 master 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 master 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 master.
  • 4433 — The Puppet access client uses this port to communicate with the RBAC service running on the master.
  • 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 master, 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 master.
  5. Download the pe-client-tools package for the platform appropriate to your workstation.
  6. Unpack the tarball and navigate to the packages/<PLATFORM> directory.
  7. 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 master, 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 master.
  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 Mac OS X workstation

You can install the client tools on a Mac OS X workstation using Finder or the command line.

  1. On the workstation, create the directory /etc/puppetlabs/puppet/ssl/certs.
  2. On the master, 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 master.
  5. Install the client tools using Finder or the command line.
    • Finder
      1. Download the OS Xpe-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 OS Xpe-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

After installing the tools, see the corresponding documentation to configure and start using each client tool.

For the Puppet access, Puppet code, or orchestrator clients, you can use a global configuration file for each service, or create a configuration file for each service on a per user basis. Instructions for creating configuration files are located in the corresponding documentation.

Global configuration file management

If you're running the Puppet code or orchestrator clients from a managed machine, you can have PE manage these clients' global configuration files with the puppet_enterprise::profile::controller class. This class manages global configuration files in /etc/puppetlabs/client-tools/.

If you're running a client from a workstation, you must create the global file and populate it with the correct configuration file settings. PE can't manage a configuration file from a non-managed workstation.

Back to top