1. Overview
2. Module Description - What the SIMP Foreman module provides
3. Setup - The basics of getting started with Foreman
   • What Foreman affects
   • Setup Requirements
   • Beginning with Foreman
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

A SIMP specific implementation of the Foreman. Designed to be able to incorporate the Foreman into a previously existing and configured puppet master.

The SIMP Foreman module allows for a functioning Foreman web UI, capable of handling smart-proxies, LDAP authentication, and user management. Puppet reports are sent to the foreman reporting tool where they are displayed in the default dashboard. For this release, only the monitoring based services are being supported.

This module is limited to the above functionality. Currently, support for the Foreman provisioning software has not been incorporated. In future releases this can be expected. Initially, however, this module was designed to provide a graphical tool to monitor Puppet, and specifically SIMP, systems.

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

Services Affected:

• postgresql
• foreman
• foreman-proxy
• httpd

WARNINGS:

• This installation of SIMP Foreman is tied heavily to the ruby-193 Software Collection
• All changes made to the Foreman via the Puppet module will take precedence over any manual changes made in the web UI. All manual changes will be overridden on the ensuing Puppet run if there is a conflict.

Minimum Requirements:

• 2 CPUs
• 2GB RAM

Repositories:

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

• Foreman - http://yum.theforeman.org/releases/
• Foreman-plugins - http://yum.theforeman.org/plugins/
• V3814 - https://www.softwarecollections.org/en/scls/rhscl/v8314/
• Httpd24 - https://www.softwarecollections.org/en/scls/rhscl/httpd24/
• Ruby 193 - https://www.softwarecollections.org/en/scls/rhscl/ruby193/

For basic information on the Foreman, see http://theforeman.org/

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

# 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 ever 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

# Obviously include all other necessary classes for this host. This is only to show
# some sample site data you may wish to have. If the default configuration works for you,
# then this won't be needed.
classes:
  - foreman
  - site::foreman

If you wish to be able to add users to connect via an LDAP server, add the following code to something like site::foreman.pp

# 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.
class site::foreman {

  # Adds an LDAP authentication source to Foreman. This assumes this authentication source
  # is LDAP and already exists.
  foreman::auth_source { 'my_awesome_ldap_server':
    ldap_server => $::fqdn,
    onthefly_register => true
  }

  # If onthefly_register is not true then you will need to
  # add uses like this.   If they are in the LDAP server
  # the password from the LDAP Server will over write the
  # one entered here but it fails if you do not give a
  # password parameter.
  foreman::user { 'amazing.user':
    auth_source => 'my_awesome_ldap_server',
    web_admin   => true,
    firstname   => 'Amazing',
    lastname    => 'User',
    password    => 'Mypassword'
  }

  foreman::user { 'untrustworth.user':
    auth_source => 'my_awesome_ldap_server',
    web_admin   => false, # This is the default, but want to show the difference from above.
    firstname   => 'Untrustworthy',
    lastname    => 'User',
    password    => 'Mypassword'
  }
}

Use onthefly_register if you want foreman to automatically create accounts when users log in using an LDAP account. To give LDAP users a default role, add groups to foreman and link them to LDAP groups and foreman roles and put LDAP users in the LDAP group. See http://theforeman.org/manuals/1.10/index.html#4.1.1LDAPAuthentication, the "Linking user groups to LDAP" section for more info.

And voila! Here is your working Foreman instance complete with LDAP authentication and users to login.

Foreman classes:

• foreman
• foreman::params
• foreman::passenger
• foreman::proxy
• foreman::proxy::facts
• foreman::proxy::puppet
• foreman::proxy::puppetca
• foreman::ssl

Foreman defines:

• foreman::auth_source
• foreman::smart_proxy
• foreman::user

Custom Types:

• foreman_auth_source
• foreman_user
• foreman_smart_proxy

Facts Used:

• domain
• fqdn
• hostname

Supported Operating Systems:

• RHEL 6.6/7.0
• CentOS 6.6/7.0

Supported Puppet Versions:

• Puppet 3.7
• Puppet 4.0

Supported Configuration Data Tools

• Hiera

If you would like to contribute to the SIMP Foreman module, please contact the SIMP team with patches, ideas, and suggestions.

Release Notes:

For all SIMP foreman release notes, please see the RPM changelog.

Initial Contributors:

• Kendall Moore [email protected]
• Trevor Vaughan [email protected]
• Chris Tessmer [email protected]
• Jacob Gingrich [email protected]
• Nick Markowski [email protected]
• Michael Riddle [email protected]