New! Support for Non-Root Agents in Puppet Enterprise

Traditionally, Puppet Enterprise agents are run as root-privileged processes. That’s in order to enable the iron-fist style of configuration management — that is, to fully own a system’s configuration, root privileges are a requirement.

But there are times when you want people to be able to manage resources with Puppet Enterprise without giving them root access. That’s why we introduced a new capability in Puppet Enterprise 3.2: the ability to run Puppet agents with non-root privileges.

What follows here is an introduction to help you, the IT practitioner, get grounded in what it means to run Puppet Enterprise non-root, and how to get started. For detailed step-by-step guidance, you’ll want to consult the documentation.

What Root Is Needed for in Puppet Enterprise

Puppet ensures configuration state for precisely what you ask it to. At one extreme, Puppet can be given an exhaustive definition of desired system configuration, and manage the system to a T, ruling with an idempotent iron fist. At the other extreme, Puppet could do almost nothing: You could provide an empty definition, and Puppet would run, report on general system information (facts), and end the run having neither contested nor checked even one iota of configuration.

You need root access to install packages using yum or apt. Root is required for starting, stopping, or refreshing system services. Root is required for editing many configuration files under /etc. If you’re going to fully own and control a system’s configuration, you must have root access.

But not everyone who’s in charge of managing parts or aspects of a system has root access. So we’ve made it possible for more people on your team to automate their management tasks with Puppet Enterprise by enabling non-root users to run agents.

Where Non-Root Agents are Useful

The classic separation-of-duties security model means many organizations task different teams with different responsibilities. One team can be responsible for the platform level configuration, such as user accounts, system packages and firewall configuration, while another team entirely is responsible for setting up and configuring business-specific applications. Through a combination of accessible user-level resources and selective privilege escalation, the full set of actions a practitioner needs to be able to take to configure a specific application can be accomplished using a restricted account.

An algorithmic means of quickly determining whether or not Puppet automation for application X is possible has always been to start by asking whether or not it is possible to perform the configuration through unattended means. If the answer is yes, configuration can be performed unattended, then in general it's safe to say Puppet can automate it. By that back-of-the-envelope calculation, it’s obvious that automation is not restricted to privileged users, so why would Puppet be? After all, we want everyone involved in system management to be able to use automation as much as possible.

What’s Different in Puppet Enterprise 3.2

Logging into a system as a restricted user and running the puppet command has worked at a basic level for a long time. But until the release of Puppet Enterprise 3.2, running agents non-root hasn’t been a supported use case, with the product requirements, documentation, and acceptance tests that all underlie full support.

As an unsupported feature, the non-root user experience prior to Puppet Enterprise 3.2 was unpredictable. Changes to Facter released in version 1.7.0 didn’t take non-root use cases into account, and introduced behavior that could cause Facter to abort when run by an unprivileged user. A variety of commonly used Puppet extensions required arcane configuration tweaks to enable non-root agent runs.

The ability to run Puppet agents with non-root privileges is now fully documented, supported and comes with clear guidance around how it works, when it should be used and when it shouldn't. This capability makes Puppet Enterprise available to many more people on your technical team, freeing them from repetitive tasks and giving them time back to do more interesting (and strategic) things.

How-To: Setting up and Running Non-Root Puppet in Puppet Enterprise

All right, enough talk.

Detailed technical documentation for making use of the “Puppet Agent with Non-Root Privileges” feature can be found in the Puppet Enterprise documentation, specifically the Running PE Agents without Root Privileges section. Since that resource exists I won’t dive too deep here, but I will present a teaser overview of how to set all this up and make use of it.

Before Puppet can be used by a non-root user, it has to be installed. The supported non-root use cases of Puppet Enterprise don’t include laying down Puppet itself, only using it. In this way, it’s pretty much the same as what you can expect for curl or ssh. Once installed, anybody can use it, but getting the packages on the system is still going to require an administrator to run yum install or the equivalent.

