Administering Foreman

The first time you log in to Foreman, you might see a warning informing you that you are using the default self-signed certificate and you might not be able to connect this browser to Foreman until the root CA certificate is imported in the browser. Use the following procedure to locate the root CA certificate on Foreman and to import it into your browser.

To use the CLI instead of the Foreman web UI, see CLI Procedure.

Use the web user interface to log in to Foreman for further configuration.

This section describes how to log in to your Foreman Hammer CLI with your FreeIPA (IdM) login and password.

This section describes how to use the Firefox browser to log in to your Foreman web UI with your FreeIPA (IdM) login and password.

This section describes how to use a Chrome browser to log in to your Foreman web UI with your FreeIPA login and password.

Use the navigation tabs to browse the Foreman web UI.

These steps show how to change your password.

Use the following procedures to reset the administrative password to randomly generated characters or to set a new administrative password.

Unless you update the ~/.hammer/cli.modules.d/foreman.yml file, you cannot use the new password with Hammer CLI.

Unless you update the ~/.hammer/cli.modules.d/foreman.yml file, you cannot use the new password with Hammer CLI.

Foreman, Katello, and Candlepin use the PostgreSQL database. If you want to use PostgreSQL as an external database, the following information can help you decide if this option is right for your Foreman configuration. Foreman supports PostgreSQL version 12.

Install a freshly provisioned system with the latest Enterprise Linux 8 to host the external databases.

You can install only the same version of PostgreSQL that is installed with the foreman-installer tool during an internal database installation. Foreman supports PostgreSQL version 12.

If you do not use firewall-cmd to configure the Linux firewall, implement using the command of your choice.

Back up and transfer existing data, then use the foreman-installer command to configure Foreman to connect to an external PostgreSQL database server.

Use this procedure to install the Foreman Ansible modules.

You can view the installed Foreman Ansible modules by running:

Alternatively, you can also see the complete list of Foreman Ansible modules and other related information at Ansible Galaxy.

All modules are in the theforeman.foreman namespace and can be referred to in the format theforeman.foreman._module_name_. For example, to display information about the activation_key module, enter the following command:

As an administrator, you can create, modify and remove Foreman users. You can also configure access permissions for a user or a group of users by assigning them different roles.

Adding SSH keys to a user allows deployment of SSH keys during provisioning. For information on deploying SSH keys during provisioning, see Deploying SSH Keys during Provisioning in Provisioning Hosts.

For information on SSH keys and SSH key creation, see Using SSH-based Authentication in Red Hat Enterprise Linux 8 Configuring basic system settings.

Personal Access Tokens allow you to authenticate API requests without using your password. You can set an expiration date for your Personal Access Token and you can revoke it if you decide it should expire before the expiration date.

Foreman provides a set of predefined roles with permissions sufficient for standard tasks, as listed in Predefined Roles Available in Foreman. It is also possible to configure custom roles, and assign one or more permission filters to them. Permission filters define the actions allowed for a certain resource type. Certain Foreman plug-ins create roles automatically.

The following table provides an overview of permissions that predefined roles in Foreman grant to a user.

To view the exact set of permissions a predefined role grants, display the role in Foreman web UI as the privileged user. For more information, see Viewing Permissions of a Role.

As mentioned in Adding Permissions to a Role, Foreman provides the ability to limit the configured user permissions to selected instances of a resource type. These granular filters are queries to the Foreman database and are supported by the majority of resource types.

Foreman can create the following email notifications:

For a complete list of email notification types, navigate to Administer > Users in the Foreman web UI, click the Username of the required user, and select the Email Preferences tab.

You can configure Foreman to send email messages to individual users registered to Foreman. Foreman sends the email to the email address that has been added to the account, if present. Users can edit the email address by clicking on their name in the top-right of the Foreman web UI and selecting My account.

Configure email notifications for a user from the Foreman web UI.

To verify the delivery of emails, send a test email to a user. If the email gets delivered, the settings are correct.

If the email is delivered, the verification is complete. Otherwise, you must perform the following diagnostic steps:

To verify that users are correctly subscribed to notifications, trigger the notifications manually.

