gawainXX/Foreman_Puppet_7.x_Raspbian.md

## Foreman_Puppet_7.x_Raspbian.md

      
    Raw
  

              Foreman_Puppet_7.x_Raspbian.md
            
          
    How to add a Raspberry Pi 10 (Buster) agent device to Foreman for management and Remote Execution

These instructions were tested on a pi 3b and 4b with the latest version of raspbian (Raspbian GNU/Linux 10 (Buster)).


This guide assumes basic competency with the command line. It also assumes your Foreman Proxy/Server and the client device you are going to be managing meet the following criteria.
Raspberry Device Configuration Requirements

OS is Raspbian 10 Buster (armhf)
Root is enabled with a set password.
SSH is enabled with PermitRootLogin is either set to prohibit-password or yes in /etc/ssh/sshd_config

prohibit-password is ideal because it reduces the chance of a password spray attack


The Raspberry device has a properly set, unique hostname. (localhost or duplicate hostnames will cause problems with the cert generation)

Foreman Proxy Configuration Requirements

Puppet, PuppetCA and SSH Smart Proxy features are installed.
The system's Fully Qualified Domain Name is resolvable by the client via DNS.
Inbound traffic is allowed for Smart Proxy and Puppet Proxy service ports. Defaults are 443,9090, 8140
You are able to SSH into the Foreman Smart Proxy server in order to sign the requested certificate and push the Proxy's Public Cert to the device, for remote execution.
Outbound traffic is allowed from the Proxy server to the target device via SSH, Port 22


I should note that I am fairly new to Foreman, Puppet and not an expert in these domains. There may be oversights or more effective ways to perform this process. 

The steps provided by aaroncoffey on the following GitHub page were used as a base for this document. https://gist.github.com/aaroncoffey/2459738bb9fb3d91f237455a4c577e9c

Connect to the Raspberry device via SSH and then run the following commands

Switch to Root Context

sudo su -

Your command prompt should now display Root@HOSTNAME:~#
Update repository and locally installed packages

apt update -y
apt upgrade -y

Install ruby

sudo apt install ruby-full -y

Install Puppet

gem install puppet

Configure Puppet Agent settings

Replace foreman.localdomain with the FQDN of the Foreman Puppet Proxy that will be managing the device.
mkdir -p /etc/puppetlabs/puppet/
# Create Puppet Agent configuration file
cat << EOF > /etc/puppetlabs/puppet/puppet.conf
[agent]
    server = "foreman.localdomain"
EOF

Create Puppet service configuration file

cat << EOF > /etc/systemd/system/puppet.service
#
# Local settings can be configured without being overwritten by package upgrades, for example
# if you want to increase puppet open-files-limit to 10000,
# you need to increase systemd's LimitNOFILE setting, so create a file named
# "/etc/systemd/system/puppet.service.d/limits.conf" containing:
# [Service]
# LimitNOFILE=10000
# You can confirm it worked by running systemctl daemon-reload
# then running systemctl show puppet | grep LimitNOFILE
#
[Unit]
Description=Puppet agent
Wants=basic.target
After=basic.target network.target

[Service]
EnvironmentFile=-/etc/sysconfig/puppetagent
EnvironmentFile=-/etc/sysconfig/puppet
EnvironmentFile=-/etc/default/puppet
ExecStart=/usr/local/bin/puppet agent $PUPPET_EXTRA_OPTS --no-daemonize
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process

[Install]
WantedBy=multi-user.target
EOF

Enable the Puppet service

systemctl enable --now puppet.service

Perform the initial agent bootstrap

This task will perform the initial agent communication, generate a cert and then try again after two minutes, giving you an opportunity to sign the cert on the server.
puppet ssl bootstrap

While the ssl bootstrapper is running, approve the agent certificate from the Foreman WebUI


On your Foreman Server;

Navigate to Infrastucture > Smart Proxies
Click the name of the Proxy server you're using to manage the device.
Click the Puppet CA tab
Click the Certificates sub tab
Find the Certificate Name that your device is requesting
Click the Reoke button next to that certificate


After the ssl bootstrap finishes, perform an agent poll and verfiy everything is green

puppet agent --test

Verify that the device is now displayed within foreman within Hosts > All Hosts

If this step failed, see the troubleshooting section
Copy the public key to the agent device, enabling Remote Execution


Open a text editor program, which we will be using as a scratch space

Paste the following into the text editor program


mkdir -p ~/.ssh
# Create Puppet Agent configuration file
cat << EOF > ~/.ssh/authorized_keys
#PLACEHOLDER
EOF
systemctl restart sshd


From the Foreman WebUI, navigate to Hosts > All Hosts and click on the host you are adding
Click on the Puppet YAML tab
Locate the line remote_execution_ssh_keys:

Underneath it there should be a line of text that starts like* - ssh-rsa......*
copy that entire line starting with ssh-rsa (exclude " - " at the  the very beginning of the line)
Paste the ssh-rsa.... sting into your text editor program , replacing #PLACEHOLDER
Run the block of code you have now created on the agent system


Test remote execution by going to the Host within Foreman , clicking Schedule Remote Job and then running a simple command such as uname -a


Troubleshooting


Invalid Certificate Error

You may receive a certificate error if there is a already a certificate stored on the proxy that has a conflicting name.

First, verify that the certificate name being requested is correctly named and that you do not have another active device that has the same hostname as the device you are adding.
Remove the stale certificate by following these steps
On your Foreman Server;

Navigate to Infrastucture > Smart Proxies
Click the name of the Proxy server you're using to manage the device.
Click Actions > Refresh
Click the Puppet CA tab
Click the Certificates sub tab
Click the filter by state dropdown menu and select pending
Find the Certificate Name that you're devices is trying to use
Click the Sign button next to that certificate


On the agent device;

Run the following command
puppet ssl clean


Retry the process beginning at section Perform an agent poll (1)


Device checks in but is not listed under All Hosts.

See if the device is listed if you change orgnization to Any Orgnization as it may be orphaned
If the device is still not listed, connect to your Foreman server's console via SSH
Run the following commands in sequence to query whether there is data for that host, replace HOSTNAME with your device's hostname
foreman-rake console
Host.find_by_name("HOSTNAME")
If you receive a bunch of values, make sure that the fields organization_id and location_id are properly set and not 'nil'

to set those values, run these commands in sequence within the foreman-rake console,replacing HOSTNAME with the name of your device, if you have more then one location or org, change the org and location values to what is correct for your environment
host = Host.find_by_name("HOSTNAME")
host.update_attribute(:organization_id, 1)
host.update_attribute(:location_id, 2)
host.update_attribute(:operatingsystem_id, 11)


Check to see if the device is now listed under "All Hosts"

In extreme cases you might need to do the above steps and then