Red Hat Training

A Red Hat training course is available for Red Hat Satellite

9.2. Using Foreman Hooks

Foreman's host orchestration can be extended by means of hooks so that additional tasks can be executed. A Foreman hook enables triggering a script (any executable can be used) when an orchestration event occurs, such as when a host is created or when provisioning of a host has completed. In addition, hooks can be made into standard Rails callbacks for any Foreman object, all with scripts.

Note

Foreman hooks can modify workflows in Satellite and therefore you might be requested to remove all hooks in order to get support from Red Hat. Foreman hooks also need to be removed before upgrading, and then reinstated after you have confirmed Satellite is working as expected.
Foreman hooks are provided by the tfm-rubygem-foreman_hooks package, which is installed by default. If required, to ensure the package is installed and up to date enter as root: 
# yum install tfm-rubygem-foreman_hooks
Loaded plugins: product-id, search-disabled-repos, subscription-manager
Package tfm-rubygem-foreman_hooks-0.3.9-2.el7sat.noarch already installed and latest version
Nothing to do
Foreman hooks are stored in /usr/share/foreman/config/hooks/. A subdirectory must be created for each Foreman object, with further subdirectories created for each event name. A Foreman object can be a host or network interface. The path to the hook is as follows: 
/usr/share/foreman/config/hooks/object/event/hook_script
For example, to create a subdirectory for hooks to be activated after the host has completed its operating system installation, enter a command as follows: 
# mkdir -p /usr/share/foreman/config/hooks/host/managed/before_provision/
If you download a script, and the appropriately named directory has been created already, then use the install command as follows to ensure the SELinux context is correct: 
install hook_script /usr/share/foreman/config/hooks/object/event/hook_script
Alternately, if you created the script directly in the event subdirectory then apply the SELinux context by entering as root: 
# restorecon -RvF /usr/share/foreman/config/hooks
The SELinux context is bin_t on Red Hat Enterprise Linux 6 and foreman_hook_t on Red Hat Enterprise Linux 7. Keep in mind that the script is running confined, therefore some actions might be denied by SELinux. Check for actions denied by SELinux by running aureport -a or looking in /var/log/audit/audit.log.
For further information on debugging SELinux problems and using the audit2allow utility:

Procedure 9.1. Creating a Foreman Hook to Use the logger Command

This hook script creates additional log messages each time Foreman provisions a new server.
  1. Create the directory structure on the Satellite Server base system: 
    # mkdir -p /usr/share/foreman/config/hooks/host/managed/before_provision/
  2. Create the script as follows: 
    # vi /usr/share/foreman/config/hooks/host/managed/before_provision/10_logger.sh
#!/bin/bash/
logger $1 $2
    The numeric prefix 10 to the file name _logger.sh determines the order of execution for scripts in the same subdirectory. Change this prefix to suit your needs.
  3. Change the script owner to foreman: 
    # chown foreman:foreman 10_logger.sh
  4. Change the script permissions to allow execution by the user: 
    # chmod u+x 10_logger.sh
  5. Ensure the SELinux context is correct on all files in the /usr/share/foreman/config/hooks directory: 
    # restorecon -RvF /usr/share/foreman/config/hooks/
  6. To enable the foreman user to use the logger command, add the following rule to the /etc/sudoers file: 
    # vi /etc/sudoers
foreman ALL=(ALL) NOPASSWD:/usr/bin/logger
  7. Restart the Foreman service for the hook to be registered: 
    # touch ~foreman/tmp/restart.txt
Every Foreman or Rail object can have a hook. See the /usr/share/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:
  • host
  • report

9.2.1. Orchestration Events

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 will 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:
  • create
  • update
  • destroy

9.2.2. Rails Events

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:
  • after_create
  • before_create
  • after_destroy
  • before_destroy
The host object has two additional callbacks that you can use:
  • host/managed/after_build triggers when a host is put into build mode.
  • host/managed/before_provision triggers when a host completes the OS install.
For the full list of Rails events, see the Constants section at the bottom of the Ruby on Rails ActiveRecord::Callbacks[14] documentation.

9.2.3. Execution of hooks

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 will be 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 will be enough 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 will be used as the priority value, thereby influencing when it is executed in relation to DNS, DHCP, VM creation, and other tasks.

9.2.4. Hook Failures and Rollback

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