Red Hat Training

A Red Hat training course is available for Red Hat Satellite

Chapter 12. Customizing Satellite Server

Red Hat Satellite Server can be extended by the addition of user interface plug-ins and by the use of hooks triggered by orchestration and Rails events. Some plug-ins are installed by default but additional plug-ins can be installed as RPM packages from the Red Hat repositories and from upstream.

Plug-ins for Satellite typically include the word foreman in the RPM package name and plug-ins for Capsule include smart_proxy in the name. View the RPM package description to confirm the identity of a plug-in using yum info or rpm -qi. For information on upstream plug-ins, see the Plugins section of the Foreman website.

Red Hat supports the API but not upstream plug-ins themselves. Some hooks are provided as RPM packages and more hooks can be created as shell scripts. This enables system administrator’s familiar with shell scripts to extend the Satellite’s capabilities without having to use Ruby and Rails.

12.1. Adding Additional Plug-ins

To list the plug-ins available from the configured repositories, you can search using part of the package name. For example, on Satellite Server, enter as root: 

# yum search rubygem-foreman
Loaded plugins: product-id, search-disabled-repos, subscription-manager
=================== N/S matched: rubygem-foreman ==============================
tfm-rubygem-foreman-redhat_access.noarch : Foreman engine to access Red Hat knowledge base and manage support cases.
tfm-rubygem-foreman-tasks.noarch : Tasks support for Foreman with Dynflow integration
tfm-rubygem-foreman_abrt.noarch : Display reports from Automatic Bug Reporting Tool in Foreman
tfm-rubygem-foreman_bootdisk.noarch : Create boot disks to provision hosts with Foreman
output truncated

To view the currently installed plug-ins on a Satellite, enter as root: 

# yum list installed | grep rubygem-foreman | grep foreman

To view the currently installed plug-ins on a Capsule, enter as root: 

# yum list installed | grep proxy

To add a new plug-in, install the package and then restart Foreman. For example, to install the Templates plug-in, enter as root: 

# yum install tfm-rubygem-foreman_templates

Restart Katello services for the plug-in to be registered: 

# katello-service restart

For additional information on plug-ins, see the Popular Plugins and List of Plugins sections on the Foreman website.

Important

Support is unable to diagnose or support your Satellite if Foreman hooks have been installed and configured. Use Foreman hooks at your own risk.

Red Hat supports the plug-in API but does not provide support for any specific upstream plug-ins themselves. Foreman hooks can modify workflows in Satellite. Because of this, Red Hat support can ask that you remove all hooks in order to get support from Red Hat.

Foreman hooks cannot be migrated by the Satellite migration process. This means that you must remove them before upgrading and then reinstate them after you have confirmed that your Satellite upgrade is working as expected.

Adding Plug-ins from the Foreman Repository

The Foreman repositories are available at http://yum.theforeman.org/plugins. Separate repositories are available for each Foreman release, containing plug-ins that are compatible with that particular version. Ensure you install plug-ins compatible with the version of Foreman on your system. To determine the Foreman release in use, enter: 

$ rpm -q foreman
foreman-1.7.2.53-1.el7sat.noarch

Configure the Foreman repository as follows: 

# /etc/yum.repos.d/foreman-plugins.repo
[foreman-plugins]
name=Foreman plugins
baseurl=http://yum.theforeman.org/plugins/1.10/el_X_/x86_64/
enabled=1
gpgcheck=0

Where X is 6 or 7 for Red Hat Enterprise Linux 6 or 7 respectively. Change the version number in the URL to match the Foreman release in use. Note the packages are not currently GPG signed.

  1. Find the package for the plug-in with the search function. For example, to search for a plug-in with the word "discovery" in the name: 

    # yum search discovery

    Alternately check the plug-in documentation for the name of the plug-in.

  2. Install the package, for example: 

    # yum install tfm-rubygem-foreman_discovery

  3. Restart Katello services for the plug-in to be registered: 

    # katello-service restart

12.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:

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 /usr/share/foreman/config/hooks/host/managed/before_provision/_10__logger.sh

  4. 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

  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 Katello services for the hook to be registered: 

    # katello-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

12.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 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

12.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[11] documentation.

12.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 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.

12.2.4. 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).