This triggers all notifications scheduled for the specified frequency for all the subscribed users. If every subscribed user receives the notifications, the verification succeeds.

Foreman can send event notifications for a host to the host’s registered owner. You can configure Foreman to send email notifications either to an individual user or a user group. When set to a user group, all group members who are subscribed to the email type receive a message.

Receiving email notifications for a host can be useful, but also overwhelming if you are expecting to receive frequent errors, for example, because of a known issue or error you are working around.

Foreman uses the Security Content Automation Protocol (SCAP) standard to define security policies.

SCAP is a framework of several specifications based on XML, such as checklists described in the Extensible Checklist Configuration Description Format (XCCDF) and vulnerabilities described in the Open Vulnerability and Assessment Language (OVAL). These specifications are encapsulated as data stream files.

Checklist items in XCCDF, also known as rules, express the desired configuration of a system item. For example, a rule may specify that no one can log in to a host over SSH using the root user account. Rules can be grouped into one or more XCCDF profiles, which allows multiple profiles to share a rule.

The OpenSCAP scanner tool evaluates system items on a host against the rules and generates a report in the Asset Reporting Format (ARF), which is then returned to Foreman for monitoring and analysis.

SCAP content is a SCAP data-stream file that contains implementation of compliance, configuration, or security baselines. A single data stream usually includes multiple XCCDF profiles. An XCCDF profile defines an industry standard or custom security standard against which you can evaluate compliance of host configuration in Foreman, such as Protection Profile for General Purpose Operating Systems (OSPP), Health Insurance Portability and Accountability Act (HIPAA), and PCI-DSS v3.2.1 Control Baseline for Enterprise Linux 9. You can adapt existing XCCDF profiles according to your requirements using tailoring files.

In Foreman, you use an XCCDF profile from SCAP content and, eventually, a tailoring file, to define a compliance policy. Foreman includes default SCAP contents from SCAP Security Guide provided by the OpenSCAP project.

For more information on how to download, deploy, modify, and create your own content, see:

You can use one of the following methods to deploy compliance policies:

You can install and enable the OpenSCAP plug-in to generate SCAP compliance reports. The OpenSCAP plug-in consists of the OpenSCAP Foreman plug-in, the OpenSCAP Hammer CLI plug-in, the OpenSCAP Smart Proxy plug-in, and the module for Puppet policy deployment.

Use one the following procedures to configure Foreman for the method that you have selected to deploy compliance policies. You will select one of these methods when you later create a compliance policy.

Use this procedure to view what SCAP contents are already loaded in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.

You can upload SCAP data streams and tailoring files to define compliance policies.

A compliance policy is a scheduled audit that checks the specified hosts for compliance against a specific XCCDF profile from a SCAP content.

You specify the schedule for scans on Foreman server and the scans are performed on hosts. When a scan completes, a report in ARF format is generated and uploaded to Foreman server. The compliance policy makes no changes to the scanned host.

A compliance policy defines a SCAP client configuration and a cron schedule. The policy is then deployed together with the SCAP client on hosts to which the policy is assigned.

To deploy a compliance policy, you must install the SCAP client, update the cron schedule file, and upload the SCAP content selected in the policy onto a host.

Hosts perform OpenSCAP scans regularly by the CRON schedule defined in the compliance policies assigned to hosts. However, you can also run a scan on a host for all configured compliance policies manually at any time.

With Foreman, you can centralize compliance monitoring and management. A compliance dashboard provides an overview of compliance of hosts and the ability to view details for each host within the scope of that policy. Compliance reports provide a detailed analysis of compliance of each host with the applicable policy. With this information, you can evaluate the risks presented by each host and manage the resources required to bring hosts into compliance. By monitoring compliance with SCAP, you can verify policy compliance and detect changes in compliance.

Note that estimations in this section are for the installations that use the Katello plug-in.

The full backup creates uncompressed archives of PostgreSQL and Pulp database files, and Foreman configuration files. Compression occurs after the archives are created to decrease the time when Foreman services are unavailable.

A full backup requires space to store the following data:

Foreman uses the foreman-maintain backup command to make backups.

There are three main methods of backing up Foreman server:

