Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

foreman

Foreman server configuration
Project URLRSS FeedReport issues

1,215,063 downloads

205 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 25.3.0 (latest)
  • 25.2.2
  • 25.2.1
  • 25.2.0
  • 25.1.0
  • 25.0.0
  • 24.2.1
  • 24.2.0
  • 24.1.0
  • 24.0.0
  • 23.2.0
  • 23.1.0
  • 23.0.0
  • 22.2.0
  • 22.1.2
  • 22.1.1
  • 22.1.0
  • 22.0.0
  • 21.2.0
  • 21.1.0
  • 21.0.0
  • 20.2.0
  • 20.1.0
  • 20.0.0
  • 19.3.0
  • 19.2.2
  • 19.2.1
  • 19.2.0
  • 19.1.1
  • 19.1.0
  • 19.0.0
  • 18.2.0
  • 18.1.0
  • 18.0.0
  • 17.0.0
  • 16.1.0
  • 16.0.0
  • 15.1.2
  • 15.1.1
  • 15.1.0
  • 15.0.3
  • 15.0.2
  • 15.0.1
  • 15.0.0
  • 14.0.2
  • 14.0.1 (deleted)
  • 14.0.0
  • 13.1.0
  • 13.0.1
  • 13.0.0
  • 12.2.0
  • 12.1.0
  • 12.0.0
  • 11.0.3
  • 11.0.2
  • 11.0.1
  • 11.0.0
  • 10.0.0
  • 9.2.0
  • 9.1.0
  • 9.0.1
  • 9.0.0
  • 8.1.1
  • 8.1.0
  • 8.0.0
  • 7.2.0
  • 7.1.0
  • 7.0.0
  • 6.0.0
  • 5.2.2
  • 5.2.1
  • 5.2.0
  • 5.1.0
  • 5.0.2
  • 5.0.1
  • 5.0.0
  • 4.0.1
  • 4.0.0
  • 3.0.3
  • 3.0.2
  • 3.0.1
  • 3.0.0
  • 2.3.2
  • 2.3.1
  • 2.3.0
  • 2.2.4
  • 2.2.3
  • 2.2.2
  • 2.2.1
  • 2.2.0
  • 2.1.4
  • 2.1.3
  • 2.1.2
  • 2.1.1
  • 2.1.0
  • 2.0.1 (deleted)
  • 1.3.0
  • 1.2.0
  • 1.2.0-rc3 (pre-release)
  • 1.2.0-rc2 (pre-release)
  • 1.2.0-rc1 (pre-release)
released Nov 4th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'theforeman-foreman', '25.3.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add theforeman-foreman
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install theforeman-foreman --version 25.3.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: foreman

Documentation

theforeman/foreman — version 25.3.0 Nov 4th 2024

Puppet Forge Build Status

Puppet module for managing Foreman

Installs and configures Foreman, part of the Foreman installer or to be used as a Puppet module.

Many Foreman plugins can be installed by adding additional foreman::plugin::* classes, extra compute resource support via foreman::compute::* classes and the Hammer CLI can be installed by adding foreman::cli.

By default, it configures Foreman to run as a standalone service fronted by Apache as a reverse proxy with a PostgreSQL database.

The web interface is configured to use Puppet's SSL certificates by default, so ensure they're present first, reconfigure server_ssl_* or disable the ssl parameter. When used with the 'puppet' module, it will generate a new CA and the required certificate.

Lots of parameters are supplied to tune the default installation, which may be found in the class documentation at the top of each manifest.

Other modules may be used in combination with this one: puppet for managing a Puppet master and agent, and foreman_proxy to configure Foreman's Smart Proxy and related services.

Database support

The default database is PostgreSQL, which will be fully installed and managed on the host this module is applied to. Databases will be created with using the en_US.utf8 locale, which means a respective OS locale must be available on the database host. The database management can be disabled with db_manage.

Rails Cache support

Foreman supports different backends as Rails cache. This is handled by this module using the parameter rails_cache_store. The parameter takes a hash containing the type and options specfic to the backend.

The default is the file backend, configured via {'type' => 'file'}. To setup for redis use a hash similar to {'type' => 'redis', 'urls' => ['localhost:8479/4'], 'options' => {'compress' => 'true', 'namespace' => 'foreman'}} where urls takes an array of redis urls which get prepended with redis:// and options using a hash with options from rails falling back to {'compress' => 'true', 'namespace' => 'foreman'} if no option is provided.

An example configuration for activating the redis backend with a local instance could look like this:

class { 'foreman':
  rails_cache_store => {
    'type' => 'redis',
    'urls' => ['localhost:8479/4'],
    'options' => {
      'compress' => 'true',
      'namespace' => 'foreman'
    }
  }
}

Support policy

At any time, the module supports two releases, however the previous version may require parameters to be changed from their default values. These should be noted below.

Thus 'master' will support the upcoming major version and the current stable. The latest release (git tag, Puppet Forge) should support current and the previous stable release.

Foreman version compatibility notes

This module targets Foreman 3.1+. The module can not be used to manage Foreman installations on EL7.

This module configures Apache to serve static assets from /var/lib/foreman/public directly. This requires an appropriate SELinux policy, like the one introduced in foreman-selinux version 3.5. Additionally, some plugin packages might be incomplatible with such a deployment. To serve assets via Rails again, set foreman::config::apache::proxy_assets to true.

Types and providers

foreman_config_entry can be used to manage settings in Foreman's database, as seen in Administer > Settings. The cli provider uses foreman-rake to change settings.

foreman_smartproxy can create and manage registered smart proxies in Foreman's database. The rest_v3 provider uses the API with Ruby's HTTP library, OAuth and JSON.

foreman_hostgroup can be used to create and destroy hostgroups. Nested hostgroups are supported and hostgroups can be assigned to locations/organizations. The type currently doesn't support other properties such as environment, puppet classes etc.

Foreman ENC via hiera

There is a function foreman::enc to retrieve the ENC data. This returns the data as a hash and can be used in Hiera. This requires the URL to use the Puppet CA infrastructure:

---
version: 5
hierarchy:
  - name: "Foreman ENC"
    data_hash: foreman::enc
    options:
      url: https://foreman.example.com

It is also possible to use HTTP basic auth by adding a username/password to the URL in the form of https://username:password@foreman.example.com.

Then within your manifests you can use lookup. For example, in manifests/site.pp:

node default {
  lookup('classes', {merge => unique}).include
}

Contributing

  • Fork the project
  • Commit and push until you are happy with your contribution
  • Send a pull request with a description of your changes

See the CONTRIBUTING.md file for much more information.

Adding new foreman::plugin::* classes is a very useful place to start contributing to this module.

More info

See https://theforeman.org or at #theforeman irc channel on freenode

Copyright (c) 2010-2013 Ohad Levy and their respective owners

Except where specified in provided modules, this program and entire repository is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.