Admin Preparation

Here’s the process an administrator must take to prep the system for running a non-root Puppet agent:

  1. Install the Puppet Enterprise agent. The interactive installer will ask for things like the location of the puppet master server. These questions are irrelevant when Puppet will be running without root privileges. You can either refrain from answering or supply dummy data, because guess what the next step is:
  2. Disable the pe-puppet service. Yep, that’s right: As a privileged user, you’re going to run the following command to completely disable the service. The pe-puppet service represents authoritative management of the system. In a non-root scenario, we’ll be handling Puppet on a per-user basis, not at the system level.

    puppet resource service pe-puppet ensure=stopped enable=false
  3. Disable the pe-mcollective service: MCollective is not in scope for Puppet Enterprise without root.

    puppet resource service pe-mcollective ensure=stopped enable=false

Note On The Puppet Master

None of the Puppet Enterprise master services run as root, and all have dedicated service user accounts. Therefore, while installation of the master (like the agent) must be handled by an admin, control over and administration of the puppet master server can be effectively handed off without granting root access by granting access to the pe-puppet service user account, along with sudo permissions for start/stop/restart of several services. See the official documentation for further details.

Using User Puppet

Now that it’s installed, any user on the system can run puppet. Everything in the docs, everything online about how to configure Puppet, the settings that can be set in puppet.conf — it all applies. As far as differences go, there are a few things that need to be done differently when preparing to run puppet from a user account.

First, you should know where to go to configure your user instance of Puppet. Like many applications, Puppet stores an individual user’s configuration in the user’s home directory. Specifically, Puppet will look for puppet.conf in $HOME/.puppet/puppet.conf by default. This gives you your go-to file for setting everything you care about, though there isn’t much here you’ll need to change or set as the defaults are quite sane. You will need, however, to create the $HOME/.puppet directory, as Puppet will not always create it without being asked.

puppet resource file $HOME/.puppet ensure=directory

Next, you will want to explicitly set the certname for your user instance of Puppet. You need to do this because the default certname will simply be the hostname or fully-qualified domain name of the system, rather than a user-unique identifier. If only one user on the box will ever be running Puppet that’s fine. The potential problem is that the certname represents a unique agent identity and cannot be shared between Puppet instances — the puppet master will not sign a certificate request if it is already aware of a certificate matching the requested name. Therefore, the first step each non-root user should take when starting Puppet for the first time is to choose and configure a unique certname. A simple convention might be user@hostname.

puppet config set certname user@host.example.tld --section agent

Finally, at a minimum, a puppet agent needs to know where the master is. Assuming the puppet master is puppet.example.com, it can be set by running a command such as the following.

puppet config set server puppet.example.com --section agent

Now the non-root user is ready to manually run puppet agent --test. The agent will connect to the master, request a certificate, and after the certificate has been signed, it will be able to download catalogs, apply them, and submit reports to the master. All as per usual, and exactly as experienced Puppet uses will expect.

What’s missing still is persistence. When running Puppet on a per-user basis, there is no systemd, no Upstart, no System-V init. If you want the agent to run periodically, as the root-enabled service would, you need to set that up yourself. The simplest method would probably be a cron job or a scheduled task. Automation of this step is of course quite easy, as the non-root puppet agent can now configure itself, given appropriate classification from the master. For example:

class user_puppet_agent {
  cron { 'puppet_agent':
    ensure  => present,
    command => '/opt/puppet/bin/puppet agent --onetime',
    minute  => ['0', '30'],
  }
}

With that, a non-root puppet agent has been configured, set up, and optionally, set to run every 30 minutes and enforce whatever classification is passed down from the Puppet Enterprise master.

Need More? Get Docs

For more information about running puppet agents with non-root privileges, and a detailed step-by-step setup reference, you’ll want the official documentation.

Reid Vandewiele is a technical solutions engineer at Puppet Labs.

Learn More

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.