1. Plugins

Plugins are tools to extend and modify the functionality of Foreman, Smart Proxy and Hammer CLI. The core Foreman applications are designed to be lean, to maximize flexibility and to minimize code bloat. Plugins offer custom functions and features so that each user can tailor their environment to their specific needs.

A plugin project may consist of a single Foreman or Smart Proxy plugin, or often a Foreman plugin, Smart Proxy plugin, and a Hammer CLI plugin working together.

Foreman plugins are implemented as Rails engines, and Foreman, Smart Proxy and Hammer CLI plugins are all packaged as gems, RPMs and Debian packages.


1.2 More plugins

Full lists of plugins are available:

2. Installation

Foreman, Smart Proxy and Hammer CLI plugins are packaged as gems, but the Foreman project provides RPMs and Debian packages to ease installation with standard Foreman packages. See below for the different installation methods, which depend on your platform.

The number of plugins available in the project repositories is increasing, so check the wiki to see if a package is available yet. If it’s an useful or popular plugin and not yet packaged, please file a feature request in the packaging project (see Bug Reporting for more details on reporting issues).

2.1 Using the Foreman installer

Some plugins can be installed using the Foreman installer, which can help with additional configuration that the plugin may require, e.g. config files or services.

To see which plugins the installer can set up, run:

# foreman-installer --help | grep enable-
    --[no-]enable-foreman-plugin-discovery Enable 'foreman_plugin_discovery' puppet module (default: false)
    --[no-]enable-foreman-plugin-docker Enable 'foreman_plugin_docker' puppet module (default: false)
    --[no-]enable-foreman-plugin-hooks Enable 'foreman_plugin_hooks' puppet module (default: false)

Run the installer with the extra --enable... argument to add the plugin. Any arguments given when Foreman was first installed will be kept the same, saved in the installer answers file.

Note that the installer will enforce the state of all managed configuration files, so manual changes will be reverted. Use --noop -v first to check for any unexpected changes.

foreman-installer --noop -v --enable-foreman-plugin-discovery

Run again without noop to make the changes:

foreman-installer --enable-foreman-plugin-discovery

Some plugins have additional parameters, which can be changed using foreman-installer -i for interactive mode or found in the foreman-installer --help output.

2.2 Package installation

Select operating system

To provide specific installation instructions, please select your operating system:

No operating system selected.

The repositories are available at yum.theforeman.org/plugins. Separate repositories are available for each Foreman release, containing plugins that are compatible with that particular version. Packages are not currently GPG signed.

If not already configured by foreman-release, add the repo by creating /etc/yum.repos.d/foreman-plugins.repo with the following content:

[foreman-plugins]
name=Foreman plugins
baseurl=http://yum.theforeman.org/plugins/1.14/el6/x86_64/
enabled=1
gpgcheck=0
[foreman-plugins]
name=Foreman plugins
baseurl=http://yum.theforeman.org/plugins/1.14/el7/x86_64/
enabled=1
gpgcheck=0
[foreman-plugins]
name=Foreman plugins
baseurl=http://yum.theforeman.org/plugins/1.14/f19/x86_64/
enabled=1
gpgcheck=0

The repositories are available at http://deb.theforeman.org plugins <version>. Separate repositories are available for each Foreman release, containing plugins that are compatible with that particular version. They are signed with the Foreman APT key.

If not already configured, add the repo by editing /etc/apt/sources.list.d/foreman.repo and adding the following line:

deb http://deb.theforeman.org/ plugins 1.14

Change the version number in the URL to match the Foreman release in use.

To install a plugin:

  1. Find the package for the plugin with the search function: yum search discovery or by checking the plugin documentation.
  2. Install the package, e.g. yum install tfm-rubygem-foreman_discovery.
  3. Restart Foreman with touch ~foreman/tmp/restart.txt or service httpd restart

Some plugins (e.g. foreman_column_view) may also require configuration in /etc/foreman/plugins/, check for any .example files. Smart proxy plugins can be configured in /etc/foreman-proxy/settings.d/.

To install a plugin:

  1. Find the package for the plugin: apt-cache search discovery
  2. Install the package, e.g. apt-get install ruby-foreman-discovery
  3. Restart Foreman: touch ~foreman/tmp/restart.txt or service apache2 restart

Some plugins (e.g. foreman_column_view) may also require configuration in /etc/foreman/plugins/, check for any .example files. Smart proxy plugins can be configured in /etc/foreman-proxy/settings.d/.

The naming of packages is as follows:

  • Packages for Foreman 1.10 or newer have a tfm-rubygem-foreman_ codefix, while packages for Foreman 1.9 or older will have a ruby193-rubygem-foreman_ codefix instead. Adapt any instructions to suit.
  • Smart proxy packages have a rubygem-smart_proxy_ codefix.
  • Hammer CLI packages for Foreman 1.10 or newer have a tfm-rubygem-hammer_cli_ codefix, while CLI packages for 1.9 or older will have a rubygem-hammer_cli_ codefix only.

The naming of packages is as follows:

  • Foreman plugin packages have a rubygem-foreman_ codefix. Adapt any instructions to suit.
  • Smart proxy packages have a rubygem-smart_proxy_ codefix.
  • Hammer CLI packages have a rubygem-hammer_cli_ codefix.

The naming of packages is as follows:

  • Packages for Foreman have a ruby-foreman- codefix.
  • Smart proxy packages have a ruby-smart-proxy- codefix.
  • Hammer CLI packages have a ruby-hammer-cli- codefix.

2.3 Advanced Installation from Gems

Not recommended, as it’s possible for the ‘gem’ command to install other, newer dependencies, which can cause problems with the Foreman installation. Do note the install without dependencies below to avoid this problem.

Ensure the plugin you want is available from rubygems.org as a gem. Plugins that aren’t published (just git repos) can’t be installed with this method without being built as a gem.

2.3.1 Red Hat distributions

If on EL6 or EL7, run scl enable tfm bash first for an SCL-enabled shell (not needed on Fedora). On Foreman 1.9 or older, use scl enable ruby193 bash instead.

  • Install without dependencies: gem install --ignore-dependencies foreman_column_view
  • If you need other dependencies (see the rubygems.org page), check the yum repo above (e.g. deface, nokogiri) or install the same way with ‘gem’
  • Add to the bundler.d/Gemfile.local.rb file as detailed below.
  • Restart Foreman with service foreman restart

If you hit problems, uninstall the added gems with <pre>gem uninstall -v VERSION GEM</pre>

2.3.2 Debian distributions

It is recommended to use ~foreman/bundler.d/Gemfile.local.rb so that it is not overwritten by future upgrades.

  • If it’s published on rubygems.org, just add the name and the latest released version will be downloaded. Add to bundler.d/Gemfile.local.rb:
gem 'foreman_sample_plugin'
  • Or bundler can install the plugin from a git repository. Add to bundler.d/Gemfile.local.rb:
gem 'foreman_sample_plugin', :git => "https://github.com/example/foreman_sample_plugin.git"
  • Next, as a Foreman user (not root), run the following command: $ bundle update foreman_sample_plugin
  • Then restart Foreman with touch ~foreman/tmp/restart.txt

3. Writing Your Own

More information about writing your own plugins is available in the wiki:

The Foreman development mailing list and IRC channels can be of help for plugin developers.


A new bug fix release for Foreman 1.14 is available. See the Foreman 1.14.2 release notes for more details.

Foreman 1.14.0 is now available, featuring new automatic IPv6 support, LDAP and template enhancements, and easier email configuration. Read about all of the changes in the release notes, and follow the quick start to install it.