Using Foreman Hooks in Satellite Server
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.
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.
Installing Foreman Hooks
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.
Use yum to install foreman hooks:
# yum install tfm-rubygem-foreman_hooks
Creating Foreman Hooks
Foreman hooks are stored in /usr/share/foreman/config/hooks/.
Procedure
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 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, see On Red Hat Enterprise Linux 7, see Fixing Problems.
Restart Satellite services for the hook to be registered:
# foreman-maintain service restart
Creating a Foreman Hook to Use the logger Command
This hook script creates additional log messages each time Foreman provisions a new server.
Procedure
Create the directory structure on the Satellite Server base system:
# mkdir -p /usr/share/foreman/config/hooks/host/managed/before_provision/
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.
Change the script owner to foreman:
# chown foreman:foreman /usr/share/foreman/config/hooks/host/managed/before_provision/_10__logger.sh
Change the script permissions to allow execution by the user:
# chmod u+x /usr/share/foreman/config/hooks/host/managed/before_provision/_10__logger.sh
Ensure the SELinux context is correct on all files in the /usr/share/foreman/config/hooks directory:
# restorecon -RvF /usr/share/foreman/config/hooks/
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
Restart Satellite services for the hook to be registered:
# foreman-maintain service restart
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:
- host
- report
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 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
Rails Events
Standard Rails events can be used on hosts, NICs as well as other objects. 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 Content from api.rubyonrails.org is not included.Ruby on Rails ActiveRecord::Callbacks documentation.
To see a list of objects that can be hooked you can run:
foreman-rake hooks:objects
To see a list of event names for an object, use a command such as the one below, where in this example events for the "host/managed" object are displayed:
foreman-rake hooks:events[host/managed]
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 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.
Hook Failures and Rollback
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).