The foreman-maintain backup command creates a time-stamped subdirectory in the backup directory that you specify. The foreman-maintain backup command does not overwrite backups, therefore you must select the correct directory or subdirectory when restoring from a backup or an incremental backup. The foreman-maintain backup command stops and restarts services as required.

When you run the foreman-maintain backup offline command, the following default backup directories are created:

If you want to set a custom directory name, add the --preserve-directory option and add a directory name. The backup is then stored in the directory you provide in the command line. If you use the --preserve-directory option, no data is removed if the backup fails.

Note that if you use a local PostgreSQL database, the postgres user requires write access to the backup directory.

You can use the foreman-maintain backup command to back up remote databases.

You can use both online and offline methods to back up remote databases, but if you use offline methods, such as snapshot, the foreman-maintain backup command performs a database dump.

You can perform an offline backup that excludes the contents of the Pulp directory. The backup without Pulp content is useful for debugging purposes and is only intended to provide access to configuration files without backing up the Pulp database. For production usecases, do not restore from a directory that does not contain Pulp content.

Use this procedure to perform an offline backup of any changes since a previous backup.

To perform incremental backups, you must perform a full backup as a reference to create the first incremental backup of a sequence. Keep the most recent full backup and a complete sequence of incremental backups to restore from.

The following script performs a full backup on a Sunday followed by incremental backups for each of the following days. A new subdirectory is created for each day that an incremental backup is performed. The script requires a daily cron job.

Note that the foreman-maintain backup command requires /sbin and /usr/sbin directories to be in PATH and the --assumeyes option is used to skip the confirmation prompt.

Perform an online backup only for debugging purposes.

When performing an online backup, if there are procedures affecting the Pulp database, the Pulp part of the backup procedure repeats until it is no longer being altered. Because the backup of the Pulp database is the most time consuming part of backing up Foreman, if you make a change that alters the Pulp database during this time, the backup procedure keeps restarting.

For production environments, use the snapshot method. For more information, see Performing a Snapshot Backup. If you want to use the online backup method in production, proceed with caution and ensure that no modifications occur during the backup.

You can perform a snapshot backup that uses Logical Volume Manager (LVM) snapshots of the Pulp, and PostgreSQL directories. Creating a backup from LVM snapshots mitigates the risk of an inconsistent backup.

The snapshot backup method is faster than a full offline backup and therefore reduces Foreman downtime.

To view the usage statement, enter the following command:

The foreman-maintain backup snapshot command creates snapshots when the services are active, and stops all services which can impact the backup. This makes the maintenance window shorter. After the successful snapshot, all services are restarted and LVM snapshots are removed.

A backup using the foreman-maintain backup command proceeds in a sequence of steps. To skip part of the backup add the --whitelist option to the command and add the step label that you want to omit.

Use this procedure to restore Foreman or Smart Proxy server from a full backup. When the restore process completes, all processes are online, and all databases and system configuration revert to the state at the time of the backup.

Use this procedure to restore Foreman or Smart Proxy server from incremental backups. If you have multiple branches of incremental backups, select your full backup and each incremental backup for the branch you want to restore, in chronological order.

When the restore process completes, all processes are online, and all databases and system configuration revert to the state at the time of the backup.

If your Smart Proxy server is a virtual machine, you can restore it from a snapshot. Creating weekly snapshots to restore from is recommended. In the event of failure, you can install, or configure a new Smart Proxy server, and then synchronize the database content from Foreman server.

If required, deploy a new Smart Proxy server, ensuring the host name is the same as before, and then install the Smart Proxy certificates. You may still have them on Foreman server, the package name ends in -certs.tar, alternately create new ones. Follow the procedures in Installing Smart Proxy server until you can confirm, in the Foreman web UI, that Smart Proxy server is connected to Foreman server. Then use the procedure Synchronizing an External Smart Proxy to synchronize from Foreman.

The host name of Foreman server is used by Foreman server components, all Smart Proxy servers, and hosts registered to it for communication. This procedure ensures that in addition to renaming Foreman server, you also update all references to point to the new host name.

The host name of Smart Proxy server is referenced by Foreman server components and all hosts registered to it. This procedure ensures that in addition to renaming Smart Proxy server, you also update all references to the new host name.

