Installing agents

You can use the console to leverage tasks that install *nix or Windows agents on target nodes.

1. In the console, click Unsigned certs > Install an agent.
2. Select a transport method.
   • SSH for *nix targets
   • WinRM for Windows targets
3. Enter the target host names and the credentials required to access them. If you use an SSH key, include begin and end tags.
4. Click Install agent.
   Tip: Click Installation job started to view the job details for the task.
   Agents are installed on the target nodes and then automatically submit certificate signing requests (CSR) to the master. The list of unsigned certificates is updated with new targets.

PE provides its own package management to help you install agents in your infrastructure.

1. If you're installing an agent with a different OS than the master, add the appropriate class for the repo that contains the agent packages.
   1. In the console, click Classification, and in the PE Infrastructure group, select the PE Master group.
   2. On the Configuration tab in the Class name field, enter pe_repo and select the repo class from the list of classes.
      Note: The repo classes are listed as pe_repo::platform::<AGENT_OS_VERSION_ARCHITECTURE>.
   3. Click Add class, and commit changes.
   4. Run puppet agent -t to configure the master node using the newly assigned class.

      The new repo is created in /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.

2. SSH into the node where you want to install the agent, and run the installation command appropriate to your environment.
   • Curl

     curl -k https://<MASTER HOSTNAME>:8140/packages/current/install.bash | sudo bash

     Tip: On AIX, which doesn't support the -k option, use --tlsv1 instead. On other platforms that don't support the -k option, you must install using a manually transferred certificate.
   • wget

     wget -O - -q --no-check-certificate --secure-protocol=TLSv1 https://<MASTER HOSTNAME>:8140/packages/current/install.bash | sudo bash

   • Solaris 10 (run as root)

     export PATH=$PATH:/opt/sfw/bin
     wget -O - -q --no-check-certificate --secure-protocol=TLSv1 https://<MASTER HOSTNAME>:8140/packages/current/install.bash | bash

If you choose not to use PE package management to install agents, you can use your own package management tools.

1. Add the agent package to your own package management and distribution system.
2. Configure the package manager on your agent node (Yum, Apt) to point to that repo.
3. Install the agent using the command appropriate to your environment.
   • Yum

     sudo yum install puppet-agent

   • Apt

     sudo apt-get install puppet-agent

4. Configure the agent as needed: puppet config set

If you choose not to or can't use curl -k to trust the master during agent installation, you can manually transfer the master CA certificate to any machines you want to install agents on, and then run the installation script against that cert.

1. On the machine that you're installing the agent on, create the directory /etc/puppetlabs/puppet/ssl/certs.
2. On the master, navigate to /etc/puppetlabs/puppet/ssl/certs/ and transfer ca.pem to the certs directory you created on the agent node. 
3. On the agent node, verify file permissions: chmod 444 /etc/puppetlabs/puppet/ssl/certs/ca.pem
4. Run the installation command, using the --cacert flag to point to the cert:

      curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem https://<MASTER HOSTNAME>:8140/packages/current/install.bash | sudo bash

If you don't have access to the internet beyond your infrastructure, you can download the appropriate agent tarball from an internet-connected system and then install using the package management solution of your choice.

You can use the console to leverage tasks that install *nix or Windows agents on target nodes.

1. In the console, click Unsigned certs > Install an agent.
2. Select a transport method.
   • SSH for *nix targets
   • WinRM for Windows targets
3. Enter the target host names and the credentials required to access them. If you use an SSH key, include begin and end tags.
4. Click Install agent.
   Tip: Click Installation job started to view the job details for the task.
   Agents are installed on the target nodes and then automatically submit certificate signing requests (CSR) to the master. The list of unsigned certificates is updated with new targets.

To install a Windows agent with PE package management, you use the pe_repo class to distribute an installation package to agents. You can use this method with or without internet access.

1. In the console, click Classification, and in the PE Infrastructure group, select the PE Master group.
2. On the Configuration tab in the Class name field, select pe_repo and select the appropriate repo class from the list of classes.
   • 64-bit (x86_64) — pe_repo::platform::windows_x86_64.
   • 32-bit (i386) — pe_repo::platform::windows_i386.
3. Click Add class and commit changes.
4. On the master, run Puppet to configure the newly assigned class.

   The new repository is created on the master at /opt/puppetlabs/server/data/packages/public/<PE VERSION>/<PLATFORM>/.

