Foreman

Foreman is a host management system for Linux systems.

Foreman in addition to Katello, Pulp, and Candlepin, provides the base system for Red Hat Satellite 6.

Installation

Foreman (with Katello)

Foreman can be installed on most Linux distributions as well as in Docker (though, the image would need to use systemd since the puppet modules depend on it). This section will go over the steps needed to get Foreman running on a server.

On a clean CentOS 7 system:

## Update system
# yum clean all

## Install repos
# yum -y localinstall http://fedorapeople.org/groups/katello/releases/yum/3.6/katello/el7/x86_64/katello-repos-latest.rpm
# yum -y localinstall http://yum.theforeman.org/releases/1.17/el7/x86_64/foreman-release.rpm
# yum -y localinstall https://yum.puppetlabs.com/puppetlabs-release-pc1-el-7.noarch.rpm
# yum -y localinstall http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

## Update packages and install new ones
# yum -y update
# yum -y install foreman-release-scl python-django katello tfm-rubygem-foreman_dhcp_browser

Ensure that the server's hostname resolves properly. If it does not (such as if you're doing this in a test environment), add it to the hosts file. For example:

# cat /etc/hosts
## The FQDN should be first
192.168.154.129    foreman.lab.cpsc.ucalgary.ca foreman

Make sure hostnames are correct

Verify that hostname returns the hostname with no domain and hostname -f returns the full FQDN.

If this isn't the case and you continue with the installation, foreman will glitch out with issues such as:

• Not being able to add the domain to foreman, with it saying it already exists
• Adding a new host will cause the domain to be appended to the hostname twice

The foreman-installer will bootstrap the installation process using the puppet modules installed in the previous step. Start the installer by running:

foreman-installer --scenario katello \
  --foreman-servername foreman \
  --foreman-serveraliases foreman \
  --foreman-initial-organization "U of C" \
  --foreman-initial-location "CPSC" \
  --foreman-db-type postgresql \
  --foreman-db-username foreman \
  --foreman-db-database foreman \
  --foreman-db-password 1GwtY31DEsQFLEVdH0oh \
  --foreman-db-manage true \
  --enable-foreman \
  --enable-foreman-plugin-discovery  \
  --enable-foreman-plugin-default-hostgroup  \
  --enable-foreman-plugin-templates  \
  --enable-foreman-plugin-hooks \
  --enable-foreman-proxy \
  --enable-foreman-proxy-plugin-pulp \
  --enable-katello \
  --enable-puppet

This stage takes a while. Make a note of the user credentials after installation succeeds.

Allow the foreman webservice, puppet, and optionally the database (for debugging purposes) through the firewall using the firewall-cmd command.

## HTTP / HTTPS
# firewall-cmd --permanent --add-port=80/tcp
# firewall-cmd --permanent --add-port=443/tcp
## Puppet
# firewall-cmd --permanent --add-port=8140/tcp
## Postgresql (only if remote connection is needed)
# firewall-cmd --permanent --add-port=5432/tcp

## Reload the firewall
# firewall-cmd --reload

You may also want to disable SELinux to simplify the debugging step on a test environment.

## Do so only if you really want to disable SELinux. Foreman should work with SELinux enabled.
# setenforce 0
# vi /etc/selinux/config

The initial setup will take a while. Once this step is complete, you should be able to access the Foreman web interface using a web browser.

Smart Proxy

A Foreman Smart Proxy provides a RESTful interface that interacts with certain services such as DHCP or DNS.

The foreman-installer can be used to install the smart proxy. Ensure that the installer does not install foreman by disabling that feature.

You may wish to use this answers file to configure a smart proxy to handle DHCP, DNS (on a remote AD server), and TFTP: https://paste.steamr.com/view/8cff58b8

Alternatively, you may install the smart proxy using the foreman-proxy package and then configuring the proxy manually by editing /etc/foreman-proxy/settings.yml.

Plugins

Plugins can be enabled when running foreman-installer.

Additional plugins can also be installed using pre-built packages. For example:

# yum install tfm-rubygem-foreman_dhcp_browser tfm-rubygem-foreman_salt

Plugins that can be configured will have their configuration files placed in /etc/foreman/plguins.

Configuration

Foreman

A few things that should be done after a clean install:

1. Add smart proxies
2. Set up domains. (Infrastructure -> Domains)
   • Set location, organization, smart proxy
3. Set up subnets. (Infrastructure -> Subnets)
   • Set location, organization, smart proxy
4. Add kickstart templates
   • Set location, organization
5. Create an Operating System Media (Hosts -> Installation Media)
   • Set location, organization
   • Fedora: http://mirror.cpsc.ucalgary.ca/mirror/fedora/linux/releases/$version/Everything/$arch/os/
   • CentOS: http://mirror.cpsc.ucalgary.ca/mirror/centos.org/$version/os/$arch/
6. Create an Operating System (Hosts -> Operating Systems)
   • Set kickstart template, operating system media, partition table, location, organization
   • Fedora: 28
   • CentOS: 7, 5.1804