You can use the foreman-rake audits:expire command to remove audit records at any time.

You can automatically delete audit records using the Saved audits interval setting. This setting is empty by default, meaning Foreman does not automatically delete the audit records.

You can use the foreman-rake audits:anonymize command to remove any user account or IP information while maintaining the audit records in the database. You can also use a cron job to schedule anonymizing the audit records at the set interval that you want.

By default, using the foreman-rake audits:anonymize command anonymizes audit records that are older than 90 days. You can specify the number of days to keep the audit records by adding the days option and add the number of days.

For example, if you want to anonymize audit records that are older than seven days, enter the following command:

Report records are created automatically in Foreman. You can use the foreman-rake reports:expire command to remove reports at any time. You can also use a cron job to schedule report record deletions at the set interval that you want.

By default, using the foreman-rake reports:expire command removes report records that are older than 90 days. You can specify the number of days to keep the report records by adding the days option and add the number of days.

For example, if you want to delete report records that are older than seven days, enter the following command:

Foreman performs regular cleaning to reduce disc space in the database and limit the rate of disk growth. As a result, Foreman backup completes faster and overall performance is higher.

By default, Foreman executes a cron job that cleans tasks every day at 19:45. Foreman removes the following tasks during the cleaning:

You can configure the cleaning unused tasks feature using these options:

Task records are created automatically in Foreman. You can use the foreman-rake foreman_tasks:cleanup command to remove tasks at any time. You can also use a cron job to schedule Task record deletions at the set interval that you want.

For example, if you want to delete task records from successful repository synchronizations, enter the following command:

You can delete tasks by ID, for example if you have submitted confidential data by mistake.

The following procedure describes how to resolve the situation when a logical volume (LV) with the Pulp database on it has no free space.

The PostgreSQL database can use a large amount of disk space especially in heavily loaded deployments. Use this procedure to reclaim some of this disk space on Foreman.

If you set the download policy to on demand, Foreman downloads packages only when the clients request them. You can clean up these packages to reclaim space.

Use this procedure to update your SSL certificate for Foreman server.

Use this procedure to update your SSL certificate for Smart Proxy server. The foreman-installer command, which the foreman-proxy-certs-generate command returns, is unique to each Smart Proxy server. You cannot use the same command on more than one Smart Proxy server.

Debug logging provides the most detailed log information and can help with troubleshooting issues that can arise with Foreman and its components. In the Foreman CLI, enable debug logging to log detailed debugging information for Foreman.

By default, Foreman comes with :INFO level logging enabled. You can increase or decrease the log levels on your Foreman.

Foreman uses a set of back-end services to perform tasks. You you experience an issue with your Foreman, check the status of Foreman services.

You can enable individual loggers for selective logging. Foreman uses the following loggers:

Foreman uses file-based logging by default. You can use the foreman-installer command to reconfigure logging.

Foreman provides system information in the form of notifications and log files.

You can also use the foreman-tail command to follow many of the log files related to Foreman. You can run foreman-tail -l to list the processes and services that it follows.

You can collect information from log files to troubleshoot Foreman.

The following table lists metadata that the journald service uses in Foreman. You can use this metadata to filter your queries.

The Foreman content dashboard contains various widgets which provide an overview of the host configuration, Content Views, compliance reports, subscriptions and hosts currently registered, promotions and synchronization, and a list of the latest notifications.

In the Foreman web UI, navigate to Monitor > Dashboard to access the content dashboard. The dashboard can be rearranged by clicking on a widget and dragging it to a different position. The following widgets are available:

To view Foreman event notification alerts, click the Notifications icon in the upper right of the screen.

By default, the Notifications area displays RSS feed events published in the Foreman Blog.

The feed is refreshed every 12 hours and the Notifications area is updated whenever new events become available.

You can configure the RSS feed notifications by changing the URL feed. The supported feed format is RSS 2.0 and Atom. For an example of the RSS 2.0 feed structure, see the Foreman Blog feed. For an example of the Atom feed structure, see the Foreman blog feed.

Audit records list the changes made by all users on Foreman. This information can be used for maintenance and troubleshooting.

The following section shows how to use the Foreman web UI to find Smart Proxy information valuable for maintenance and troubleshooting.

