Foreman

This chapter gives instruction for getting a basic configuration of Foreman Foreman working in a SIMP environment for monitoring purposes.

Note

The existance of this module does not mean SIMP recommends Foreman above any other monitoring tool for use with SIMP.

The pupmod-simp-foreman Module

The simp-foreman module is intended to install Foreman onto an existing and configured SIMP puppet master. Unlike the the Foreman installation tool, it will not erase your Puppet configuration. It provides a functioning Foreman web UI and is capable of handling smart-proxies, LDAP authentication, and Foreman user management. Puppet reports are sent to the foreman reporting tool where they are displayed in the default dashboard.

Note

For this release, only the monitoring-based services are supported. Foreman’s provisioning software has not been incorporated.

Note

All aspects of this module are known to work with SELinux in enforcing mode.

Warning

The Foreman does not run with FIPS mode enabled due to the use of the MD5 libraries by ActiveRecord. You can track the associated bug report as Issue 3511 in the Foreman Redmine.

Foreman Setup

Before installing the simp-foreman module, make sure you have read the Foreman documentation: Foreman. You will need to understand how to configure and use the monitoring. This documentation will also provide with current system requirements.

This installation and the instructions install Foreman on the Puppet server and is configured to use one Puppet server. You will have to change the installation to get it working on larger systems or if you want to install it on another server. Read the Foreman Documentation to help with that.

Configure and Install repositories

Some repositories and software collections must be imported to use the Foreman module. They are as follows.

For RedHat and CentOS systems

Configure SIMP to install Foreman

In order to setup the Foreman web UI, you’ll want to set the following in Hiera:

In the hosts/<puppet-server>.<your-domain>.yaml file, add the following:

# By default, the admin user password will be autogenerated and nonsensical looking.
# Set that here if you wish to have control over it.
foreman::admin_password : 'No one will never hack this!'
# These are the hosts that will connect to your Foreman proxy. You'll want to make sure
# all hosts who are reporting to Foreman appear here.
foreman::proxy::trusted_hosts :
  - your.first.host
  - your.second.host
  - your.nth.host

 # Make sure reporting is turned on in Puppet!
 pupmod::report : true

 # Include the classes to install foreman. (Obviously include all other necessary classes
 # for this host.
 classes:
   - foreman
   - site::foreman

Configuring Foreman to use LDAP

If you have LDAP configured in your SIMP and want to use it to access Foreman add something like the following to a a site manifest (ie /etc/puppet/environments/production/modules/site/manifest/foreman.pp):

class site::foreman {
  foreman::auth_source { 'my_awesome_ldap_server':
     ldap_server =>  'LDAPserver.your.domain',
     onthefly_register => true
  }
  foreman::user { 'amazing.user':
    auth_source => 'my_awesome_ldap_server',
    web_admin   => true,
    firstname   => 'Amazing',
    lastname    => 'User',
    password    => 'MyPassword'
  }
}

This class assumes foreman has already been included somewhere. Add ‘include foreman’ as the first line inside of the class if that is not true

The first section, foreman::auth_source, will configure Foreman to use your LDAP server. The setting “onthefly_register” configures Foreman to create a user from the user’s LDAP entry when they log into the web site the first time. By default a user is assigned the role of “ANONYMOUS,” which will give them an error when they log in. To prevent this you should use the Foreman administration interface to create User Groups. You link these groups to “Roles” and LDAP Groups. Then users in the appropriate LDAP group will get role linked to that group. See the Foreman users guide “Linking User Groups to LDAP” section for more information.

The second section, foreman::user, can be used to create foreman users in the Foreman database (if you are using LDAP, you don’t need this). If you add a user here and they are in LDAP, the password setting will be over written by the password in LDAP. It will error out if you don’t have a value for password. It will set it to the password value only if can not contact LDAP.

Finish the install

The three steps above should get you a working instance. Puppet must run several times to complete the install. Once Puppet runs cleanly, refer to the Foreman Documentation at http://www.theforman.org/ for information on further configuration options.

Troubleshooting

Rubygem errors during installation

If you get errors during installation that rubygems are the wrong version, you probably forgot to set up the epel repository. Foreman installs its own version of ruby and needs access to epel repositories.

Collecting Facts

If you want to collect facts, you will need to get a copy /etc/puppet/nodes.rb from the forman site (see the facts section of the foreman documentation) edit the foreman cron job under /etc/cron.d and uncomment out the collection and... give puppet the right to run cron jobs. To give puppet the right to run cronjobs add the following code to your forman.pp manifest under site:

pam::access::manage { 'foreman-puppet':
   users   => 'puppet',
   origins => ['cron']
}

Foreman Not Running

If you get the error

Error: Could not send report: Error 400 on SERVER: Could not autoload foreman: Class Foreman is already defined in Puppet::Reports

This is due to the foreman report module crashing and not unloading properly. Puppet won’t let it reload. This is a problem in Puppet 3.8. The only way you can fix it is to restart puppet. See: https://tickets.puppetlabs.com/browse/PUP-1189

Reports Not Collecting

If your reports are not collecting and you get an error like this in the /var/log/foreman/production.log:

“No smart proxy server found on [“puppet.your.domain”] and is not in trusted_puppetmaster_hosts”

Then you will need to set the trusted_puppetmaster_hosts setting in /etc/foreman/settings.yaml to point to your puppet server. (it should default to your puppet server but if you have more than one or have moved the foreman to another server it may error out.

You can set this variable by adding:

foreman::trusted_puppetmaster_hosts : "<your puppet server>"

to the hiera yaml file for the foreman server.