1. Foreman 1.3 Manual

Foreman Architecture

A Foreman installation will always contain a central foreman instance that is responsible for providing the Web based GUI, node configurations, initial host configuration files, etc. However, if the foreman installation supports unattended installations then other operations need to be performed to fully automate this process. The smart proxy manages remote services and is generally installed with all Foreman installations to allow for TFTP, DHCP, DNS, and Puppet, and the Puppet CA.

Smart-Proxy

A Smart-Proxy is located on or near a machine that performs a specific function and helps foreman orchestrate the process of commissioning a new host. Placing the proxy on or near to the actual service will also help reduce latencies in large distributed organizations.

Release notes for 1.3

Headline features

New installer

A new installer based on the kafo project is available. Refer to the installation section of the manual for more information.

Smart-proxy auto-registration

In the default all-in-one setup, the smart-proxy is automatically registered in the Foreman UI, using the API during installation. You can change that behavior with register_in_foreman puppet class parameter (or installer option --foreman-proxy-register-in-foreman).

The install module that manages Puppet was refactored, the puppet::server class is now top level. Please review updated readme if you install Foreman directly via your Puppet infrastructure.

Foreman CLI

Brand new command-line interface for Foreman codenamed “Hammer” is introduced by this release. The first version, which is released with Foreman 1.3, is not yet feature-complete and should be treated as a “preview”.

To install the new Foreman command line client, install package rubygem-hammer_cli_foreman first and run:

hammer -h

Compute resources additions

Support for Amazon EC2’s Virtual Private Cloud (VPC) feature has been added, allowing selection of VPC security groups when creating new hosts.

Support for Google Compute Engine as a compute resource has been added. Packages are unavailable in RC1 due to the late addition, but should follow. This implementation is currently in beta state.

Since web-based VNC/SPICE console is popular, we have added possibility to set VNC password for libvirt and VMware resources which helps to integrate with VMs created outside Foreman too. SPICE support can now be enabled for libvirt VMs too.

Compute resource passwords can now be encrypted in the database.

Bare metal association

VM and host records can be now matched via MAC address, either all at once by clicking on Associate VMs at the Compute Resource level, or the Associate button, if available on the compute resource VM. There is logic to determine if it is capable of matching a host.

LDAP filtering

It is now possible to to restrict LDAP authentication to a security group which was highly demanded feature. In the LDAP definition dialog, there is new field called “Custom LDAP search filter” which can be used for that purpose.

Host IP updating

A nice and handy feature which is useful when you have no Puppet Master and using token-based templates. Before Foreman 1.3, there was no other way to get the IP updated, now foreman does that automatically when “update_ip_from_built_request” setting is set.

Plugins as RPM packages

Various plugins have been packaged as RPMs for easy installation, including foreman_discovery, foreman_content, foreman_hooks, or foreman_simplify. For the whole list head over to plugin documentation.

API v2 improvements

The new “experimental” API version (v2) has been improved, providing new features while retaining API compatibility. API v1 still remains the default version. To use API v2, users must pass “version=2” in the header. For example:

curl -u admin:secret -H 'Accept:application/json,version=2' http://abc.com/api/locations

New features include REMOTE_USER support, data format consolidation, better logging, documentation, smart classes support, network interfaces, power management and boot device APIs.

New translations

Foreman 1.3 is now fully translated into (in alphabetical order):

• British English
• Chinese Simplified
• French
• Galcian
• German
• Spanish

Join the translation effort now at transifex.com site.

Upgrade notes

Puppet dependency removed

Puppet dependency was removed from Foreman core, so all Puppet usage is in the smart proxy only. This will make it optional for people who don’t use Puppet, plus avoid conflicts when loading Puppet as a library. In addition, if puppetmaster is not on the same server as Foreman, Puppet no longer needs to be installed there at all.

To accomplish this, the way facts and reports are uploaded was changed. Specifically, Foreman itself now uses a JSON format, and the ENC (node.rb) and Puppet report processor (foreman.rb) have been updated to handle changing Puppet-specific data into JSON. Existing ENC/Reports scripts will need a change to the latest version, which can be found in the installer git repository:

• external_node_v2.rb.erb
• foreman-report_v2.rb.erb

Read-only settings

Configuration values defined via settings.yaml file are now presented in the Foreman Settings page as read-only settings. Every time value is changed in settings.yaml Foreman automatically updates the database. See #2764 for more info.

API version 2 changes

The new API v2 is still work in progress, there are some changes to the API, parameters and output format. We are working hard to stabilize this API in future releases.