The legacy foreman_hooks plugin provided full access to model objects that the webhooks plugin does not intentionally provide.

The scope of what is available is limited by the safemode and all objects and macros are both subject to an API stability promise and are fully documented.

The number of events triggered by webhooks is substantially fewer than with foreman_hooks.

Webhooks are processed asynchronously so there is minimal risk of tampering with internals of the system. It is not possible to migrate from foreman_hooks without creating payloads for each individual webhook script. However, the webhooks plugin comes with several example payload templates. You can also use the example payloads with shellhooks to simplify migration.

Both script and payload templates must be customized to achieve similar results.

Use the following procedure to install webhooks. After installing webhooks, you can configure Foreman server to send webhook requests.

Webhook templates are used to generate the body of HTTP request to a configured target when a webhook is triggered. Use the following procedure to create a webhook template in the Foreman web UI.

When creating a webhook template, you must follow the format of the target application for which the template is intended. For example, an application can expect a "text" field with the webhook message. Refer to the documentation of your target application to find more about how your webhook template format should look like.

You can customize events, payloads, HTTP authentication, content type, and headers through the Foreman web UI.

Use the following procedure to create a webhook in the Foreman web UI.

When configuring webhooks with endpoints with non-standard HTTP or HTTPS ports, an SELinux port must be assigned, see Configuring SELinux to Ensure Access to Foreman on Custom Ports in Installing Foreman 3.5 Server with Katello 4.7 Plugin on RHEL/CentOS.

The following table contains a list of webhook events that are available from the Foreman web UI. Action events trigger webhooks only on success, so if an action fails, a webhook is not triggered.

For more information about payload, go to Administer > About > Support > Templates DSL. A list of available types is provided in the following table. Some events are marked as custom, in that case, the payload is an object object but a Ruby hash (key-value data structure) so syntax is different.

With webhooks, you can only map one Foreman event to one API call. For advanced integrations, where a single shell script can contain multiple commands, you can install a Smart Proxy shellhooks plugin that exposes executables using a REST HTTP API.

You can then configure a webhook to reach out to a Smart Proxy API to run a predefined shellhook. A shellhook is an executable script that can be written in any language as long as it can be executed. The shellhook can for example contain commands or edit files.

You must place your executable scripts in /var/lib/foreman-proxy/shellhooks with only alphanumeric characters and underscores in their name.

You can pass input to shellhook script through the webhook payload. This input is redirected to standard input of the shellhook script. You can pass arguments to shellhook script using HTTP headers in format X-Shellhook-Arg-1 to X-Shellhook-Arg-99. For more information on passing arguments to shellhook script, see:

The HTTP method must be POST. An example URL would be: https://smartproxy.example.com:9090/shellhook/My_Script.

You must enable Smart Proxy Authorization for each webhook connected to a shellhook to enable it to authorize a call.

Standard output and standard error output are redirected to the Smart Proxy logs as messages with debug or warning levels respectively.

The shellhook HTTPS calls do not return a value.

For an example on creating a shellhook script, see Creating a Shellhook to Print Arguments.

Optionally, you can install and enable the shellhooks plugin on each Smart Proxy used for shellhooks, using the following command:

Use this procedure to pass arguments to a shellhook script using webhooks.

Use this procedure to pass arguments to a shellhook script using curl.

Create a simple shellhook script that prints "Hello World!" when you run a remote execution job.

As you start typing a search query, a list of valid options to complete the current part of the query appears. You can either select an option from the list and keep building the query using the prediction, or continue typing. To learn how free text is interpreted by the search engine, see Using Free Text Search.

When you enter free text, it will be searched for across multiple fields. For example, if you type "64", the search will return all hosts that have that number in their name, IP address, MAC address, and architecture.

Because of searching across all fields, free text search results are not very accurate and searching can be slow, especially on a large number of hosts. For this reason, we recommend that you avoid free text and use more specific, syntax-based queries whenever possible.

You can save search queries as bookmarks for reuse. You can also delete or modify a bookmark.

Bookmarks appear only on the page on which they were created. On some pages, there are default bookmarks available for the common searches, for example, all active or disabled hosts.