7. Configure Host Groups (Configure -> Host Groups)

   • CentOS	
     CentOS/Servers	
     Fedora	
     Fedora/Lab	
     Fedora/Lab/Graphics	
     Fedora/Lab/Pi	
     Unmanaged
     

   • Each with package_groupX

Puppet

Puppet modules can be installed on the puppet master (on foreman) by running:

# puppet module install puppetlabs-ntp --version 7.1.1

If it is working, the module should be placed in /etc/puppetlabs/code/environments/production/modules.

Since installing this module changed the contents in the 'production' environment, you can 'sync' the changes by importing it through the foreman web interface under 'Configure' -> 'Environments'.

If importing an environment succeeds but doesn't actually import anything, make sure that all hosts do not have an environment set and try again.

Host Groups

This is specific to computer science.

Ensure that each host group has the following parameter:

Name	Value
install_type	text
system_type	text
ntp-server	ntp.cpsc.ucalgary.ca
time-zone	America/Edmonton
salt_master	salt.cs.ucalgary.ca
package_groups0	cpsc-base
remote_execution_ssh_keys	*authorized_keys* for root

Default PXE Menu

The default PXE menu that is shown is configured by the /var/lib/tftpboot/pxelinux.cfg/default file. This file is generated by Foreman using the default template "PXELinux global default" when you click on the "Build PXE Default" button on the Provisioning Template page on all (?) smart proxies that have been configured with TFTP.

Troubleshooting

Custom Certificates

If using self-signed certificates you may get:

/Stage[main]/Foreman_proxy::Register/Foreman_smartproxy[foreman-proxy2.lab.cpsc.ucalgary.ca]: Could not evaluate: Exception SSL_connect returned=1 errno=0 state=error: certificate verify failed in get request to: https://foreman.lab.cpsc.ucalgary.ca/api/v2/smart_proxies?search=name=%22foreman-proxy2.lab.cpsc.ucalgary.ca%22
/usr/share/foreman-installer/modules/foreman/lib/puppet/provider/foreman_resource/rest_v3.rb:89:in `rescue in request'
/usr/share/foreman-installer/modules/foreman/lib/puppet/provider/foreman_resource/rest_v3.rb:71:in `request'
/usr/share/foreman-installer/modules/foreman/lib/puppet/provider/foreman_smartproxy/rest_v3.rb:6:in `proxy'
/usr/share/foreman-installer/modules/foreman/lib/puppet/provider/foreman_smartproxy/rest_v3.rb:13:in `id'
/usr/share/foreman-installer/modules/foreman/lib/puppet/provider/foreman_smartproxy/rest_v3.rb:17:in `exists?'

Fix this by adding the self-signed certificate from the foreman server to the foreman proxy system.

[root@foreman]# cp "/etc/puppetlabs/puppet/ssl/certs/ca.pem" 
[root@foreman-proxy2 anchors]#  cp ca.pem /etc/pki/ca-trust/source/anchors
[root@foreman-proxy2 anchors]# update-ca-trust extract
[root@foreman-proxy2 anchors]# wget -O - https://foreman.lab.cpsc.ucalgary.ca/api/v2/smart_proxies
--2018-06-01 12:45:47--  https://foreman.lab.cpsc.ucalgary.ca/api/v2/smart_proxies
Resolving foreman.lab.cpsc.ucalgary.ca (foreman.lab.cpsc.ucalgary.ca)... 192.168.154.129
Connecting to foreman.lab.cpsc.ucalgary.ca (foreman.lab.cpsc.ucalgary.ca)

DNS Update Failure

If you get...

D, [2018-06-08T16:03:36.393622 666bc3da] DEBUG -- : Requesting credentials for Kerberos principal foremanproxy/foreman-proxy.lab.cs.ucalgary.ca@LAB.CS.UCALGARY.CA using keytab /etc/foreman-proxy/dns.keytab
E, [2018-06-08T16:03:36.393967 666bc3da] ERROR -- : Failed to initialise credential cache from keytab: krb5_get_init_creds_keytab: Key table entry not found
E, [2018-06-08T16:03:36.394216 666bc3da] ERROR -- : Failed to initailize credentials cache from keytab: krb5_get_init_creds_keytab: Key table entry not found
D, [2018-06-08T16:03:36.394293 666bc3da] DEBUG -- : Failed to initailize credentials cache from keytab: krb5_get_init_creds_keytab: Key table entry not found (RuntimeError)

Then it means your principal name or keytab file is wrong. Fix this by editing the dns_nsupdate_gss.yml so that :dns_tsig_principal: is defined to the proper principal name.

Cannot PXE Boot - PXE-E79

PXE-E79: NBP is too big to fit in free base memory

You're trying to boot a UEFI program while in legacy BIOS mode. You probably selected GRUB2-EFI as the boot loader rather than legacy BIOS when setting up your host.

Cannot import Puppet Environment

If importing an environment succeeds but doesn't actually import anything, make sure that all hosts do not have an environment set and try again.

If it still doesn't work, try clearing the puppet environment classes and try again. DELETE FROM "environment_classes";

See Also

API reference

• https://theforeman.org/api/1.8/index.html