5. On the node, open an administrative PowerShell window, and install:

   [Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; $webClient = New-Object System.Net.WebClient; $webClient.DownloadFile('https://<MASTER HOSTNAME>:8140/packages/current/install.ps1', 'install.ps1'); .\install.ps1

Notice: /Service[puppet]/ensure: ensure changed 'stopped' to 'running'
service { 'puppet':
  ensure => 'running',
  enable => 'true',
}

If you need to perform a secure installation on Windows nodes, you can manually transfer the master CA certificate to target nodes, and run a specialized installation script against that cert.

1. Transfer the installation script and the CA certificate from your master to the node you're installing.

   File	Location on master	Location on target node
   Installation script (install.ps1)	/opt/puppetlabs/server/data/packages/public/	Any accessible local directory.
   CA certificate (ca.pem)	/etc/puppetlabs/puppet/ssl/certs/	C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\

2. Run the installation script, using the -UsePuppetCA flag: .\install.ps1 -UsePuppetCA

Use the Windows .msi package if you need to specify agent configuration details during installation, or if you need to install Windows agents locally without internet access.

1. Install the agent on each node that you want to operate as a non-root user.
2. Log in to the agent node and add the non-root user:

   puppet resource user <UNIQUE NON-ROOT USERNAME> ensure=present managehome=true

   Note: Each non-root user must have a unique name.
3. Set the non-root user password.

   For example, on most *nix systems: passwd <USERNAME>

4. Stop the puppet service:

   puppet resource service puppet ensure=stopped enable=false

   By default, the puppet service runs automatically as a root user, so it must be disabled.

5. Disable the Puppet Execution Protocol agent.
   1. In the console, click Classification, and in the PE Infrastructure group, select the PE Agent group.
   2. On the Configuration tab, select the puppet_enterprise::profile::agent class, specify parameters, click Add parameter, and then commit changes. 

      Parameter	Value
      pxp_enabled	false

6. Change to the non-root user and generate a certificate signing request:

   puppet agent -t --certname "<UNIQUE NON-ROOT USERNAME.HOSTNAME>" --server "<MASTER HOSTNAME>"

   Tip: If you wish to use su - <NON-ROOT USERNAME> to switch between accounts, make sure to use the - (-l in some unix variants) argument so that full login privileges are correctly granted. Otherwise you might see permission denied errors when trying to apply a catalog.
7. On the master or in the console, approve the certificate signing request.
8. On the agent node as the non-root user, set the node's certname and the master hostname, and then run Puppet.

   puppet config set certname <UNIQUE NON-ROOT USERNAME.HOSTNAME> --section agent

   puppet config set server <PUPPET MASTER HOSTNAME> --section agent

   puppet agent -t

   The configuration specified in the catalog is applied to the node.

   Tip: If you see Facter facts being created in the non-root user’s home directory, you have successfully created a functional non-root agent.

1. Install the agent on each node that you want to operate as a non-root user.
2. Log in to the agent node and add the non-root user:

   puppet resource user <UNIQUE NON-ADMIN USERNAME> ensure=present managehome=true password="puppet" groups="Users"

   Note: Each non-root user must have a unique name.
3. Stop the puppet service:

   puppet resource service puppet ensure=stopped enable=false

   By default, the puppet service runs automatically as a root user, so it must be disabled.

4. Change to the non-root user and generate a certificate signing request:

   puppet agent -t --certname "<UNIQUE NON-ADMIN USERNAME>" --server "<MASTER HOSTNAME>"

   Important: This Puppet run submits a cert request to the master 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.
5. As the non-root user, create a configuration file at %USERPROFILE%/.puppet/puppet.conf to specify the agent certname and the hostname of the master:

   [main]
   certname = <UNIQUE NON-ADMIN USERNAME.hostname>
   server = <MASTER HOSTNAME>

6. As the non-root user, submit a cert request: puppet agent -t.
7. On the master or in the console, approve the certificate signing request.
   Important: It's possible to sign the root user certificate in order to allow that user to also manage the node. However, this introduces the possibility of unwanted behavior and security issues. For example, if your site.pp has no default node configuration, running the agent as non-admin could lead to unwanted node definitions getting generated using alt hostnames, a potential security issue. If you deploy this scenario, ensure the root and non-root users never try to manage the same resources, have clear-cut node definitions, ensure that classes scope correctly, and so forth.
8. On the agent node as the non-root user, run Puppet: puppet agent -t.

   The configuration specified in the catalog is applied to the node.