Large changes to the API v2 include replacement of api/lookup_keys by api/smart_variables and api/smart_class_parameters (tickets #2810 and #2142) or removal of JSON roots (#2803).

New foreman-rake command

A new foreman-rake command replaces the various rake commands for running administrative tasks. It is a wrapper around rake that changes to the correct user and directory and on SCL-enabled systems also uses the scl command. The foreman-rake command is provided in packages for all OSes to make administration of Foreman consistent.

More information about software collections is available in the Software Collections manual section.

Release notes for 1.3.2

Foreman 1.3.2 is a bug fix release for the 1.3 series. Only the core Foreman component has been updated - the installer remains at 1.3.1 and the smart proxy and SELinux packages remain at version 1.3.0.

CLI (Hammer)

• New version, includes support for:
  • Smart class parameter commands (#3035)
  • Host power management commands (#3594)
  • Printing IDs and names of created resources (#3246)
  • APIv2 support for Foreman 1.4 (#3766)
  • Additional network interfaces for bare metal hosts (#3713)
  • Automatic pagination for browsing and per_page setting (#3743)
• Improved command line completion (#3629)
• Fix random column sorting (#3504)
• Fix exit from shell on any error (#3741)
• Fix error on invalid boolean parameter values (#3742)
• Fix description of domain description (#3518)
• Fix help output of medium create command (#3756)
• Fix OS set_parameter command error (#3583)
• Fix setting puppetclass-ids on host create (#3818)
• Fix errors when creating resources via CSV (#3839)
• among many other improvements!

Compute resources and Hosts creation

• Fix VMware library loading issue preventing host creation (#2680)
• Supply VMware guest_id to prevent host creation issue with new Fog versions (#3653)
• GCE: fix image selection due to attribute name (#3698)
• GCE: fix correct username attribute to be supplied for images (#3832)

Packaging

• Pin rabl to 0.9.0 for Ruby 1.8 compatibility (#3682)
• Pin fog to 0.15.x to reduce incompatibilities (#3717)
• Pin ruby-libvirt to 0.4.0 for Ruby 1.8 compatibility (#3855)
• Pin locale to 2.0.9 for Ruby 1.8 compatibility (#3881)

Web Interface

• Fix SQL error when searching for puppet classes (#3603)
• Change redirection of host edit cancel button to host detail page (#3661)

Various fixes and features

• Fixed DB constraint preventing host deletion when an expired build token exists (#3468)
• Handle tables without primary keys during foreman-rake db:convert:prod2dev (#2783)
• Disable foreign key constraints for PostgreSQL during foreman-rake db:convert:prod2dev (#3268)
• Total value fixed in summary report e-mail subject lines (#3645)

A full list of changes in 1.3.2 is also available via Redmine

Release notes for 1.3.1

Foreman 1.3.1 is a bug fix release for the 1.3 series. Only the core Foreman component and the installer have been updated - the smart proxy and SELinux packages remain at version 1.3.0.

API

• Usergroup members now shown on retrieval (#3256)
• Compatibility break in APIv1 in 1.3.0 fixed, environment in host retrieval restored (#3267)

Authentication and Authorization

• Ambiguous ‘id’ column error fixed on Rails 3.2.8 installations when fact filters used (#3122)

CLI (Hammer)

• New version, includes support for:
  • Tabular output (#2971)
  • CSV output (#2978)
  • More options for host creation and update (#3063)
  • Fact commands (#2927)
  • Operating system association commands
  • Organization and location association commands
  • Report browsing commands
  • Hardware model commands
  • Puppet classes commands, including import from smart proxy
  • Compute resource image commands
• Improved handling of unknown errors (#2959)
• compute_resource_id added to host command (#2951)
• Fixed template listing (#3289)
• Fixed ArgumentError (interning empty string) on “hammer host info” (#3352)
• Fixed organization subcommands (#3370)
• Fixed bash autocompletion (#2939)
• Use username and password from FOREMAN_USERNAME/PASSWORD if unset in config (#2974)
• Add -P argument to prompt for a password (#2979)
• among many other improvements!

Compute resources and Hosts creation

• Incorrect subnets shown for extra interfaces during host edit fixed (#3270)
• Remove requirement to enter hostname for additional managed NICs (#3481)

Facts and Importers

• Intermittent facts disappearance fixed, facts importer rewritten (#2967)

Installer and packaging

• passenger-status fixed in EL6 RPMs (#3197)
• foreman-plugins repo definition now has GPG checking disabled (#3251)
• BIND rndc key no longer overwritten on each installer run (#3484)
• rubyzip version pinned for Ruby 1.8 support (#3369)
• Updated to Rails 3.2.15 (#3498)
• mod_expires enabled on Debian installations
• Fix various puppet lint warnings
• Set owner of PostgreSQL DB to foreman, allowing it to be dropped
• Set appropriate expiry headers for web application assets and use compressed versions
• Add puppetrun_provider parameter to foreman_proxy module
• Fix ssl_* parameters for Foreman ENC/report config on puppet module
• Restart puppet agent when configuration updated
• Add Amazon Linux support to tftp/xinetd modules

Internationalization

• Updated translations for French, small updates for German, Spanish, English (UK)

Puppet and Puppet integration

• Puppet classes with new or changed parameters are now updated via puppet:import:puppet_classes rake task (#2895)
• node.rb --push-facts now tracks which fact files have already been uploaded (#3262)
• node.rb skips empty fact files
• puppet:import:hosts_and_facts rake task argument error fixed (#3269)

Web Interface

• Dashboard page speed improved for non-admin users with large number of managed hosts (#2982)
• Host show page speed improved with optimized SQL queries (#3243)
• Duplicate notification when creating a compute resource fixed (#3266)
• Organization/location list links to hosts fixed when the name contains a space (#3277)
• Page titles added to login/logout screens (#3350)
• Loading text now disappears when loading fact charts (#3486)

VM management

• VMware compute resources now show VMs in all folders (#2093)

Various fixes and features

• Foreign key errors on MySQL using prod2dev rake task fixed (#3212)
• Spoofing of PXELinux templates on PostgreSQL now populates initrd/vmlinuz (#3239)
• FactoryGirl support added to tests for use in plugins (#3293)
• Incorrect report search links for hosts fixed in report e-mails (#3581)

A full list of changes in 1.3.1 is also available via Redmine

Release notes for 1.3

API

• Ability to authenticate to new API via REMOTE_USER (#2988)
• Installation media API was missing some features (#2933)
• Added find by fullname for Operatingsystem (#2932)
• API v2 was missing some nested routes (#2898)
• Refactored method find_nested_obj into API::BaseController (#2869)
• Taxonomy controller was polished (#2838)
• Removed :boolean in API docs (#2817)
• Parameters API v2 index output no longer contain JSON roots (#2803)
• Better logging in the production.log for the API (#2757)
• Fixed rake apipie:static (#2564)
• Taxonomy controllers were not documented (#2525)
• Refactored proxy API (c140d2973)
• Nic::BMC CRUD and proxy operations API (8588f9a)
• Implemented preventing the API returning errors for a wrong owner_type (#2179)
• Removed #as_json method from AR models (#2985 and #3052)
• Added missing fields for host API (#2989)
• Added NIC CRUD, power and boot operations (#3046)
• API v1/v2 StatisticsController and removed JSON from UI controller (#2984)
• Route /api/fact_values was missing from v2 API (#3165)
• Extra validations for V2 API removed (#3207)
• API calls to /api/[class]/[object]/parameters/[parameter] fixed (#3111)

Authentication and Authorization

• Support for cross-domain authentication (#2722)
• Added ability to restrict LDAP authentication to a security group (#863)
• User Filters now only apply to Host::Managed (#2501)
• Users now have a new filter to subscribe to new hostgroups (#1853)
• Restricted APIs to resources that a user is permitted to manage (CVE-2013-4182) (#2863)

CLI

• Implemented commands for managing:
  • config templates (#2926)
  • common parameters (#2925)
  • smart proxies (#2919)
  • hostgroups (#2917)
  • installation media (#2913)
  • partition tables (#2911)
  • config templates (#2926)
  • operating systems (#2914)
  • fact values (#2927)
• Prints lists in grep friendly tabular format (#2971)
• Support for logging (#2824)
• Take credentials from environment variables or ask on them interactively (#2974, #2979)
• Command autocompletion in shell mode (#2939)
• Reading config files from a custom location (#2885)

Compute resources and Hosts creation

• Openstack power controls is now working properly (#2891)
• Removed direct endpoints from Rackspace compute resource (#2833)
• The rackspace compute resource’s client method no longer shows warning (#2832)
• Foreman::Provision::SSH was requiring fog even on non-fog installations (#2813)
• Allowed libvirt to use spice display (#2721)
• Error retrieving VM list from Rackspace compute resource was fixed (#2540)
• Added possibility to encrypt compute resource password (#2424)
• Selecting a different OpenStack tenant had no effect (#2169)
• New option to choose whether a libvirt-based VM should have a VNC password set or not (#1711)
• New host creation in VSphere was failing (#2694)
• Added support for GCE (Google Compute Engine) (#1719)
• Added VPC support to EC2 compute resource (#1871, #1879)
• Support for converting bare metal hosts to/from VMs on compute resources (#1923)
• Added oVirt/RHEV quota support (#2288)
• It is possible to select NIC type for libvirt (#2944)
• Fixed syntax error on detail page of VM (#2996)
• Fixed URL and Description fields for CR (#2875)
• Fixed use_uuid_for_certificates option (#3222)
• Removed double calls to CR provider when creating a new host (#3218)

Proxy and Services

• Missing logger include in Proxy::DNS::Nsupdate was fixed (#3009)
• Optional setting for custom DNS TTL value in settings.yml (#2790)
• Configuration ssldir was fixed for Puppet (#3173)

Facts and Importers

• Fixed MySQL error on hosts_and_facts import when FQDN is missing (#2431)
• Made automatic host creation switchable (#1963)
• Checkboxes on Import environments form are unchecked by default (#2599)
• Allowed ERB in ENC global / class parameters (#2260)

Installer and packaging

• Foreign keys were introduced in the database (#2400)
• Proxy registration (27e7436925)
• Added package version parameter to allow the use of all pacakge->ensure
• Make reports and enc real puppetmaster parameters
• Documentation of parameters
• Template foreman-apache.conf.erb now works in all Apache httpd 2.x versions
• Add new dns_managed param
• Changed operatingsystem to osfamily for Fedora
• Fix for installation on Amazon Linux (df25a804e)
• Allowed show_diff parameter to be set
• Made puppet::server install from puppet topclass (3c158112a7)
• Fixed rename of server variable in env
• Converted multitype parameters to strings
• Corrected envs dir variable
• Added new disable_schedules option for use with Puppet >= 3.4
• Puppet 3.4+ compatibility fixes
• More puppet unit tests
• Skipped empty log arrays (#3045)
• Package ruby193-rubygems-devel was not included in repos (#2836)
• Added new foreman-rake command (#2684)
• Fixed foreign key on trend deleting (#3097)
• Script foreman-debug now collect httpd logs (#3147)
• Package rubygem-ancestry was conflicting with f19-updates (#3142)
• Fixed incompatible gettext_i18n_rails with gettext 2.x (#3167)
• We now print message at the end of configuration (#3131)
• Method delete_all is used for performance reasons when orphaning records (#3202)
• Added plugins repo to foreman-release (#2981)
• Command passenger-status is now working (#3197)
• Partial Amazon Linux support (##17 ##113)
• Full BMC support (##2853)

Internationalization

• Fixed many untranslated errors (#2632)
• Upgraded to the new version of gettext_i18n_rails (#2596)
• Support for i18ntion of plugins in Foreman Core (#2942)

Puppet and Puppet integration

• Puppet was removed from the core (#2414)
• An incorrect error message in the logs when POST’ing to sign a cert via /puppet/ca/ ([#2941](http://projects.theforeman.org/issues/2941))
• On class reimport, Foreman was running class parameter validations even when parameter override is disabled (#2758)
• If FQDN for puppetmaster was starting with “puppet”, Foreman was stripping the domain. (#1745)
• Linked non-zero report summaries to the equivalent report search (#1848)
• Facter require statements were fixed (#3030)
• Added rake task to import puppet environments (#3051)
• Added rake task for sending reports (#3059)

Web Interface

• Now using the future relative tense for each orchestration step during provisioning (#2867)
• Gravatar e-mail addresses now working properly (#2825)
• Enhance puppet classes assignment (#2780)
• Foreman graphs are clickable again (#2665)
• Extended AR to add getter/setter methods “names” similar to “ids” (#2945)
• Changed extension on files with .erb to .html.erb (#2910)
• Method `lookup_values_attributes=’ was not defined in Host::Managed (NameError) (#2812)
• Refactored /conflig/initializers directory (#2740)
• ActiveSupport::Concern syntax refactored (#2739)
• Refactored /lib directory to app/models/concerns or app/controllers/concerns and app/services (#2411)
• Foreman scoped_search on hosts params was only searching for boolean parameters (#2871)
• Setting categories were not consistently loaded and shown in ‘development’ environment (#2766)
• Possibility to optionally update Host.ip as part of /unattended/built (#2576)
• Removed all legacy api code in UI controllers (#2969)
• Added Capybara integration tests, but without javascripts (#2272)
• Fixed “is invalid is invalid” error (#3093)
• Settings defined in settings.yaml are now read only (#2764)
• More restful API v2 JSON responses in puppetclasses (#2810)
• Bumped version of apipie-rails (#3120)
• Now using the standard CentOS mirror (#3130)
• Locale was set to last language by default (#3077)
• New puppetclass creation was failing (#3090)
• OS edit was failing on foreign keys (#3071)
• Fixed space before parenthesis warning (#3087)
• Fixed settings updating (#3089)
• FactTrend fixed in trends (#3095)
• Avoided flapping os.release_name for Debian (#2244)
• Fixed duplicate Organization tabs (#3139)
• Fixed undefined local variable or method render_403 (#3141)
• Settings descriptions were not updating (#2756)
• Array values in settings UI were not displayed correctly after update (#3180)
• Fixed assignment of a Security group to EC2 instance when creating host (#3133)
• Non Admin user is not failing to override parameters when creating a new hosts (#3076)
• Consistent sorting of parameters in hosts and hostgroups (#3106)
• Lookup values fqdn/hostgroup limited (#3206)
• Fixed STI auditable_type (#3190)
• Default root password is now MD5 hashed (#3241)

VM management

• Fixed wrong autoload paths (#2821)
• Foreman was unable to delete a host with vmware-tools installed (#2704)
• HostSubject is now retrieved via oVirt/RHEV API (#2809)
• Added checkbox to select thin or thick provision for vSphere volumes (#3088
• Association of vSphere VMs was failing (#3110)
• Fixed Vmware: error listing VMs (#3072)
• EC2 images listing was broken (#3128)
• Was unable to show EC2 VM info (#3129)

Various fixes and features

• Deleting a currently selected org was resulting to a 404 hell (#2877)
• Puppet class naming fix (#2970)
• Updated to Rails 3.2.14 (#2830)
• Foreman-debug was giving: lsb_release: command not found (#2814)
• Rubygem nokogiri 1.6.0 was incompatible with Ruby 1.8 (#2808)
• The smart-proxy package name is no longer prefixed with scl_prefix. (#2807)
• Thread dump now possible via kill -TTIN ([#2795](http://projects.theforeman.org/issues/2795))
• Fixed remote_addr setting (#2751)
• Build foreman_api is now a non-SCL package for the installer (#2743)

A full list of changes in 1.3.0 is available via the Roadmap

Contributors

We’d like to thank the following people who contributed to the Foreman 1.3 release:

Aaron Stone, Adam Price, Amos Benari, Andy Bohne, Antony Perigault, Arnoud de Jonge, Ash Caire, Bernard McKeever, Cédric Jeanneret, Daniel Baeurer, Daniel Lobato, Dmitri Dolguikh, Dominic Cleal, Ewoud Kohl van Wijngaarden, Florentin Raud, Florian Ernst, Gavin McCance, Gaël Chamoulaud, Greg Sutcliffe, Grégoire Morpain, Ian Mordey, Ivan Nečas, James Bailey, Jason Montleon, Jeremy Kitchen, Jimmi Dyson, Joseph Mitchell Magen, Justin Foreman, Kamil Winczek, Libor Zoubek, Luke Alford, Lukáš Zapletal, Marek Hulán, Mark O’Shea, Martin Bačovský, Martin Matuska, Michael Moll, Mickaël Canévet, Mikael Fridh, Nacho Barrientos, Nils Domrose, Ohad Levy, Povilas Daukintis, Rick Sherman, Romain Vrignaud, Ryan Davies, Sam Kottler, Stef Telford, Stephen Hoekstra, Tomas Strachota, bmx0r, kleind, snobear.

As well as all users who helped test releases, report bugs and provide feedback on the project.

2. Quickstart

The Foreman installer is a collection of Puppet modules that installs everything required for a full working Foreman setup. It uses native OS packaging (e.g. RPM and .deb packages) and adds necessary configuration for the complete installation.

Components include the Foreman web UI, Smart Proxy, Passenger (for the puppet master and Foreman itself), and optionally TFTP, DNS and DHCP servers. It is configurable and the Puppet modules can be read or run in “no-op” mode to see what changes it will make.

Supported platforms

• RHEL derivatives (CentOS), version 6 (EPEL required, plus subscribe to “optional” channel on RHEL 6)
• Fedora 18, 19
• Debian 7 (Wheezy)
• Debian 6 (Squeeze) (update Puppet from backports)
• Ubuntu 12.04 (Precise)

Other operating systems will need to use alternative installation methods (see the manual).

2.1 Installation

The Foreman installer uses Puppet to install Foreman. This guide assumes that you have a newly installed operating system, on which the installer will setup Foreman, a puppet master with Passenger and the Smart Proxy by default.

Downloading the installer

For Red Hat variants, run this (replace ‘el6’ with ‘f18’ or ‘f19’ as appropriate):

yum -y install http://yum.theforeman.org/releases/1.3/el6/x86_64/foreman-release.rpm
yum -y install foreman-installer

For Debian variants, run this (replace ‘wheezy’ with ‘precise’ if on Ubuntu 12.04, or ‘squeeze’ for Debian 6):

echo "deb http://deb.theforeman.org/ wheezy 1.3" > /etc/apt/sources.list.d/foreman.list
wget -q http://deb.theforeman.org/pubkey.gpg -O- | apt-key add -
apt-get update && apt-get install foreman-installer

Running the installer

The installation run is non-interactive, but the configuration can be customized by supplying any of the options listed in foreman-installer --help, or by running foreman-installer -i for interactive mode. More examples are given in the Installation Options section. Adding -v will disable the progress bar and display all changes. To run the installer, execute:

foreman-installer

After it completes, Foreman will be accessible at https://fqdn/ with a default username/password of “admin” and “changeme”.

2.2 Puppet Management

After installation, the Foreman installer will have set up a puppet master on the host, fully integrated with Foreman. First run the Puppet agent on the Foreman host which will send the first Puppet report to Foreman, automatically creating the host in Foreman’s database.

puppet agent --test

In Foreman, click on the Hosts tab and your Foreman host should be visible in the list with an “O” status. This indicates its status is OK, with no changes made on the last Puppet run.

Downloading a Puppet module

Next, we’ll install a Puppet module for managing the NTP service. If you have Puppet 2.7.14 or higher, install the module automatically from Puppet Forge to our “production” environment (the default):

puppet module install -i /etc/puppet/environments/production/modules saz/ntp

On older versions, download the tar.gz and unpack to /etc/puppet/environments/production/modules/. Rename the directory to “ntp”, removing the author and version number.

In Foreman, go to More > Configuration > Puppet Classes and click Import from hostname (top right) to read the available Puppet classes from the puppet master and populate Foreman’s database. The “ntp” class will appear in the Puppet class list if installed correctly.

Using the Puppet module

Click on the “ntp” class in the list, change to the Smart Class Parameters tab and select the server_list parameter on the left hand side. Tick the Override checkbox so Foreman manages the “server_list” parameter of the class and change the default value if desired, before submitting the page.

• More info: Parameterized classes documentation
• Screencast: Parameterized class support in Foreman

Change back to the Hosts tab and click Edit on the Foreman host. On the Puppet Classes tab, expand the ntp module and click the + icon to add the ntp class to the host, then save the host.

Clicking the YAML button when back on the host page will show the ntp class and the server_list parameter, as passed to Puppet via the ENC (external node classifier) interface. Re-run puppet agent --test on the Foreman host to see the NTP service automatically reconfigured by Puppet and the NTP module.

Adding more Puppet-managed hosts

Other hosts with Puppet agents installed can use this puppet master by setting server = foreman.example.com in puppet.conf. Sign their certificates in Foreman by going to More > Configuration > Smart Proxies > Certificates or using puppet cert list and puppet cert sign on the puppet master.

Puppet classes can be added to host groups in Foreman instead of individual hosts, enabling a standard configuration of many hosts simultaneously. Host groups are typically used to represent server roles.

3. Installing Foreman

There are several different methods of installing Foreman. The recommended way is with the puppet based Foreman Installer but you may also use your distribution’s package manager or install directly from source.

3.1 System Requirements

This sections outlines the system requirements for an installation of Foreman. This will cover the hardware requirements, OS requirements and firewall requirements. This includes variations for all supported database types.

3.1.1 Supported Platforms

The following operating systems are supported by the installer, have packages and are tested for deploying Foreman:

• RHEL derivatives (CentOS) version 6
  • EPEL is required
  • On RHEL 6, subscribe to the “optional” child channel (yum-config-manager --enable rhel-6-server-optional-rpms)
• Fedora 18, 19
• Debian 7 (Wheezy)
• Debian 6 (Squeeze)
  • Ensure Puppet is updated from backports
• Ubuntu 12.04 (Precise)

All platforms will require Puppet 2.6.5 or higher. Puppet 3.x is supported and may be installed from the Puppet Labs repositories.

Other operating systems will need to use alternative installation methods, such as from source.

The following operating systems are known to install successfully from Foreman:

• RHEL derivatives (CentOS) 3+
• Fedora
• Ubuntu
• Debian
• Solaris 8, 10
• OpenSUSE 11.4

3.1.2 Firewall Configuration

Protect your Foreman environment by blocking all unnecessary and unused ports.

Ports indicated with * are running by default on a Foreman all-in-one installation and should be open.

3.2 Foreman Installer

The Foreman installer is a collection of Puppet modules that installs everything required for a full working Foreman setup. It uses native OS packaging (e.g. RPM and .deb packages) and adds necessary configuration for the complete installation.

Components include the Foreman web UI, Smart Proxy, Passenger (for the puppet master and Foreman itself), and optionally TFTP, DNS and DHCP servers. It is configurable and the Puppet modules can be read or run in “no-op” mode to see what changes it will make.

It’s strongly recommended to use the installer instead of only installing packages, as the installer uses OS packages and it saves a lot of time otherwise spent replicating configuration by hand.

By default it will configure:

• Apache HTTP with SSL (using a Puppet-signed certificate)
• Foreman running under mod_passenger
• Smart Proxy configured for Puppet, TFTP and SSL
• Puppet master running under mod_passenger
• Puppet agent configured
• TFTP server (under xinetd on Red Hat platforms)

Other modules can be enabled, which will also configure:

• ISC DHCP server
• BIND DNS server

3.2.1 Installation

The Foreman installer uses Puppet to install Foreman. This guide assumes that you have a newly installed operating system, on which the installer will setup Foreman, a puppet master with Passenger and the Smart Proxy by default.

Downloading the installer

For Red Hat variants, run this (replace ‘el6’ with ‘f18’ or ‘f19’ as appropriate):

yum -y install http://yum.theforeman.org/releases/1.3/el6/x86_64/foreman-release.rpm
yum -y install foreman-installer

For Debian variants, run this (replace ‘wheezy’ with ‘precise’ if on Ubuntu 12.04, or ‘squeeze’ for Debian 6):

echo "deb http://deb.theforeman.org/ wheezy 1.3" > /etc/apt/sources.list.d/foreman.list
wget -q http://deb.theforeman.org/pubkey.gpg -O- | apt-key add -
apt-get update && apt-get install foreman-installer

Running the installer

The installation run is non-interactive, but the configuration can be customized by supplying any of the options listed in foreman-installer --help, or by running foreman-installer -i for interactive mode. More examples are given in the Installation Options section. Adding -v will disable the progress bar and display all changes, while --noop will run without making any changes. To run the installer, execute:

foreman-installer

After it completes, Foreman will be accessible at https://fqdn/ with a default username/password of “admin” and “changeme”. Logs of the installation are stored under /var/log/foreman-installer.

3.2.2 Installer Options

The installer is a collection of Puppet modules, which have a large number of parameters available to customize the configuration. Parameters can be set by running foreman-installer with arguments, e.g. --foreman-db-type, changing settings in interactive mode or by setting up an answers file.

The precedence for settings is for those set by arguments to foreman-installer or interactive mode, then the answers file, then the Puppet manifest defaults.

foreman-installer arguments

Every parameter available in the installer can be set using command line arguments to foreman-installer. Run foreman-installer --help for a list of every available option.

When running the installer, all arguments passed on the command line will be persisted by default to /etc/foreman/foreman-installer.yaml and used automatically on subsequent runs, without needing to specify those arguments again. This persistence can be disabled with the -b option.

Interactive mode

The installer also provides a text driven interface to customize configuration parameters, and can be run by executing:

foreman-installer -i

Available options

Answers file

The answers file describes the classes that will be applied to the host to install Foreman, along with their parameters. The foreman-installer package stores it at /etc/foreman/foreman-installer.yaml. By default, the all-in-one setup will include Foreman, a puppetmaster, Puppet agent, and the Smart Proxy:

---
foreman:
  custom_repo: true
foreman_proxy:
  custom_repo: true
puppet:
  server: true

Other examples are given in the next section, or /usr/share/foreman-installer/README.md.

3.2.3 Installation Scenarios

The Foreman installer can accommodate more complex, multi-host setups when supplied with appropriate parameters.

Setting up Foreman with external Puppet masters

Using the scenarios outlined below, a simple scale-out setup can be created as follows:

1. On the Foreman host, run a complete foreman-installer all-in-one installation to provide Foreman, a Puppet master and smart proxy. This will be the Puppet CA.

For each Puppet master:

1. Generate a new certificate following the steps in the SSL CA section and transfer it to the new Puppet master host
2. Run the standalone Puppet master installation as detailed below

Each Puppet master will register with Foreman as a smart proxy, while the instance running on the Foreman host itself will act as a central Puppet CA. These can be selected while adding new hosts or host groups.

SSL certificate authority setup

The scenarios below assume a single Puppet CA (certificate authority) for all hosts, which is also used for Foreman and smart proxy communications, though more complex deployments are possible. This might be the central Foreman host, or a particular Puppet master.

Other systems require certificates to be generated on the central Puppet CA host, then distributed to them before running foreman-installer (else it may generate a second CA). To prepare these, on the host acting as Puppet CA, run:

# puppet cert generate new-puppetmaster.example.com
Notice: new-puppetmaster.example.com has a waiting certificate request
Notice: Signed certificate request for new-puppetmaster.example.com
Notice: Removing file Puppet::SSL::CertificateRequest new-puppetmaster.example.com at '/var/lib/puppet/ssl/ca/requests/new-puppetmaster.example.com.pem'
Notice: Removing file Puppet::SSL::CertificateRequest new-puppetmaster.example.com at '/var/lib/puppet/ssl/certificate_requests/new-puppetmaster.example.com.pem'

# ls /var/lib/puppet/ssl/*/new-puppetmaster.example.com.pem
/var/lib/puppet/ssl/certs/new-puppetmaster.example.com.pem
/var/lib/puppet/ssl/private_keys/new-puppetmaster.example.com.pem
/var/lib/puppet/ssl/public_keys/new-puppetmaster.example.com.pem

Transfer the following files to the same paths on the new host:

• /var/lib/puppet/ssl/certs/ca.pem
• /var/lib/puppet/ssl/certs/new-puppetmaster.example.com.pem
• /var/lib/puppet/ssl/private_keys/new-puppetmaster.example.com.pem

This provides the new host a certificate in the same authority, but doesn’t make it a CA itself. Certificates will continue to be generated on the central Puppet CA host.

Standalone Puppet master

A standalone Puppet master can be configured along with a smart proxy installation, enabling the Puppet infrastructure to be scaled out. A certificate should be generated and copied to the host first to make it part of the same CA, else a new Puppet CA will be generated.

Command line arguments:

foreman-installer \
  --no-enable-foreman \
  --enable-puppet \
  --puppet-server-ca=false \
  --puppet-server-foreman-url=http://foreman.example.com \
  --enable-foreman-proxy \
  --foreman-proxy-tftp=false \
  --foreman-proxy-foreman-base-url=http://foreman.example.com \
  --foreman-proxy-oauth-consumer-key=<key here> \
  --foreman-proxy-oauth-consumer-secret=<secret here>

Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from More > Settings > Auth, and set the Foreman URLs appropriately. These allow the smart proxy to register automatically with the Foreman instance, or disable with --foreman-proxy-register-in-foreman=false.

Foreman server without the Puppet master

The default “all-in-one” Foreman installation includes a Puppet master, but this can be disabled. Foreman by default uses Puppet’s SSL certificates however, so a certificate must be generated and copied to the host first, or all SSL communications need to be disabled.

Command line arguments:

foreman-installer \
  --puppet-server=false \
  --foreman-proxy-puppetrun=false \
  --foreman-proxy-puppetca=false

This will still configure the Puppet agent, but this too can be disabled with --no-enable-puppet to disable the whole Puppet module.

Smart proxy for DNS, DHCP etc.

The smart proxy allows management of various network services, such as DNS, DHCP and TFTP. The installer can set up a basic smart proxy service ready to be configured, or it can install and configure BIND or ISC DHCP ready to go. A certificate should be generated and copied to the host first so Foreman can contact the proxy server.

Command line arguments for a basic smart proxy installation:

foreman-installer \
  --no-enable-foreman \
  --no-enable-puppet \
  --enable-foreman-proxy \
  --foreman-proxy-tftp=false \
  --foreman-proxy-foreman-base-url=http://foreman.example.com \
  --foreman-proxy-oauth-consumer-key=<key here> \
  --foreman-proxy-oauth-consumer-secret=<secret here>

Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from More > Settings > Auth, and set the Foreman URL appropriately. These allow the smart proxy to register automatically with the Foreman instance, or disable with --foreman-proxy-register-in-foreman=false.

Command line arguments for a smart proxy configured with just BIND, setting DNS forwarders and overriding the default forward and reverse DNS zones:

foreman-installer \
  --no-enable-foreman \
  --no-enable-puppet \
  --enable-foreman-proxy \
  --foreman-proxy-tftp=false \
  --foreman-proxy-puppet=false \
  --foreman-proxy-puppetca=false \
  --foreman-proxy-dns=true \
  --foreman-proxy-dns-interface=eth0 \
  --foreman-proxy-dns-zone=example.com \
  --foreman-proxy-dns-reverse=0.0.10.in-addr.arpa \
  --foreman-proxy-dns-forwarders=8.8.8.8 \
  --foreman-proxy-dns-forwarders=8.8.4.4 \
  --foreman-proxy-foreman-base-url=http://foreman.example.com \
  --foreman-proxy-oauth-consumer-key=<key here> \
  --foreman-proxy-oauth-consumer-secret=<secret here>

Ensure the dns-interface argument is updated with the correct network interface name for the DNS server to listen on.

Command line arguments for a smart proxy configured with just ISC DHCP and a single DHCP subnet:

foreman-installer \
  --no-enable-foreman \
  --no-enable-puppet \
  --enable-foreman-proxy \
  --foreman-proxy-puppet=false \
  --foreman-proxy-puppetca=false \
  --foreman-proxy-tftp=false \
  --foreman-proxy-dhcp=true \
  --foreman-proxy-dhcp-interface=eth0 \
  --foreman-proxy-dhcp-gateway=10.0.0.1 \
  --foreman-proxy-dhcp-range="10.0.0.50 10.0.0.200" \
  --foreman-proxy-dhcp-nameservers="10.0.1.2,10.0.1.3" \
  --foreman-proxy-foreman-base-url=http://foreman.example.com \
  --foreman-proxy-oauth-consumer-key=<key here> \
  --foreman-proxy-oauth-consumer-secret=<secret here>

Also ensure here that the dhcp-interface argument is updated for the interface to run DHCP on.

3.3 Install From Packages

Packages are available for Red Hat and Debian-based distributions. This will install a standalone Foreman service running under WEBrick, which has limited scalability.

The Puppet-based Foreman installer is recommended for most environments, instead of installing only the packages as it will perform full configuration too.

3.3.1 RPM Packages

Foreman is packaged for the following RPM based distributions:

• RHEL and derivatives, version 6
• Fedora 18, 19

For most users, it’s highly recommended to use the installer as the packages only provide the software and a standalone Foreman service. The installer installs these packages, then additionally configures Foreman to run under Apache and Passenger with PostgreSQL, plus can configure a complete Puppet setup integrated with Foreman.

Pre-requisites

All RHEL and derivatives must be subscribed to EPEL to provide additional dependencies. Install epel-release from here to automatically configure it.

RHEL 6 hosts must also be subscribed to the “Optional” channel in RHN.

Optionally, the Puppet Labs repository can be configured to obtain the latest version of Puppet available, instead of the version on EPEL. See the Puppet Labs Package Repositories documentation on how to configure these.

Available repositories

Three main repos are provided at http://yum.theforeman.org:

• /releases/latest or /releases/VERSION (e.g. /releases/1.3) carries the stable releases and updates of Foreman and its dependencies.
• /rc carries release candidates only in the few weeks prior to a release. Ensure after a release is made that you use the main releases repo instead.
• /nightly carries the latest development builds and as such, may be unstable or occasionally broken.

Under each repo are directories for each distribution, then each architecture.

Release packages

To set up the repository, foreman-release packages are provided which add a repo definition to /etc/yum.repos.d. Install the appropriate release RPM from these lists:

yum localinstall http://yum.theforeman.org/releases/1.3/el6/x86_64/foreman-release.rpm
yum localinstall http://yum.theforeman.org/releases/1.3/f18/x86_64/foreman-release.rpm
yum localinstall http://yum.theforeman.org/releases/1.3/f19/x86_64/foreman-release.rpm

For release candidate or nightly RPMs, change the URL as appropriate based on the above list of available repositories.

Signing

Release and release candidate packages are signed by the “Foreman Archive Signing Key packages@theforeman.org” (0xE775FF07). Nightly packages are not signed.

A copy of the key is available from public keyservers or here.

Available packages

Install foreman and other foreman-* packages to add functionality:

foreman               Foreman server
foreman-proxy         Foreman Smart Proxy
foreman-compute       EC2, OpenStack and Rackspace provisioning support
foreman-libvirt       libvirt provisioning support
foreman-ovirt         oVirt/RHEV provisioning support
foreman-vmware        VMware provisioning support
foreman-cli           Foreman CLI utility
foreman-console       Console additions
foreman-selinux       SELinux targeted policy
foreman-mysql         MySQL database support
foreman-mysql2        MySQL database support
foreman-postgresql    PostgreSQL database support
foreman-sqlite        SQLite database support

Setup

1. Configure by editing /etc/foreman/settings.yaml and /etc/foreman/database.yml
2. After changing the database, migrate it: sudo -u foreman /usr/share/foreman/extras/dbmigrate
3. Start the foreman service or set up passenger: service foreman start

Upgrade

See upgrade instructions

3.3.2 Software Collections

The RPMs use a packaging technique called Software Collections, or SCL. This provides Ruby and all dependencies required to run Foreman separately from the version of Ruby provided by the distribution.

The current stack is “ruby193”, which provides Ruby 1.9.3 and Ruby on Rails 3.2. All packages will have a “ruby193-“ prefix, allowing them to be easily identified, and will install entirely underneath /opt/rh/ruby193.

The system Ruby version is left alone and will still be used for packages provided both by the distribution, and other third parties who target the system Ruby (e.g. Puppet packages).

Foreman currently uses SCL only on RHEL and EL clones where a newer version of Ruby is desired. Fedora only uses the distro version of Ruby.

In order to run rake commands for Foreman, or scripts that run in the same environment, ruby193-rake and ruby193-ruby wrappers are provided as alternatives for the usual rake or ruby. In order to run a series of commands or a script directly within the software collection, scl enable ruby193 'other command' can be used. It is also possible to run scl enable ruby193 bash to get a shell within the context of the SCL. Foreman rake tasks should be run with “foreman-rake”, which automates this process.

More general information about software collections is available from these links:

• RHEL packaging: Software Collections (SCLs)
• Fedora Contributor Documentation: Software Collections Guide

Passenger under the SCL

When running Foreman under Passenger (the default installer setup), a specific configuration is needed for SCL (on EL), since Foreman operates under the SCL Ruby and other apps such as the puppetmaster will use the system Ruby. Passenger 4 is shipped in the Foreman repos as it can be configured with separate Ruby binaries per VirtualHost. The full configuration is described below.

The following packages must be installed:

• mod_passenger
• ruby193-rubygem-passenger
• ruby193-rubygem-passenger-native
• ruby193-rubygem-passenger-native-libs
• rubygem-passenger
• rubygem-passenger-native
• rubygem-passenger-native-libs

Ensure all version numbers match and are at least 4.0. mod_passenger provides the Apache module, while there are two copies of the Ruby components, one for the SCL Ruby (ruby193-rubygem-*) and one for the system Ruby (rubygem-*).

The /etc/httpd/conf.d/passenger.conf file is supplied by mod_passenger and should contain:

LoadModule passenger_module modules/mod_passenger.so
<IfModule mod_passenger.c>
   PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-4.0.5
   PassengerRuby /usr/bin/ruby
</IfModule>

Check for .rpmsave or .rpmnew config backup files if this isn’t correct. Note that this refers to the system Ruby paths by default, allowing everything except Foreman (i.e. the puppetmaster) to run under the system Ruby.

Next, the Foreman config file at /etc/httpd/conf.d/foreman.conf must contain this entry in both HTTP and HTTPS VirtualHost sections:

PassengerRuby /usr/bin/ruby193-ruby

The full foreman.conf template from the installer is available here for comparison.

Ensure both RailsAutoDetect and RakeAutoDetect config entries are removed from foreman.conf and puppet.conf when using Passenger 4, since they have been deprecated.

When successfully configured, two Passenger RackApp processes will be visible and by inspecting the open files, the Ruby version being loaded can be confirmed:

# ps auxww | grep RackApp
foreman  16627  0.1 15.4 466980 157196 ?       Sl   07:35   0:09 Passenger RackApp: /usr/share/foreman
puppet   16697  0.8 11.3 253080 115720 ?       Sl   07:35   1:13 Passenger RackApp: /etc/puppet/rack
# lsof -p 16697 | grep libruby
ruby    16697 puppet  mem    REG              253,0   951224  272286 /usr/lib64/libruby.so.1.8.7
# lsof -p 16627 | grep libruby
ruby    16627 foreman  mem    REG              253,0  2041096  171190 /opt/rh/ruby193/root/usr/lib64/libruby.so.1.9.1

3.3.3 Debian Packages

The Foreman packages should work on the following Debian-based Linux distributions:

Distributions

• Debian Linux 7.0 (Wheezy)
• Debian Linux 6.0 (Squeeze)
• Ubuntu Linux 12.04 LTS

Foreman might still work on these distros, but it has not been tested (let us know if it works for you):

• Debian Linux 5.0 (Lenny)
• Ubuntu Linux 11.04
• Ubuntu Linux 10.10

If you encounter any errors during the installation, please file a bug report!

Apt Configuration

Add one of the following lines to your /etc/apt/sources.list (alternatively in a separate file in /etc/apt/sources.list.d/foreman.list):

# Stable packages

# Debian Wheezy
deb http://deb.theforeman.org/ wheezy 1.3
# Debian Squeeze
deb http://deb.theforeman.org/ squeeze 1.3
# Ubuntu Precise
deb http://deb.theforeman.org/ precise 1.3

# Nightly builds. Beware: HERE BE DRAGONS

# Debian Wheezy
deb http://deb.theforeman.org/ wheezy nightly
# Debian Squeeze
deb http://deb.theforeman.org/ squeeze nightly
# Ubuntu Precise
deb http://deb.theforeman.org/ precise nightly

You may also want some plugins from the plugin repo:

# Plugins compatible with Stable
deb http://deb.theforeman.org/ plugins 1.3
# Plugins compatible with Nightly
deb http://deb.theforeman.org/ plugins nightly

The public key for secure APT can be downloaded here

You can add this key with

apt-key add pubkey.gpg

or combine downloading and registering:

wget -q http://deb.theforeman.org/pubkey.gpg -O- | apt-key add -

The key fingerprint is

7059 542D 5AEA 367F 7873  2D02 B348 4CB7 1AA0 43B8
Foreman Automatic Signing Key (2014) <packages@theforeman.org>

Remember to update your package lists!

apt-get update

Install packages

The packages are now split by gem dependencies - there are 11 packages to choose from. These are:

Main package:

• foreman

Database gems - you need at least one of these:

• foreman-sqlite3
• foreman-mysql2
• foreman-mysql
• foreman-pgsql

Optional functionality:

• foreman-console
• foreman-compute
• foreman-libvirt
• foreman-ovirt
• foreman-test
• foreman-vmware

Command line interface:

• ruby-hammer-cli
• ruby-hammer-cli-foreman

Installation instructions are:

# Install packages  (adjust additional packages as needed)
apt-get install foreman foreman-sqlite3 foreman-libvirt

# Copy sample db config to /etc
cp /usr/share/foreman/config/database.yml.example /etc/foreman/database.yml

# Review settings and DB config
vi /etc/foreman/settings.yaml /etc/foreman/database.yml

# Perform initial DB setup
su - foreman -s /bin/bash -c /usr/share/foreman/extras/dbmigrate

The packages should auto-run db:migrate if /etc/foreman/database.yml exists. So the initial db:migrate is only needed during first install, upgrades should just work.

Upgrade

See upgrade instructions

3.4 Install From Source

Installing the latest development code: Foreman has now moved to using Rails 3 and Bundler to get up and running. This is the preferred way to get Foreman if you want to benefit from the latest improvements. By using the git repository you can also upgrade more easily. You will need to have Bundler installed manually for now (check your distribution repositories, or install it via rubygems).

Foreman will run with the following requirements (aside from rubygem dependencies):

• Ruby 1.8.7 or 1.9
• rubygems
• Puppet >= 0.24.4

The installation has been successfully tested on RHEL[5,6], Fedora[13,14,15,16,17], Debian Linux 6.0 (Squeeze) and Ubuntu Linux 12.04 (the community has reported varying success with other Debian/Ubuntu versions - 12.10 seems fine for example). For older operating systems you might need additional packages (e.g. sqlite). It is also known to work on Solaris and Mac.

to get latest “development” version do:

You will want to make sure that you have one of the mysql-devel, postgresql-devel, and sqlite-devel libraries installed so the database gems can install properly. Also, you would also need gcc, ruby-devel, libxml-devel, libxslt-devel, and libvirt-devel packages

For RHEL6 or clones, you can issue the following commands to install all required packages:

yum groupinstall "Development Tools" "Development Libraries"
yum -y install gcc-c++ git ruby ruby-devel rubygems \
    libvirt-devel mysql-devel postgresql-devel openssl-devel \
    libxml2-devel sqlite-devel libxslt-devel zlib-devel \
    readline-devel

Additionally, it is important that config/database.yml is set to use the correct database in the “production” block. Rails (and subsequently Foreman) will use these connection settings under “production” to manage the database it uses and setup the necessary schema.

git clone https://github.com/theforeman/foreman.git -b develop
cd foreman
cp config/settings.yaml.example config/settings.yaml
cp config/database.yml.example config/database.yml
gem install bundler
# depending on database configured in yml file you can skip others
# (we are assuming sqlite to be configured)
bundle install --without mysql mysql2 pg test --path vendor # or postgresql
# set up database schema, precompile assets and locales
RAILS_ENV=production bundle exec rake db:migrate
RAILS_ENV=production bundle exec rake db:seed assets:precompile locale:pack

You can run Foreman with the command ”./script/rails s -e production”

Latest stable version

to get latest “stable” version do:

git clone https://github.com/theforeman/foreman.git -b 1.3-stable

CLI (Hammer)

To install hammer from git checkouts, you will just need rake installed on your system. Clone and install CLI core

$ git clone https://github.com/theforeman/hammer-cli.git
$ cd hammer-cli
$ rake install
$ cd ..

and clone plugin with foreman commands

$ git clone https://github.com/theforeman/hammer-cli-foreman.git
$ cd hammer-cli-foreman
$ rake install
$ cd ..

You can install other hammer plugins via any of the methods mentioned above.

3.5 Configuration

The following sections detail the configuration steps required to get Foreman working in your environment. Lets get started!

3.5.1 Initial Setup

Configuration

Foreman configuration is managed from two places; a configuration file config/settings.yaml and from the SETTINGS/Foreman Settings page. A full description of the configuration options is given at foreman_configuration

Database

Foreman requires a database of its own to operate - database sharing is unsupported. By default, the installer uses PostgreSQL, while a package or source installation will use SQLite. If you want to use other database (e.g. MySQL) please modify the configuration file under config/database.yml.

In all cases, please use the production settings.

to initialize the database schema type:

foreman-rake db:migrate

For more information please see the database configuration page here

Import Data from Puppet

At this point, you might want to go through the [[FAQ]] to see how can you import your data into Foreman.

Start The Web Server

if you installed via rpm, just start the foreman service, or start the builtin web server by typing:

RAILS_ENV=production rails server

and point your browser to http://foreman:3000

If you would like to keep the server running, its recommend to setup passenger or use the RPM. Example usage with passenger can be found on GitHub.

Getting your Puppet Reports into Foreman

Read Puppet_Reports to learn how to get your nodes to report to Foreman.

3.5.2 Configuration Options

Configuration is broken into two parts. The config/settings.yaml file and the SETTINGS/Foreman Settings page. The configuration file contains a few low-level options that need to be set before Foreman starts but the majority of Foreman customization is managed from within the program on the Foreman Settings page.

The config/settings.yaml file

YAML start

The first non-comment line of this file must be three dashes.

---

login

This boolean option configures whether Foreman requires users to to login. If it is set then each user will be expected to authenticate themselves and all operations will occur, and be audited, under their identity. When this option is false then all activity will be executed under the admin account.

:login: true

require_ssl

This boolean option configures whether Foreman insists on using only https/ssl encrypted communication channels in the web interface. This does not configure the channels used to contact the smart-proxies. Note that certain operations will still accept a http connection even if this is set, for example, the downloading of a finish script.

:require_ssl: true

unattended

This boolean option configures whether Foreman will act as a simple node classifier for puppet, or support the full spectrum of operations required for managing a host’s lifecycle. When set to true then foreman will provide full host building facilities for various operating systems.

:unattended: true

The ‘More/Settings’ page

administrator

When Foreman needs to mail the administrator then this is the email address that it will contact. Default: root@.

default_puppet_environment

When Foreman receives a fact upload from a machine that it has not previously come across it will create a host in its database. If the facts from that host did not contain information about the puppet environment then it will assign the default_puppet_environment environment to this host. Default: production

Default_variables_Lookup_Path

A Smart-variable’s match criteria are evaluated in a specific order and if this search order is not provided then Default_variables_Lookup_Path is used. Default: [“fqdn”, “hostgroup”, “os”, “domain”]

email_reply_address

The return address applied to outgoing emails. Default: Foreman-noreply@<your domain>

Enable_Smart_Variables_in_ENC

Whether Smart-variables should be included in the yaml node information provided to puppet. Default: true

entries_per_page

The number of entries that will be shown in the web interface for list operations. Default: 20

failed_report_email_notification

If this option is set to true then an email will be sent to the host’s owner whenever a report is received that contains errors. If the host is not owned or Foreman is not configured to use logins then send the email to the administrator. Default: false

foreman_url

Emails may contain embedded references to Foreman’s web interface. This option allows the hostname component of the URL to be configured. Default: foreman.

ignore_puppet_facts_for_provisioning

If this option is set to true then Foreman will not update a host’s IP and MAC with the values that it receives in a host’s facts and it will also include Foreman’s values for IP and MAC to puppet in its node information. Default: false

manage_puppetca

If this option is set to true then Foreman will manage a host’s Puppet certificate signing. If it is set to false then some external mechanism is required to ensure that the host’s certificate request is signed. Default: true

use_uuid_for_certificates

When enabled, Foreman will generate UUIDs for each host instead of using the hostname as the Puppet certname, which is more reliable with changing hostnames. Note that when disabling this setting, existing stored certnames won’t be changed or discarded until new certificates are requested from a host (i.e. on a rebuild), in order that the existing certificate remains known to Foreman and can be revoked.

modulepath

This it the modulepath that foreman uses when processing puppet modules. It is usually able to determine this itself at runtime but if it is not able to find a value then modulepath is used. Default: /etc/puppet/modules

puppet_interval

This is the number of minutes between each run of puppet. Default: 30

puppet_server

The default puppet server hostname. For larger organizations this is often a non fqdn so that a name like puppet can be a different host within each DNS domain. Default: puppet

puppetconfdir

Path to directory containing puppet.conf. Default: /etc/puppet

puppetrun

If this option is set to true then Foreman will be able to trigger a puppet run on any host that it manages. Default: false

root_pass

If a root password is not provided whilst configuring a host then this encrypted password is used when building the machine. The plain text password “123123” has been encrypted to produce the default value. Default: xybxa6JUkz63w (To generate a new one you should use: openssl passwd -1 “your_password” )

safemode_render

The default templating system used within Foreman allows unlimited interpolated variables and expressions. This could obviously be abused so a evaluation environment is provided that restricts the template variables and expressions to a whitelist. When this option is true then only known helper methods and instance variables will be available in template expansion. Default: true

ssl_ca_file

The SSL Certificate Authority file that Foreman will use when connecting to its smart-proxies. Default: The CA file used by puppet

ssl_certificate

The SSL certificate that Foreman will use when connecting to its smart-proxies. Default: The host certificate used by puppet

ssl_priv_key

The SSL private key file that Foreman will use when connecting to its smart-proxies. Default: The private key file used by puppet

update_environment_from_facts

If Foreman receives an environment fact from one of its hosts and if this option is true, it will update the host’s environment with the new value. By default this is not the case as Foreman should manage the host’s environment. Default: false

using_storeconfigs

Must be false, a shared storeconfigs database (which this setting refers to) is now unsupported.

3.5.3 Database Setup

Foreman is a rails application. Therefore, anything that is supported under RAILS (sqlite, mysql, postgresql, …) can be used. See 3.3 Install From Packages for a list of packages for connecting foreman to the databse of your choice. At this time, Oracle DB is known to not work. Patches are welcome!

The database configuration file can be found at:

/etc/foreman/database.yml

SQLite (default)

By default, the database will be created in the db subdirectory.

production:
  adapter: sqlite3
  database: db/production.sqlite3
  pool: 5
  timeout: 5000

MySQL

Edit your config/database.yml and modify:

production:
  adapter: mysql
  database: puppet
  username: puppet
  password: password
  host: localhost
  socket: "/var/run/mysqld/mysqld.sock"

If you use foreman 1.0 with foreman-mysql2 use ‘adapter: mysql2’ instead

Afterwards you would need to re-populate your database, simply execute extras/dbmigrate script.

PostgreSQL

Edit your config/database.yml and modify:

production:
  adapter: postgresql
  database: foreman
  username: foreman
  password: password
  host: localhost

Switching from SQLite to MySQL/PostgreSQL while maintaining existing data

We have a rake task for this. First setup your database.yml to have the sqlite db as production and the mysql/psql db as dev:

production:
  adapter: sqlite3
  database: db/production.sqlite3
  pool: 5
  timeout: 5000

development:
  adapter: postgresql
  database: foreman
  username: foreman
  password: password
  host: localhost

Now migrate both dbs so they’re consistent:

bundle exec rake db:migrate RAILS_ENV=production
bundle exec rake db:migrate RAILS_ENV=development

Now move the data to the new db

bundle exec rake db:convert:prod2dev

(On RPM distros, remove “bundle exec” from the start of these commands.)

Once you’ve migrated to your new database using prod2dev, you should update your database.yml file to point your ‘production’ environment at the new database. You should also update the ‘development’ environment to point to an alternative location (for example, at SQLite) to ensure you don’t accidentally overwrite your production database.

Special notes for migrating to Postgres

Firstly, the default installer setup doesn’t give superuser privileges to the ‘foreman’ user, which then prevents the prod2dev script from temporarily disabling foreign keys. You’ll need to do

sudo -u postgres psql -c 'ALTER USER foreman WITH SUPERUSER'

before the prod2dev call, and

sudo -u postgres psql -c 'ALTER USER foreman WITH NOSUPERUSER'

after it.

Secondly, the psql sequence numbers will be wrong after the prod2dev execution. You can fix them like this:

cat <<EOF > reset.sql
SELECT  'SELECT SETVAL(' ||quote_literal(S.relname)|| ', MAX(' ||quote_ident(C.attname)|| ') ) FROM ' ||quote_ident(T.relname)|| ';'
FROM pg_class AS S, pg_depend AS D, pg_class AS T, pg_attribute AS C
WHERE S.relkind = 'S'
    AND S.oid = D.objid
    AND D.refobjid = T.oid
    AND D.refobjid = C.attrelid
    AND D.refobjsubid = C.attnum
ORDER BY S.relname;
EOF
psql -Atq -f reset.sql -o temp foreman
psql -f temp foreman
rm temp reset.sql

(big thanks to Fixing Sequences for the fix)

3.5.4 Puppet Reports

Foreman uses a custom puppet reports address (similar to tagmail or store) which Puppet will use to upload it’s report into Foreman. This enables you to see the reports through the web interface as soon as the client finishes its run.

Configuration

Client

Ensure that the puppet clients has the following option in their puppet.conf:

report = true

Without it, no reports will be sent.

puppetmaster

1. copy https://raw.github.com/theforeman/puppet-foreman/master/templates/foreman-report_v2.rb.erb to your report directory
2. e.g. /usr/lib/ruby/1.8/puppet/reports/foreman.rb, /usr/lib/ruby/site_ruby/1.8/puppet/reports/foreman.rb, /var/lib/gems/1.8/gems/puppet-2.6.4/lib/puppet/reports/foreman.rb or /usr/lib/ruby/vendor_ruby/puppet/reports.
3. make sure you copied the foreman-report_v2.rb.erb to foreman.rb so puppet can find it!
4. open the new file with your favorite editor
5. edit the URL to point to foreman.
6. add this report in your puppetmaster reports - e.g, in your master puppet.conf under the main section add:

reports=log, foreman

and restart your puppetmaster

You should start seeing reports coming in under the reports link.

Expire Reports automatically

You will probably want to delete your reports after some time to limit database growth. To do so, you can set a cronjob:

Available conditions:

• days => number of days to keep reports (defaults to 7)
• status => status of the report (defaults to 0 –> “reports with no errors”)

Example:

1. Expires all reports regardless of their status

   foreman-rake reports:expire days=7

2. expires all non interesting reports after one day

   foreman-rake reports:expire days=1 status=0

3.5.5 Facts and the ENC

Foreman can act as a classifier to Puppet through the External Nodes interface. This is a mechanism provided by Puppet to ask for configuration data from an external service, via a script on the puppetmaster.

The external nodes script we supply also deals with uploading facts from hosts to Foreman, so we will discuss the two things together.

Configuration

puppetmaster

1. Copy external_node_v2.rb.erb to the Puppet configuration directory, e.g. ‘/etc/puppet’
2. The name you choose for the file is arbitrary, but we will assume ‘node.rb’, e.g. ‘/etc/puppet/node.rb’. Ensure it is executable by the puppet user.
3. Edit the new file, and configure the settings:
   • url - The address of the Foreman server (e.g. http://foreman )
   • puppetdir - The location of Puppet’s cache dir (e.g. /var/lib/puppet )
   • ssl_* - SSL certs as per Securing Communications With SSL
4. Add the following lines to the [master] section of puppet.conf:
   • external_nodes = /etc/puppet/node.rb
   • node_terminus = exec

Restart the puppetmaster. When the next agent checks in, the puppetmaster will upload fact data for this host to Foreman, and download the ENC data.

Client

No agent configuration is necessary to use this functionality.

Testing the config

Make sure that the puppet user can execute the ENC script and it works:

sudo -u puppet /etc/puppet/node.rb [the name of a node, eg agent.local]

should output something like:

parameters:
  puppetmaster: puppet
  foreman_env: &id001 production
classes:
  helloworld:
environment: *id001

This output should match the information displayed when you click on the YAML button on the Host page in Foreman.

For further information see the Puppet Labs docs on external nodes

Assigning data to hosts through the ENC

Foreman passes all assoicated parameters, classes,and class parameters, to the Host, including those inherited from host groups, domains, or global settings. See section Managing Puppet for more information on assigning configuration to hosts.

Pushing Facts to Foreman when not using the ENC functionality

There are several options for pushing fact data to Foreman if you are using Foreman for reporting/inventory only.

Using node.rb

The ENC script (node.rb) accepts an option to run in ‘batch-mode’. In this mode, the script iterates over the cached fact data stored on the puppet master, and uploads all of it to Foreman.

Download and configure the node.rb script as above, and then call it like this:

sudo -u puppet /etc/puppet/node.rb --push-facts

Direct HTTP upload

As of Foreman 1.3, the fact-upload API endpoint accepts data in pure JSON. You can push data to Foreman as a hash containing:

{
  "name": "fqdn-of-host.domain.com",
  "certname": "optional-certname-of-host.domain.com",
  "facts": {
    "fact1": "string",
    "fact2": "true",
    "fact3": "1.2.3.4",
    ...
  }
}

The ‘certname’ is optional but will be used to location the Host in Foreman if supplied. The ‘facts’ hash must be a flat hash, not nested with other arrays or hashes. See link-to-API-when-its-updated-here for more details.

This body can be POSTed to ‘/api/hosts/facts’ using Foreman API v2. See the node.rb template for an example of constructing and sending data in Ruby.

3.5.6 CLI

The Command Line Interface is based on the hammer framework. The foreman-related commands are defined in plugin hammer_cli_foreman

Format and locations

Configuration is set based on the following files, loaded in this order:

• /etc/foreman/cli_config.yml.
• ~/.foreman/cli_config.yml
• ./config/cli_config.yml (config dir in CWD)
• custom location specified on command line - -c CONF_FILE_PATH

Later files have precedence if they redefines the same option.

Hammer uses yaml formatting for its configuration. The config file template is contained in the hammer_cli gem

gem contents hammer_cli|grep cli_config.template.yml

and can be copied to one of the locations above and changed as needed. The packaged version of hammer copies the template to /etc for you.

Plugins

Plugins are disabled by default. You have to edit the config file and enable them manually under modules option, as can be seen in the sample config below.

Plugin specific configuration should be nested under plugin’s name.

Options

• :log_dir: <path> - directory where the logs are stored. The default is /var/log/foreman/ and the log file is named hammer.log
• :log_level: <level> - logging level. One of debug, info, warning, error, fatal
• :log_owner: <owner> - logfile owner
• :log_group: <group> - logfile group
• :log_size: 1048576 - size in bytes, when exceeded the log rotates. Default is 1MB
• :watch_plain: false - turn on/off syntax highlighting of data being logged in debug mode

Sample config

:modules:
    - hammer_cli_foreman

:foreman:
    :host: 'https://localhost/'
    :username: 'admin'
    :password: 'changeme'

:log_dir: '/var/log/foreman/'
:log_level: 'debug'

3.6 Upgrade

Upgrading to Foreman 1.3

Preparation

Before updating to 1.3, make sure you have successfully upgraded to 1.2 first.

Upgrading across more than one version is not supported, so it’s required to upgrade to each intermediate version and follow all upgrade instructions for the previous versions.

Please check the upgrade notes for this release, as there may be things to be aware of or additional steps:

• Foreman 1.3 Upgrade Notes

Step 1 - Backup

It is recommended that you backup your database and modifications to Foreman files(config/settings.yaml, unattended installations etc). Most upgrades are safe but it never hurts to have a backup just in case.

For more information about how to backup your instance head over to Backup

Step 2 - Perform the upgrade

Before proceeding, it is necessary to shutdown the Foreman instance.

Now it’s time to perform the actual upgrade. This process if different depending on how you downloaded Foreman. You only need to perform one of the following options.

Option 1 - Upgrading from a package on Fedora or RHEL

Upgrading from 1.2

Important note: Foreign keys on the SQL database level were introduced in the Foreman 1.3. During migration, all orphaned records are deleted automatically. It is strongly recommended to backup database prior proceeding with upgrade.

To upgrade an existing Foreman 1.2 installation, first update with the appropriate foreman-release package from the above list of release packages, e.g. for RHEL6

yum upgrade http://yum.theforeman.org/releases/1.3/el6/x86_64/foreman-release.rpm
cat /etc/yum.repos.d/foreman.repo.rpmnew > /etc/yum.repos.d/foreman.repo

Next upgrade all Foreman packages:

yum upgrade ruby\* foreman\*

If you wish to install the SELinux policy, also install the foreman-selinux package.

If Foreman doesn’t load due to a Passenger error (particularly referencing bundler_ext), verify the configuration against the description in the Software Collections section below.

You can skip to Step 3.

Option 2 - Upgrading from a package on Debian or Ubuntu

Upgrading from 1.2

Upgrading from 1.2 to 1.3 has been tested on both Debian and Ubuntu. Updating the packages will upgrade the application and automatically migrate the database.

apt-get update
apt-get dist-upgrade

You can skip to Step 3.

Option 3 - Downloaded release (tar.bz2)

• Uncompress the new program archive in a new directory.
• Copy your database settings-file config/database.yml into the new config directory.
• If your database is a simple file (e.g. SQLite), don’t forget to make it available in the new directory.

VERY IMPORTANT: do NOT overwrite config/settings.yml with the old one.

Option 4 - Upgrading from git

Please note now that the development branch has moved to Rails 3, you MUST take care to select a branch and make sure you get the correct one.

1. Go to the Foreman root directory and run the following command:

For staying on the stable branch:

• git checkout 1.3-stable
• git pull

The following step is the one that could change the contents of your database. Go to your new Foreman directory (or the git dir), then migrate your database:

foreman-rake db:migrate

You should compile i18n strings and precompile assets now:

foreman-rake locale:pack
foreman-rake assets:precompile

Step 3 - Cleanup

Database should be migrated already, but you can make sure by executing the migration script again, it should produce no errors or output:

foreman-rake db:migrate

You should clear the cache and the existing sessions:

foreman-rake tmp:cache:clear
foreman-rake tmp:sessions:clear

Step 4 - Restart

Restart the application server (e.g. mongrel, thin, passenger)

Common issues

See Troubleshooting

4. General Foreman

This section covers general information on using Foreman to manage your infrastructure. It covers the features of the web interface, managing puppet, provisioning systems and the installation and configuration of Foreman Smart Proxies.

4.1 Web Interface

4.1.1 LDAP Authentication

Foreman natively supports LDAP authentication using one or multiple LDAP directories.

Enabling LDAP

Enable LDAP and User/Group settings menus

Edit your config/setting.yml

:login: true

and restart Foreman

Setting up

Go to More > Users > LDAP Authentication

Click on New LDAP Source and enter the following

• Name: an arbitrary name for the directory
• Host: the LDAP host name
• Port: the LDAP port (default is 389)
• LDAPS: check this if you want or need to use LDAPS to access the directory
• Account: leave this field empty if your LDAP can be read anonymously, otherwise enter a user name that has read access to the LDAP or use $login (which will be replaced with the actual user credentials upon login)
• Account Password: password for the account (if defined above and its not using the $login)
• baseDN: the top level DN of your LDAP directory tree

On the fly user creation

By checking On-the-fly user creation, any LDAP user will have his Foreman account automatically created the first time he logs into Foreman. For that, you have to specify the LDAP attributes name (firstname, lastname, email) that will be used to create their Foreman accounts.

Examples

Active Directory

Name              = My Directory
Host              = host.domain.org
Port              = 636
TLS               = yes
Onthefly register = yes
Account           = MyDomain\$login
Password          = (leave blank)
Base DN           = CN=users,DC=host,DC=domain,DC=org
attr login        = sAMAccountName
attr firstname    = givenName
attr lastname     = sN
mail              = mail

OpenLDAP

Name              = My Directory
Host              = host.domain.org
Port              = 389
TLS               = no
Onthefly register = yes
Account           = (leave blank if anonymous access is enabled)
Password          = (leave blank)
Base DN           = ou=Users,dc=domain,dc=co,dc=il
attr login        = uid
attr firstname    = givenName
attr lastname     = sn
mail              = mail

Note that LDAP attribute names are case sensitive.

Troubleshooting

If you want to use on-the-fly user creation, make sure that Foreman can fetch from your LDAP all the required information to create a valid user. For example, on-the-fly user creation won’t work if you don’t have valid email addresses in your directory (you will get an ‘Invalid username/password’ error message when trying to log in).

4.1.2 Roles and Permissions

A user’s access to the features of Foreman are constrained by the roles and permissions that they are granted. These permissions are also used to restrict the set of hosts, host groups and domains that a user is able to access and modify.

Note: a user with global admin enabled is not restricted by the authorization system. This is the default for installations that do not have :login:true in config/settings.yml.

A logged in user will be granted the Anonymous role plus one or more additional roles. The permissions associated with these roles are aggregated and determine the final permission set.

Roles may be administered only by a user with global admin privileges.

Roles

These may be created, deleted and edited on the Roles page. Each role will be associates with one or more base privileges.

There are two builtin system roles

1. Anonymous: This is a set of permissions that every user at your installation will be granted, irrespective of any other roles that they have.
2. Default user: When a new Role is created this set of permissions are used as the template for the Role. The name is somewhat misleading but basically an ordinary default user who was assigned this Role would have these permissions set.

Permissions

These determine the operations that are allowed to be performed upon the items to which they refer. For simple items, like an architecture, this operates as expected but for more complex items, such as, the hosts a user is able to operate on, there is an additional layer of security called filtering.

When editing a user account there is a section at the bottom that narrows the scope of the permissions granted to a subset of the hosts, domains and host groups. See filtering below.

Filtering

If the filtering section at the bottom of the user’s profile page has no content then the permissions that the user has been granted will apply to all hosts within the system.

However, if the filtering section is in use then the permissions will apply only to those items selected in the filters and the user will have no access to anything not selected by the filters.

This is primarily a mechanism for restricting access to hosts. However if one or more domains or host groups are selected then this also restricts where parameters can be created, edited and deleted.

Filtering operates by generating a list of hosts on which actions can be performed. The list may be built out of four components

1. Ownership: The hosts that a user owns directly or hosts that are owned by a user group of which the user is a member.

2. Domain membership: The hosts that exist within one or more indicated domains.

3. Compute resource membership: The hosts that are deployed on one or more compute resources.

4. Host group membership: The hosts that are defined as being of one or more host group types.

5. Fact filtering: These restrict the hosts to those machines that have this fact associated with them. As a fact is only generated during a puppet run, this filter will only refer to machines that have been built and therefore cannot be used to restrict the creation of machines.

These four pools of hosts can be combined by adding them together or the filters can be used to restrict the selected hosts to a smaller and smaller subset of the total. Think of it as set operations.

Note: If the “Administrator” check box is checked for a user, filtering will not take effect.

Example

A user’s filter section has the select checkbox unticked, indicating that the user’s owned hosts are not included in the final set of hosts, (unless they are selected some other way.)

The domain selection is prefixed with plus all and the two domains a.com and b.com are ticked. This implies that the hosts selected are the user’s hosts, (of which there are none,) plus all the hosts in a.com and b.com.

The host group section is prefixed by must be and the hostgroup web server is selected. This implies that the hosts selected are the user’s hosts, (of which there are none,) plus all the hosts in a.com and b.com but they must be of type web server.

The fact filter section is prefixed by must match and there are two filters virtual = vmware and architecture = i386. This implies that the hosts selected are the user’s hosts, (of which there are none,) plus all the hosts in a.com and b.com but they must be of type web server and must match an i386 vmware host.

In any of these sections above, if the prefix had been plus all then every host in the system that matched the selections would have been added to the final host list, (though possibly removed by a later filter.)

4.1.3 Trends

Trends in Foreman allow you to track changes in your infrastructure over time. It allows you to track both Foreman related information and any puppet facts. The Trend pages give a graph of how the number of hosts with that value have changed over time, and the current hosts list.

There are two pieces to the Trends area, the Trends to track and their corresponding counters. To define trend counters, use the “Add Trend Counter” button on the ‘/trends’ page. Optionally set the “Name” field to over-ride odd puppet fact names to be more readable. Once created you can optionally ‘Edit’ the Trend to change the display names of the underlying values.

Next, to start collecting trend data, set a cron job to execute ‘foreman-rake trends:counter’. Each time the rake task executes it will create 1 tick on the graphs, so you can fine tune the granularity with your cron job. We recommend using the same as your puppet run interval (30 minutes). Here’s an example to run once per hour:

0 * * * * /usr/sbin/foreman-rake trends:counter

Finally note that these trends are the same for all users. So if you delete a Trend category you will loose all history for that trend and the trackers will start all over again. So please be careful when deleting.

4.1.4 Auditing

Foreman supports auditing of almost all changes that happen within Foreman, from both the UI and from the API. Auditing is done at a user level, and is thus ineffective if :login: is set to false, as all audits will be done as the ‘admin’ user.

Basic View

Got to the Audit tab to see a view of what has changed. This view can be filtered by the type of change or by the object that was altered (e.g. search for a hostname to see all changes relating to that host). You also get the parent object - so if a parameter was modified, you can see what host/group that parameter belongs to. The timestamp of the change and the user who performed it will be listed.

Extended Audits for Templates

Template changes also store a diff of the changes, and the ability to roll back to a previous version of the template.

4.2 Managing Puppet

In this section we’ll look at the various ways we can control and interact with Puppet.

4.2.1 Environments

Puppet environments are mapped directly into Foreman. They can be used at various levels throughout the Foreman interface. Puppet environments are generally used to separate classes from different types of Host, typically allowing changes to a module to tested in one environment (e.g. development) before being pushed to another (e.g production).

Defining Environments

There are several ways to create Puppet environments within Foreman.

Manual creation

To create an environment by hand, simply go to More > Configuration > Environments and click New Environment. Give the new environment a name and save.

Importing from Puppet

Foreman can detect all the environments and classes contained on a PuppetMaster, and import them automatically. To do this, go to More > Configuration > Environments and click on *Import from *. Foreman will scan the PuppetMaster, and display a confirmation of the detected changes. Select the changes you wish to apply and confirm.

Assigning Environments to Hosts

This is done from the Host Edit page, on the Host tab. Selecting an environment will filter the classes visible on the Puppet Classes tab to just the classes in the selected environment.

You can also also mass-assign an environment to a group of hosts - tick the checkboxes of the required Hosts in the Hosts index, and then select Change Environment from the buttons at top of the page.

Environments with Hostgroups

You can assign an environment to a hostgroup as well. This functions as a form of default - a user creating a new host and selecting the hostgroup will automatically have the environment pre-selected. The user is not prevented from changing the environment of the new host, it simply saves a few clicks if they are happy with it.

4.2.2 Classes

Puppet classes are generally imported from the Puppet Master(s) via the Import button on the Puppet Classes page. They can also be created by hand, and manually associated with a set of environments (for filtering purposes).

Importing Classes

Go to More > Configuration > Puppet Classes and click the Import button. This will not be visible unless you have at least one Puppet Master with a puppet-enabled Smart Proxy

The “Hosts” Column

Under More > Configuration > Puppet Classes you will also see a column called “Hosts”. This column represents the number of hosts the given module/class has been assigned to. Clicking this figure will list the hosts.

This column currently suffers from a known bug. This bug means this count excludes host groups from final figure.

Ignoring classes on import

It’s often to have a module structure like this:

$ tree git/
git/
└── manifests
    ├── init.pp
    ├── install.pp
    ├── params.pp
    └── repo.pp

In this situation, Foreman would offer to create:

git
git::install
git::params
git::repo

However, if we know that the subclasses are not intended for direct consumption, but are only really part of the internal structure of the module, then we would want to exclude those from the import mechanism, so that Foreman only offers to import git. We can achieve this via the file config/ignored_environments.yml. This file takes a set of regular expressions - any class which matches one of them will not be imported. So, for this example, we might configure:

:filters:
  - !ruby/regexp '/install$/'
  - !ruby/regexp '/params$/'
  - !ruby/regexp '/repo$/'

Assigning Classes to Hosts

To cause Puppet to apply your classes, you will need to assign them to your Hosts. This can be done at either an individual host level, or at a group level. The process is the same; edit the Host(group), select an Environment, and then go to the Puppet Classes tab and select what classes you want in this Host(Group).

Checking the results

To see how Foreman is passing the classes to Puppet, go to a Host and click the YAML button. You will be shown the exact YAML data sent to the PuppetMaster - the classes will be in the “classes” hash.

4.2.3 Parameters

Foreman’s concept of parameters maps onto Puppet’s idea of default-scope parameters. Foreman allows us to define a hierarchy of parameter inheritance.

Global Parameters

These are defined in More > Configuration > Global Parameters and will apply to every host in Foreman.

Domain Parameters

These are defined for all Hosts in a given domain. Edit the domain from More > Provisioning > Domains and switch to the Parameters tab and specify a parameter. If it has the same name as a Global Parameter, it will override the Global one.

Hostgroup Parameters

These are defined for all Hosts in the Group. Edit the Hostgroup from More > Configuration > Host Groups and switch to the Parameters tab and specify a parameter. If it has the same name as a Global or Domain Parameter, it will override it.

Host Parameters

The final (most-specific) level of Parameters applies only to a single Host. Edit a Host and switch to Parameters, and you will see all it’s inherited parameters from the other three layers (note: they will all be marked as “Scope: Global” as this refers to the Puppet scope, not the Foreman scope). You can override higher-level parameters or define new ones here.

Checking the results

To see how Foreman is passing the parameters to Puppet, go to a Host and click the YAML button. You will be shown the exact YAML data sent to the PuppetMaster -the parameters will be in the “parameters” hash.

4.2.4 Smart Variables

Smart variables are a tool to provide data (Key / Value), normally to your puppet ENC, depending on a set of rules. They are intended to be a stepping stone to full parameterized classes.

Smart variable is usually associated with a puppet class, and may have multiple values, all depending on hierarchical context or various conditions a user can wish to apply.

for example:

Creating a Smart Variable

Start by going to Foreman > More > Puppetclasses and then click one of your classes to edit it.

Click on the Smart Variables tab. If you have any existing Smart Variables, they will be listed at the left side of the tab.

Click New Variable, and you will be presented with a set of input fields:

Once you’ve created the defaults for your Smart variable, you then need to add at least one criterion to match against - click the “plus” under your variable, and two more input fields will appear:

Validators

The fourth and fifth fields in the Smart Variable combine to produce a validation criteria for the final value of the Smart Variable.

String validators

At present, the string type cannot be validated - leave the validator field blank, and all strings in the variable will be considered acceptable

Regexp / List validators

By entering a list (comma-separated, no spaces) or a regex (no delimiter required), the value to be assigned to the Smart Variable will be checked against this list. If the value does not match the validator, and error will be raised.

Ordering

All the ordering information is stored in the sixth field of the Smart Variable (order). The order matters and is used to find the first match.

Examples

Example 1 - Simple change to a single host

All our hosts use server.foo for something, except bob.domain.com which uses server2.bar:

Example 2 - Change for a group of hosts (via custom fact) with validation and ordering

Most hosts need to use a port of 80 but all machines with a fact region and value europe need to use 8080. To do this, you have to add the factname (in this example region) to the searchlist:

Note that all machines will get either 80 or 8080 as required, except foo.domain which will generate an error, since 67 is not in the list validator. Note also that foo.domain will match before region, since it is higher in the searchlist. The rule ordering does not matter.

It is also possible to mix conditions, e.g.

API usage

It’s also possible to retrieve these values if you’re not using a ENC, via a custom Puppet function or a http request.. You’ll need to retrieve the value from

https://foreman/hosts/<fqdn>/lookup_keys/<key>

You can find a ready-made function for your puppet module here

4.2.5 Parameterized Classes

Parameterized Class Support (PCS) permits detecting, importing, and supplying parameters direct to classes which support it, via the ENC.

Requirements

• Foreman 1.1+
• Foreman-Proxy 1.1+
• Puppet 2.6.5+

Setup

Firstly, you’ll need to enable the PCS support. Go to More > Settings, select the Puppet tab, and ensure Parameterized_Classes_in_ENC is set to true.

Now you’ll need to import some parameterized classes from your puppet master. If you don’t have any parameterized classes in your modules dir, the foreman-installer has several, you can download a few modules from the Puppet Forge. Once you have some parameterized modules, import your classes (see 4.2.2 Classes)

Configure a class

This example will work with the foreman class from the installer. Click on the class, and you should get a page with 3 tabs, like so:

The middle tab, “Smart Class Parameter”, is the important one. Click onto that, and you should see something like this:

On the left, we have a list of possible parameters that the class supports. On the right, we have the configuration options for the parameter selected.

Lets configure the foreman class to change the user the foreman processes run as. Select the user parameter, at the end of the list. Now lets go through the options:

• Puppet Environments / Name
  • These can’t be edited, they’re just for information.
• Description
  • Purely information textbox for making notes in. Not passed to puppet, or reused anywhere else
• Override (important)
  • If this is unchecked, Foreman will not attempt to control this variable, and it will not be passed to Puppet via the ENC.
• Type
  • The type of data we want to pass. Most commonly a string, but many other data types are supported. There’s no easy way to tell what type of data puppet is expecting, so you will need to read through the code/documentation that comes with a particular module to find out. Changing the type field requires an appropriately set “Default Value” field.
• Default Value
  • This will be imported from puppet initially, but if puppet is using any class inheritance, you’ll get something unhelpful like “${$foreman::params::user}”. This is because Foreman won’t follow the inheritance, so you’ll need to set a sensible default value

Ok, so let’s configure our user parameter. We want to tick Override, set type to “String” and set the default value to “foreman”, like so:

Setting up Matchers

We’ve configured the default, but that’s not very useful. We need to be able to override the default for hosts or groups of hosts. To do that we need the “Override Value For Specific Hosts” section at the bottom of the page.

Let’s say that any machine in the “development” puppet environment should use a value of “foremandev” instead of “foreman” for the “user” parameter. Add “environment” to the end of the matchers list, then click the “New Matcher-Value” button, and fill it out like this:

This is a basic configuration - for more complex examples of using matchers, see the 4.2.4 Smart Variables page.

Complex Data

Here’s an example of adding an array parameter. Note the use of YAML in the editbox:

This will be converted to the normal [“a”,”b”] syntax when you save. You can also use Hashes, YAML or JSON as data types too.

Template Variables

Because Foreman offers templating capabilities, you can utilise pre-existing variables, macros and or functions within your parameterized classes. This is especially useful if you need to send a string to Puppet/Chef, but have a need to embed host specific information within the string, such as the host’s FQDN.

Let’s look a quick example situation: we need to configure RabbitMQ and have it use our existing Puppet SSL certs. Using what we’ve learnt above, we jump into the RabbitMQ class and configure the “ssl cert” parameter as such:

As you can see we’re utilising a template variable within the parameter’s string just like we would in a normal template file. The important part of this string, as we’re sure you’ve gathered, is the “@host.name” element. This pulls the FQDN from Foreman’s facts and inserts it into the string.

More information regarding templates can be found on the wiki. This page also contains the pre-existing functions and macros you can use in your templates and parameter classes.

Editing Param from within a Host

If Foreman manages the value of a class parameter (“override = true”), it’s also possible to update a host-specific override from the host itself. That way you don’t have to grant access to the Puppet Classes page to everyone. From a Host, click Edit, go to the Parameters tab, and you’ll see the variable, the class-scope, and the current value. You can then override the value for that host:

If you go back and look at the Puppet class, you’ll see Foreman has added a matcher for that host:

Currently this only works for Hosts, not Hostgroups. For more complex logic, like matching on facts, use the Puppet Class page

Input Validation

The “Optional Input Validator” section can be used to restrict the allowed values for the parameter. This functions in the same way as for Smart Variables, but it is important to note that the validation applies to changes made from the Host edit page as well as the Puppet Classes edit page.

For example, to restrict the “user” field to either “foreman” or “foremandev”, tick the Required checkbox, and then set:

• Type: List
• Rule: foreman,foremandev

4.3 Smart Proxies

The Smart Proxy is a project which provides a restful API to various sub-systems.

Its goal is to provide an API for a higher level orchestration tools (such as Foreman). The Smart proxy provides an easy way to add or extended existing subsystems and API’s.

Currently supported (Click on the links below for more details).

• DHCP - ISC DHCP and MS DHCP Servers
• DNS - Bind and MS DNS Servers
• TFTP - any UNIX based tftp server
• Puppet - Any Puppet server from 0.24.x
• Puppet CA - Manage certificate signing, cleaning and autosign on a Puppet CA server

If you require another sub system type or implementation, Please add a new feature request.

After you got it running, You would need to configure each one of the sub systems via the settings.yml file in the config directory.

4.3.1 Smart Proxy Installation

A smart proxy is an autonomous web-based foreman component that is placed on a host performing a specific function in the host commissioning phase. It receives requests from Foreman to perform operations that are required during the commissioning process and executes them on its behalf. More details can be found on the Foreman Architecture page.

To fully manage the commissioning process then a smart proxy will have to manipulate these services, DHCP, DNS, Puppet CA, Puppet and TFTP. These services may exist on separate machines or several of them may be hosted on the same machine. As each smart proxy instance is capable of managing all the of these services, there is only need for one proxy per host. In the special case of a smart proxy managing a windows DHCP server, the host machine must be running Windows and support the netsh dhcp utility, it does not need to be the Microsoft DHCP server itself.

Packages

RPM and Debian packages are available, see the Install from Packages section for configuration and install the foreman-proxy package.

Source code

You can get the latest stable code from GitHub (via git).

git clone git://github.com/theforeman/smart-proxy.git

Configuration file

Usually can be found at /etc/foreman-proxy/settings.yml or on the config/settings.yml subdirectory. You can use the settings.yml.example file inside the config directory as a template for your own settings.yml.

If you don’t plan to use one of the subsystems, please disable them in this configuration file. For more information see Smartproxy Configuration

Start the daemon

  bin/smart-proxy.rb

Or if you installed it via a package simply start the foreman-proxy service.

Add the smart-proxy to Foreman

• Go to [FOREMAN_URL]/smart_proxies and click New Proxy
• Type in the Name for your Proxy and the URL of your Proxy, with the Port used.

For example:

  Name: Puppet-Proxy
  URL: http://puppet.your-domain.com:8443

4.3.2 Smart Proxy Settings

The configuration for Smart-Proxy is held in the /etc/foreman-proxy/settings.yml or config/settings.yml file.

YAML start

The first non-comment line of this file must be three dashes.

---

SSL configuration

The existence of all the three ssl key entries below enables the use of an SSL connections.

NOTE that both client certificates need to be signed by the same CA, which must be in the ssl_ca_file, in order for this to work see SSL for more information

  :ssl_certificate: ssl/certs/fqdn.pem
  :ssl_ca_file: ssl/certs/ca.pem
  :ssl_private_key: ssl/private_keys/fqdn.key

This is the list of hosts from which the smart proxy will accept connections. If this list is empty then every verified SSL connection is allowed to access the API.

:trusted_hosts:
- foreman.prod.domain
- foreman.dev.domain

Instance attributes

If this entry is present and not false then Smart-Proxy will attempt to disconnect itself from the controlling terminal and daemonize itself.

:daemon: true

The port listened to by the proxy. If this is not present then the default Sinatra port of 4567 is used.

:port: 8443

TFTP section

Activate the TFTP management module within the Smart-Proxy instance.

The tftproot value is directory into which tftp files are copied and then served from. The tftp daemon will also be expected to chroot to this location. This component is only supported in the Unix environment

:tftp: true
:tftproot: /var/lib/tftpboot
:tftp_servername: name of your tftp server (used for next server value in your dhcp reservation) - defaults to the host name of your proxy.

NOTE: the foreman proxy user must have read/write access to the tftpboot/pxelinux.cfg and tftpboot/boot directories.

DNS section

Activate the DNS management module within the Smart-Proxy instance.

The DNS module can manipulate any DNS server that complies with the ISC Dynamic DNS Update standard and can therefore be used to manage both Microsoft and Bind servers. Updates can also be done using GSS-TSIG, see the documentation.

The dns_key specifies a file containing a shared secret used to generate a signature for the update request (TSIG record). This option should not be used if you plan to use Kerberos/GSS-TSIG (for example for DNS servers shipped with FreeIPA or Microsoft AD).

If neither the dns_key or GSS-TSIG is used then the update request is sent without any signature. Unsigned update requests are considered insecure. Some DNS servers can be configured to accept only signed signatures.

The dns_server option is used if the Smart-Proxy is not located on the same physical host as the DNS server. If it is not specified then localhost is presumed.

:dns: true
:dns_key: /home/proxy/keys/Kapi.+157+47848.private
:dns_server: dnsserver.site.domain.com

NOTE: if you use a key, make sure that the foreman proxy account can read that file.

DHCP section

Activate the DHCP management module within the Smart-Proxy instance.

:dhcp: true

If the DHCP server is ISC compliant then set dhcp_vendor to isc. In this case Smart-Proxy must run on the same host as the DHCP server. If the proxy is managing a Microsoft DHCP server then set dhcp_vendor to native_ms. Smart-Proxy must then be run on an NT server so as to access the Microsoft native tools, though it does not have to be the same machine as the DHCP server. More details can be found at [[Foreman:Foreman Architecture]].

:dhcp_vendor: isc

The DHCP component needs access to the DHCP configuration file as well as the currently allocated leases. The section below shows these values for a RedHat client. In the case of a Smart-Proxy hosted on an Ubuntu machine then these values would be more appropriate: /etc/dhcp3/dhcpd.conf and /var/lib/dhcp3/dhcpd.leases

:dhcp_config: etc/dhcpd.conf
:dhcp_leases: etc/dhcpd.leases

NOTE: Make sure that the foreman proxy account can read both ISC configuration files.

If your native_ms implementation is slow then you can request that the smart proxy only operate on a subset of the subnets managed by the dhcp server.

:dhcp_subnets: [192.168.1.0/255.255.255.0, 192.168.11.0/255.255.255.0]

If you secured your DHCP with an “omapi_key”, add the entries:

:dhcp_key_name: omapi_key
:dhcp_key_secret: XXXXXXXX

Puppet Certificate Authority section

Activate the Puppet CA management module within the Smart-Proxy instance.

This should only be enabled in the Smart-Proxy that is hosted on the machine responsible for providing certificates to your puppet clients. You would expect to see a directory /var/lib/puppet/ssl/ca on such a host.

:puppetca: true

If your puppet SSL directory is located elsewhere, you’ll need to set ‘ssldir’ as well.

:ssldir: /etc/puppet/ssl

:puppetdir: /etc/puppet

The proxy requires write access to the puppet autosign.conf file, which is usually owner and group puppet, and has mode 0644 according to the puppet defaults.

Ensure the foreman-proxy user is added to the puppet group ( e.g. gpasswd -a foreman-proxy puppet or usermod -aG puppet foreman-proxy)

puppet.conf:

[master]
autosign = $confdir/autosign.conf {owner = service, group = service, mode = 664 }

Sudo access to the proxy is required - in your sudoers file ensure you have the following lines:

For older puppet (pre-3.0) with separate sub-commands available:

foreman-proxy ALL = NOPASSWD: /usr/sbin/puppetca *
Defaults:foreman-proxy !requiretty

For newer monolithic puppet without separate commands (3.0-onwards)

foreman-proxy ALL = NOPASSWD: /usr/bin/puppet cert *
Defaults:foreman-proxy !requiretty

Puppet section

Activate the puppet management module within the Smart-Proxy instance.

This should only be enabled in the Smart-Proxy that is hosted on the machine capable of executing puppetrun. This will be a puppetmaster. This can also be set to true if you need to import puppet classes from the puppetmaster. Without this the import will not be possible

:puppet: true

:puppet_conf: /etc/puppet/puppet.conf
# Defaults to %INSTALL_DIR%/.puppet/puppet.conf

puppet run/kick

Sudo access for the proxy is required - in your sudoers file ensure you have the following lines (use /opt/puppet/bin/puppet for Puppet Enterprise):

Defaults:foreman-proxy !requiretty
foreman-proxy ALL = NOPASSWD: /usr/sbin/puppetrun

If you are using Puppet 3.0 or higher, the puppetrun binary has been removed and so the Smart Proxy will use puppet kick. The sudoers entry should be:

Defaults:foreman-proxy !requiretty
foreman-proxy ALL = NOPASSWD: /usr/bin/puppet kick *

MCollective

The proxy can trigger Puppet runs using the MCollective “puppet” agent. To enable this, add this line to settings.yml:

:puppet_provider: mcollective

And then add a sudoers rule:

Defaults:foreman-proxy !requiretty
foreman-proxy ALL = NOPASSWD: /usr/bin/mco puppet runonce *

Logging

The proxy’s output is captured to the log_file and may be filtered via the usual unix syslog levels:

• WARN
• DEBUG
• ERROR
• FATAL
• INFO
• UNKNOWN

See Ruby’s Logger class for details.

:log_file: /tmp/proxy.log
:log_level: DEBUG

4.3.3 ISC DHCP

ISC implementation is based on the omapi interface, which means:

• No need for root permissions on your DHCP server
• No need to restart (or “sync”) your dhcp server after every modifications.

Configuration

• dhcpd configuration file: ensure you have the following line in your dhcpd.conf file (somewhere in the top first lines):

omapi-port 7911;

• configure the settings file to point to your dhcpd.conf and dhcpd.leases files (make sure they are readable by the smart-proxy user)
• make sure the omshell command (/usr/bin/omshell) can be executed by the smart-proxy user.
• make sure that /etc/dhcp and /etc/dhcp/dhcpd.conf has group foreman-proxy

Securing the dhcp API

The dhcpd api server will listen to any host. You might need to add a omapi_key to provide basic security.

Example generating a key (on CentOS):

yum install bind97
dnssec-keygen -r /dev/urandom -a HMAC-MD5 -b 512 -n HOST omapi_key
cat Komapi_key.+*.private |grep ^Key|cut -d ' ' -f2-

1. Edit your “/etc/dhcpd.conf”:

    omapi-port 7911;
    key omapi_key {
    algorithm HMAC-MD5;
    secret "XXXXXXXXX"; #<-The output from the generated key above.
    };
    omapi-key omapi_key;
    

2. Make sure you also add the omapi_key to your proxy’s [[Smart-Proxy:Settingsyml#DHCP-section

   settings.yml]]

3. Restart the dhcpd and foreman-proxy services

Testing

If everything works, you could browse your dhcp server data if you goto http://proxy:8443/dhcp

The next step is to set up appropriate Subnets in Foreman from the settings menu.

Sample dhcpd.conf

ddns-update-style interim;
ignore client-updates;
authoritative;
allow booting;
allow bootp;

omapi-port 7911;
#Optional key:
key omapi_key {
        algorithm HMAC-MD5;
        secret "2wgoV3yukKdKMkmOzOn/hIsM97QgLTT4CLVzg9Zv0sWOSe1yxPxArmr7a/xb5DOJTm5e/9zGgtzL9FKna0NWis==";
}
omapi-key omapi_key;

subnet 10.1.1.0 netmask 255.255.255.0 {
# --- default gateway
  option routers      10.1.1.254;
  option subnet-mask  255.255.255.0;

  option domain-name    "domain.com";
  option domain-name-servers  10.1.1.1, 8.8.8.8;
  option log-servers    syslog;
  option ntp-servers    ntp;

  range dynamic-bootp 10.1.1.10 10.1.1.250;
  default-lease-time 21600;
  max-lease-time 43200;

}

4.3.4 MS DHCP

The Microsoft smart-proxy installation procedure is very basic compared to the RPM or APT based solution.

It is required that this procedure is executed as an administrator.

It is not required that the smart-proxy be on the same host as the MS dhcp server. The smart-proxy just needs to be on a windows host that has netsh commands available.

1. Go to the smart-proxy repository at https://github.com/theforeman/smart-proxy
2. Select download and choose the latest revision
3. Extract this to a directory that does not have any spaces in its name.
4. Go to the rubyinstaller webpage at http://rubyinstaller.org/downloads/
5. Download and install the “ruby 1.8.7 release 334”:http://rubyforge.org/frs/download.php/74293/rubyinstaller-1.8.7-p334.exe (Allow the ruby associations to be installed.)
6. Open a CMD window and, using gem install –version X.X.X –platform ?????, add these gems

  columnize (0.3.2)
  highline (1.6.1)
  json (1.4.6 x86-mswin32)
  linecache (0.43 mswin32)
  mime-types (1.16)
  mocha (0.9.11)
  net-ping (1.3.7)
  rack (1.2.0)
  rake (0.8.7)
  rest-client (1.6.1)
  sinatra (1.1.0)
  tilt (1.1)
  win32-api (1.4.6 x86-mswin32-60)
  win32-open3 (0.3.2 x86-mswin32-60)
  win32-service (0.7.1 x86-mswin32-60)
  windows-api (0.4.0)
  windows-pr (1.1.2)

Command to download them all:

wget http://rubygems.org/downloads/columnize-0.3.2.gem \
     http://rubygems.org/downloads/haml-3.0.24.gem \
     http://rubygems.org/downloads/highline-1.6.1.gem \
     http://rubygems.org/downloads/json-1.4.6-x86-mswin32.gem \
     http://rubygems.org/downloads/linecache-0.43-mswin32.gem \
     http://rubygems.org/downloads/mime-types-1.16.gem \
     http://rubygems.org/downloads/mocha-0.9.11.gem \
     http://rubygems.org/downloads/net-ping-1.3.7.gem \
     http://rubygems.org/downloads/rack-1.2.0.gem \
     http://rubygems.org/downloads/rake-0.8.7.gem \
     http://rubygems.org/downloads/rest-client-1.6.1.gem \
     http://rubygems.org/downloads/sinatra-1.1.0.gem \
     http://rubygems.org/downloads/tilt-1.1.gem \
     http://rubygems.org/downloads/win32-api-1.4.6-x86-mswin32-60.gem \
     http://rubygems.org/downloads/win32-open3-0.3.2-x86-mswin32-60.gem \
     http://rubygems.org/downloads/win32-service-0.7.1-x86-mswin32-60.gem \
     http://rubygems.org/downloads/windows-api-0.4.0.gem \
     http://rubygems.org/downloads/windows-pr-1.1.2.gem

To get it to work on Windows 2008 R2 some of the packages has to change

 columnize (0.3.2)
 highline (1.6.1)
 json (1.4.6 x86-mingw32)
 linecache (0.43 mswin32)
 mime-types (1.16)
 mocha (0.9.11)
 net-ping (1.3.7)
 rack (1.2.0)
 rake (0.8.7)
 rest-client (1.6.1)
 sinatra (1.1.0)
 tilt (1.1)
 win32-api (1.4.6 x86-mingw32)
 win32-open3 (0.3.2 x86-mingw32)
 win32-service (0.7.1 x86-mswin32-60)
 windows-api (0.4.0)
 windows-pr (1.1.2)

Easy copy and paste method (platform may be different for you. Please check gem environment to find out.

  gem install --version 0.3.2 --platform x86-mingw32 columnize
  gem install --version 1.6.1 --platform x86-mingw32 highline
  gem install --version 1.4.6 --platform x86-mingw32 json
  gem install --version 0.43 --platform x86-mingw32 linecache
  gem install --version 1.16 --platform x86-mingw32 mime-types
  gem install --version 0.9.11 --platform x86-mingw32 mocha
  gem install --version 1.3.7 --platform x86-mingw32 net-ping
  gem install --version 1.2.0 --platform x86-mingw32 rack
  gem install --version 0.8.7 --platform x86-mingw32 rake
  gem install --version 1.6.1 --platform x86-mingw32 rest-client
  gem install --version 1.1.0 --platform x86-mingw32 sinatra
  gem install --version 1.1 --platform x86-mingw32 tilt
  gem install --version 1.4.6 --platform x86-mingw32 win32-api
  gem install --version 0.3.2 --platform x86-mingw32 win32-open3
  gem install --version 0.7.1 --platform x86-mingw32-60 win32-service
  gem install --version 0.4.0 --platform x86-mingw32 windows-api
  gem install --version 1.1.2 --platform x86-mingw32 windows-pr

Command to download them all:

wget http://rubygems.org/downloads/columnize-0.3.2.gem \
     http://rubygems.org/downloads/haml-3.0.24.gem \
     http://rubygems.org/downloads/highline-1.6.1.gem \
     http://rubygems.org/downloads/json-1.4.6-x86-mingw32.gem \
     http://rubygems.org/downloads/linecache-0.43-mswin32.gem \
     http://rubygems.org/downloads/mime-types-1.16.gem \
     http://rubygems.org/downloads/mocha-0.9.11.gem \
     http://rubygems.org/downloads/net-ping-1.3.7.gem \
     http://rubygems.org/downloads/rack-1.2.0.gem \
     http://rubygems.org/downloads/rake-0.8.7.gem \
     http://rubygems.org/downloads/rest-client-1.6.1.gem \
     http://rubygems.org/downloads/sinatra-1.1.0.gem \
     http://rubygems.org/downloads/tilt-1.1.gem \
     http://rubygems.org/downloads/win32-api-1.4.6-x86-mingw32.gem \
     http://rubygems.org/downloads/win32-open3-0.3.2-x86-mingw32.gem \
     http://rubygems.org/downloads/win32-service-0.7.1-x86-mswin32-60.gem \
     http://rubygems.org/downloads/windows-api-0.4.0.gem \
     http://rubygems.org/downloads/windows-pr-1.1.2.gem

8) CD to the root of the smart-proxy install directory

9) Edit config/settings.yml so that it looks a bit like this

Sample config/settings.yml file

 ---
 # HTTPS settings
 :ssl_certificate: c:\documents\smart-proxy\config\signed.pem
 :ssl_private_key: c:\documents\smart-proxy\config\private.pem
 :ssl_ca_file:     c:\documents\smart-proxy\config\ca.pem

 :trusted_hosts: [ foreman.someware.com]

 :daemon: false


 # Enable DHCP management
 :dhcp: true
 # The vendor can be either isc or native_ms
 :dhcp_vendor: native_ms
 # The dhcp_server is only used by the native_ms implementation
 :dhcp_server: 172.29.90.240

 # Where our proxy log files are stored
 # filename or STDOUT
 # Unix setting
 #:log_file: log/proxy.log
 # Windows setting
 :log_file: c:\tmp\proxy.log
 # valid options are
 # Logger::WARN, Logger::DEBUG, Logger::Error, Logger::Fatal, Logger:INFO, LOGGER::UNKNOWN
 #:log_level: Logger::DEBUG

10) Create the SSL key

10.1) Login to your puppetmaster

10.2) puppetca –generate Smart-proxy FQDN. (Do not use an alias here.)

10.3) Copy the private key, the public certificate and the ca.pem from /var/lib/puppet/ssl over to the locations that you specified in the setting file.

11) Test the installation by running ruby bin\smart-proxy.rb

12) Install the program as a service

12.1) ruby extra\register-service.rb

12.2) This may install the service but not run it. If so then try to start the service from the Ordinary Microsoft services snapin utility.

13) You may test connectivity by running the extra\query.rb utility from your foreman host. (Note that this file comes from the extra directory in the smart-proxy release.)

4.3.5 BIND

Bind configuration manipulation is based on nsupdate, which means that in theory could also be used to manipulate other dns servers which support nsupdate (such as Microsoft DNS server).

Configuration

In order to communicate securely with your dns server, you would need a key which will be used by nsupdate and your named daemon using ddns-confgen or dnssec-keygen

example using ddns-confgen

execute ‘ddns-confgen -k foreman -a hmac-md5’ - this should output something like the following:

# To activate this key, place the following in named.conf, and
# in a separate keyfile on the system or systems from which nsupdate
# will be run:
key "foreman" {
        algorithm hmac-md5;
        secret "GGd1oNCxaKsh8HA84sP1Ug==";
};

# Then, in the "zone" statement for each zone you wish to dynamically
# update, place an "update-policy" statement granting update permission
# to this key.  For example, the following statement grants this key
# permission to update any name within the zone:
update-policy {
        grant foreman zonesub ANY;
};

# After the keyfile has been placed, the following command will
# execute nsupdate using this key:
nsupdate -k /path/to/keyfile

You should create a new file (such as /etc/rndc.key or other) and store the key “foreman {…} in it. in the proxy Settings file you should point to this file location - make sure that the proxy have read permissions to this file.

In your named file, you could add the update-policy statement or something like this named example file if you need more fine grained permissions.

4.3.6 GSS-TSIG DNS

Both BIND as configured in FreeIPA and Microsoft AD DNS servers can accept DNS updates using GSS-TSIG authentication. This uses Kerberos principals to authenticate to the DNS server. Under Microsoft AD, this is known as “Secure Dynamic Update”.

Pre-requisites

• Kerberos principal in the realm/domain that Smart Proxy can use
• Kerberos keytab for the above principal

Microsoft AD configuration

A user has to be created in Active Directory that will be used by the Smart Proxy, e.g. foremanproxy. This will automatically create a service principal, e.g. foremanproxy@EXAMPLE.COM.

Test the Kerberos login with that user on the Smart Proxy using kinit:

kinit foremanproxy@EXAMPLE.COM

This requires that the /etc/krb5.conf file is setup correctly. By default many systems use DNS to locate the Kerberos DC. A KDC can also be statically set in this file. There are dozens of documents on how to do this on the net.

If login works, the keytab file can be created using ktutil. First clear the Kerberos ticket cache:

kdestroy

Now create the keytab file with ktutil:

ktutil: addent -password -p foreman@EXAMPLE.COM -k 1 -e RC4-HMAC
ktutil: wkt dns.keytab
ktutil: q

Once the keytab file has been created, test it using kinit:

kinit foreman@EXAMPLE.COM -k -t dns.keytab

If this works, clear the Kerberos ticket cache once again using kdestroy.

Store the keytab at /etc/foreman-proxy/dns.keytab, ensure permissions are 0600 and the owner is foreman-proxy.

The DNS zone Dynamic Updates option on the DNS zones can now be set to Secure Only. Now follow the steps below under Proxy Configuration.

FreeIPA configuration

A service principal is required for the Smart Proxy, e.g. foremanproxy/proxy.example.com@EXAMPLE.COM.

First of all, create a new principal (FreeIPA service) for Foreman, e.g. ipa service-add foremanproxy/proxy.example.com@EXAMPLE.COM.

Then fetch the keytab, e.g. ipa-getkeytab -p foremanproxy/proxy.example.com@EXAMPLE.COM -s ipa-server.example.com -k /etc/foreman-proxy/dns.keytab.

Store the keytab at /etc/foreman-proxy/dns.keytab, ensure permissions are 0600 and the owner is foreman-proxy.

The ACL on updates to the DNS zone then needs to permit the service principal. In the FreeIPA web UI, under the DNS zone, go to the Settings tab and add to the BIND update policy a new grant:

grant foremanproxy\047ipa.example.com@EXAMPLE.COM wildcard * ANY;

Note the \047 is written verbatim, and don’t forget the semicolon.

Proxy configuration

Next, update the proxy configuration file (/etc/foreman-proxy/settings.yml) with the following settings:

:dns_provider: nsupdate_gss
:dns_tsig_keytab: /etc/foreman-proxy/dns.keytab
:dns_tsig_principal: foremanproxy/ipa.example.com@EXAMPLE.COM

4.3.7 SSL

The smart proxy can work in SSL mode, where both sides verify and trust each other. Requests from Foreman will only be accepted if the SSL certificate can be verified. Since proxies abstract a high level of control over your infrastructure, the configuration and security of keys and certificates is important.

Using Puppet CA certificates

Since Foreman integrates with Puppet heavily, it is recommended to use the Puppet Certificate Authority (CA) to secure proxy access. See the Security Communciations with SSL section for more advanced installations (multiple or internal CAs).

If the smart proxy host is not managed by Puppet, you will need to generate a certificate - skip forward to the generate section.

When using Puppet’s certificates, the following lines will be required in puppet.conf to relax permissions to the puppet group. The foreman and/or foreman-proxy users should then be added to the puppet group.

[main]
privatekeydir = $ssldir/private_keys { group = service }
hostprivkey = $privatekeydir/$certname.pem { mode = 640 }

Configuring the proxy

Configure the locations to the SSL files in /etc/foreman-proxy/settings.yml, plus the list of trusted Foreman hosts:

:ssl_certificate: /var/lib/puppet/ssl/certs/FQDN.pem
:ssl_ca_file: /var/lib/puppet/ssl/certs/ca.pem
:ssl_private_key: /var/lib/puppet/ssl/private_keys/FQDN.pem

:trusted_hosts:
- foreman.corp.com
#- foreman.dev.domain

Generating a certificate

To generate a certificate for a proxy host that isn’t managed by Puppet, do the following:

1. Generate a new certificate on your puppetmaster: puppet cert --generate <proxy-FQDN>
2. Copy the certificates and key from the puppetmaster to the smart proxy in /etc/foreman-proxy:<ol>

</ol>

Follow the configuration section above, however use the /etc/foreman-proxy paths instead of the Puppet defaults.

Configuring Foreman

For Foreman to connect to an SSL-enabled smart proxy, it needs configuring with SSL certificates in the same way. If the Foreman system is managed by Puppet, it will already have these, else certificates can be generated following the above instructions.

The locations of the certificates are managed in the Settings page, under Provisioning with the ssl_ca_file, ssl_certificate and ssl_priv_key settings. By default these will point to the Puppet locations - for manually generated certificates, or non-standard locations, they may have to be changed.

Lastly, when adding the smart proxy in Foreman, ensure the URL begins with https:// rather than http://.

4.3.8 TFTP

An essential first step in netbooting a system is preparing the TFTP server with the PXE configuration file and boot images. This document assumes that you have already configured your DHCP infrastructure, either via manual configuration or through the DHCP smart proxy.

Configuration Values

Once enabled, there is currently only one valid setting to change, the default TFTP root. This is set with the :tftproot: parameter, which defaults to /var/lib/tftpboot.

Foreman tries to guess the right server name that should put into the dhcp record, if this is not what you want, you can override it - see tftp_servername under Settings.yml.

Setting Up the Proxy Server Host

Regardless of the filesystem setup is performed, you must also make sure you have the wget utility installed and in the default path. wget is used to download OS specific installation when a given host is enabled for the build process.

Automatic Setup

Foreman includes a TFTP server module that will perform all of the basic setup. It defaults to TFTP root of /var/lib/tftpboot, which may change if necessary. You will still need to provide the basic TFTP load images in your TFTP root directory. For vanilla PXE booting, this includes pxelinux.0, menu.c32, and chain.c32.

Manual Setup

The setup is very simple, and may be performed manually if desired.

1. The TFTP root directory must exist (we will use /var/lib/tftpboot in this example).
2. Populate /var/lib/tftpboot with PXE booting prerequisites. At a minimum, this should include:
   • pxelinux.0
   • menu.c32
   • chain.c32
3. Create the directory /var/lib/tftpboot/boot and make it writeable by the foreman proxy user (foreman-proxy, for instance, when installing through a rpm package).
4. Create the directory /var/lib/tftpboot/pxelinux.cfg and make it writeable by the foreman proxy user (foreman-proxy).

Setting Up Foreman

Workflow

This is a rough outline of the steps triggered on the TFTP smart proxy host when you click on the “Build” link for a host.

1. Call mkdir -p /var/lib/tftpboot/pxelinux.cfg if it does not already exist.
2. Create a host-specific TFTP configuration file in /var/lib/tftpboot/pxelinux.cfg/01-XX-XX-XX-XX-XX-XX, named based off of the MAC address, using the associated PXE template.
3. Call mkdir -p /var/lib/tftpboot/boot if it does not already exist.
4. Download the OS specific kernel and initrd files using wget.
   1. The download URLs are derived from the installation media path, and OS specific log (see app/models/redhat.rb and debian.rb in foreman for examples of the gory details).
   2. The debian.rb file tries to guess if you want Ubuntu or Debian, based on the Name you give to your OS in the UI. If the name does not contain ‘ubuntu’ or ‘debian’, it may default to debian, hence fail to fetch the kernel/initrd.
5. The exact wget command is wget --no-check-certificate -nv -c <src> -O "<destination>"
6. At this point, the TFTP state is ready for the installation process.
7. Once the host has completed installation, the OS specific installation script should inform foreman by retrieving the built URL.
8. The host-specific TFTP configuration file is deleted.
9. The kernel and initrd are not deleted, but left in place for future installs of the same OS and architecture combination. Please note that in the unlikely case that these files are modified, the simplistic freshness check of wget will likely get confused, corrupting the downloaded versions of the files. If this happens, you should simply delete the files and let them be re-downloaded from scratch.

Limitations

At the moment, the proxy is not able to fetch boot files using NFS. As a workaround, expose your installation medium (or use a public mirror) over http/ftp to configure one machine with the require boot files. this would be resolved as part of #992.

4.4 Provisioning

This chapter details the configuration of the required UI components necessary to provision an OS onto a host.

4.4.1 Operating Systems

The Operating Systems page (More -> Provisioning -> Operating Systems) details the OSs known to Foreman, and is the central point that the other required components tie into.

Creating an Operating System

Simply click New Operatingsystem on the main page. You will be taken to a screen where you can create the bare essentials of a new OS. Not everything required for a successful provision is on this page (yet) - the remaining components will appear for selection as we create them.

You will need to fill in the first few parts of the form (Name, Major, Minor, Family, and possibly some family-dependent information). In the case of OSs like Fedora, it is fine to leave Minor blank.

If the default Partition Tables & Installation media are suitable, then you can assign them now. If not, return here after each step in this chapter to assign the newly created objects to your Operating System

Auto-created Operating Systems

Foreman does not come with any Operating Systems by default. However, Foreman will detect the Operating System of any host which reports in via Puppet - if the OS of that Host is supported, it will be created (with very basic settings) and assigned to the Host. Thus you may find some OSs already created for you.

4.4.2 Installation Media

The Installation Media represents the web URL from where the installation packages can be retrieved (i.e. the OS mirror). Some OS Media is pre-created for you when Foreman is first installed. However, it is best to edit the media you are going to use and ensure the Family is set.

New Installation Media

If your OS of choice does not have a mirror pre-created for you, click the New Medium button to create one. There are a few variables which can be used to pad out the URL. For example:

http://mirror.averse.net/centos/$major.$minor/os/$arch

Be sure to set the Family for the Media

Assign to Operating System

If you have not already done so, return to the Operating System page for your OS and assign the Media to it now.

4.4.3 Provisioning Templates

The Provision Templates is the core of Foreman’s flexibility to deploy the right OS with the right options. There are several types of template, along with a flexible matching system to deliver different templates to different Hosts.

Foreman comes with pre-created templates for the more common OSs, but you will need to review these.

Template Kinds

There are 5 template kinds:

• PXELinux - Deployed to the TFTP server to ensure the Host boots the correct installer with the correct kernel options
• Provision - The main unattended installation file; e.g. Kickstart or Preseed
• Finish - A post-install script used to take custom actions after the main provisioning is complete
• Script - An arbitrary script, not used by default, useful for certain custom tasks
• gPXE - USed in {g,i}PXE environments in place of PXELinux

In practice, most environments only make use of the first 3. The Create Host action deploys the PXELinux template to the TFTP server. The PXELinux template directs the host to retrieve the Provision template. The Provision template will direct the installer to retrieve and run the Finish template at the end of the install, and the Finish template will notify Foreman the build is complete just before reboot.

Editing Templates

Clicking a template will take you to the edit page. All templates are ERB-enabled, and you can access many variables about the to-be-installed-host within the template. See Template Writing for ideas.

As noted in 4.1.4 Auditing, changes to the templates are logged as diffs - you can browse the history of changes to the templates from the History tab within the Edit Template page. You can also revert changes here.

Template Association

When editing a Template, you must assign a list of Operating Systems which this Template can be used with. Optionally, you can restrict a template to a list of Hostgroups and/or Environments

When a Host requests a template (e.g. during provisioning), Foreman will select the best match from the available templates of that type, in the following order:

• Host-group and Environment
• Host-group only
• Environment only
• Operating system default

The final entry, Operating System default, can be set by editing the Operating System page.

Associating an Operating System default template

You will need to associate at least one PXELinux, Provision, and Finish template to your Operating System, and this must be done in two steps. First edit each of the templates, switch to the Association tab, and ensure the appropriate OSs are checked. Then edit the Operating System, switch to the Templates tab, and choose a default template for each template kind.

4.4.4 Partition Tables

Partition templates are a subset of normal Provisioning Templates. They are handled separately because it is frequently the case that an admin wants to deploy the same host template (packages, services, etc) with just a different harddisk layout to account for different servers’ capabilities.

Foreman comes with pre-created templates for common Operating Systems, but it is good to edit the template, check it’s content and it’s Family setting. If the Family is wrong, be sure to go back to Operating Systems and associate it with your Operating System.

Dynamic Partition tables

When creating a new Host, you will be given the option to create a Dynamic Partition table. This is essentially a ‘one-off’ partition table that is stored with the host and used only for that host. It replaces the choice of Partition Table from the normal list of those associated with the selected OS.

4.4.5 Architectures

Architectures are simple objects, usually created by Foreman automatically when Hosts check in via Puppet. However, none are created by default, so you may need to create them if you’re not using Foreman for reporting.

Creating a new Architecture

Simply click New Architecture to create a new one. This should match the Facter fact :architecture e.g. “x86_64”. If you’ve already created some Operating Systems, you can associate the Architecture with the OS now; if not, the list of Architectures will be present when you create an OS.

4.5 Command Line Interface

The framework used for implementation of command line client for foreman provides many features common for modern CLI applications. The task of managing Foreman from command line is quite complex so the commands have to be organized in more levels of subcommands. There is help available for each level to make it easy to use. Some other features for greater comfort are option validation, logging and customizable output formatting.

4.5.1 Usage Examples

Basic help and list of supported commands:

$ hammer -h
Usage:
    hammer [OPTIONS] SUBCOMMAND [ARG] ...

Parameters:
    SUBCOMMAND                    subcommand
    [ARG] ...                     subcommand arguments

Subcommands:
    shell                         Interactive Shell
    architecture                  Manipulate Foreman's architectures.
    global_parameter              Manipulate Foreman's global parameters.
    compute_resource              Manipulate Foreman's compute resources.
    domain                        Manipulate Foreman's domains.
    environment                   Manipulate Foreman's environments.
    fact                          Search Foreman's facts.
    report                        Browse and read reports.
    puppet_class                  Browse and read reports.
    host                          Manipulate Foreman's hosts.
    hostgroup                     Manipulate Foreman's hostgroups.
    location                      Manipulate Foreman's locations.
    medium                        Manipulate Foreman's installation media.
    model                         Manipulate Foreman's hardware models.
    os                            Manipulate Foreman's operating system.
    organization                  Manipulate Foreman's organizations.
    partition_table               Manipulate Foreman's partition tables.
    proxy                         Manipulate Foreman's smart proxies.
    subnet                        Manipulate Foreman's subnets.
    template                      Manipulate Foreman's config templates.
    user                          Manipulate Foreman's users.

Options:
    -v, --verbose                 be verbose
    -c, --config CFG_FILE         path to custom config file
    -u, --username USERNAME       username to access the remote system
    -p, --password PASSWORD       password to access the remote system
    --version                     show version
    --show-ids                    Show ids of associated resources
    --csv                         Output as CSV (same as --adapter=csv)
    --output ADAPTER              Set output format. One of [base, table, silent, csv]
    --csv-separator SEPARATOR     Character to separate the values
    -P, --ask-pass                Ask for password
    --autocomplete LINE           Get list of possible endings
    -h, --help                    print help

First level command help:

$ hammer architecture -h
Usage:
    hammer architecture [OPTIONS] SUBCOMMAND [ARG] ...

Parameters:
    SUBCOMMAND                    subcommand
    [ARG] ...                     subcommand arguments

Subcommands:
    list                          List all architectures.
    info                          Show an architecture.
    create                        Create an architecture.
    delete                        Delete an architecture.
    update                        Update an architecture.
    add_operatingsystem           Associate a resource
    remove_operatingsystem        Disassociate a resource

Options:
    -h, --help                    print help

Second level command help:

$ hammer architecture create -h
Usage:
    hammer architecture create [OPTIONS]

Options:
    --name NAME                    
    --operatingsystem-ids OPERATINGSYSTEM_IDS 
                                  Operatingsystem ID’s
    -h, --help                    print help

4.5.2 Success Story

There was a set of common commands identified as necessary for basic Foreman management, we called it “success story” and track the progress of its implementation. The commands could also serve as a basic hammer cookbook.

The goal is to provision bare metal host on a clean install of Foreman. The following steps are necessary:

• create smart proxy

hammer proxy create --name myproxy --url https://proxy.my.net:8443

• create architecture

hammer architecture create --name x86_64

• create new subnet

hammer subnet create --name "My Net" --network "192.168.122.0" --mask "255.255.255.0" --gateway "192.168.122.1" --dns-primary "192.168.122.1"

• import existing subnet from a proxy

  missing, see #3355

• create new domain

hammer domain create --name "my.net" --fullname "My network"

• associate domain with proxy

hammer domain update --id 1 --dns-id 1

• associate subnet with domain

hammer subnet update --id 1 --domain-ids 1

• associate subnet with proxy (DHCP, TFTP, DNS)

hammer subnet update --id 1 --dhcp-id 1 --tftp-id 1 --dns-id 1

• create new partition table

hammer partition_table create --name "Redhat test" --file /tmp/rh_test.txt

• create new OS

hammer os create --name RHEL --major 6 --minor 4

• create new template

hammer template create --name "kickstart mynet" --type provision --file /tmp/ks.txt

• edit existing pre-defined template

hammer template dump --id 4 > /tmp/ks.txt
    vim /tmp/ks.txt
hammer template update --id 4 --file /tmp/ks.txt

• associate applicable OS with pre-defined template

hammer template update --id 1 --operatingsystem-ids 1

Listing associated OS’s is still missing - see #3360

• associate OS with architecture

hammer os update --id 1 --architecture-ids 1

• associate OS with part table

hammer os update --id 1 --ptable-ids 1

• associate OS with install media

hammer os update --id 1 --medium-ids 1

• associate OS with install provision and pxelinux templates

  Missing, needs investigation, may be related to #3360

• create libvirt compute resource

hammer compute_resource create --name libvirt --url "qemu:///system" --provider Libvirt

• import puppet classes

  missing - see #3035

• and finally create a bare metal host entry

  works with some options, needs improvements - see #3063

5. Advanced Foreman

5.1 API

API v1 is the default version for Foreman 1.3.x.

This section documents the JSON API conventions for the Foreman API v2 and Katello API v2, both of which are not released. To test out new features in API v2, see Section 5.1.6, to specify version.

5.1.1 CRUD Request Examples

The following examples show the basic CRUD operations (Create, Read, Update, Delete) using the JSON API.

Show a Collection of Objects

Get of a collection of domains: GET /api/domains

Send a HTTP GET request. No JSON data hash is required.

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" https://foreman.example.com/api/domains

This returns a collection JSON response. The format for a collection response is described in Section 5.1.2.

Show a Single Object

Get a single domain: GET /api/domains/:id or GET /api/domains/:name

Send a HTTP GET request with the object’s unique identifier, either :id or :name. No JSON data hash is required.

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains/42
# or
$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains/foo

This returns a single object in JSON format. The format for a single object response is described in Section 5.1.3.

Create an Object

Create a new domain: POST /api/domains

Send a HTTP POST request with a JSON data hash containing the required fields to create the object. In this example, a domain is being created.

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" -X POST \
    -d { "name":"foo.bar.com","fullname":"foo.bar.com description" } https://foreman.example.com/api/domains

This returns the newly created object in JSON format. The format for a single object response is described in Section 5.1.3.

Update an Object

Update a domain: PUT /api/domains/:id or PUT /api/domains/:name

Send a HTTP PUT request with the object’s unique identifier, either :id or :name, plus a JSON data hash containing only the data to be updated. In this example, only the domain name is being updated. $ curl -k -u admin:changeme -H “Accept: version=2,application/json” -X PUT
-d { “name”: “a new name” } https://foreman.example.com/api/domains/12 # or $ curl -k -u admin:changeme -H “Accept: version=2,application/json” -X PUT
-d { “name”: “a new name” } https://foreman.example.com/api/domains/foo

This returns the newly updated object in JSON format. The format for a single object response is described in Section 5.1.3.

Delete an Object

Delete a domain: DELETE /api/domains/:id or DELETE /api/domains/:name

Send a HTTP DELETE request with the object’s unique identifier, either :id or :name. No JSON data hash is required.

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" -X DELETE \
    https://foreman.example.com/api/domains/17
# or
$ curl -k -u admin:changeme -H "Accept: version=2,application/json" -X DELETE \
    https://foreman.example.com/api/domains/foo

This returns the deleted object in JSON format. The format for a single object response is described in Section 5.1.3.

5.1.2 JSON Response Format for Collections

Collections are a list of objects (i.e. hosts, domains, etc). The format for a collection JSON response consists of a results root node and metadata fields total, subtotal, page, per_page. Note: for Katello objects, the metadata includes limit, offset instead of page, per_page.

Below is an example of the format for a collection JSON response for a list of domains: GET /api/domains

{
    "total": 3,
    "subtotal": 3,
    "page": 1,
    "per_page": 20,
    "search": null,
    "sort": {
        "by": null,
        "order": null
    },
    "results": [
        {
            "id": 23,
            "name": "qa.lab.example.com",
            "fullname": "QA",
            "dns_id": 10,
            "created_at": "2013-08-13T09:02:31Z",
            "updated_at": "2013-08-13T09:02:31Z"
        },
        {
            "id": 25,
            "name": "sat.lab.example.com",
            "fullname": "SATLAB",
            "dns_id": 8,
            "created_at": "2013-08-13T08:32:48Z",
            "updated_at": "2013-08-14T07:04:03Z"
        },
        {
            "id": 32,
            "name": "hr.lab.example.com",
            "fullname": "HR",
            "dns_id": 8,
            "created_at": "2013-08-16T08:32:48Z",
            "updated_at": "2013-08-16T07:04:03Z"
        }
    ]
}

The response metadata fields are described below:

• total - total number of objects without any search parameters
• subtotal - number of objects returned with given search parameters (if there is no search, then subtotal equals total)
• page (Foreman only) - page number
• per_page (Foreman only) - maximum number of objects returned per page
• limit - (Katello only) specified number of objects to return in collection response
• offset - (Katello only) number of objects skipped before beginning to return collection.
• search - search string (based on scoped_scoped syntax)
• sort
  • by - the field that the collection is sorted by
  • order - sort order, either ASC for ascending or DESC for descending
• results - collection of objects. See Section 5.1.4 for how to change the root name from ‘results’ to something else.

5.1.3 JSON Response Format for Single Objects

Single object JSON responses are used to show a single object. The object’s unique identifier :id or :name is required in the GET request. Note that :name may not always be used as a unique identifier, but :id can always be used. The format for a single object JSON response consists of only the object’s attributes. There is no root node and no metadata by default. See Section 5.1.4 for how to add a root name.

Below is an example of the format for a single object JSON response: GET /api/domains/23 or GET /api/domains/qa.lab.example.com

{
    "id": 23,
    "name": "qa.lab.example.com",
    "fullname": "QA",
    "dns_id": 10,
    "created_at": "2013-08-13T09:02:31Z",
    "updated_at": "2013-08-13T09:02:31Z"
}

5.1.4 Customize JSON Responses

Customize Root Node for Collections

The default root node name for collections is results but can be changed.

To change the root node name per API request, pass root_name= as a URL parameter. See example below:

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains?root_name=data

Customize Root Node for Single Object

There is no root node as the default for single object JSON responses, but it can be added.

To change the object’s root node name per API request, pass object_name= as a URL parameter. See example below:

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains/23?object_name=record

Customize Partial Response Attributes

Currently, there is no option to change or customize which attributes are returned for collections or single objects. In the future, customized partial responses such as fields=field1,field2,field3 or fields=all may be implemented (#3019). Similarly, there is currently no option to specify child nodes in an API call or to remove child nodes if they are returned by default.

Custom Number of Objects in Collection Per Response

Foreman paginates all collections in the JSON response. The number of objects returned per request is defined in More > Settings > General > entries_per_page. The default is 20. Thus, if there are 27 objects in a collection, only 20 will be returned for the default page=1.

To view the next page, pass page= as a URL parameter. See example below:

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains?page=2

The example above will show the remaining 7 objects in our example of 27 objects in the collection.

To increase or decrease the number of objects per response, pass per_page= as a URL parameter. See example below:

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains?per_page=1000

This will return all the objects in one request since 27 is less than the per_page parameter set to 1000.

Custom Search of Collections Per Response

Foreman uses the gem scoped_search for searching and filtering which allows all query search parameters to be specified in one string. To filter results of a collection, pass search= as a URL parameter. See example below:

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains?search=name%3Dexample.com

The number of objects returned will be shown in the subtotal metadata field, and the query string will be shown in the search metadata field.

Custom Sort of Collections Per Response

Custom sort order per collection can be specified by passing order= as a URL parameter. See example below:

$ curl -k -u admin:changeme -H "Accept: version=2,application/json" \
    https://foreman.example.com/api/domains?order=name+DESC

The default sort order is ascending (ASC) if only a field name is passed. The sort parameters will be shown in sort by and order metadata fields.

5.1.5 Nested API routes

The goal is to implement nested routes for all objects as an alternative to filtering collections.

For example, rather then filtering subnets by a specified domain using a search string

$ GET /api/subnets?search=name%3Dqa.lab.example.com

the alternative nested route below returns the same result as the above.

$ GET /api/domains/qa.lab.example.com/subnets

All actions will be accessible in the nested route as in the main route.

5.1.6 API Versioning

The default API version is v1 for Foreman 1.3.

There are two methods of selecting API v2:

1. In the header, pass Accept: application/json,version=2

2. In the URL, pass /v2/ such as GET /api/v2/hosts

Similarly, when API version v2 becomes the default, v1 can still be used by passing Accept: application/json,version=1 in the header or api/v1/ in the URL.

5.2 Compute Resources

Foreman supports creating and managing hosts on a number of virtualization and cloud services - referred to as “compute resources” - as well as bare metal hosts.

The capabilities vary between implementations, depending on how the compute resource provider deploys new hosts and what features are available to manage currently running hosts. Some providers are able to support unattended installation using PXE, while others are image-based. Some providers have graphical consoles that Foreman interfaces to, and most have power management features. A summary of all providers and their support features is given below, and more detailed sections follow with specific notes.

Support for these features is aimed at being as transparent as possible, allowing the same configuration to be applied to hosts irrespective of the provider in use (compute resource or not). The selection of compute resource is made when creating a new host and the host in Foreman’s database remains associated to the VM that’s created, allowing it to be managed throughout the lifetime of the host.

5.2.1 Using Compute Resources

The following steps describe how to configure a compute resource and provision new hosts on it.

1. Ensure the necessary package for the provider (from the above table) is installed, e.g. yum -y install foreman-ovirt. Restart the Foreman application to complete installation.

2. Add a compute resource under More > Provisioning > Compute Resources > New Compute Resource. Select the provider type from the menu and appropriate configuration options will be displayed. Check the notes sections below for any provider-specific setup instructions.

3. Click the Test Connection button after entering the configuration. If no error is displayed, the test was successful.

4. After saving the compute resource, existing virtual machines can be browsed by clicking on the compute resource and the Virtual Machines tab.

5. For providers that use images, click on the compute resource, then the Images tab, where known images are listed. To register images that Foreman can use, click New Image and enter the details.

6. To provision a new host on this compute resource, from Hosts, click New Host and select the compute resource from the Deploy to menu.

Also note the following features:

1. When viewing a host, power management controls and the console access button are in the top right hand corner of the page.

2. If a host provisioned on a compute resource is deleted, the VM and associated storage on the compute resource will also be deleted.

3. Users in Foreman can have access restricted to hosts present on certain compute resources. For more information, see Filtering in 4.1.2 Roles and Permissions.

5.2.2 EC2 Notes

• Ensure AMIs are added under the Images tab on the compute resource with the correct username for it to SSH into the image.
• Add a provisioning template of type finish which will be executed over SSH on the new image.
• Ensure the finish template is associated to the OS (on the Associations tab) and is set as the default for the operating system too.
• Enabling use_uuid_for_certificates in More > Settings is recommended for consistent Puppet certificate IDs instead of hostnames.
• VPC subnets and security groups can be selected on the Network tab when creating a host.
• The Managed IP dropdown menu allows selection between using the public and private IP address for communication from Foreman to the instance.

A full example for configuring EC2 provisioning is given on the Foreman blog: EC2 provisioning using Foreman.

5.2.3 Google Compute Engine Notes

• Requires client e-mail address and p12 certificate file to access
• Ensure images are associated under the Images tab on the compute resource.
• Add a provisioning template of type finish which will be executed over SSH on the new image.
• Ensure the finish template is associated to the OS (on the Associations tab) and is set as the default for the operating system too.
• Enabling use_uuid_for_certificates in More > Settings is recommended for consistent Puppet certificate IDs instead of hostnames.
• The External IP checkbox means the public IP address (rather than private IP) will be used for communication with the instance from Foreman.

5.2.4 Libvirt Notes

• Currently only supports KVM hypervisors.
• VM consoles will be configured by default to listen on 0.0.0.0, change this via libvirt_default_console_address in More > Settings > Provisioning.
• libvirt’s DNS and DHCP server (dnsmasq) can be disabled and replaced by BIND and ISC DHCPD (managed by Foreman) by creating a new virtual network and disabling DHCP support.

To connect to the hypervisor using SSH:

1. Configure SSH keys (ssh-keygen) for the ‘foreman’ user on the Foreman host to connect fully automatically to the remote hypervisor host.
2. Change to the ‘foreman’ user, test the connection and ensure the remote host has been trusted.
3. If connecting to the hypervisor as a non-root user, set up PolicyKit to permit access to libvirt. Note that different versions of PolicyKit have different configuration formats. 1, 2.
4. Add the compute resource with a URL following one of these examples:
   • qemu+ssh://root@hypervisor.example.com/system to use the remote ‘root’ account
   • qemu+ssh://hypervisor.example.com/system to use the remote ‘foreman’ account

To connect to the hypervisor over TCP without authentication or encryption (not recommended):

1. Set the following options in libvirtd.conf:
   • listen_tls = 0
   • listen_tcp = 1
   • auth_tcp = "none"
2. Enable libvirtd listening, e.g. set LIBVIRTD_ARGS="--listen" in /etc/sysconfig/libvirtd
3. Add the compute resource with a URL following this example:
   • qemu+tcp://hypervisor.example.com:16509/system

If you have difficulty connecting, test access using the virsh command under the ‘foreman’ account on the Foreman host first, e.g. virsh -c qemu+ssh://hypervisor.example.com/system list.

5.2.5 OpenStack Notes

• Supports OpenStack Nova for creating new compute instances.
• A floating IP address group is required as Foreman will use the public IP address of the instance to complete provisioning over SSH (#2270).

A full example for configuring image-based provisioning is given on the Foreman blog, also applicable to OpenStack: EC2 provisioning using Foreman.

5.2.6 oVirt / RHEV Notes

• SPICE consoles are displayed using an HTML5 client, so no native XPI extension is necessary.

5.2.7 Rackspace Notes

• The compute resource URL refers to the identity API URL, e.g. https://identity.api.rackspacecloud.com/v2.0

A full example for configuring image-based provisioning is given on the Foreman blog, also applicable to Rackspace: EC2 provisioning using Foreman.

5.2.8 VMware Notes

• Only VMware clusters using vSphere are supported, not standalone ESX or ESXi servers (#1945).

Consoles are provided using VNC connections from Foreman to the ESX server, which requires a firewall change to open the respective ports (TCP 5910 to 5930)

ssh root@esx-srv
vi /etc/vmware/firewall/vnc.xml

Add the following file content:

<ConfigRoot>
<service id='0032'>
 <id>VNC</id>
 <rule id = '0000'>
  <direction>inbound</direction>
  <protocol>tcp</protocol>
  <porttype>dst</porttype>
  <port>
   <begin>5910</begin>
   <end>5930</end>
  </port>
 </rule>
 <enabled>true</enabled>
</service>
</ConfigRoot>

Apply and check the firewall rule:

esxcli network firewall refresh
esxcli network firewall ruleset list | grep VNC

Lastly, make the rule persistent:

cp /etc/vmware/firewall/vnc.xml /vmfs/volumes/datastore1/vnc.xml
vi /etc/rc.local
# At end of file:
cp /vmfs/volumes/datastore1/vnc.xml /etc/vmware/firewall/
esxcli network firewall refresh

5.3 Install Locations

Missing content. Consider contributing, you kind soul!

5.4 Securing Communications with SSL

The Foreman web application needs to communicate securely with associated smart proxies and puppet masters, plus users and applications connecting to the web interface. This section details recommended SSL configurations.

5.4.1 Securing Puppet Master Requests

In a typical ENC-based setup with reporting, puppet masters require access to Foreman for three tasks:

1. Retrieval of external nodes information (classes, parameters)
2. Uploading of host facts
3. Uploading of host reports

All traffic here is initiated by the puppet master itself. Other traffic from Foreman to the puppet master for certificate signing etc. is handled via smart proxies (SSL configuration covered in the next section).

Configuration options

The Foreman interface authorizes access to puppet master interfaces based on its list of registered smart proxies with the Puppet feature, and identifies hosts using client SSL certificates.

Five main settings control the authentication, the first are in Foreman under Settings, Auth:

• require_ssl_puppetmasters (default: true), requires a client SSL certificate on the puppet master requests, and will verify the CN of the certificate against the smart proxies. If false, it uses the reverse DNS of the IP address making the request.
• restrict_registered_puppetmasters (default: true), only permits access to hosts that have a registered smart proxy with the Puppet feature.
• trusted_puppetmaster_hosts, a whitelist of hosts that overrides the check for a registered smart proxy

And two in config/settings.yaml:

• login (default: true), must be enabled to prevent anonymous access to Foreman.
• require_ssl (default: false), should be enabled to require SSL for all communications, which in turn will require client SSL certificates if require_ssl_puppetmasters is also enabled. If false, host-based access controls will be available for HTTP requests.

Enabling full SSL communications

Using Apache HTTP with mod_ssl and mod_passenger is recommended. For simple setups, the Puppet certificate authority (CA) can be used, with Foreman and other hosts using certificates generated by puppet cert.

1. Set Foreman’s require_ssl_puppetmasters, restrict_registered_puppetmasters and require_ssl to true.
2. The mod_ssl configuration must contain:

1. *SSLCACertificateFile* set to the Puppet CA
2. *SSLVerifyClient optional*
3. *SSLOptions +StdEnvVars*

1. ENC script (e.g. /etc/puppet/node.rb) should have these settings:

1. *:ssl_ca* set to the Puppet CA
2. *:ssl_cert* set to the puppet master's certificate
3. *:ssl_key* set to the puppet master's private key

1. Report processor (e.g. /usr/lib/ruby/site_ruby/1.8/puppet/reports/foreman.rb) should have these settings:

1. *$foreman_ssl_ca* set to the Puppet CA
2. *$foreman_ssl_cert* set to the puppet master's certificate
3. *$foreman_ssl_key* set to the puppet master's private key

Troubleshooting

Warning messages will be printed to Foreman’s log file (typically /var/log/foreman/production.log) when SSL-based authentication fails.

• No SSL cert with CN supplied indicates no client SSL certificate was supplied, or the CN wasn’t present on a certificate. Check the client script has the certificate and key configured and that mod_ssl has SSLVerifyClient set.
• SSL cert has not been verified indicates the client SSL certificate didn’t validate with the SSL terminator’s certificate authority. Check the client SSL certificate is signed by the CA set in mod_ssl’s SSLCACertificateFile and is still valid. More information might be in error logs.
• SSL is required indicates the client is using an HTTP URL instead of HTTPS.
• No smart proxy server found on $HOST indicates Foreman has no smart proxy registered for the source host, add it to the Smart Proxies page in Foreman. A common cause of this issue is the hostname in the URL doesn’t match the hostname seen here in the log file - change the registered proxy URL to match. If no smart proxy is available or can be installed, use trusted_puppetmaster_hosts and add this hostname to the whitelist.

Advanced SSL notes

A typical small setup will use a single Puppet CA and certificates it provides for the Foreman host and puppet master hosts. In larger setups with multiple CAs or an internal CA, this will require more careful configuration to ensure all hosts can trust each other.

• Ensure the Common Name (CN) is present in certificates used by Foreman (as clients will validate it) and puppet master clients (used to verify against smart proxies).
• Foreman’s SSL terminator must be able to validate puppet master client SSL certificates. In Apache with mod_ssl, the SSLCACertificateFile option must point to the CA used to validate clients and SSLVerifyClient set to optional.
• Environment variables from the SSL terminator are used to get the client certificate’s DN and verification status. mod_ssl’s SSLOptions +StdEnvVars setting enables this. Variable names are defined by ssl_client_dn_env and ssl_client_verify_env settings in Foreman.

Reduced security: HTTP host-based authentication

In non-SSL setups, host-based authentication can be performed, so any connection from a host running a puppet smart proxy is able to access the interfaces.

1. Set restrict_registered_puppetmasters to true.
2. Set require_ssl_puppetmasters and require_ssl to false.

No security: disable authentication

Entirely disabling authentication isn’t recommended, since it can lead to security exploits through YAML import interfaces and expose sensitive host information, however it may be useful for troubleshooting.

1. Set require_ssl_puppetmasters, restrict_registered_puppetmasters and require_ssl to false.

5.4.2 Securing Smart Proxy Requests

Foreman makes HTTP requests to smart proxies for a variety of orchestration tasks. In a production setup, these should use SSL certificates so the smart proxy can verify the identity of the Foreman host.

In a simple setup, a single Puppet Certificate Authority (CA) can be used for authentication between Foreman and proxies. In more advanced setups with multiple CAs or an internal CA, the services can be configured as follows.

Proxy configuration options

/etc/foreman-proxy/settings.yml contains the locations to the SSL certificates and keys:

---
# SSL Setup

# if enabled, all communication would be verified via SSL
# NOTE that both certificates need to be signed by the same CA in order for this to work
# see http://theforeman.org/projects/smart-proxy/wiki/SSL for more information
:ssl_certificate: /var/lib/puppet/ssl/certs/FQDN.pem
:ssl_ca_file: /var/lib/puppet/ssl/certs/ca.pem
:ssl_private_key: /var/lib/puppet/ssl/private_keys/FQDN.pem

In this example, the proxy is sharing Puppet’s certificates, but it could equally use its own.

In addition it contains a list of hosts that connections will be accepted from, which should be the host(s) running Foreman:

# the hosts which the proxy accepts connections from
# commenting the following lines would mean every verified SSL connection allowed
:trusted_hosts:
- foreman.corp.com
#- foreman.dev.domain

Configuring Foreman

For Foreman to connect to an SSL-enabled smart proxy, it needs configuring with SSL certificates in the same way.

The locations of the certificates are managed in the Settings page, under Provisioning - the ssl_ca_file, ssl_certificate and ssl_priv_key settings. By default these will point to the Puppet locations - for manually generated certificates, or non-standard locations, they may have to be changed.

Lastly, when adding the smart proxy in Foreman, ensure the URL begins with https:// rather than http://.

Sharing Puppet certificates

If using Puppet’s certificates, the following lines will be required in puppet.conf to relax permissions to the puppet group. The foreman and/or foreman-proxy users should then be added to the puppet group.

[main]
privatekeydir = $ssldir/private_keys { group = service }
hostprivkey = $privatekeydir/$certname.pem { mode = 640 }

Note that the “service” keyword will be interpreted by Puppet as the “puppet” service group.

5.5 Backup, Recovery and Migration

This chapter will provide you with information how to backup and recover your instance. All commands presented here are just examples and should be considered as a template command for your own backup script which differs from one environment to other.

It is possible to perform a migration by doing backup one one host and recovery on a different host, but in this case pay attention to different configuration between the two hosts.

This can be applied to the Foreman application itself, but pay attention when migrating smart-proxy and services because things like different IP addresses or hostnames will need manual intervention.

5.5.1 Backup

This chapter will provide you with information how to backup a Foreman instance.

Database

PostgreSQL

The pg_dump command can be used to backup the contents of a PostgreSQL database to a text file. The most reliable way of backing up PostgreSQL database is:

su postgres -c "pg_dump -Fc foreman > foreman.dump"

MySQL database

The mysqldump command can be used to backup the contents of your MySQL database to a text file.

mysqldump --opt foreman > foreman.sql

Please follow MySQL documentation about other options for doing backups.

SQLite database

To backup SQLite database perform this simple step:

sqlite3 /path/to/foreman/db/production.db .dump > foreman.dump

SQLite databases are all contained in a single file, so you can back them up by copying the file to another location, but it is recommended to shut down the instance first, or at lest verify the integrity of the created archive using sqlite3 command. The dump command above is preferred.

Configuration

On Red Hat compatible systems issue the following command to backup whole /etc directory structure:

tar --selinux -czvf etc_foreman_dir.tar.gz /etc/foreman

For all other distribution do similar command:

tar -czvf etc_foreman_dir.tar.gz /etc/foreman

Puppet master

On the puppet master node, issue the following command to backup Puppet certificates on Red Hat compatible systems

tar --selinux -czvf var_lib_puppet_dir.tar.gz /var/lib/puppet/ssl

For all other distribution do similar command:

tar -czvf var_lib_puppet_dir.tar.gz /var/lib/puppet/ssl

DHCP, DNS and TFTP services

Depending on used software packages, perform backup of important data and configuration files according to the documentation. For ISC DHCP and DNS software, these are located within /etc and /var directories depending on your distribution as well as TFTP service.

5.5.2 Recovery

Recovery process is supposed to be performed on the same host the backup was created on on the same distribution and version.

If you planning to migrate Foreman instance, please read remarks in the beginning of this chapter.

Note: Foreman instance must be stopped before proceeding.

PostgreSQL

The pg_restore command can be used to recover contents of your PostgreSQL database from the database dump. The most reliable way PostgreSQL database is:

su postgres -c "pg_restore -C -d postgres foreman.dump"

MySQL database

The mysql command can be used to recover contents of your MySQL database from the database dump in SQL format.

mysql < dump.sql

Please follow MySQL documentation about other options for data recovery.

SQLite database

To recover from SQLite dump perform this simple step:

sqlite3 /path/to/foreman/db/production.db < foreman.dump

It is possible just to copy db file, but Foreman instance must be stopped.

Configuration

On Red Hat compatible systems issue the following command to restore whole /etc directory structure:

tar --selinux -xzvf etc_foreman_dir.tar.gz -C /

For all other distribution do similar command:

tar -xzvf etc_foreman_dir.tar.gz -C /

It is recommended to extract files to an empty directory first and inspect the content before overwriting current files (change -C option to an empty directory).

Puppet master

On the puppet master node, issue the following command to restore Puppet certificates on Red Hat compatible systems

tar --selinux -xzvf var_lib_puppet_dir.tar.gz -C /

For all other distribution do similar command:

tar -xzvf var_lib_puppet_dir.tar.gz -C /

It is recommended to inspect the content of the restore first (see above).

DHCP, DNS and TFTP services

Depending on used software packages, perform recovery of important data and configuration files according to the documentation. This depends on the software and distribution that is in use.

5.6 Rails Console

Foreman is a Ruby on Rails application, which provides an interactive console for advanced debugging and troubleshooting tasks. Using this allows easy bypass of authorization and security mechanisms, and can easily lead to loss of data or corruption unless care is taken.

To access the Rails console, choose the method below appropriate to the installation method.

RPM installations

As root, execute:

yum install foreman-console
cd ~foreman && sudo -u foreman scl enable ruby193 'RAILS_ENV=production rails c'

Debian and source installations

As root, execute:

cd ~foreman && sudo -u foreman RAILS_ENV=production bundle exec rails c

Set up

To assume full admin permissions in order to modify objects, enter in the console:

User.current = User.admin

6. Troubleshooting

There are two primary methods of getting support for the Foreman: IRC and mailing lists.

IRC

We work on the libera.chat servers. You can get general support in #theforeman, while development chat takes place in #theforeman-dev.

Mailing lists

Mailing lists are available via Google Groups. Much like IRC, we have a general users (support, Q/A, etc) lists and a development list:

• foreman-users
• foreman-dev