Install non-root agents

You can configure non-root agents on *nix and Windows nodes. Running agents without root privileges allows teams to perform some, but not all, administrative actions in Puppet Enterprise (PE) that would otherwise require root privileges.

For example, assume a team with root privileges maintains your infrastructure’s platform, and a separate team with diminished privileges maintains your infrastructure’s applications. If the application team needs to manage their part of the infrastructure independently, they can do this by running Puppet without root privileges.

Non-root users can perform a reduced set of management tasks, including configuring settings, configuring Facter external facts, running puppet agent --test, and running Puppet with non-privileged cron jobs or a similar scheduling service. Non-root users can also classify nodes by writing or editing manifests in directories where they have write privileges.

By default, PE is installed with root privileges; therefore, a root user must install the agent and configure non-root access to the primary server. The root user also sets up non-root users on the primary server and relevant agent nodes.

Note: In Windows, the administrator is equivalent to the root user. For the sake of simplicity, our documentation might use root to refer to either the root user or the administrator.

Non-root user functionality

Non-root users can use a subset of administrative functionality. Non-root agents can't perform any operations requiring root privileges, such as installing system packages.

*nix non-root functionality

Non-root users on *nix agents can enforce these resource types, with some caveats as noted:
  • augeas
  • cron: Can only view or set non-root cron jobs
    • If you run a cron job as non-root user and you use the -u flag to sets a user with root privileges, the job fails with this error message: Notice: /Stage[main]/Main/Node[nonrootuser]/Cron[illegal_action]/ensure: created must be privileged to use -u
  • exec: Cannot run as another user or group
  • file: Non-root user must have read/write privileges
  • notify
  • schedule
  • service
  • ssh_authorized_key
  • ssh_key

Non-root users on *nix agents can inspect host, mount, and package resource types with the puppet resource <RESOURCE_TYPE> command.

Windows non-root functionality

Windows non-root agents are limited in comparison to *nix non-root agents. While you can enforce and inspect some resource types, you are limited to what the agent user has permission to do, which isn't much by default. For example, you can't create a file or directory in C:\Windows unless the agent user has permission to do so.

Non-root users on Windows agents can enforce exec and file resource types.

Non-root users on Windows agents can use the puppet resource <RESOURCE_TYPE> command to inspect these resource types:
  • host
  • package
  • user
  • group
  • service

Install non-root *nix agents

To configure a *nix agent node to run without root privileges, a root user must install the agent, configure non-root access to the primary server, and set up non-root users on the primary server and relevant agent nodes.

Before you begin
Install the agent on each node you want to operate without root privileges. You can Install agents with the install script, Install agents from the console, or use one of the other methods to Install *nix agents.
Note: Unless specified otherwise, perform these steps as a root user or with sudo.
  1. Log in to the agent node and run this command to add the non-root user: 
    sudo puppet resource user <UNIQUE_NON-ROOT_USERNAME> ensure=present managehome=true
    Note: Each non-root user must have a unique name.
  2. Set the non-root user password. On most *nix systems, you can use passwd <USERNAME> to do this.
  3. Because the puppet service runs as an administrator by default, you must disable it. To stop the puppet service run: 
    sudo puppet resource service puppet ensure=stopped enable=false
  4. Disable the Puppet Execution Protocol (PXP) agent.
    1. In the console, click Node groups, and in the PE Infrastructure group, select the PE Agent group.
    2. On the Classes tab, select the puppet_enterprise::profile::agent class.
    3. Set the pxp_enabled parameter to false.
    4. Click Add parameter and commit changes.
  5. Switch to the non-root user.
    Important: If you use su - <NON-ROOT USERNAME> to switch accounts, use the - argument (or -l, in some Unix variants) to correctly grant full login privileges. Otherwise you might get permission denied errors when trying to apply a catalog.
  6. As the non-root user, run this command to generate a CSR: 
    sudo puppet agent -t --certname "<UNIQUE_NON-ROOT_USERNAME.HOSTNAME>" --server "<PRIMARY_HOSTNAME>"
    Make sure to format the certname string correctly by combining the non-root user's username and the hostname with a period between.
  7. On the primary server or in the PE console, approve the CSR.
  8. On the agent node as the non-root user, run these three commands to set the node's certname, set the primary server's hostname, and run Puppet: 
    sudo puppet config set certname <UNIQUE_NON-ROOT-USERNAME.HOSTNAME> --section agent
sudo puppet config set server <PRIMARY_HOSTNAME> --section agent
sudo puppet agent -t
    The certname and hostname are defined in the node's puppet.conf file.
Results
The configuration specified in the catalog is applied to the agent node.
What to do next
If you see Facter facts being created in the non-root user’s home directory, you have successfully configured a functional non-root agent. To confirm the non-root agent's configuration, verify that:
  • The agent can request certificates and apply the catalog from the primary server when a non-root user runs Puppet. As a non-root user, try running puppet agent -t to test this.
  • The agent service is not running. Run service puppet status to check this.
  • Non-root users can collect existing facts by running facter on the agent.
  • Non-root users can define new external facts.

Install non-root Windows agents

To configure a Windows agent node to run without root privileges, a root user must install the agent, configure non-root access to the primary server, and set up non-root users on the primary server and relevant agent nodes.

Before you begin
Install the agent on each node you want to operate without root privileges. You can Install agents with the install script, Install agents from the console, or use one of the other methods to Install Windows agents.
Note: Unless specified otherwise, perform these steps as an administrator.
  1. Log in to the agent node, open a command prompt as an administrator, and run this command to add the non-root user: 
    puppet resource user <UNIQUE_NON-ADMIN_USERNAME> ensure=present managehome=true password="<PASSWORD>" groups="<EXISTING_GROUP>"
    Note: Each non-root user must have a unique name.
  2. Because the puppet service runs as an administrator by default, you must disable it. To stop the puppet service, open a command prompt as an administrator and run: 
    puppet resource service puppet ensure=stopped enable=false
  3. Switch to the non-root user and run this command to generate a CSR: 
    puppet agent -t --certname "<UNIQUE_NON-ADMIN_USERNAME.hostname>" --server "<PRIMARY_HOSTNAME>"
    Make sure to format the certname string correctly by combining the non-root user's username and the hostname with a period between.
    Important: This Puppet run submits a CSR to the primary server and creates a /.puppet directory structure in the non-root user’s home directory. If this directory is not created automatically, you must manually create it before continuing.
  4. As the non-root user, create a puppet.conf file in the .puppet directory (at %USERPROFILE%/.puppet/). Edit the puppet.conf file and specify the agent certname and the primary server's hostname. For example: 
    [main]
certname = <UNIQUE_NON-ADMIN_USERNAME.hostname>
server = <PRIMARY_HOSTNAME>
  5. As the non-root user, run puppet agent -t to submit a CSR.
  6. On the primary server or in the PE console, approve the CSR.
    Important: It's possible to sign the root user certificate to allow the non-admin user to also manage the node; however, this is a security concern due to the opportunity for unwanted behavior. For example, if your site.pp has no default node configuration, and a non-admin user runs the agent, unwanted node definitions could be generated with alt hostnames, which is a potential security issue. If you elect to allow non-admin users to also manage nodes, make sure you take precautions such as having clear node definitions, correctly scoping classes, and ensuring root and non-root users never try to manage the same resources.
  7. On the agent node as the non-root user, run puppet agent -t
Results
The configuration specified in the catalog is applied to the node.