Search available plugins using the Satellite CLI.

Install plugins using the Satellite CLI.

To verify the install, use yum to list installed plugins:

Configure the Foreman repository using the Satellite CLI.

For additional information on foreman plugins, see the Popular Plugins and List of Plugins sections on the Foreman website.

Foreman hooks are provided by the tfm-rubygem-foreman_hooks package, which is installed by default. Ensure that the package is installed and up to date using yum as root.

Foreman hooks are stored in /usr/share/foreman/config/hooks/.

This hook script creates additional log messages each time Foreman provisions a new server.

Every Foreman or Rail object can have a hook. See the /usr/share/foreman/app/models/ directory or, to get a full list of available models, enter the following commands:

# foreman-rake console
>
ActiveRecord::Base.descendants.collect(&:name).collect(&:underscore).sort
=> ["audited/adapters/active_record/audit", "compute_resource", "container",
output truncated

This command output also lists some technical tables which are unlikely to be used with Foreman hooks, for example "active_record" or "habtm". These are most commonly used:

Foreman supports orchestration tasks for hosts and network interfaces, referred to as objects, when the object is created, updated, and destroyed. These tasks are shown to the user in the web UI. If they fail, they automatically trigger a rollback of the action. Orchestration hooks can be given a priority, therefore it is possible to order them before or after built-in orchestration steps (before a DNS record is deployed for example).

To add a hook to an event, use the following event names:

For hooks on anything apart from hosts and NICs (which support orchestration, as above) then the standard Rails events can be used. Every event has a "before" and "after" hook and these are the most interesting events provided:

The host object has two additional callbacks that you can use:

For the full list of Rails events, see the Constants section at the bottom of the Ruby on Rails ActiveRecord::Callbacks^[5] documentation.

Hooks are executed in the context of the Foreman server, so usually under the foreman user. The first argument is always the event name, enabling scripts to be symbolically linked into multiple event directories. The second argument is the string representation of the object that was hooked, for example the host name for a host:

~foreman/config/hooks/host/managed/create/50_register_system.sh create foo.example.com

A JSON representation of the hook object is passed in on standard input. This JSON is generated by the v2 API views. A utility to read this with jgrep is provided in examples/hook_functions.sh and sourcing this utility script is sufficient for most users. Otherwise, closing standard input is recommend to prevent the pipe buffer from filling which would block the Foreman thread.

echo '{"host":{"name":"foo.example.com"}}' \
  | ~foreman/config/hooks/host/managed/create/50_register_system.sh \
       create foo.example.com

Every hook within the event directory is executed in alphabetical order. For orchestration hooks, an integer prefix in the hook filename is used as the priority value, thereby influencing when it is executed in relation to DNS, DHCP, VM creation, and other tasks.

If a hook fails and exits with a non-zero return code, the event is logged. For Rails events, execution of other hooks continue. For orchestration events, a failure halts the action and rollback occurs. If another orchestration action fails, the hook might be called again to rollback its action. In that case the first argument changes as appropriate, so it must be obeyed by the script (for example, a "create" hook is called with "destroy" if it has to be rolled back later).