1. Accessing Foreman
After Foreman has been installed and configured, use the Foreman web UI interface to log in to Foreman for further configuration.
1.1. Foreman web UI overview
You can manage and monitor your Foreman infrastructure from a browser with the Foreman web UI. For example, you can use the following navigation features in the Foreman web UI:
Navigation feature | Description |
---|---|
Organization dropdown |
Choose the organization you want to manage. |
Location dropdown |
Choose the location you want to manage. |
Monitor |
Provides summary dashboards and reports. |
Content |
Provides content management tools. This includes content views, activation keys, and lifecycle environments. |
Hosts |
Provides host inventory and provisioning configuration tools. |
Configure |
Provides general configuration tools and data, including host groups and Ansible content. |
Infrastructure |
Provides tools on configuring how Foreman interacts with the environment. |
Provides event notifications to keep administrators informed of important environment changes. |
|
Administer |
Provides advanced configuration for settings such as users, role-based access control (RBAC), and general settings. |
1.2. Importing the Katello root CA certificate
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.
-
Your Foreman is installed and configured.
-
Identify the fully qualified domain name of your Foreman server:
# hostname -f
-
Access the
pub
directory on your Foreman server using a web browser pointed to the fully qualified domain name:https://foreman.example.com/pub
-
When you access Foreman for the first time, an untrusted connection warning displays in your web browser. Accept the self-signed certificate and add the Foreman URL as a security exception to override the settings. This procedure might differ depending on the browser being used. Ensure that the Foreman URL is valid before you accept the security exception.
-
Select
katello-server-ca.crt
. -
Import the certificate into your browser as a certificate authority and trust it to identify websites.
-
From the Foreman CLI, copy the
katello-server-ca.crt
file to the machine you use to access the Foreman web UI:# scp /var/www/html/pub/katello-server-ca.crt username@hostname:remotefile
-
In the browser, import the
katello-server-ca.crt
certificate as a certificate authority and trust it to identify websites.
1.3. Logging in to Foreman
Use the web user interface to log in to Foreman for further configuration.
-
Ensure that the Katello root CA certificate is installed in your browser. For more information, see Importing the Katello root CA certificate.
-
Access Foreman server using a web browser pointed to the fully qualified domain name:
https://foreman.example.com/
-
Enter the user name and password created during the configuration process. If a user was not created during the configuration process, the default user name is admin. If you have problems logging in, you can reset the password. For more information, see Resetting the administrative user password.
1.4. Logging in to Hammer CLI with FreeIPA credentials
Authenticate to the Foreman Hammer CLI with your FreeIPA username and password.
-
You have configured Hammer CLI to accept FreeIPA credentials. For more information, see Configuring Hammer CLI to accept FreeIPA credentials in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
Authenticate as a user defined in FreeIPA to obtain a Kerberos ticket-granting ticket (TGT):
$ kinit FreeIPA_user
WarningIf you enabled access to the Foreman API and the Foreman web UI when you were configuring FreeIPA as the authentication provider for Foreman, an attacker might now obtain an API session after the user receives the Kerberos TGT. The attack is possible even if the user did not previously enter the Foreman login credentials anywhere, for example in the browser.
-
If Hammer is not configured to negotiate authentication, initiate an authentication session manually:
$ hammer auth login negotiate
Note
|
If you destroy the active Kerberos ticket, for example with |
-
Use any
hammer
command to check that the system does not ask you to authenticate. For example:$ hammer host list
-
For more information about authenticating with Hammer, see
hammer auth --help
.
1.5. Logging in to the Foreman web UI with FreeIPA credentials in Mozilla Firefox
You can use Mozilla Firefox to log in to the Foreman web UI with your FreeIPA credentials.
Use the latest stable Mozilla Firefox browser.
-
You have FreeIPA authentication configured in your Foreman environment. For more information, see Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
The host on which you are using Mozilla Firefox is a client in the FreeIPA domain.
-
Your Mozilla Firefox is configured for Single Sign-On (SSO).
-
Obtain the Kerberos ticket granting ticket (TGT):
$ kinit user Password for user@EXAMPLE.COM:
-
In Mozilla Firefox, go to the URL of your Foreman server.
-
You are logged in automatically.
Alternatively:
-
In your browser address bar, enter the URL of your Foreman server.
-
Enter your username and password.
1.6. Logging in to the Foreman web UI with FreeIPA credentials in Chrome
You can use Chrome to log in to the Foreman web UI with your FreeIPA credentials.
Use the latest stable Chrome browser.
-
You have FreeIPA authentication configured in your Foreman environment. For more information, see Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
The host on which you are using Chrome is a client in the FreeIPA domain.
-
Enable the Chrome browser to use Kerberos authentication:
$ google-chrome --auth-server-whitelist=".example.com" --auth-negotiate-delegate-whitelist=".example.com"
NoteInstead of allowlisting the whole domain, you can also allowlist a specific Foreman server.
-
Obtain the Kerberos ticket-granting ticket (TGT):
$ kinit user Password for user@EXAMPLE.COM:
-
In Chrome, go to the URL of your Foreman server.
-
You are logged in automatically.
Alternatively:
-
In your browser address bar, enter the URL of your Foreman server.
-
Enter your username and password.
1.7. Logging in to Foreman configured with Keycloak as an authentication source
With Keycloak configured as an external authentication source for Foreman, users defined in a Keycloak realm can log in to Foreman server. The particular login methods available to users depend on how you configured integration between Keycloak and Foreman.
To authenticate to the Foreman web UI:
-
In your browser, go to
https://foreman.example.com
and enter your credentials.
To authenticate to the Foreman web UI by using Keycloak TOTP:
-
In your browser, log in to Foreman. Foreman redirects you to the Keycloak login screen.
-
Enter your username and password, and click Log In.
-
On your first login attempt, Keycloak requests you to configure your client by scanning the bar code and entering your PIN. Once authenticated, your browser redirects you back to Foreman and logs you in.
To authenticate to the Foreman CLI with Hammer:
-
Ensure that Hammer is configured to enforce session usage in
~/.hammer/cli.modules.d/foreman.yml
::foreman: :use_sessions: true
-
Initiate an authentication session with
hammer auth login oauth
:# hammer auth login oauth \ --oidc-token-endpoint 'https://keycloak.example.com/auth/realms/Foreman_realm/protocol/openid-connect/token' \ --oidc-authorization-endpoint 'https://keycloak.example.com/auth' \ --oidc-client-id 'foreman.example.com-hammer-openidc' \ --oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob
To authenticate to the Foreman CLI with Hammer by using Keycloak TOTP:
-
Ensure that Hammer is configured to enforce session usage in
~/.hammer/cli.modules.d/foreman.yml
::foreman: :use_sessions: true
-
Initiate an authentication session by using
--two-factor
withhammer auth login oauth
:# hammer auth login oauth \ --two-factor \ --oidc-token-endpoint 'https://keycloak.example.com/auth/realms/Foreman_realm/protocol/openid-connect/token' \ --oidc-authorization-endpoint 'https://keycloak.example.com/auth' \ --oidc-client-id 'foreman.example.com-hammer-openidc' \ --oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob
-
You will be prompted to enter a success code. To retrieve the success code, navigate to the URL that the command returns.
-
Enter the success code in CLI.
To log in to the Foreman web UI using the Keycloak PIV cards:
-
In Mozilla Firefox, log in to Foreman and enter your credentials.
-
When prompted, enter the PIN of the PIV card.
-
Choose the certificate for authentication. Browser verifies this certificate with Keycloak. Once authenticated, browser redirects you back to Foreman and logs you in.
1.8. Changing the password
These steps show how to change your password.
-
In the Foreman web UI, click your user name at the top right corner.
-
Select My Account from the menu.
-
In the Current Password field, enter the current password.
-
In the Password field, enter a new password.
-
In the Verify field, enter the new password again.
-
Click Submit to save your new password.
1.9. Resetting the administrative user password
Use the following procedures to reset the administrative password to randomly generated characters or to set a new administrative password.
-
Log in to the base operating system where Foreman server is installed.
-
Enter the following command to reset the password:
# foreman-rake permissions:reset Reset to user: admin, password: qwJxBptxb7Gfcjj5
-
Use this password to reset the password in the Foreman web UI.
-
Edit the
~/.hammer/cli.modules.d/foreman.yml
file on Foreman server to add the new password:# vi ~/.hammer/cli.modules.d/foreman.yml
Unless you update the ~/.hammer/cli.modules.d/foreman.yml
file, you cannot use the new password with Hammer CLI.
-
Log in to the base operating system where Foreman server is installed.
-
To set the password, enter the following command:
# foreman-rake permissions:reset password=new_password
-
Edit the
~/.hammer/cli.modules.d/foreman.yml
file on Foreman server to add the new password:# vi ~/.hammer/cli.modules.d/foreman.yml
Unless you update the ~/.hammer/cli.modules.d/foreman.yml
file, you cannot use the new password with Hammer CLI.
1.10. Setting a custom message on the Login page
-
In the Foreman web UI, navigate to Administer > Settings, and click the General tab.
-
Click the edit button next to Login page footer text, and enter the desired text to be displayed on the login page. For example, this text may be a warning message required by your company.
-
Click Save.
-
Log out of the Foreman web UI and verify that the custom text is now displayed on the login page below the Foreman version number.
2. Starting and stopping Foreman
Foreman provides the foreman-maintain service
command to manage Foreman services from the command line.
This is useful when creating a backup of Foreman.
For more information on creating backups, see Backing up Foreman server and Smart Proxy server.
After installing Foreman with the foreman-installer
command, all Foreman services are started and enabled automatically.
View the list of these services by executing:
# foreman-maintain service list
To see the status of running services, execute:
# foreman-maintain service status
To stop Foreman services, execute:
# foreman-maintain service stop
To start Foreman services, execute:
# foreman-maintain service start
To restart Foreman services, execute:
# foreman-maintain service restart
3. Tuning Foreman server with predefined profiles
If your Foreman deployment includes more than 5000 hosts, you can use predefined tuning profiles to improve performance of Foreman.
Note that you cannot use tuning profiles on Smart Proxies.
You can choose one of the profiles depending on the number of hosts your Foreman manages and available hardware resources.
The tuning profiles are available in the /usr/share/foreman-installer/config/foreman.hiera/tuning/sizes
directory.
When you run the foreman-installer
command with the --tuning
option, deployment configuration settings are applied to Foreman in the following order:
-
The default tuning profile defined in the
/usr/share/foreman-installer/config/foreman.hiera/tuning/common.yaml
file -
The tuning profile that you want to apply to your deployment and is defined in the
/usr/share/foreman-installer/config/foreman.hiera/tuning/sizes/
directory -
Optional: If you have configured a
/etc/foreman-installer/custom-hiera.yaml
file, Foreman applies these configuration settings.
Note that the configuration settings that are defined in the /etc/foreman-installer/custom-hiera.yaml
file override the configuration settings that are defined in the tuning profiles.
Therefore, before applying a tuning profile, you must compare the configuration settings that are defined in the default tuning profile in /usr/share/foreman-installer/config/foreman.hiera/tuning/common.yaml
, the tuning profile that you want to apply and your /etc/foreman-installer/custom-hiera.yaml
file, and remove any duplicated configuration from the /etc/foreman-installer/custom-hiera.yaml
file.
- default
-
Number of hosts: 0 – 5000
RAM: 20G
Number of CPU cores: 4
- medium
-
Number of hosts: 5001 – 10000
RAM: 32G
Number of CPU cores: 8
- large
-
Number of hosts: 10001 – 20000
RAM: 64G
Number of CPU cores: 16
- extra-large
-
Number of hosts: 20001 – 60000
RAM: 128G
Number of CPU cores: 32
- extra-extra-large
-
Number of hosts: 60000+
RAM: 256G
Number of CPU cores: 48+
-
Optional: If you have configured the
custom-hiera.yaml
file on Foreman server, back up the/etc/foreman-installer/custom-hiera.yaml
file tocustom-hiera.original
. You can use the backup file to restore the/etc/foreman-installer/custom-hiera.yaml
file to its original state if it becomes corrupted:# cp /etc/foreman-installer/custom-hiera.yaml \ /etc/foreman-installer/custom-hiera.original
-
Optional: If you have configured the
custom-hiera.yaml
file on Foreman server, review the definitions of the default tuning profile in/usr/share/foreman-installer/config/foreman.hiera/tuning/common.yaml
and the tuning profile that you want to apply in/usr/share/foreman-installer/config/foreman.hiera/tuning/sizes/
. Compare the configuration entries against the entries in your/etc/foreman-installer/custom-hiera.yaml
file and remove any duplicated configuration settings in your/etc/foreman-installer/custom-hiera.yaml
file. -
Enter the
foreman-installer
command with the--tuning
option for the profile that you want to apply. For example, to apply the medium tuning profile settings, enter the following command:# foreman-installer --tuning medium
4. Migrating from internal Foreman databases to external databases
When you install Foreman, the foreman-installer command installs PostgreSQL databases on the same server as Foreman. If you are using the default internal databases but want to start using external databases to help with the server load, you can migrate your internal databases to external databases.
To confirm whether your Foreman server has internal or external databases, you can query the status of your databases:
For PostgreSQL, enter the following command:
# foreman-maintain service status --only postgresql
To migrate from the default internal databases to external databases, you must complete the following procedures:
-
Preparing a host for external databases. Prepare a Red Hat Enterprise Linux 8 server to host the external databases.
-
Installing PostgreSQL. Prepare PostgreSQL with databases for Foreman, Pulp and Candlepin with dedicated users owning them.
-
Migrating to external databases. Edit the parameters of
foreman-installer
to point to the new databases, and runforeman-installer
.
4.1. PostgreSQL as an external database considerations
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.
-
Increase in free memory and free CPU on Foreman
-
Flexibility to set
shared_buffers
on the PostgreSQL database to a high number without the risk of interfering with other services on Foreman -
Flexibility to tune the PostgreSQL server’s system without adversely affecting Foreman operations
-
Increase in deployment complexity that can make troubleshooting more difficult
-
The external PostgreSQL server is an additional system to patch and maintain
-
If either Foreman or the PostgreSQL database server suffers a hardware or storage failure, Foreman is not operational
-
If there is latency between the Foreman server and database server, performance can suffer
4.2. Preparing a host for external databases
Install a freshly provisioned system with the latest Enterprise Linux 9 or Enterprise Linux 8 to host the external databases.
-
The prepared host must meet Foreman’s Storage Requirements.
Select the operating system and version you are installing external database on:
4.2.1. Enterprise Linux 9
-
Install the
katello-repos-latest.rpm
package# dnf install https://yum.theforeman.org/releases/3.11/el9/x86_64/foreman-release.rpm \ https://yum.theforeman.org/katello/4.13/katello/el9/x86_64/katello-repos-latest.rpm
-
Verify that the required repositories are enabled:
# dnf repolist enabled
4.2.2. Enterprise Linux 8
-
Install the
katello-repos-latest.rpm
package# dnf install https://yum.theforeman.org/releases/3.11/el8/x86_64/foreman-release.rpm \ https://yum.theforeman.org/katello/4.13/katello/el8/x86_64/katello-repos-latest.rpm
-
Enable the following module:
# dnf module enable katello:el8
NoteEnablement of the module
katello:el8
warns about a conflict withpostgresql:10
andruby:2.5
as these modules are set to the default module versions on Enterprise Linux 8. The modulekatello:el8
has a dependency for the modulespostgresql:12
andruby:2.7
that will be enabled with thekatello:el8
module. These warnings do not cause installation process failure, hence can be ignored safely.
-
Verify that the required repositories are enabled:
# dnf repolist enabled
4.3. Installing PostgreSQL
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.
-
To install PostgreSQL, enter the following command:
# dnf install postgresql-server postgresql-evr postgresql-contrib
-
To initialize PostgreSQL, enter the following command:
# postgresql-setup initdb
-
Edit the
/var/lib/pgsql/data/postgresql.conf
file:# vi /var/lib/pgsql/data/postgresql.conf
Note that the default configuration of external PostgreSQL needs to be adjusted to work with Foreman. The base recommended external database configuration adjustments are as follows:
-
checkpoint_completion_target: 0.9
-
max_connections: 500
-
shared_buffers: 512MB
-
work_mem: 4MB
-
-
Remove the
#
and edit to listen to inbound connections:listen_addresses = '*'
-
Add the following line to the end of the file to use SCRAM for authentication:
password_encryption=scram-sha-256
-
Edit the
/var/lib/pgsql/data/pg_hba.conf
file:# vi /var/lib/pgsql/data/pg_hba.conf
-
Add the following line to the file:
host all all Foreman_ip/32 scram-sha-256
-
To start, and enable PostgreSQL service, enter the following commands:
# systemctl enable --now postgresql
-
Open the postgresql port on the external PostgreSQL server:
# firewall-cmd --add-service=postgresql
-
Make the changes persistent:
# firewall-cmd --runtime-to-permanent
-
Switch to the
postgres
user and start the PostgreSQL client:$ su - postgres -c psql
-
Create three databases and dedicated roles: one for Foreman, one for Candlepin, and one for Pulp:
CREATE USER "foreman" WITH PASSWORD 'Foreman_Password'; CREATE USER "candlepin" WITH PASSWORD 'Candlepin_Password'; CREATE USER "pulp" WITH PASSWORD 'Pulpcore_Password'; CREATE DATABASE foreman OWNER foreman; CREATE DATABASE candlepin OWNER candlepin; CREATE DATABASE pulpcore OWNER pulp;
-
Connect to the Pulp database:
postgres=# \c pulpcore You are now connected to database "pulpcore" as user "postgres".
-
Create the
hstore
extension:pulpcore=# CREATE EXTENSION IF NOT EXISTS "hstore"; CREATE EXTENSION
-
Exit the
postgres
user:# \q
-
From Foreman server, test that you can access the database. If the connection succeeds, the commands return
1
.# PGPASSWORD='Foreman_Password' psql -h postgres.example.com -p 5432 -U foreman -d foreman -c "SELECT 1 as ping" # PGPASSWORD='Candlepin_Password' psql -h postgres.example.com -p 5432 -U candlepin -d candlepin -c "SELECT 1 as ping" # PGPASSWORD='Pulpcore_Password' psql -h postgres.example.com -p 5432 -U pulp -d pulpcore -c "SELECT 1 as ping"
4.4. Migrating to external databases
Back up and transfer existing data, then use the foreman-installer
command to configure Foreman to connect to an external PostgreSQL database server.
-
You have installed and configured a PostgreSQL server on a Enterprise Linux server.
-
On Foreman server, stop all Foreman services except for PostgreSQL:
# foreman-maintain service stop --exclude postgresql
-
Back up the internal databases:
# foreman-maintain backup online \ --preserve-directory \ --skip-pulp-content \ /var/migration_backup
-
Transfer the data to the new external databases:
PGPASSWORD='Foreman_Password' pg_restore -h postgres.example.com -U foreman -d foreman < /var/migration_backup/foreman.dump PGPASSWORD='Candlepin_Password' pg_restore -h postgres.example.com -U candlepin -d candlepin < /var/migration_backup/candlepin.dump PGPASSWORD='Pulpcore_Password' pg_restore -h postgres.example.com -U pulp -d pulpcore < /var/migration_backup/pulpcore.dump
-
Use the
foreman-installer
command to update Foreman to point to the new databases:# foreman-installer \ --katello-candlepin-manage-db false \ --katello-candlepin-db-host postgres.example.com \ --katello-candlepin-db-name candlepin \ --katello-candlepin-db-user candlepin \ --katello-candlepin-db-password Candlepin_Password \ --foreman-proxy-content-pulpcore-manage-postgresql false \ --foreman-proxy-content-pulpcore-postgresql-host postgres.example.com \ --foreman-proxy-content-pulpcore-postgresql-db-name pulpcore \ --foreman-proxy-content-pulpcore-postgresql-user pulp \ --foreman-proxy-content-pulpcore-postgresql-password Pulpcore_Password \ --foreman-db-manage false \ --foreman-db-host postgres.example.com \ --foreman-db-database foreman \ --foreman-db-username foreman \ --foreman-db-password Foreman_Password
5. Managing Foreman with Ansible collections
Foreman Ansible Collections is a set of Ansible modules that interact with the Foreman API. You can manage and automate many aspects of Foreman with Foreman Ansible collections.
5.1. Installing the Foreman Ansible modules
Use this procedure to install the Foreman Ansible modules.
-
Install the package using the following command:
# dnf install ansible-collection-theforeman-foreman
5.2. Viewing the Foreman Ansible modules
You can view the installed Foreman Ansible modules by running:
# ansible-doc -l theforeman.foreman
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:
$ ansible-doc theforeman.foreman.activation_key
6. Managing users and roles
A User defines a set of details for individuals using the system. Users can be associated with organizations and environments, so that when they create new entities, the default settings are automatically used. Users can also have one or more roles attached, which grants them rights to view and manage organizations and environments. See Managing users for more information on working with users.
You can manage permissions of several users at once by organizing them into user groups. User groups themselves can be further grouped to create a hierarchy of permissions. For more information on creating user groups, see Creating and managing user groups.
Roles define a set of permissions and access levels. Each role contains one on more permission filters that specify the actions allowed for the role. Actions are grouped according to the Resource type. Once a role has been created, users and user groups can be associated with that role. This way, you can assign the same set of permissions to large groups of users. Foreman provides a set of predefined roles and also enables creating custom roles and permission filters as described in Creating and managing roles.
6.1. Managing users
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.
6.1.1. Creating a user
Use this procedure to create a user. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Administer > Users.
-
Click Create User.
-
Enter the account details for the new user.
-
Click Submit to create the user.
The user account details that you can specify include the following:
-
On the User tab, select an authentication source from the Authorized by list:
-
INTERNAL: to manage the user inside Foreman server.
-
EXTERNAL: to manage the user with external authentication. For more information, see Configuring External Authentication in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
-
On the Organizations tab, select an organization for the user. Specify the default organization Foreman selects for the user after login from the Default on login list.
ImportantIf a user is not assigned to an organization, their access is limited.
-
Create a user:
# hammer user create \ --auth-source-id My_Authentication_Source \ --login My_User_Name \ --mail My_User_Mail \ --organization-ids My_Organization_ID_1,My_Organization_ID_2 \ --password My_User_Password
The
--auth-source-id 1
setting means that the user is authenticated internally, you can specify an external authentication source as an alternative. Add the--admin
option to grant administrator privileges to the user. Specifying organization IDs is not required.You can modify the user details later by using the
hammer user update
command.
-
For more information about creating user accounts by using Hammer, enter
hammer user create --help
.
6.1.2. Assigning roles to a user
Use this procedure to assign roles to a user. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Administer > Users.
-
Click the username of the user to be assigned one or more roles.
NoteIf a user account is not listed, check that you are currently viewing the correct organization. To list all the users in Foreman, click Default Organization and then Any Organization.
-
Click the Locations tab, and select a location if none is assigned.
-
Click the Organizations tab, and check that an organization is assigned.
-
Click the Roles tab to display the list of available roles.
-
Select the roles to assign from the Roles list.
To grant all the available permissions, select the Administrator checkbox.
-
Click Submit.
To view the roles assigned to a user, click the Roles tab; the assigned roles are listed under Selected items. To remove an assigned role, click the role name in Selected items.
-
To assign roles to a user, enter the following command:
# hammer user add-role --id user_id --role role_name
6.1.3. Impersonating a different user account
Administrators can impersonate other authenticated users for testing and troubleshooting purposes by temporarily logging on to the Foreman web UI as a different user. When impersonating another user, the administrator has permissions to access exactly what the impersonated user can access in the system, including the same menus.
Audits are created to record the actions that the administrator performs while impersonating another user. However, all actions that an administrator performs while impersonating another user are recorded as having been performed by the impersonated user.
-
Ensure that you are logged on to the Foreman web UI as a user with administrator privileges for Foreman.
-
In the Foreman web UI, navigate to Administer > Users.
-
To the right of the user that you want to impersonate, from the list in the Actions column, select Impersonate.
When you want to stop the impersonation session, in the upper right of the main menu, click the impersonation icon.
6.1.4. Creating an API-only user
You can create users that can interact only with the Foreman API.
-
You have created a user and assigned roles to them. Note that this user must be authorized internally. For more information, see Creating a user and Assigning roles to a user.
-
Log in to your Foreman as admin.
-
Navigate to Administer > Users and select a user.
-
On the User tab, set a password. Do not save or communicate this password with others. You can create pseudo-random strings on your console:
# openssl rand -hex 32
-
Create a Personal Access Token for the user. For more information, see Creating a Personal Access Token.
6.2. Managing SSH keys
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.
6.2.1. Managing SSH keys for a user
Use this procedure to add or remove SSH keys for a user. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
Ensure that you are logged in to the Foreman web UI as an Admin user of Foreman or a user with the create_ssh_key permission enabled for adding SSH key and destroy_ssh_key permission for removing a key.
-
In the Foreman web UI, navigate to Administer > Users.
-
From the Username column, click on the username of the required user.
-
Click on the SSH Keys tab.
-
To Add SSH key
-
Prepare the content of the public SSH key in a clipboard.
-
Click Add SSH Key.
-
In the Key field, paste the public SSH key content from the clipboard.
-
In the Name field, enter a name for the SSH key.
-
Click Submit.
-
-
To Remove SSH key
-
Click Delete on the row of the SSH key to be deleted.
-
Click OK in the confirmation prompt.
-
-
To add an SSH key to a user, you must specify either the path to the public SSH key file, or the content of the public SSH key copied to the clipboard.
-
If you have the public SSH key file, enter the following command:
# hammer user ssh-keys add \ --user-id user_id \ --name key_name \ --key-file ~/.ssh/id_rsa.pub
-
If you have the content of the public SSH key, enter the following command:
# hammer user ssh-keys add \ --user-id user_id \ --name key_name \ --key ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNtYAAABBBHHS2KmNyIYa27Qaa7EHp+2l99ucGStx4P77e03ZvE3yVRJEFikpoP3MJtYYfIe8k 1/46MTIZo9CPTX4CYUHeN8= host@user
To delete an SSH key from a user, enter the following command:
# hammer user ssh-keys delete --id key_id --user-id user_id
To view an SSH key attached to a user, enter the following command:
# hammer user ssh-keys info --id key_id --user-id user_id
To list SSH keys attached to a user, enter the following command:
# hammer user ssh-keys list --user-id user_id
6.3. Managing Personal Access Tokens
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.
6.3.1. Creating a Personal Access Token
Use this procedure to create a Personal Access Token.
-
In the Foreman web UI, navigate to Administer > Users.
-
Select a user for which you want to create a Personal Access Token.
-
On the Personal Access Tokens tab, click Add Personal Access Token.
-
Enter a Name for you Personal Access Token.
-
Optional: Select the Expires date to set an expiration date. If you do not set an expiration date, your Personal Access Token will never expire unless revoked.
-
Click Submit. You now have the Personal Access Token available to you on the Personal Access Tokens tab.
ImportantEnsure to store your Personal Access Token as you will not be able to access it again after you leave the page or create a new Personal Access Token. You can click Copy to clipboard to copy your Personal Access Token.
-
Make an API request to your Foreman server and authenticate with your Personal Access Token:
# curl https://foreman.example.com/api/status --user My_Username:My_Personal_Access_Token
-
You should receive a response with status
200
, for example:{"foreman_version":"3.11.0","result":"ok","status":200,"version":"3.5.1.10","api_version":2}
If you go back to Personal Access Tokens tab, you can see the updated Last Used time next to your Personal Access Token.
6.3.2. Revoking a Personal Access Token
Use this procedure to revoke a Personal Access Token before its expiration date.
-
In the Foreman web UI, navigate to Administer > Users.
-
Select a user for which you want to revoke the Personal Access Token.
-
On the Personal Access Tokens tab, locate the Personal Access Token you want to revoke.
-
Click Revoke in the Actions column next to the Personal Access Token you want to revoke.
-
Make an API request to your Foreman server and try to authenticate with the revoked Personal Access Token:
# curl https://foreman.example.com/api/status --user My_Username:My_Personal_Access_Token
-
You receive the following error message:
{ "error": {"message":"Unable to authenticate user My_Username"} }
6.4. Creating and managing user groups
6.4.1. User groups
With Foreman, you can assign permissions to groups of users. You can also create user groups as collections of other user groups. If using an external authentication source, you can map Foreman user groups to external user groups as described in Configuring External User Groups in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
User groups are defined in an organizational context, meaning that you must select an organization before you can access user groups.
6.4.2. Creating a user group
Use this procedure to create a user group.
-
In the Foreman web UI, navigate to Administer > User Groups.
-
Click Create User group.
-
On the User Group tab, specify the name of the new user group and select group members:
-
Select the previously created user groups from the User Groups list.
-
Select users from the Users list.
-
-
On the Roles tab, select the roles you want to assign to the user group. Alternatively, select the Admin checkbox to assign all available permissions.
-
Click Submit.
-
To create a user group, enter the following command:
# hammer user-group create \ --name My_User_Group_Name \ --role-ids My_Role_ID_1,My_Role_ID_2 \ --user-ids My_User_ID_1,My_User_ID_2
6.5. Creating and managing roles
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 plugins create roles automatically.
6.5.1. Creating a role
Use this procedure to create a role.
-
In the Foreman web UI, navigate to Administer > Roles.
-
Click Create Role.
-
Provide a Name for the role.
-
Click Submit to save your new role.
-
To create a role, enter the following command:
# hammer role create --name My_Role_Name
To serve its purpose, a role must contain permissions. After creating a role, proceed to Adding permissions to a role.
6.5.2. Cloning a role
Use the Foreman web UI to clone a role.
-
In the Foreman web UI, navigate to Administer > Roles and select Clone from the drop-down menu to the right of the required role.
-
Provide a Name for the role.
-
Click Submit to clone the role.
-
Click the name of the cloned role and navigate to Filters.
-
Edit the permissions as required.
-
Click Submit to save your new role.
6.5.3. Adding permissions to a role
Use this procedure to add permissions to a role. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Administer > Roles.
-
Select Add Filter from the drop-down list to the right of the required role.
-
Select the Resource type from the drop-down list. The (Miscellaneous) group gathers permissions that are not associated with any resource group.
-
Click the permissions you want to select from the Permission list.
-
Depending on the Resource type selected, you can select or deselect the Unlimited and Override checkbox. The Unlimited checkbox is selected by default, which means that the permission is applied on all resources of the selected type. When you disable the Unlimited checkbox, the Search field activates. In this field you can specify further filtering with use of the Foreman search syntax. For more information, see Granular permission filtering. When you enable the Override checkbox, you can add additional locations and organizations to allow the role to access the resource type in the additional locations and organizations; you can also remove an already associated location and organization from the resource type to restrict access.
-
Click Next.
-
Click Submit to save changes.
-
List all available permissions:
# hammer filter available-permissions
-
Add permissions to a role:
# hammer filter create \ --permission-ids My_Permission_ID_1,My_Permission_ID_2 \ --role My_Role_Name
For more information about roles and permissions parameters, enter the hammer role --help
and hammer filter --help
commands.
6.5.4. Viewing permissions of a role
Use the Foreman web UI to view the permissions of a role.
-
In the Foreman web UI, navigate to Administer > Roles.
-
Click Filters to the right of the required role to get to the Filters page.
The Filters page contains a table of permissions assigned to a role grouped by the resource type. It is also possible to generate a complete table of permissions and actions that you can use on your Foreman system. For more information, see Creating a complete permission table.
6.5.5. Creating a complete permission table
Use the Foreman CLI to create a permission table.
-
Ensure that the
foreman-console
package is installed on Foreman server:# dnf install foreman-console
-
Start the Foreman console with the following command:
# foreman-rake console
-
Insert the following code into the console:
f = File.open('/tmp/table.html', 'w') result = Foreman::AccessControl.permissions {|a,b| a.security_block <=> b.security_block}.collect do |p| actions = p.actions.collect { |a| "<li>#{a}</li>" } "<tr><td>#{p.name}</td><td><ul>#{actions.join('')}</ul></td><td>#{p.resource_type}</td></tr>" end.join("\n") f.write(result)
The above syntax creates a table of permissions and saves it to the
/tmp/table.html
file. -
Press
Ctrl
+D
to exit the Foreman console. -
Insert the following text at the first line of
/tmp/table.html
:<table border="1"><tr><td>Permission name</td><td>Actions</td><td>Resource type</td></tr>
-
Append the following text at the end of
/tmp/table.html
:</table>
-
Open
/tmp/table.html
in a web browser to view the table.
6.6. Predefined roles available in Foreman
The following table provides an overview of permissions that predefined roles in Foreman grant to a user.
For a complete set of predefined roles and the permissions they grant, log in to Foreman web UI as the privileged user and navigate to Administer > Roles. For more information, see Viewing permissions of a role.
Predefined role | Permissions the role provides | Additional information |
---|---|---|
Auditor |
View the Audit log. |
|
Default role |
View tasks and jobs invocations. |
Foreman automatically assigns this role to every user in the system. |
Manager |
View and edit global settings. |
|
Organization admin |
All permissions except permissions for managing organizations. |
An administrator role defined per organization. The role has no visibility into resources in other organizations. By cloning this role and assigning an organization, you can delegate administration of that organization to a user. |
Site manager |
View permissions for various items. Permissions to manage hosts in the infrastructure. |
A restrained version of the Manager role. |
System admin |
Edit global settings in Administer > Settings. View, create, edit, and destroy users, user groups, and roles. View, create, edit, destroy, and assign organizations and locations but not view resources within them. |
Users with this role can create users and assign all roles to them. Give this role only to trusted users. |
Viewer |
View the configuration of every element of the Foreman structure, logs, reports, and statistics. |
6.7. Granular permission filtering
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.
6.7.1. Creating a granular permission filter
Use this procedure to create a granular filter. To use the CLI instead of the Foreman web UI, see the CLI procedure.
Foreman does not apply search conditions to create actions. For example, limiting the create_locations action with name = "Default Location" expression in the search field does not prevent the user from assigning a custom name to the newly created location.
Specify a query in the Search field on the Edit Filter page. Deselect the Unlimited checkbox for the field to be active. Queries have the following form:
field_name operator value
-
field_name marks the field to be queried. The range of available field names depends on the resource type. For example, the Partition Table resource type offers family, layout, and name as query parameters.
-
operator specifies the type of comparison between field_name and value. See Supported operators for granular search for an overview of applicable operators.
-
value is the value used for filtering. This can be for example a name of an organization. Two types of wildcard characters are supported: underscore (_) provides single character replacement, while percent sign (%) replaces zero or more characters.
For most resource types, the Search field provides a drop-down list suggesting the available parameters. This list appears after placing the cursor in the search field. For many resource types, you can combine queries using logical operators such as and, not and has operators.
-
To create a granular filter, enter the
hammer filter create
command with the--search
option to limit permission filters, for example:# hammer filter create \ --permission-ids 91 \ --search "name ~ ccv*" \ --role qa-user
This command adds to the qa-user role a permission to view, create, edit, and destroy content views that only applies to content views with name starting with ccv
.
6.7.2. Examples of using granular permission filters
As an administrator, you can allow selected users to make changes in a certain part of the environment path. The following filter allows you to work with content while it is in the development stage of the application lifecycle, but the content becomes inaccessible once is pushed to production.
Applying permissions for the host resource type
The following query applies any permissions specified for the Host resource type only to hosts in the group named host-editors.
hostgroup = host-editors
The following query returns records where the name matches XXXX, Yyyy, or zzzz example strings:
name ^ (XXXX, Yyyy, zzzz)
You can also limit permissions to a selected environment. To do so, specify the environment name in the Search field, for example:
Dev
You can limit user permissions to a certain organization or location with the use of the granular permission filter in the Search field. However, some resource types provide a GUI alternative, an Override checkbox that provides the Locations and Organizations tabs. On these tabs, you can select from the list of available organizations and locations. For more information, see Creating an organization-specific manager role.
Creating an organization-specific manager role
Use the Foreman web UI to create an administrative role restricted to a single organization named org-1.
-
In the Foreman web UI, navigate to Administer > Roles.
-
Clone the existing Organization admin role. Select Clone from the drop-down list next to the Filters button. You are then prompted to insert a name for the cloned role, for example org-1 admin.
-
Click the desired locations and organizations to associate them with the role.
-
Click Submit to create the role.
-
Click org-1 admin, and click Filters to view all associated filters. The default filters work for most use cases. However, you can optionally click Edit to change the properties for each filter. For some filters, you can enable the Override option if you want the role to be able to access resources in additional locations and organizations. For example, by selecting the Domain resource type, the Override option, and then additional locations and organizations using the Locations and Organizations tabs, you allow this role to access domains in the additional locations and organizations that is not associated with this role. You can also click New filter to associate new filters with this role.
6.7.3. Supported operators for granular search
Operator |
Description |
and |
Combines search criteria. |
not |
Negates an expression. |
has |
Object must have a specified property. |
Operator |
Description |
= |
Is equal to. An equality comparison that is case-sensitive for text fields. |
!= |
Is not equal to. An inversion of the = operator. |
~ |
Like. A case-insensitive occurrence search for text fields. |
!~ |
Not like. An inversion of the ~ operator. |
^ |
In. An equality comparison that is case-sensitive search for text fields. This generates a different SQL query to the Is equal to comparison, and is more efficient for multiple value comparison. |
!^ |
Not in. An inversion of the ^ operator. |
>, >= |
Greater than, greater than or equal to. Supported for numerical fields only. |
<, ⇐ |
Less than, less than or equal to. Supported for numerical fields only. |
7. Configuring email notifications
Email notifications are created by Foreman server periodically or after completion of certain events. The periodic notifications can be sent daily, weekly or monthly.
For an overview of available notification types, see Email notification types.
Users do not receive any email notifications by default. An administrator can configure users to receive notifications based on criteria such as the type of notification, and frequency.
Important
|
Foreman server does not enable outgoing emails by default, therefore you must review your email configuration. For more information, see Configuring Foreman server for Outgoing Emails in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux. |
7.1. Email notification types
Foreman can create the following email notifications:
- Audit summary
-
A summary of all activity audited by Foreman server.
- Compliance policy summary
-
A summary of OpenSCAP policy reports and their results.
- Content view promote failure
-
A notification sent after content view promotion fails.
- Content view publish failure
-
A notification sent after content view publication fails.
- Host built
-
A notification sent after a host is built.
- Host errata advisory
-
A summary of applicable and installable errata for hosts managed by the user.
- Promote errata
-
A notification sent only after a content view promotion. It contains a summary of errata applicable and installable to hosts registered to the promoted content view. This allows a user to monitor what updates have been applied to which hosts.
- Repository sync failure
-
A notification sent after repository synchronization fails.
- Smart Proxy sync failure
-
A notification sent after Smart Proxy synchronization fails.
- Sync errata
-
A notification sent only after synchronizing a repository. It contains a summary of new errata introduced by the synchronization.
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.
7.2. Configuring email notification preferences
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.
Note
|
If you want to send email notifications to a group email address instead of an individual email address, create a user account with the group email address and minimal Foreman permissions, then subscribe the user account to the desired notification types. |
-
The user you are configuring to receive email notifications has a role with this permission:
view_mail_notifications
.
-
In the Foreman web UI, navigate to Administer > Users.
-
Click the Username of the user you want to edit.
-
On the User tab, verify the value of the Mail field. Email notifications will be sent to the address in this field.
-
On the Email Preferences tab, select Mail Enabled.
-
Select the notifications you want the user to receive using the drop-down menus next to the notification types.
NoteThe Audit Summary notification can be filtered by entering the required query in the Mail Query text box.
-
Click Submit.
The user will start receiving the notification emails.
7.3. Testing email delivery
To verify the delivery of emails, send a test email to a user. If the email gets delivered, the settings are correct.
-
In the Foreman web UI, navigate to Administer > Users.
-
Click on the username.
-
On the Email Preferences tab, click Test email.
A test email message is sent immediately to the user’s email address.
If the email is delivered, the verification is complete. Otherwise, you must perform the following diagnostic steps:
-
Verify the user’s email address.
-
Verify Foreman server’s email configuration.
-
Examine firewall and mail server logs.
7.4. Testing email notifications
To verify that users are correctly subscribed to notifications, trigger the notifications manually.
-
To trigger the notifications, execute the following command:
# foreman-rake reports:_My_Frequency_
Replace My_Frequency with one of the following:
-
daily
-
weekly
-
monthly
This triggers all notifications scheduled for the specified frequency for all the subscribed users. If every subscribed user receives the notifications, the verification succeeds.
Note
|
Sending manually triggered notifications to individual users is currently not supported. |
7.5. Changing email notification settings for a host
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.
-
In the Foreman web UI, navigate to Hosts > All Hosts, locate the host that you want to view, and click Edit in the Actions column.
-
Go to the Additional Information tab. If the checkbox Include this host within Foreman reporting is checked, then the email notifications are enabled on that host.
-
Optional: Toggle the checkbox to enable or disable the email notifications.
NoteIf you want to receive email notifications, ensure that you have an email address set in your user settings.
8. Backing up Foreman server and Smart Proxy server
You can back up your Foreman deployment to ensure the continuity of your Foreman deployment and associated data in the event of a disaster. If your deployment uses custom configurations, you must consider how to handle these custom configurations when you plan your backup and disaster recovery policy.
Note
|
If you create a new instance of the Foreman server, decommission the old instances after restoring the backup. Cloned instances are not supposed to run in parallel in a production environment. |
To create a backup of your Foreman server or Smart Proxy server and all associated data, use the foreman-maintain backup
command.
Backing up to a separate storage device on a separate system is highly recommended.
Foreman services are unavailable during the backup.
Therefore, you must ensure that no other tasks are scheduled by other administrators.
You can schedule a backup using cron
.
For more information, see the Example of a weekly full backup followed by daily incremental backups.
During offline backups, the services are inactive and Foreman is in a maintenance mode. All the traffic from outside on port 443 is rejected by a firewall to ensure there are no modifications triggered.
A backup contains sensitive information from the /root/ssl-build
directory.
For example, it can contain hostnames, ssh keys, request files and SSL certificates.
You must encrypt or move the backup to a secure location to minimize the risk of damage or unauthorized access to the hosts.
You can also use conventional backup methods. For more information, see Recovering and restoring a system in Red Hat Enterprise Linux 8 Configuring basic system settings.
Note
|
If you plan to use the |
-
When creating a snapshot or conventional backup, you must stop all services as follows:
# foreman-maintain service stop
-
Start the services after creating a snapshot or conventional backup:
# foreman-maintain service start
8.1. Estimating the size of a backup
Note that estimations in this section are for the installations that use the Katello plugin.
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:
-
Uncompressed Foreman database and configuration files
-
Compressed Foreman database and configuration files
-
An extra 20% of the total estimated space to ensure a reliable backup
-
Enter the
du
command to estimate the size of uncompressed directories containing Foreman database and configuration files:# du -sh /var/lib/pgsql/data /var/lib/pulp 100G /var/lib/pgsql/data 100G /var/lib/pulp # du -csh /var/lib/tftpboot /etc /root/ssl-build \ /var/www/html/pub /opt/puppetlabs 16M /var/lib/tftpboot 37M /etc 900K /root/ssl-build 100K /var/www/html/pub 2M /opt/puppetlabs 942M total
-
Calculate how much space is required to store the compressed data.
The following table describes the compression ratio of all data items included in the backup:
Table 3. Backup data compression ratio Data type Directory Ratio Example results PostgreSQL database files
/var/lib/pgsql/data
80 – 85%
100 GB → 20 GB
Pulp RPM files
/var/lib/pulp
(not compressed)
100 GB
Configuration files
/var/lib/tftpboot
/etc
/root/ssl-build
/var/www/html/pub
/opt/puppetlabs
85%
942 MB → 141 MB
In this example, the compressed backup data occupies 120 GB in total.
-
To calculate the amount of available space you require to store a backup, calculate the sum of the estimated values of compressed and uncompressed backup data, and add an extra 20% to ensure a reliable backup.
This example requires 201 GB plus 120 GB for the uncompressed and compressed backup data, 321 GB in total. With 64 GB of extra space, 385 GB must be allocated for the backup location.
8.2. Performing a full backup of Foreman server or Smart Proxy server
Foreman uses the foreman-maintain backup
command to make backups.
There are two main methods of backing up Foreman server:
-
Offline backup
-
Online backup
For more information about each of these methods, you can view the usage statements for each backup method.
# foreman-maintain backup offline --help
# foreman-maintain backup online --help
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:
-
foreman-backup
on Foreman -
foreman-proxy-backup
on Smart Proxy
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 method, the foreman-maintain backup
command performs a database dump.
To enable Foreman to save the backup to an NFS share, ensure that the root
user of your Foreman server or Smart Proxy server can write to the NFS share.
NFS export options such as root_squash
and all_squash
are known to prevent this.
For more information, see Red Hat Enterprise Linux Configuring and using network files services and Red Hat Enterprise Linux Securing network services.
-
Ensure that your backup location has sufficient available disk space to store the backup. For more information, see Estimating the size of a backup.
Warning
|
Request other users of Foreman server or Smart Proxy server to save any changes and warn them that Foreman services are unavailable for the duration of the backup. Ensure no other tasks are scheduled for the same time as the backup. |
-
On Foreman server, enter the following command:
# foreman-maintain backup offline /var/foreman-backup
-
On Smart Proxy server, enter the following command:
# foreman-maintain backup offline /var/foreman-proxy-backup
8.3. Performing a backup without Pulp content
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.
Warning
|
Request other users of Foreman server or Smart Proxy server to save any changes and warn them that Foreman services are unavailable for the duration of the backup. Ensure no other tasks are scheduled for the same time as the backup. |
-
Ensure that your backup location has sufficient available disk space to store the backup. For more information, see Estimating the size of a backup.
-
To perform an offline backup without Pulp content, enter the following command:
# foreman-maintain backup offline --skip-pulp-content /var/backup_directory
8.4. Performing an incremental backup
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.
Warning
|
Request other users of Foreman server or Smart Proxy server to save any changes and warn them that Foreman services are unavailable for the duration of the backup. Ensure no other tasks are scheduled for the same time as the backup. |
-
Ensure that your backup location has sufficient available disk space to store the backup. For more information, see Estimating the size of a backup.
-
To perform a full offline backup, enter the following command:
# foreman-maintain backup offline /var/backup_directory
-
To create a directory within your backup directory to store the first incremental back up, enter the
foreman-maintain backup
command with the--incremental
option:# foreman-maintain backup offline --incremental /var/backup_directory/full_backup /var/backup_directory
-
To create the second incremental backup, enter the
foreman-maintain backup
command with the--incremental
option and include the path to the first incremental backup to indicate the starting point for the next increment. This creates a directory for the second incremental backup in your backup directory:# foreman-maintain backup offline --incremental /var/backup_directory/first_incremental_backup /var/backup_directory
-
Optional: If you want to point to a different version of the backup, and make a series of increments with that version of the backup as the starting point, you can do this at any time. For example, if you want to make a new incremental backup from the full backup rather than the first or second incremental backup, point to the full backup directory:
# foreman-maintain backup offline --incremental /var/backup_directory/full_backup /var/backup_directory
8.5. Example of a weekly full backup followed by daily incremental backups
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.
#!/bin/bash -e PATH=/sbin:/bin:/usr/sbin:/usr/bin DESTINATION=/var/backup_directory if [[ $(date +%w) == 0 ]]; then foreman-maintain backup offline --assumeyes $DESTINATION else LAST=$(ls -td -- $DESTINATION/*/ | head -n 1) foreman-maintain backup offline --assumeyes --incremental "$LAST" $DESTINATION fi exit 0
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.
8.6. Performing an online backup
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 offline method. For more information, see Performing a full backup of Foreman server or Smart Proxy server. If you want to use the online backup method in production, proceed with caution and ensure that no modifications occur during the backup.
Warning
|
Request other users of Foreman server or Smart Proxy server to save any changes and warn them that Foreman services are unavailable for the duration of the backup. Ensure no other tasks are scheduled for the same time as the backup. |
-
Ensure that your backup location has sufficient available disk space to store the backup. For more information, see Estimating the size of a backup.
-
To perform an online backup, enter the following command:
# foreman-maintain backup online /var/backup_directory
8.7. Skipping steps when performing backups
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 the step label that you want to omit.
-
To display a list of available step labels, enter the following command:
# foreman-maintain advanced procedure run -h
-
To skip a step of the backup, enter the
foreman-maintain backup
command with the--whitelist
option. For example:# foreman-maintain backup online \ --whitelist backup-metadata \ /var/backup_directory
9. Restoring Foreman server or Smart Proxy server from a backup
You can restore Foreman server or Smart Proxy server from the backup data that you create as part of Backing up Foreman server and Smart Proxy server. This process outlines how to restore the backup on the same server that generated the backup, and all data covered by the backup is deleted on the target system. If the original system is unavailable, provision a system with the same configuration settings and host name.
9.1. Restoring from a full backup
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.
-
Ensure that you are restoring to the correct instance. The Foreman instance must have the same host name, configuration, and be the same minor version (X.Y) as the original system.
-
Ensure that you have an existing target directory. The target directory is read from the configuration files contained within the archive.
-
Ensure that you have enough space to store this data on the base system of Foreman server or Smart Proxy server as well as enough space after the restoration to contain all the data in the
/etc/
and/var/
directories contained within the backup.To check the space used by a directory, enter the following command:
# du -sh /var/backup_directory
To check for free space, enter the following command:
# df -h /var/backup_directory
Add the
--total
option to get a total of the results from more than one directory. -
Ensure that all SELinux contexts are correct. Enter the following command to restore the correct SELinux contexts:
# restorecon -Rv /
-
Choose the appropriate method to install Foreman or Smart Proxy:
-
To install Foreman server from a connected network, follow the procedures in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
To install a Smart Proxy server, follow the procedures in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
-
-
Copy the backup data to Foreman server’s local file system. Use
/var/
or/var/tmp/
. -
Run the restoration script.
# foreman-maintain restore /var/backup_directory
Where backup_directory is the time-stamped directory or subdirectory containing the backed-up data.
The restore process can take a long time to complete, because of the amount of data to copy.
-
For troubleshooting, you can check
/var/log/foreman/production.log
and/var/log/messages
.
9.2. Restoring from incremental backups
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.
-
Restore the last full backup using the instructions in Restoring from a full backup.
-
Remove the full backup data from Foreman server’s local file system, for example,
/var/
or/var/tmp/
. -
Copy the incremental backup data to Foreman server’s local file system, for example,
/var/
or/var/tmp/
. -
Restore the incremental backups in the same sequence that they are made:
# foreman-maintain restore /var/backup_directory/FIRST_INCREMENTAL # foreman-maintain restore /var/backup_directory/SECOND_INCREMENTAL
-
For troubleshooting, you can check
/var/log/foreman/production.log
and/var/log/messages
.
9.3. Backup and restore Smart Proxy server using a virtual machine snapshot
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 content from Foreman server to Smart Proxy servers to synchronize from Foreman.
9.3.1. Synchronizing content from Foreman server to Smart Proxy servers
Use this procedure to synchronize content from your Foreman server to your Smart Proxy server.
-
Ensure that you either select the relevant organization and location context of your Smart Proxy server or choose Any Organization and Any Location.
-
In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
-
Select your Smart Proxy server.
-
On the Overview tab, click Synchronize.
-
Select Optimized Sync to synchronize content from your Foreman server to your Smart Proxy server that bypasses unnecessary steps to speed up performance.
-
Select Complete Sync to perform a complete sync from your Foreman server to your Smart Proxy server that synchronizes content even if the metadata has not changed.
-
10. Renaming Foreman server or Smart Proxy server
To rename Foreman server or Smart Proxy server, use the katello-change-hostname
script.
Important
|
When changing the domain name of your Foreman server or Smart Proxy server, update the hostname using |
10.1. Renaming Foreman server
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.
Warning
|
Renaming your Foreman server host shuts down all Foreman services on that host. The services restart after the renaming is complete. |
-
Back up your Foreman server before changing its host name. If you fail to successfully rename it, restore it from the backup. For more information, see Backing up Foreman server and Smart Proxy server.
-
Run the
hostname
andhostname -f
commands on Foreman server. If both commands do not return the FQDN of Foreman server, thekatello-change-hostname
script will fail to complete.If the
hostname
command returns the shortname of Foreman server instead of the FQDN, usehostnamectl set-hostname My_Old_FQDN
to set the old FQDN correctly before using thekatello-change-hostname
script. -
If Foreman server has a custom SSL certificate installed, obtain a new certificate for the new FQDN of the host. For more information, see Configuring Foreman server with a Custom SSL Certificate in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
On Foreman server, run the
katello-change-hostname
script, and provide the new host name. Choose one of the following methods:-
If your Foreman server is installed with the default self-signed SSL certificates:
# katello-change-hostname new-foreman \ --username My_Username \ --password My_Password
-
If your Foreman server is installed with custom SSL certificates:
# katello-change-hostname new-foreman \ --username My_Username \ --password My_Password \ --custom-cert "/root/ownca/test.com/test.com.crt" \ --custom-key "/root/ownca/test.com/test.com.key"
-
-
If you have created a custom SSL certificate for the new Foreman server host name, run the Foreman installation script to install the certificate. For more information about installing a custom SSL certificate, see Deploying a Custom SSL Certificate to Foreman server in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
Reregister all hosts and Smart Proxy servers that are registered to Foreman server. For more information, see Registering Hosts in Managing hosts.
-
On all Smart Proxy servers, run the Foreman installation script to update references to the new host name:
# foreman-installer \ --foreman-proxy-foreman-base-url https://new-foreman.example.com \ --foreman-proxy-trusted-hosts new-foreman.example.com
-
On Foreman server, list all Smart Proxy servers:
# hammer proxy list
-
On Foreman server, synchronize content for each Smart Proxy server:
# hammer proxy content synchronize \ --id My_smart-proxy_ID
-
If you use the virt-who agent, update the virt-who configuration files with the new host name.
-
If you use external authentication, reconfigure Foreman server for external authentication after you run the
katello-change-hostname
script. For more information, see Configuring External Authentication in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
10.2. Renaming Smart Proxy server
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.
Warning
|
Renaming your Smart Proxy server host shuts down all Foreman services on that host. The services restart after the renaming is complete. |
-
Back up your Smart Proxy server before renaming. If you fail to successfully rename it, restore it from the backup. For more information, see Backing up Foreman server and Smart Proxy server.
-
Run the
hostname
andhostname -f
commands on Smart Proxy server. If both commands do not return the FQDN of Smart Proxy server, thekatello-change-hostname
script will fail to complete.If the
hostname
command returns the shortname of Smart Proxy server instead of the FQDN, usehostnamectl set-hostname My_Old_FQDN
to set the old FQDN correctly before attempting to use thekatello-change-hostname
script.
-
On your Foreman server, generate a new certificates archive file for your Smart Proxy server.
-
If you are using the default SSL certificate, regenerate the default SSL certificates:
# foreman-proxy-certs-generate \ --certs-tar /root/new-smartproxy.example.com-certs.tar \ --foreman-proxy-fqdn new-smartproxy.example.com
Ensure that you enter the full path to the
.tar
file. -
If you are using a custom SSL certificate, create a new SSL certificate for your Smart Proxy server. For more information, see Configuring Smart Proxy server with a Custom SSL Certificate in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
-
-
On your Foreman server, copy the certificates archive file to your Smart Proxy server. For example, to copy the archive file to the
root
user’s home directory:# scp /root/new-smartproxy.example.com-certs.tar root@smartproxy.example.com:
-
On your Smart Proxy server, run the
katello-change-hostname
script and provide the host’s new name, Foreman credentials, and certificates archive file name.# katello-change-hostname new-smartproxy.example.com \ --certs-tar /root/new-smartproxy.example.com-certs.tar \ --password My_Password \ --username My_Username
Ensure that you enter the full path to the
.tar
file. -
If you have created a custom certificate for your Smart Proxy server, deploy the certificate to your Smart Proxy server by entering the
foreman-installer
command that theforeman-proxy-certs-generate
command returned in a previous step. For more information, see Deploying a Custom SSL Certificate to Smart Proxy server in Installing a Smart Proxy Server 3.11 on Enterprise Linux. -
On all hosts registered to your Smart Proxy server, enter the following commands to reinstall the bootstrap RPM, reregister clients, and refresh their subscriptions.
You can use the remote execution feature to perform this step. For more information, see Configuring and Setting up Remote Jobs in Managing hosts.
On hosts running Enterprise Linux 8+, run the following commands:
# dnf remove katello-ca-consumer* # dnf install http://new-smartproxy.example.com/pub/katello-ca-consumer-latest.noarch.rpm # subscription-manager register \ --environment="My_Lifecycle_Environment" \ --force \ --org="My_Organization" # subscription-manager refresh
-
Update the Smart Proxy host name in the Foreman web UI.
-
In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
-
Locate Smart Proxy server in the list, and click Edit.
-
Edit the Name and URL fields to match Smart Proxy server’s new host name, then click Submit.
-
On your DNS server, add a record for the new hostname of your Smart Proxy server, and delete the record of the previous host name.
-
11. Maintaining Foreman server
This chapter provides information on how to maintain a Foreman server, including information on how to work with audit records, how to clean unused tasks, and how to recover Pulp from a full disk.
11.1. Deleting audit records manually
You can use the foreman-rake audits:expire
command to remove audit records at any time.
-
Delete the audit records using the
foreman-rake audits:expire
command:# foreman-rake audits:expire days=Number_Of_Days
This command deletes all audit records older than
Number_Of_Days
.
11.2. Deleting audit records automatically
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.
-
In the Foreman web UI, navigate to Administer > Settings.
-
On the General tab, find the Saved audits interval setting.
-
Set the value of the setting to the number of days after which you want Foreman to delete the audit records.
11.3. Anonymizing 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:
# foreman-rake audits:anonymize days=7
11.4. Deleting report records
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-rake reports:expire days=7
11.5. Configuring the cleaning unused tasks feature
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:
-
Tasks that have run successfully and are older than thirty days
-
All tasks that are older than a year
You can configure the cleaning unused tasks feature using these options:
-
To configure the time at which Foreman runs the cron job, set the
--foreman-plugin-tasks-cron-line
parameter to the time you want in cron format. For example, to schedule the cron job to run every day at 15:00, enter the following command:# foreman-installer --foreman-plugin-tasks-cron-line "00 15 * * *"
-
To configure the period after which Foreman deletes the tasks, edit the
:rules:
section in the/etc/foreman/plugins/foreman-tasks.yaml
file. -
To disable regular task cleanup on Foreman, enter the following command:
# foreman-installer --foreman-plugin-tasks-automatic-cleanup false
-
To reenable regular task cleanup on Foreman, enter the following command:
# foreman-installer --foreman-plugin-tasks-automatic-cleanup true
11.6. Deleting task records
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:
# foreman-rake foreman_tasks:cleanup TASK_SEARCH='label = Actions::Katello::Repository::Sync' STATES='stopped'
11.7. Deleting a task by ID
You can delete tasks by ID, for example if you have submitted confidential data by mistake.
-
Connect to your Foreman server using SSH:
# ssh root@foreman.example.com
-
Optional: View the task:
# hammer task info --id My_Task_ID
-
Delete the task:
# foreman-rake foreman_tasks:cleanup TASK_SEARCH="id=My_Task_ID"
-
Optional: Ensure the task has been removed from Foreman server:
# hammer task info --id My_Task_ID
Note that because the task is deleted, this command returns a non-zero exit code.
11.8. Recovering from a full disk
The following procedure describes how to resolve the situation when a logical volume (LV) with the Pulp database on it has no free space.
-
Let running Pulp tasks finish but do not trigger any new ones as they can fail due to the full disk.
-
Ensure that the LV with the
/var/lib/pulp
directory on it has sufficient free space. Here are some ways to achieve that:-
Remove orphaned content:
# foreman-rake katello:delete_orphaned_content RAILS_ENV=production
This is run weekly so it will not free much space.
-
Change the download policy from Immediate to On Demand for as many repositories as possible and remove already downloaded packages. See the Red Hat Knowledgebase solution How to change syncing policy for Repositories on Satellite from "Immediate" to "On-Demand" on the Red Hat Customer Portal for instructions.
-
Grow the file system on the LV with the
/var/lib/pulp
directory on it. For more information, see Growing a logical volume and file system in Red Hat Enterprise Linux 8 Configuring and managing logical volumes.NoteIf you use an untypical file system (other than for example ext3, ext4, or xfs), you might need to unmount the file system so that it is not in use. In that case, complete the following steps:
-
Stop Foreman services:
# foreman-maintain service stop
-
Grow the file system on the LV.
-
Start Foreman services:
# foreman-maintain service start
-
-
-
If some Pulp tasks failed due to the full disk, run them again.
11.9. Reclaiming PostgreSQL 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.
-
Stop all services, except for the
postgresql
service:# foreman-maintain service stop --exclude postgresql
-
Switch to the
postgres
user and reclaim space on the database:# su - postgres -c 'vacuumdb --full --all'
-
Start the other services when the vacuum completes:
# foreman-maintain service start
11.10. Reclaiming space from on demand repositories
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.
Note
|
Space reclamation requires an existing repository. For deleted repositories, wait for the next scheduled orphan cleanup or remove orphaned content manually: # foreman-rake katello:delete_orphaned_content |
-
In the Foreman web UI, navigate to Content > Products.
-
Select a product.
-
On the Repositories tab, click the repository name.
-
From the Select Actions list, select Reclaim Space.
-
In the Foreman web UI, navigate to Content > Products.
-
Select the product name.
-
On the Repositories tab, select the checkbox of the repositories.
-
Click Reclaim Space at the top right corner.
-
In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
-
Select the Smart Proxy server.
-
Click Reclaim space.
12. Renewing the SSL certificate
This chapter provides information on how to renew the SSL certificate on Foreman server as well as on Smart Proxy server.
12.1. Renewing a SSL certificate on Foreman server
Use this procedure to update your SSL certificate for Foreman server.
-
You must create a new Certificate Signing Request (CSR) and send it to the Certificate Authority to sign the certificate. Refer to the Configuring Foreman server with a Custom SSL Certificate guide before creating a new CSR because the Server certificate must have X.509 v3
Key Usage
andExtended Key Usage
extensions with required values. In return, you will receive the Foreman server certificate and CA bundle.
-
Before deploying a renewed custom certificate on your Foreman server, validate the SSL input files. Note that for the
katello-certs-check
command to work correctly, Common Name (CN) in the certificate must match the FQDN of Foreman server:# katello-certs-check -t foreman \ -b /root/foreman_cert/ca_cert_bundle.pem \ -c /root/foreman_cert/foreman_cert.pem \ -k /root/foreman_cert/foreman_cert_key.pem
If the command is successful, it returns the following
foreman-installer
command. You can use this command to deploy the renewed CA certificates to Foreman server:# foreman-installer --scenario katello \ --certs-server-cert "/root/foreman_cert/foreman_cert.pem" \ --certs-server-key "/root/foreman_cert/foreman_cert_key.pem" \ --certs-server-ca-cert "/root/foreman_cert/ca_cert_bundle.pem" \ --certs-update-server \ --certs-update-server-ca
Important
|
Do not delete the certificate files after you deploy the certificate. They are required when upgrading Foreman server. |
Note
|
If a new consumer package |
-
Access the Foreman web UI from your local machine. For example, https://foreman.example.com.
-
In your browser, view the certificate details to verify the deployed certificate.
12.2. Renewing a SSL certificate on Smart Proxy 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.
-
You must create a new Certificate Signing Request and send it to the Certificate Authority to sign the certificate. Refer to the Configuring Foreman server with a Custom SSL Certificate guide before creating a new CSR because the Foreman server certificate must have X.509 v3
Key Usage
andExtended Key Usage
extensions with required values. In return, you will receive the Smart Proxy server certificate and CA bundle.
-
On your Foreman server, validate the SSL certificate input files:
# katello-certs-check -t smart-proxy \ -b /root/smart-proxy_cert/ca_cert_bundle.pem \ -c /root/smart-proxy_cert/smart-proxy_cert.pem \ -k /root/smart-proxy_cert/smart-proxy_cert_key.pem
-
On your Foreman server, generate the certificate archive file for your Smart Proxy server:
# foreman-proxy-certs-generate \ --certs-tar "/root/My_Certificates/smartproxy.example.com-certs.tar" \ --certs-update-server \ --foreman-proxy-fqdn "smartproxy.example.com" \ --server-ca-cert "/root/My_Certificates/ca_cert_bundle.pem" \ --server-cert "/root/My_Certificates/smart-proxy_cert.pem" \ --server-key "/root/My_Certificates/smart-proxy_cert_key.pem"
-
On your Foreman server, copy the certificate archive file to your Smart Proxy server:
# scp /root/My_Certificates/smartproxy.example.com-certs.tar user@smartproxy.example.com:
You can move the copied file to the applicable path if required.
-
Retain a copy of the
foreman-installer
command that theforeman-proxy-certs-generate
command returns for deploying the certificate to your Smart Proxy server. -
Deploy the certificate on your Smart Proxy server using the
foreman-installer
command returned by theforeman-proxy-certs-generate
command:# foreman-installer --scenario foreman-proxy-content \ --certs-tar-file "/root/My_Certificates/smartproxy.example.com-certs.tar" \ --certs-update-server \ --foreman-proxy-foreman-base-url "https://foreman.example.com" \ --foreman-proxy-register-in-foreman "true"
Important
|
Do not delete the certificate archive file on the Smart Proxy server after you deploy the certificate. They are required when upgrading Smart Proxy server. |
Note
|
If a new consumer package |
13. Logging and reporting problems
The following sections describe the most commonly used log files and debugging tools available in Foreman.
13.1. Increasing logging levels to help with debugging
You can increase the logging level of Foreman components to troubleshoot Foreman.
Increasing the logging level to debug
provides the most detailed information.
The default logging level is info
.
13.1.1. Increasing the logging level for the Foreman application
To increase logging for the Foreman application:
-
Set the logging level to
debug
:# foreman-installer --foreman-logging-level debug
-
After you complete debugging, reset the logging level to the default value:
# foreman-installer --reset-foreman-logging-level
For more information about Foreman logging settings, use foreman-installer
with the --full-help
option:
# foreman-installer --full-help | grep logging
13.1.2. Increasing the logging level for Hammer
You can find the log in ~/.hammer/log/hammer.log
.
To increase logging for Hammer:
-
In
/etc/hammer/cli_config.yml
, set the:log_level:
option todebug
:
:log_level: 'debug'
13.1.3. Increasing the logging level for Smart Proxy
You can find the log in /var/log/foreman-proxy/proxy.log
.
To increase logging for Smart Proxy:
-
Set the logging level to
debug
:# foreman-installer --foreman-proxy-log-level DEBUG
-
After you complete debugging, reset the logging level to the default value:
# foreman-installer --reset-foreman-proxy-log-level
Note
|
Running foreman-installer will revert the setting back to default. |
13.1.4. Increasing the logging level for Candlepin
You can find the logs in /var/log/candlepin/candlepin.log
and /var/log/candlepin/error.log
.
To increase logging for Candlepin:
-
Set the logging level to
DEBUG
:# foreman-installer --katello-candlepin-loggers log4j.logger.org.candlepin:DEBUG
If the candlepin log files are too verbose, you can decrease the default debug level:
# foreman-installer \ --katello-candlepin-loggers log4j.logger.org.candlepin:DEBUG \ --katello-candlepin-loggers log4j.logger.org.candlepin.resource.ConsumerResource:WARN \ --katello-candlepin-loggers log4j.logger.org.candlepin.resource.HypervisorResource:WARN
-
After you complete debugging, reset the logging level to the default value:
# foreman-installer --reset-katello-candlepin-loggers
13.1.5. Increasing the logging level for Redis
You can find the log for Redis in /var/log/redis/redis.log
.
To increase logging for Redis:
-
In
/etc/redis.conf
, set the logging level todebug
:loglevel debug
-
Restart the Redis service:
# systemctl restart redis
Note
|
Running foreman-installer will revert the setting to default. |
13.1.6. Increasing the logging level for Foreman installer
You can find the log files in /var/log/foreman-installer/
.
To increase the logging level of the Foreman installer, add the --verbose-log-level debug
option during the installation:
# foreman-installer --verbose-log-level debug
13.1.7. Increasing the logging level for Pulp
By default, Pulp logs to syslog
.
You can view the log in /var/log/messages
or with journalctl
.
To increase logging for Pulp:
-
In
/etc/pulp/settings.py
, set the logging level toDEBUG
:LOGGING = {"dynaconf_merge": True, "loggers": {'': {'handlers': ['console'], 'level': 'DEBUG'}}}
-
Restart the Pulp services:
# systemctl restart \ pulpcore-api \ pulpcore-content \ pulpcore-resource-manager \ pulpcore-worker@1 \ pulpcore-worker@2 \ redis
13.1.8. Increasing the logging level for Puppet agent
You can find the logs in /var/log/puppetlabs/puppet/
.
To increase logging for Puppet agent:
-
Set the logging level to
debug
:# foreman-installer --puppet-agent-additional-settings log_level:debug
13.1.9. Increasing the logging level for Puppet server
You can find the logs in /var/log/puppetlabs/puppetserver/
.
To increase logging for Puppet server:
-
Set the logging level to
debug
:# foreman-installer --puppet-server-additional-settings log_level:debug
-
Restart the Puppet server:
# foreman-maintain service restart --only puppetserver
13.2. Configuring logging levels with Hammer CLI
You can use Hammer to log debugging information for various Foreman components.
The default logging level is INFO
.
-
To list the components whose logging level you can change by using
hammer
:# hammer admin logging --list
-
To set
DEBUG
level logging for all components:# hammer admin logging --all --level-debug # foreman-maintain service restart
-
To set
PRODUCTION
level logging for all components:# hammer admin logging --all --level-production # foreman-maintain service restart
-
To set
DEBUG
level logging for a specific component:# hammer admin logging --components My_Component --level-debug # foreman-maintain service restart
-
To list all available logging options:
# hammer admin logging --help
13.3. Configuring logging type and layout
By default, Foreman uses file-based logging.
You can use foreman-installer
to change the logging type and logging layout.
-
Enter the following
foreman-installer
command to configure logging to thejournald
service:# foreman-installer \ --foreman-logging-type journald \ --foreman-proxy-log JOURNAL
-
Optional: To inspect the log messages, use the
journalctl
utility. For example:-
journalctl --unit foreman
andjournalctl --unit foreman-proxy
show messages for theforeman
andforeman-proxy
units -
journalctl REQUEST=request_ID
shows messages for a specified request
-
-
Enter the following
foreman-installer
command to configure file-based logging:# foreman-installer \ --reset-foreman-logging-type \ --reset-foreman-proxy-log
-
Optional: To inspect the log messages, view these files:
-
/var/log/foreman/production.log
-
/var/log/foreman-proxy.log
-
-
On your Foreman server, enable logging to JSON output for
foreman-installer
:# foreman-installer \ --foreman-logging-layout json \ --foreman-logging-type file
-
Optional: Inspect the log messages using
jq
:# cat /var/log/foreman/production.log | jq
13.4. Selective debugging with individual loggers
You can enable individual loggers for selective debugging.
-
Enable the required individual loggers. For example, to enable
sql
andldap
loggers, enter the following command:# foreman-installer \ --foreman-loggers ldap:true \ --foreman-loggers sql:true
-
Optional: Reset all loggers to their default values:
# foreman-installer --reset-foreman-loggers
13.5. Overview of individual loggers
The following list provides an overview of selected loggers.
You can find the complete list of loggers with their default values in
/usr/share/foreman/config/application.rb
under Foreman::Logging.add_loggers
.
app
-
Logs web requests and all general application messages.
Default value: true.
audit
-
Logs additional fact statistics, numbers of added, updated, and removed facts.
Default value: true.
background
-
Logs information from the background processing component.
blob
-
Logs contents of rendered templates for auditing purposes.
ImportantThe blob
logger might contain sensitive data. dynflow
-
Logs information from the Dynflow process.
ldap
-
Logs high level LDAP queries and LDAP operations.
Default value: false.
notifications
-
Logs information from the notifications component.
permissions
-
Logs queries to user roles, filters, and permissions when loading pages.
Default value: false.
sql
-
Logs SQL queries made through Rails ActiveRecord.
Default value: false.
telemetry
-
Logs debugging information from telemetry.
templates
-
Logs information from the template renderer component.
13.6. Retrieving the status of services
Foreman uses a set of back-end services. When troubleshooting, you can check the status of Foreman services.
-
In the Foreman web UI, navigate to Administer > About.
-
On the Smart Proxies tab, view the status of all Smart Proxies.
-
On the Compute Resources tab, view the status of attached compute resource providers.
-
In the Backend System Status table, view the status of all back-end services.
-
-
Get information from the database and Foreman services:
# hammer ping
-
Check the status of the services running in systemd:
# foreman-maintain service status
Run
foreman-maintain service --help
for more information. -
Perform a health check:
$ foreman-maintain health check
Run
foreman-maintain health --help
for more information.
13.7. Restarting services
Foreman uses a set of back-end services. When troubleshooting, you can restart the services if needed.
-
Restart Foreman services:
# foreman-maintain service restart
13.8. Utilities for processing log information
You can collect information from log files to troubleshoot Foreman.
- sosreport
-
The
sosreport
command collects configuration and diagnostic information from a Linux system, such as the running Kernel version, loaded modules, running services, and system and service configuration files. This output is stored in a tar file located at/var/tmp/sosreport-XXX-20171002230919.tar.xz
.For more information, run
sosreport --help
or see What is a sosreport and how can I create one?.ImportantThe
sosreport
command removes security information such as passwords, tokens, and keys while collecting information. However, the tar files can still contain sensitive information about the Foreman server. Send the tar files directly to the intended recipient and not to a public target. - foreman-tail
-
The
foreman-tail
command displays Foreman logs in real time.For more information, see the
foreman-tail(8)
man page.
13.9. Log file directories
The following table provides an overview of selected log directories on Foreman server:
Log file directory | Description of log file content |
---|---|
|
Subscription management |
|
Installer |
|
Foreman maintain |
|
Foreman proxy |
|
Foreman |
|
Apache HTTP server |
|
Various other log messages |
|
Puppet |
|
Candlepin web service logs |
13.10. System journal metadata
The following table lists metadata that the journald
service uses in Foreman.
You can use this metadata to filter your queries.
- AUDIT_ACTION
-
Audit action performed
Example: Create, update, or delete
- AUDIT_TYPE
-
Audit resource type
Example: Host, Subnet, or ContentView
- AUDIT_ID
-
Audit resource database ID as a number
- AUDIT_ATTRIBUTE
-
Audit resource field or an updated database column
- AUDIT_FIELD_OLD
-
Old audit value of an update action
- AUDIT_FIELD_NEW
-
New audit value of an update action
- AUDIT_ID
-
Record database ID of the audit subject
- AUDIT_ATTRIBUTE
-
Attribute name or column on which an action was performed
Example: Name or description
- EXCEPTION_MESSAGE
-
Exception message when error is logged
- EXCEPTION_CLASS
-
Exception Ruby class when error is logged
- EXCEPTION_BACKTRACE
-
Exception backtrace as a multiline string when error is logged
- LOC_ID
-
Location database ID
- LOC_NAME
-
Location name
- LOC_LABEL
-
Location label
- LOGGER
-
Logger name
To see the current list of loggers enabled by default, enter this command:
# awk '/add_loggers/,/^$/' /usr/share/foreman/config/application.rb
- ORG_ID
-
Organization database ID
- ORG_NAME
-
Organization name
- ORG_LABEL
-
Organization label
- REMOTE_IP
-
Remote IP address of a client
- REQUEST
-
Request ID generated by the Action Dispatch module
- SESSION
-
Random ID generated per session or a request for a sessionless request
- TEMPLATE_NAME
-
Template name
- TEMPLATE_DIGEST
-
Digest (SHA256) of rendered template contents
- TEMPLATE_HOST_NAME
-
Host name for a rendered template if present
- TEMPLATE_HOST_ID
-
Host database ID for a rendered template if present
- USER_LOGIN
-
User login name
14. Monitoring resources
The following chapter details how to configure monitoring and reporting for managed systems. This includes host configuration, content views, compliance, registered hosts, promotions, and synchronization.
14.1. Using the Foreman content dashboard
The Foreman content dashboard contains various widgets which provide an overview of the host configuration, content views, compliance reports, 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:
- Host Configuration Status
-
An overview of the configuration states and the number of hosts associated with it during the last reporting interval. The following table shows the descriptions of the possible configuration states.
Table 4. Host configuration states Icon State Description Hosts that had performed modifications without error
Host that successfully performed modifications during the last reporting interval.
Hosts in error state
Hosts on which an error was detected during the last reporting interval.
Good host reports in the last 35 minutes
Hosts without error that did not perform any modifications in the last 35 minutes.
Hosts that had pending changes
Hosts on which some resources would be applied but Puppet was configured to run in the
noop
mode.Out of sync hosts
Hosts that were not synchronized and the report was not received during the last reporting interval.
Hosts with no reports
Hosts for which no reports were collected during the last reporting interval.
Hosts with alerts disabled
Hosts which are not being monitored.
Click the particular configuration status to view hosts associated with it.
- Host Configuration Chart
-
A pie chart shows the proportion of the configuration status and the percentage of all hosts associated with it.
- Latest Events
-
A list of messages produced by hosts including administration information, product changes, and any errors.
Monitor this section for global notifications sent to all users and to detect any unusual activity or errors.
- Run Distribution (last 30 minutes)
-
A graph shows the distribution of the running Puppet agents during the last puppet interval which is 30 minutes by default. In this case, each column represents a number of reports received from clients during 3 minutes.
- New Hosts
-
A list of the recently created hosts. Click the host for more details.
- Task Status
-
A summary of all current tasks, grouped by their state and result. Click the number to see the list of corresponding tasks.
- Latest Warning/Error Tasks
-
A list of the latest tasks that have been stopped due to a warning or error. Click a task to see more details.
- Discovered Hosts
-
A list of all bare-metal hosts detected on the provisioning network by the Discovery plugin.
- Latest Errata
-
A list of all errata available for hosts registered to Foreman.
- Content Views
-
A list of all content views in Foreman and their publish status.
- Sync Overview
-
An overview of all products or repositories enabled in Foreman and their synchronization status. All products that are in the queue for synchronization, are unsynchronized or have been previously synchronized are listed in this section.
- Host Collections
-
A list of all host collections in Foreman and their status, including the number of content hosts in each host collection.
- Virt-who Configuration Status
-
An overview of the status of reports received from the
virt-who
daemon running on hosts in the environment. The following table shows the possible states.Table 5. virt-who configuration states State Description No Reports
No report has been received because either an error occurred during the virt-who configuration deployment, or the configuration has not been deployed yet, or virt-who cannot connect to Foreman during the scheduled interval.
No Change
No report has been received because hypervisor did not detect any changes on the virtual machines, or virt-who failed to upload the reports during the scheduled interval. If you added a virtual machine but the configuration is in the No Change state, check that virt-who is running.
OK
The report has been received without any errors during the scheduled interval.
Total Configurations
A total number of virt-who configurations.
Click the configuration status to see all configurations in this state.
The widget also lists the three latest configurations in the No Change state under Latest Configurations Without Change.
- Latest Compliance Reports
-
A list of the latest compliance reports. Each compliance report shows a number of rules passed (P), failed (F), or othered (O). Click the host for the detailed compliance report. Click the policy for more details on that policy.
- Compliance Reports Breakdown
-
A pie chart shows the distribution of compliance reports according to their status.
- Red Hat Insights Actions
-
Red Hat Insights is a tool embedded in Foreman that checks the environment and suggests actions you can take. The actions are divided into 4 categories: Availability, Stability, Performance, and Security.
- Red Hat Insights Risk Summary
-
A table shows the distribution of the actions according to the risk levels. Risk level represents how critical the action is and how likely it is to cause an actual issue. The possible risk levels are: Low, Medium, High, and Critical.
NoteIt is not possible to change the date format displayed in the Foreman web UI.
14.1.1. Managing tasks
Foreman keeps a complete log of all planned or performed tasks, such as repositories synchronised, errata applied, and content views published. To review the log, navigate to Monitor > Foreman Tasks > Tasks.
In the Task window, you can search for specific tasks, view their status, details, and elapsed time since they started. You can also cancel and resume one or more tasks.
The tasks are managed using the Dynflow engine. Remote tasks have a timeout which can be adjusted as needed.
-
In the Foreman web UI, navigate to Administer > Settings.
-
Enter %_timeout in the search box and click Search. The search should return four settings, including a description.
-
In the Value column, click the icon next to a number to edit it.
-
Enter the desired value in seconds, and click Save.
Note
|
Adjusting the %_finish_timeout values might help in case of low bandwidth. Adjusting the %_accept_timeout values might help in case of high latency. |
When a task is initialized, any back-end service that will be used in the task, such as Candlepin or Pulp, will be checked for correct functioning. If the check fails, you will receive an error similar to the following one:
There was an issue with the backend service candlepin: Connection refused – connect(2).
If the back-end service checking feature turns out to be causing any trouble, it can be disabled as follows.
-
In the Foreman web UI, navigate to Administer > Settings.
-
Enter check_services_before_actions in the search box and click Search.
-
In the Value column, click the icon to edit the value.
-
From the drop-down menu, select false.
-
Click Save.
14.2. Configuring RSS notifications
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.
-
In the Foreman web UI, navigate to Administer > Settings and select the Notifications tab.
-
In the RSS URL row, click the edit icon in the Value column and type the required URL.
-
In the RSS enable row, click the edit icon in the Value column to enable or disable this feature.
14.3. Monitoring Foreman server
Audit records list the changes made by all users on Foreman. This information can be used for maintenance and troubleshooting.
-
In the Foreman web UI, navigate to Monitor > Audits to view the audit records.
-
To obtain a list of all the audit attributes, use the following command:
# foreman-rake audits:list_attributes
14.4. Monitoring Smart Proxy server
The following section shows how to use the Foreman web UI to find Smart Proxy information valuable for maintenance and troubleshooting.
14.4.1. Viewing general Smart Proxy information
In the Foreman web UI, navigate to Infrastructure > Smart Proxies to view a table of Smart Proxy servers registered to Foreman server. The information contained in the table answers the following questions:
- Is Smart Proxy server running?
-
This is indicated by a green icon in the Status column. A red icon indicates an inactive Smart Proxy, use the
service foreman-proxy restart
command on Smart Proxy server to activate it. - What services are enabled on Smart Proxy server?
-
In the Features column you can verify if Smart Proxy for example provides a DHCP service or acts as a Pulp mirror. Smart Proxy features can be enabled during installation or configured in addition. For more information, see Installing Smart Proxy server.
- What organizations and locations is Smart Proxy server assigned to?
-
A Smart Proxy server can be assigned to multiple organizations and locations, but only Smart Proxies belonging to the currently selected organization are displayed. To list all Smart Proxies, select Any Organization from the context menu in the top left corner.
After changing the Smart Proxy configuration, select Refresh from the drop-down menu in the Actions column to ensure the Smart Proxy table is up to date.
Click the Smart Proxy name to view further details. At the Overview tab, you can find the same information as in the Smart Proxy table. In addition, you can answer to the following questions:
- Which hosts are managed by Smart Proxy server?
-
The number of associated hosts is displayed next to the Hosts managed label. Click the number to view the details of associated hosts.
- How much storage space is available on Smart Proxy server?
-
The amount of storage space occupied by the Pulp content in
/var/lib/pulp
is displayed. Also the remaining storage space available on the Smart Proxy can be ascertained.
14.4.2. Monitoring services
In the Foreman web UI, navigate to Infrastructure > Smart Proxies and click the name of the selected Smart Proxy. At the Services tab, you can find basic information on Smart Proxy services, such as the list of DNS domains, or the number of Pulp workers. The appearance of the page depends on what services are enabled on Smart Proxy server. Services providing more detailed status information can have dedicated tabs at the Smart Proxy page. For more information, see Monitoring Puppet.
14.4.3. Monitoring Puppet
In the Foreman web UI, navigate to Infrastructure > Smart Proxies and click the name of the selected Smart Proxy. At the Puppet tab you can find the following:
-
A summary of Puppet events, an overview of latest Puppet runs, and the synchronization status of associated hosts at the General sub-tab.
-
A list of Puppet environments at the Environments sub-tab.
At the Puppet CA tab you can find the following:
-
A certificate status overview and the number of autosign entries at the General sub-tab.
-
A table of CA certificates associated with the Smart Proxy at the Certificates sub-tab. Here you can inspect the certificate expiry data, or cancel the certificate by clicking Revoke.
-
A list of autosign entries at the Autosign entries sub-tab. Here you can create an entry by clicking New or delete one by clicking Delete.
Note
|
The Puppet and Puppet CA tabs are available only if you have Puppet enabled in your Foreman. |
-
For more information, see Enabling Puppet Integration with Foreman in Configuring hosts by using Puppet.
15. Using webhooks
A webhook is a way for a web page or web application to provide other applications with information in real time. Webhooks are only triggered after an event occurs. The request usually contains details of the event. An event triggers callbacks, such as sending an e-mail confirming a host has been provisioned. Webhooks enable you to define a call to an external API based on Foreman internal event using a fire-and-forget message exchange pattern. The application sending the request does not wait for the response, or ignores it.
Payload of a webhook is created from webhook templates. Webhook templates use the same ERB syntax as Provisioning templates. Available variables:
-
@event_name
: Name of an event. -
@webhook_id
: Unique event ID. -
@payload
: Payload data, different for each event type. To access individual fields, use@payload[:key_name]
Ruby hash syntax. -
@payload[:object]
: Database object for events triggered by database actions (create, update, delete). Not available for custom events. -
@payload[:context]
: Additional information as hash like request and session UUID, remote IP address, user, organization and location.
Because webhooks use HTTP, no new infrastructure needs be added to existing web services.
The typical use case for webhooks in Foreman is making a call to a monitoring system when a host is created or deleted.
Webhooks are useful where the action you want to perform in the external system can be achieved through its API. Where it is necessary to run additional commands or edit files, the shellhooks plugin for Smart Proxies is available. The shellhooks plugin enables you to define a shell script on the Smart Proxy that can be executed through the API.
You can use webhooks successfully without installing the shellhooks plugin.
For a list of available events, see Available webhook events.
15.1. Migrating to webhooks
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.
15.2. Installing the webhooks plugin
Use the following procedure to install the webhooks plugin. Then, you can configure Foreman server to send webhook requests.
-
Install the webhooks plugin by running the following command:
# foreman-installer --enable-foreman-plugin-webhooks
-
Optional: Install the webhooks CLI plugin:
# foreman-installer --enable-foreman-cli-webhooks
15.3. Creating a webhook template
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.
-
In the Foreman web UI, navigate to Administer > Webhook > Webhook Templates.
-
Click Clone an existing template or Create Template.
-
Enter a name for the template.
-
Use the editor to make changes to the template payload.
A webhook HTTP payload must be created using Foreman template syntax. The webhook template can use a special variable called
@object
that can represent the main object of the event.@object
can be missing in case of certain events. You can determine what data are actually available with the@payload
variable.For more information, see Template Writing Reference in Managing hosts and for available template macros and methods, visit
/templates_doc
on Foreman server. -
Optional: Enter the description and audit comment.
-
Assign organizations and locations.
-
Click Submit.
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.
- Running remote execution jobs
-
This webhook template defines a message with the ID and result of a remote execution job. The webhook which uses this template can be subscribed to events such as
Actions Remote Execution Run Host Job Succeeded
orActions Remote Execution Run Host Job Failed
.{ "text": "job invocation <%= @object.job_invocation_id %> finished with result <%= @object.task.result %>" }
- Creating users
-
This webhook template defines a message with the login and email of a created user. The webhook which uses this template should be subscribed to the
User Created
event.{ "text": "user with login <%= @object.login %> and email <%= @object.mail %> created" }
15.4. Creating a webhook
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.
-
In the Foreman web UI, navigate to Administer > Webhook > Webhooks.
-
Click Create new.
-
From the Subscribe to list, select an event.
-
Enter a Name for your webhook.
-
Enter a Target URL. Webhooks make HTTP requests to pre-configured URLs. The target URL can be a dynamic URL.
-
Click Template to select a template. Webhook templates are used to generate the body of the HTTP request to Foreman server when a webhook is triggered.
-
Enter an HTTP method.
-
Optional: If you do not want activate the webhook when you create it, uncheck the Enabled flag.
-
Click the Credentials tab.
-
Optional: If HTTP authentication is required, enter User and Password.
-
Optional: Uncheck Verify SSL if you do not want to verify the server certificate against the system certificate store or Foreman CA.
-
On the Additional tab, enter the HTTP Content Type. For example,
application/json
,application/xml
ortext/plain
on the payload you define. The application does not attempt to convert the content to match the specified content type. -
Optional: Provide HTTP headers as JSON. ERB is also allowed.
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 Server with Katello 4.13 plugin on Enterprise Linux.
15.5. Available webhook events
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.
Event name | Description | Payload |
---|---|---|
Actions Katello Content View Promote Succeeded |
A content view was successfully promoted. |
Actions::Katello::ContentView::Promote |
Actions Katello Content View Publish Succeeded |
A repository was successfully synchronized. |
Actions::Katello::ContentView::Publish |
Actions Remote Execution Run Host Job Succeeded |
A generic remote execution job succeeded for a host. This event is emitted for all Remote Execution jobs, when complete. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Errata Install Succeeded |
Install errata using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Group Install Succeeded |
Install package group using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Package Install Succeeded |
Install package using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Group Remove |
Remove package group using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Package Remove Succeeded |
Remove package using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Service Restart Succeeded |
Restart Services using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Group Update Succeeded |
Update package group using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Package Update Succeeded |
Update package using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Foreman OpenSCAP Run Scans Succeeded |
Run OpenSCAP scan. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Ansible Run Host Succeeded |
Runs an Ansible Playbook containing all the roles defined for a host. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Ansible Run Smart Proxy Upgrade Succeeded |
Upgrade Smart Proxies on given Smart Proxy servers. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Ansible Configure Cloud Connector Succeeded |
Configure Cloud Connector on given hosts. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Ansible Run Playbook Succeeded |
Run an Ansible Playbook against given hosts. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Ansible Enable Web Console Succeeded |
Run an Ansible Playbook to enable the web console on given hosts. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Puppet Run Host Succeeded |
Perform a single Puppet run. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Katello Module Stream Action Succeeded |
Perform a module stream action using the Katello interface. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Leapp Pre-upgrade Succeeded |
Upgradeability check for RHEL 7 host. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Leapp Remediation Plan Succeeded |
Run Remediation plan with Leapp. |
Actions::RemoteExecution::RunHostJob |
Actions Remote Execution Run Host Job Leapp Upgrade Succeeded |
Run Leapp upgrade job for RHEL 7 host. |
Actions::RemoteExecution::RunHostJob |
Build Entered |
A host entered the build mode. |
Custom event: |
Build Exited |
A host build mode was canceled, either it was successfully provisioned or the user canceled the build manually. |
Custom event: |
Content View Created/Updated/Destroyed |
Common database operations on a content view. |
Katello::ContentView |
Domain Created/Updated/Destroyed |
Common database operations on a domain. |
Domain |
Host Created/Updated/Destroyed |
Common database operations on a host. |
Host |
Hostgroup Created/Updated/Destroyed |
Common database operations on a hostgroup. |
Hostgroup |
Model Created/Updated/Destroyed |
Common database operations on a model. |
Model |
Status Changed |
Global host status of a host changed. |
Custom event: |
Subnet Created/Updated/Destroyed |
Common database operations on a subnet. |
Subnet |
Template Render Performed |
A report template was rendered. |
Template |
User Created/Updated/Destroyed |
Common database operations on a user. |
User |
15.6. Shellhooks
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
.
Note
|
Unlike the |
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.
15.7. Installing the shellhooks plugin
Optionally, you can install and enable the shellhooks plugin on each Smart Proxy used for shellhooks.
-
Run the following command:
# foreman-installer --enable-foreman-proxy-plugin-shellhooks
15.8. Passing arguments to shellhook script using webhooks
Use this procedure to pass arguments to a shellhook script using webhooks.
-
When creating a webhook, on the Additional tab, create HTTP headers in the following format:
{ "X-Shellhook-Arg-1": "VALUE", "X-Shellhook-Arg-2": "VALUE" }
Ensure that the headers have a valid JSON or ERB format. Only pass safe fields like database ID, name, or labels that do not include new lines or quote characters.
For more information, see Creating a webhook.
{ "X-Shellhook-Arg-1": "<%= @object.content_view_version_id %>", "X-Shellhook-Arg-2": "<%= @object.content_view_name %>" }
15.9. Passing arguments to shellhook script using curl
Use this procedure to pass arguments to a shellhook script using curl.
-
When executing a shellhook script using
curl
, create HTTP headers in the following format:"X-Shellhook-Arg-1: VALUE" "X-Shellhook-Arg-2: VALUE"
# curl -sX POST -H 'Content-Type: text/plain' \ -H "X-Shellhook-Arg-1: Version 1.0" \ -H "X-Shellhook-Arg-2: My content view" \ --data "" https://smartproxy.example.com:9090/shellhook/My_Script
15.10. Creating a shellhook to print arguments
Create a simple shellhook script that prints Hello World!
when you run a remote execution job.
-
You have the webhooks and shellhooks plugins installed. For more information, see:
-
Modify the
/var/lib/foreman-proxy/shellhooks/print_args
script to print arguments to standard error output so you can see them in the Smart Proxy logs:#!/bin/sh # # Prints all arguments to stderr # echo "$@" >&2
-
In the Foreman web UI, navigate to Administer > Webhook > Webhooks.
-
Click Create new.
-
From the Subscribe to list, select Actions Remote Execution Run Host Job Succeeded.
-
Enter a Name for your webhook.
-
In the Target URL field, enter the URL of your Smart Proxy server followed by
:9090/shellhook/print_args
:https://smartproxy.example.com:9090/shellhook/print_args
Note that
shellhook
in the URL is singular, unlike theshellhooks
directory. -
From the Template list, select Empty Payload.
-
On the Credentials tab, check Smart Proxy Authorization.
-
On the Additional tab, enter the following text in the Optional HTTP headers field:
{ "X-Shellhook-Arg-1": "Hello", "X-Shellhook-Arg-2": "World!" }
-
Click Submit. You now have successfully created a shellhook that prints "Hello World!" to Smart Proxy logs every time you a remote execution job succeeds.
-
Run a remote execution job on any host. You can use
time
as a command. For more information, see Executing a Remote Job in Managing hosts. -
Verify that the shellhook script was triggered and printed "Hello World!" to Smart Proxy server logs:
# tail /var/log/foreman-proxy/proxy.log
You should find the following lines at the end of the log:
[I] Started POST /shellhook/print_args [I] Finished POST /shellhook/print_args with 200 (0.33 ms) [I] [3520] Started task /var/lib/foreman-proxy/shellhooks/print_args\ Hello\ World\! [W] [3520] Hello World!
16. Searching and bookmarking
Foreman features powerful search functionality on most pages of the Foreman web UI. It enables you to search all kinds of resources that Foreman manages. Searches accept both free text and syntax-based queries, which can be built using extensive input prediction. Search queries can be saved as bookmarks for future reuse.
16.1. Building search queries
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.
16.1.1. Query syntax
parameter operator value
Available fields, resources to search, and the way the query is interpreted all depend on context, that is, the page where you perform the search. For example, the field "hostgroup" on the Hosts page is equivalent to the field "name" on the Host Groups page. The field type also determines available operators and accepted values.
16.1.2. Query operators
All operators that can be used between parameter and value are listed in the following table. Other symbols and special characters that might appear in a prediction-built query, such as colons, do not have special meaning and are treated as free text.
Operator | Short Name | Description | Example |
---|---|---|---|
= |
EQUALS |
Accepts numerical, temporal, or text values. For text, exact case sensitive matches are returned. |
|
!= |
NOT EQUALS |
||
~ |
LIKE |
Accepts text or temporal values. Returns case insensitive matches. Accepts the following wildcards: _ for a single character, % or * for any number of characters including zero. If no wildcard is specified, the string is treated as if surrounded by wildcards: %rhel7% |
|
!~ |
NOT LIKE |
||
> |
GREATER THAN |
Accepts numerical or temporal values. For temporal values, the operator > is interpreted as "later than", and < as "earlier than". Both operators can be combined with EQUALS: >= <= |
|
< |
LESS THAN |
||
^ |
IN |
Compares an expression against a list of values, as in SQL. Returns matches that contain or not contain the values, respectively. |
|
!^ |
NOT IN |
||
HAS or set? |
|
Returns values that are present or not present, respectively. |
|
NOT HAS or null? |
|
Simple queries that follow the described syntax can be combined into more complex ones using logical operators AND, OR, and NOT. Alternative notations of the operators are also accepted:
Operator | Alternative Notations | Example | ||
---|---|---|---|---|
and |
& |
&& |
<whitespace> |
|
or |
| |
|| |
|
|
not |
– |
! |
|
|
16.1.3. Query values
- Text Values
-
Text containing whitespaces must be enclosed in quotes. A whitespace is otherwise interpreted as the AND operator.
Examples:
hostgroup = "Web servers"
The search will return hosts with assigned host group named "Web servers".
hostgroup = Web servers
The search will return hosts in the host group Web with any field matching %servers%.
- Temporal Values
-
Many date and time formats are accepted, including the following:
-
"10 January 2017"
-
"10 Jan 2017"
-
10-January-2017
-
10/January/2017
-
"January 10, 2017"
-
Today, Yesterday, and the like.
-
Warning
|
Avoid ambiguous date formats, such as 02/10/2017 or 10-02-2017. |
16.2. 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.
Note
|
Multi-word queries must be enclosed in quotes, otherwise the whitespace is interpreted as the AND operator. |
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.
16.3. Managing bookmarks
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.
16.3.1. Creating bookmarks
This section details how to save a search query as a bookmark. You must save the search query on the relevant page to create a bookmark for that page, for example, saving a host related search query on the Hosts page.
-
In the Foreman web UI, navigate to the page where you want to create a bookmark.
-
In the Search field, enter the search query you want to save.
-
Select the arrow to the right of the Search button and then select Bookmark this search.
-
In the Name field, enter a name for the new bookmark.
-
In the Search query field, ensure your search query is correct.
-
Ensure the Public checkbox is set correctly:
-
Select the Public checkbox to set the bookmark as public and visible to all users.
-
Clear the Public checkbox to set the bookmark as private and only visible to the user who created it.
-
-
Click Submit.
To confirm the creation, either select the arrow to the right of the Search button to display the list of bookmarks, or navigate to Administer > Bookmarks and then check the Bookmarks list for the name of the bookmark.
16.3.2. Deleting bookmarks
You can delete bookmarks on the Bookmarks page.
-
In the Foreman web UI, navigate to Administer > Bookmarks.
-
On the Bookmarks page, click Delete for the Bookmark you want to delete.
-
When the confirmation window opens, click OK to confirm the deletion.
To confirm the deletion, check the Bookmarks list for the name of the bookmark.
Appendix A: Administration settings
This section contains information about settings that you can edit in the Foreman web UI by navigating to Administer > Settings.
A.1. General settings
Setting | Default Value | Description |
---|---|---|
Administrator email address |
The default administrator email address |
|
Foreman URL |
URL where your Foreman instance is reachable. See also Provisioning > Unattended URL. |
|
Entries per page |
20 |
Number of records shown per page in Foreman |
Fix DB cache |
No |
Foreman maintains a cache of permissions and roles.
When set to |
DB pending seed |
No |
Should the |
Smart Proxy request timeout |
60 |
Open and read timeout for HTTP requests from Foreman to Smart Proxy (in seconds). |
Login page footer text |
Text to be shown in the login-page footer. |
|
HTTP(S) proxy |
Set a proxy for outgoing HTTP(S) connections from the Foreman product. System-wide proxies must be configured at the operating system level. |
|
HTTP(S) proxy except hosts |
[] |
Set hostnames to which requests are not to be proxied. Requests to the local host are excluded by default. |
Show Experimental Labs |
No |
Whether or not to show a menu to access experimental lab features (requires reload of page). |
Display FQDN for hosts |
Yes |
If set to |
Out of sync interval |
30 |
Hosts report periodically, and if the time between reports exceeds this duration in minutes, hosts are considered out of sync.
You can override this on your hosts by adding the |
Foreman UUID |
Foreman instance ID. Uniquely identifies a Foreman instance. |
|
Default language |
The UI for new users uses this language. |
|
Default timezone |
The timezone to use for new users. |
|
Instance title |
The instance title is shown on the top navigation bar (requires a page reload). |
|
Saved audits interval |
Duration in days to preserve audit data. Leave empty to disable the audits cleanup. |
|
New host details UI |
Yes |
Foreman loads the new UI for host details. |
A.2. Task settings
Setting | Default Value | Description |
---|---|---|
Sync task timeout |
120 |
Number of seconds to wait for a synchronous task to finish before an exception is raised. |
Enable dynflow console |
Yes |
Enable the dynflow console ( |
Require auth for dynflow console |
Yes |
The user must be authenticated as having administrative rights before accessing the dynflow console. |
Proxy action retry count |
4 |
Number of attempts permitted to start a task on the Smart Proxy before failing. |
Proxy action retry interval |
15 |
Time in seconds between retries. |
Allow proxy batch tasks |
Yes |
Allow triggering tasks on the Smart Proxy in batches. |
Proxy tasks batch size |
100 |
Number of tasks included in one request to the Smart Proxy if |
Tasks troubleshooting URL |
URL pointing to the task troubleshooting documentation.
It should contain a |
|
Polling intervals multiplier |
1 |
Polling multiplier used to multiply the default polling intervals. You can use this to prevent polling too frequently for long running tasks. |
A.3. Template sync settings
Setting | Default Value | Description |
---|---|---|
Associate |
New |
Associate templates with OS, organization and location. |
Branch |
Default branch in Git repo. |
|
Commit message |
Templates export made by a Foreman user |
Custom commit message for exported templates. |
Dirname |
/ |
The directory within the Git repo containing the templates. |
Filter |
Import or export of names matching this regex. Case-insensitive. Snippets are not filtered. |
|
Force import |
No |
If set to |
Lock templates |
Keep, do not lock new |
How to handle lock for imported templates. |
Metadata export mode |
Refresh |
Default metadata export mode. Possible options:
|
Negate |
No |
Negate the filter for import or export. |
Prefix |
A string added as a prefix to imported templates. |
|
Repo |
Target path from where to import or export templates. Different protocols can be used, for example:
When exporting to |
|
Verbosity |
No |
Choose verbosity for Rake task importing templates. |
A.4. Discovered settings
Setting | Default Value | Description |
---|---|---|
Discovery location |
Indicates the default location to place discovered hosts in. |
|
Discovery organization |
Indicates the default organization to which discovered hosts are added. |
|
Interface fact |
discovery_bootif |
Fact name to use for primary interface detection. |
Create bond interfaces |
No |
Automatically create a bond interface if another interface is detected on the same VLAN using LLDP. |
Clean all facts |
No |
Clean all reported facts (except discovery facts) during provisioning. |
Hostname facts |
discovery_bootif |
List of facts to use for the hostname (comma separated, first wins). |
Auto provisioning |
No |
Use the provisioning rules to automatically provision newly discovered hosts. |
Reboot |
Yes |
Automatically reboot or kexec discovered hosts during provisioning. |
Hostname prefix |
mac |
The default prefix to use for the hostname. Must start with a letter. |
Fact columns |
Extra facter columns to show in host lists (comma separated). |
|
Highlighted facts |
Regex to organize facts for highlights section – e.g. |
|
Storage facts |
Regex to organize facts for the storage section. |
|
Software facts |
Regex to organize facts for the software section. |
|
Hardware facts |
Regex to organize facts for the hardware section. |
|
Network facts |
Regex to organize facts for the network section. |
|
IPMI facts |
Regex to organize facts for the Intelligent Platform Management Interface (IPMI) section. |
|
Lock PXE |
No |
Automatically generate a Preboot Execution Environment (PXE) configuration to pin a newly discovered host to discovery. |
Locked PXELinux template name |
pxelinux_discovery |
PXELinux template to be used when pinning a host to discovery. |
Locked PXEGrub template name |
pxegrub_discovery |
PXEGrub template to be used when pinning a host to discovery. |
Locked PXEGrub2 template name |
pxegrub2_discovery |
PXEGrub2 template to be used when pinning a host to discovery. |
Force DNS |
Yes |
Force the creation of DNS entries when provisioning a discovered host. |
Error on existing NIC |
No |
Do not permit to discover an existing host matching the MAC of a provisioning Network Interface Card (NIC) (errors out early). |
Type of name generator |
Fact + prefix |
Discovery hostname naming pattern. |
Prefer IPv6 |
No |
Prefer IPv6 to IPv4 when calling discovered nodes. |
A.5. Boot disk settings
Setting | Default Value | Description |
---|---|---|
iPXE directory |
|
Path to directory containing iPXE images. |
ISOLINUX directory |
|
Path to directory containing ISOLINUX images. |
SYSLINUX directory |
|
Path to directory containing SYSLINUX images. |
Grub2 directory |
|
Path to directory containing |
Host image template |
Boot disk iPXE - host |
iPXE template to use for host-specific boot disks. |
Generic image template |
Boot disk iPXE - generic host |
iPXE template to use for generic host boot disks. |
Generic Grub2 EFI image template |
Boot disk Grub2 EFI - generic host |
Grub2 template to use for generic Extensible Firmware Interface (EFI) host boot disks. |
ISO generation command |
genisoimage |
Command to generate ISO image, use |
Installation media caching |
Yes |
Installation media files are cached for full host images. |
Allowed bootdisk types |
[generic, host, full_host, subnet] |
List of permitted bootdisk types. Leave blank to disable it. |
A.6. Content settings
Setting | Default Value | Description |
---|---|---|
Default HTTP Proxy |
Default HTTP Proxy for syncing content. |
|
CDN SSL version |
SSL version used to communicate with the CDN. |
|
Default synced OS provisioning template |
Kickstart default |
Default provisioning template for operating systems created from synced content. |
Default synced OS finish template |
Kickstart default finish |
Default finish template for new operating systems created from synced content. |
Default synced OS user-data |
Kickstart default user data |
Default user data for new operating systems created from synced content. |
Default synced OS PXELinux template |
Kickstart default PXELinux |
Default PXELinux template for new operating systems created from synced content. |
Default synced OS PXEGrub template |
Kickstart default PXEGrub |
Default PXEGrub template for new operating systems created from synced content. |
Default synced OS PXEGrub2 template |
Kickstart default PXEGrub2 |
Default PXEGrub2 template for new operating systems created from synced content. |
Default synced OS iPXE template |
Kickstart default iPXE |
Default iPXE template for new operating systems created from synced content. |
Default synced OS partition table |
Kickstart default |
Default partitioning table for new operating systems created from synced content. |
Default synced OS kexec template |
Discovery Foreman community kexec |
Default kexec template for new operating systems created from synced content. |
Default synced OS Atomic template |
Atomic Kickstart default |
Default provisioning template for new atomic operating systems created from synced content. |
Manifest refresh timeout |
1200 |
Timeout when refreshing a manifest (in seconds). |
Subscription connection enabled |
Yes |
Can communicate with the Foreman community Portal for subscriptions. |
Installable errata from Content View |
No |
Calculate errata host status based only on errata in a host’s content view and lifecycle environment. |
Restrict Composite Content View promotion |
No |
If this is enabled, a composite content view cannot be published or promoted, unless the content view versions that it includes exist in the target environment. |
Check services before actions |
Yes |
Check the status of backend services such as pulp and candlepin before performing actions? |
Batch size to sync repositories in |
100 |
How many repositories should be synced concurrently on a Smart Proxy. A smaller number may lead to longer sync times. A larger number will increase dynflow load. |
Sync Smart Proxies after Content View promotion |
Yes |
Whether or not to auto sync Smart Proxies after a content view promotion. |
Default Custom Repository download policy |
|
Default download policy for custom repositories.
Either |
Default Foreman community Repository download policy |
|
Default download policy for enabled Foreman community repositories.
Either |
Default Smart Proxy download policy |
|
Default download policy for Smart Proxy syncs.
Either |
Pulp export destination filepath |
|
On-disk location for exported repositories. |
Pulp 3 export destination filepath |
|
On-disk location for Pulp 3 exported repositories. |
Pulp client key |
|
Path for SSL key used for Pulp server authentication. |
Pulp client cert |
|
Path for SSL certificate used for Pulp server authentication. |
Sync Connection Timeout |
300 |
Total timeout in seconds for connections when syncing. |
Delete Host upon unregister |
No |
When unregistering a host using subscription-manager, also delete the host record. Managed resources linked to the host such as virtual machines and DNS records might also be deleted. |
Subscription manager name registration fact |
When registering a host using subscription-manager, force use the specified fact for the host name (in the form of |
|
Subscription manager name registration fact strict matching |
No |
If this is enabled, and |
Default Location subscribed hosts |
Default Location |
Default location where new subscribed hosts are stored after registration. |
Expire soon days |
120 |
The number of days remaining in a subscription before you are reminded about renewing it. |
Content View Dependency Solving Default |
No |
The default dependency solving value for new content views. |
Host Duplicate DMI UUIDs |
[] |
If hosts fail to register because of duplicate Desktop Management Interface (DMI) UUIDs, add their comma-separated values here. Subsequent registrations generate a unique DMI UUID for the affected hosts. |
Host Profile Assume |
Yes |
Enable new host registrations to assume registered profiles with matching hostname as long as the registering DMI UUID is not used by another host. |
Host Profile Can Change In Build |
No |
Enable host registrations to bypass Host Profile Assume as long as the host is in build mode. |
Host Can Re-Register Only In Build |
No |
Enable hosts to re-register only when they are in build mode. |
Host Tasks Workers Pool Size |
5 |
Number of workers in the pool to handle the execution of host-related tasks. When set to 0, the default queue is used. Restart of the dynflowd/foreman-tasks service is required. |
Applicability Batch Size |
50 |
Number of host applicability calculations to process per task. |
Autosearch |
Yes |
For pages that support it, automatically perform the search while typing in search input. |
Autosearch delay |
500 |
If Autosearch is enabled, delay in milliseconds before executing searches while typing. |
Pulp bulk load size |
2000 |
The number of items fetched from a single paged Pulp API call. |
Upload profiles without Dynflow |
Yes |
Enable Katello to update host installed packages, enabled repositories, and module inventory directly instead of wrapped in Dynflow tasks (try turning off if Puma processes are using too much memory). |
Orphaned Content Protection Time |
1440 |
Time in minutes to consider orphan content as orphaned. |
Prefer registered through proxy for remote execution |
No |
Prefer using a proxy to which a host is registered when using remote execution. |
Allow deleting repositories in published content views |
Yes |
Enable removal of repositories that the user has previously published in one or more content view versions. |
A.7. Authentication settings
Setting | Default Value | Description |
---|---|---|
OAuth active |
Yes |
Foreman will use OAuth for API authorization. |
OAuth consumer key |
***** |
OAuth consumer key. |
OAuth consumer secret |
***** |
OAuth consumer secret. |
OAuth map users |
No |
Foreman maps users by username in the request-header. If this is disabled, OAuth requests have administrator rights. |
Failed login attempts limit |
30 |
Foreman blocks user logins from an incoming IP address for 5 minutes after the specified number of failed login attempts. Set to 0 to disable brute force protection. |
Restrict registered Smart Proxies |
Yes |
Only known Smart Proxies can access features that use Smart Proxy authentication. |
Trusted hosts |
[] |
List of hostnames, IPv4, IPv6 addresses or subnets to be trusted in addition to Smart Proxies for access to fact/report importers and ENC output. |
SSL certificate |
|
SSL Certificate path that Foreman uses to communicate with its proxies. |
SSL CA file |
|
SSL CA file path that Foreman uses to communicate with its proxies. |
SSL private key |
|
SSL Private Key path that Foreman uses to communicate with its proxies. |
SSL client DN env |
HTTP_SSL_CLIENT_S_DN |
Environment variable containing the subject DN from a client SSL certificate. |
SSL client verify env |
HTTP_SSL_CLIENT_VERIFY |
Environment variable containing the verification status of a client SSL certificate. |
SSL client cert env |
HTTP_SSL_CLIENT_CERT |
Environment variable containing a client’s SSL certificate. |
Server CA file |
SSL CA file path used in templates to verify the connection to Foreman. |
|
Websockets SSL key |
|
Private key file path that Foreman uses to encrypt websockets. |
Websockets SSL certificate |
|
Certificate path that Foreman uses to encrypt websockets. |
Websockets encryption |
Yes |
VNC/SPICE websocket proxy console access encryption ( |
Login delegation logout URL |
Redirect your users to this URL on logout. Enable Authorize login delegation also. |
|
Authorize login delegation auth source user autocreate |
External |
Name of the external authentication source where unknown externally authenticated users (see Authorize login delegation) are created. Empty means no autocreation. |
Authorize login delegation |
No |
Authorize login delegation with |
Authorize login delegation API |
No |
Authorize login delegation with |
Idle timeout |
60 |
Log out idle users after the specified number of minutes. |
BCrypt password cost |
9 |
Cost value of bcrypt password hash function for internal auth-sources (4 – 30). A higher value is safer but verification is slower, particularly for stateless API calls and UI logins. A password change is needed to affect existing passwords. |
BMC credentials access |
Yes |
Permits access to BMC interface passwords through ENC YAML output and in templates. |
OIDC JWKs URL |
OpenID Connect JSON Web Key Set (JWKS) URL.
Typically |
|
OIDC Audience |
[] |
Name of the OpenID Connect Audience that is being used for authentication. In the case of Keycloak this is the Client ID. |
OIDC Issuer |
The issuer claim identifies the principal that issued the JSON Web tokens (JWT), which exists at a |
|
OIDC Algorithm |
The algorithm used to encode the JWT in the OpenID provider. |
A.8. Email settings
Setting | Default Value | Description |
---|---|---|
Email reply address |
Email reply address for emails that Foreman is sending. |
|
Email subject prefix |
Prefix to add to all outgoing email. |
|
Send welcome email |
No |
Send a welcome email including username and URL to new users. |
Delivery method |
Sendmail |
Method used to deliver email. |
SMTP enable StartTLS auto |
Yes |
SMTP automatically enables StartTLS. |
SMTP OpenSSL verify mode |
Default verification mode |
When using TLS, you can set how OpenSSL checks the certificate. |
SMTP address |
SMTP address to connect to. |
|
SMTP port |
25 |
SMTP port to connect to. |
SMTP HELO/EHLO domain |
HELO/EHLO domain. |
|
SMTP username |
Username to use to authenticate, if required. |
|
SMTP password |
***** |
Password to use to authenticate, if required. |
SMTP authentication |
none |
Specify authentication type, if required. |
Sendmail arguments |
-i |
Specify additional options to sendmail. Only used when the delivery method is set to sendmail. |
Sendmail location |
|
The location of the sendmail executable. Only used when the delivery method is set to sendmail. |
A.9. Notifications settings
Setting | Default Value | Description |
---|---|---|
RSS enable |
Yes |
Pull RSS notifications. |
RSS URL |
URL from which to fetch RSS notifications. |
A.10. Provisioning settings
Setting | Default Value | Description |
---|---|---|
Host owner |
Default owner on provisioned hosts, if empty Foreman uses the current user. |
|
Root password |
***** |
Default encrypted root password on provisioned hosts. |
Unattended URL |
URL that hosts retrieve templates from during the build. When it starts with https, unattended, or userdata, controllers cannot be accessed using HTTP. |
|
Safemode rendering |
|
Enables safe mode rendering of provisioning templates.
The default and recommended option When set to |
Access unattended without build |
No |
Enable access to unattended URLs without build mode being used. |
Query local nameservers |
No |
Foreman queries the locally configured resolver instead of the SOA/NS authorities. |
Installation token lifetime |
360 |
Time in minutes that installation tokens should be valid for. Set to 0 to disable the token. |
SSH timeout |
120 |
Time in seconds before SSH provisioning times out. |
Libvirt default console address |
0.0.0.0 |
The IP address that should be used for the console listen address when provisioning new virtual machines using libvirt. |
Update IP from built request |
No |
Foreman updates the host IP with the IP that made the build request. |
Use short name for VMs |
No |
Foreman uses the short hostname instead of the FQDN for creating new virtual machines. |
DNS timeout |
[5, 10, 15, 20] |
List of timeouts (in seconds) for DNS lookup attempts such as the |
Clean up failed deployment |
Yes |
Foreman deletes the virtual machine if the provisioning script ends with a non-zero exit code. |
Type of name generator |
|
Specifies the method used to generate a hostname when creating a new host. The default The The |
Default PXE global template entry |
Default PXE menu item in a global template – |
|
Default PXE local template entry |
Default PXE menu item in local template – |
|
iPXE intermediate script |
iPXE intermediate script |
Intermediate iPXE script for unattended installations. |
Destroy associated VM on host delete |
No |
Destroy associated VM on host delete. When enabled, VMs linked to hosts are deleted on Compute Resource. When disabled, VMs are unlinked when the host is deleted, meaning they remain on Compute Resource and can be re-associated or imported back to Foreman again. This does not automatically power off the VM |
Maximum structured facts |
100 |
Maximum number of keys in structured subtree, statistics stored in |
Default Global registration template |
Global Registration |
Global Registration template. |
Default 'Host initial configuration' template |
Linux host_init_config default |
Default 'Host initial configuration' template, automatically assigned when a new operating system is created. |
CoreOS Transpiler Command |
[ |
Full path to CoreOS transpiler (ct) with arguments as an comma-separated array |
Fedora CoreOS Transpiler Command |
|
Full path to Fedora CoreOS transpiler (fcct) with arguments as an comma-separated array |
Global default PXEGrub2 template |
PXEGrub2 global default |
Global default PXEGrub2 template. This template is deployed to all configured TFTP servers. It is not affected by upgrades. |
Global default PXELinux template |
PXELinux global default |
Global default PXELinux template. This template is deployed to all configured TFTP servers. It is not affected by upgrades. |
Global default PXEGrub template |
PXEGrub global default |
Global default PXEGrub template. This template is deployed to all configured TFTP servers. It is not affected by upgrades. |
Global default iPXE template |
iPXE global default |
Global default iPXE template. This template is deployed to all configured TFTP servers. It is not affected by upgrades. |
Local boot PXEGrub2 template |
PXEGrub2 default local boot |
Template that is selected as PXEGrub2 default for local boot. |
Local boot PXELinux template |
PXELinux default local boot |
Template that is selected as PXELinux default for local boot. |
Local boot PXEGrub template |
PXEGrub default local boot |
Template that is selected as PXEGrub default for local boot. |
Local boot iPXE template |
iPXE default local boot |
Template that is selected as iPXE default for local boot. |
Manage PuppetCA |
Yes |
Foreman automates certificate signing upon provision of a new host. |
Use UUID for certificates |
No |
Foreman uses random UUIDs for certificate signing instead of hostnames. |
A.11. Facts settings
Setting | Default Value | Description |
---|---|---|
Create new host when facts are uploaded |
Yes |
Foreman creates the host when new facts are received. |
Location fact |
foreman_location |
Hosts created after a Puppet run are placed in the location specified by this fact. |
Organization fact |
foreman_organization |
Hosts created after a Puppet run are placed in the organization specified by this fact. The content of this fact should be the full label of the organization. |
Default location |
Default Location |
Hosts created after a Puppet run that did not send a location fact are placed in this location. |
Default organization |
Default Organization |
Hosts created after a Puppet run that did not send an organization fact are placed in this organization. |
Update hostgroup from facts |
Yes |
Foreman updates a host’s hostgroup from its facts. |
Ignore facts for operating system |
No |
Stop updating operating system from facts. |
Ignore facts for domain |
No |
Stop updating domain values from facts. |
Update subnets from facts |
None |
Foreman updates a host’s subnet from its facts. |
Ignore interfaces facts for provisioning |
No |
Stop updating IP and MAC address values from facts (affects all interfaces). |
Ignore interfaces with matching identifier |
[ |
Skip creating or updating host network interfaces objects with identifiers matching these values from incoming facts.
You can use a * wildcard to match identifiers with indexes, e.g. |
Exclude pattern for facts stored in Foreman |
[ |
Exclude pattern for all types of imported facts (Puppet, Ansible, rhsm).
Those facts are not stored in the foreman database.
You can use a * wildcard to match names with indexes, e.g. |
Default Puppet environment |
production |
Foreman defaults to this puppet environment if it cannot auto detect one. |
ENC environment |
Yes |
Foreman explicitly sets the puppet environment in the ENC yaml output.
This avoids conflicts between the environment in |
Update environment from facts |
No |
Foreman updates a host’s environment from its facts. |
A.12. Configuration management settings
Setting | Default Value | Description |
---|---|---|
Create new host when report is uploaded |
Yes |
Foreman creates the host when a report is received. |
Matchers inheritance |
Yes |
Foreman matchers are inherited by children when evaluating smart class parameters for hostgroups, organizations, and locations. |
Default parameters lookup path |
[ |
Foreman evaluates host smart class parameters in this order by default. |
Interpolate ERB in parameters |
Yes |
Foreman parses ERB in parameters value in the ENC output. |
Always show configuration status |
No |
All hosts show a configuration status even when a Puppet Smart Proxy is not assigned. |
Puppet interval |
35 |
Duration in minutes after servers reporting using Puppet are classed as out of sync. |
Puppet out of sync disabled |
No |
Disable host configuration status turning to out of sync for Puppet after report does not arrive within configured interval. |
A.13. Remote execution settings
Setting | Default Value | Description |
---|---|---|
Fallback to Any Proxy |
No |
Search the host for any proxy with Remote Execution. This is useful when the host has no subnet or the subnet does not have an execution proxy. |
Enable Global Proxy |
Yes |
Search for Remote Execution proxy outside of the proxies assigned to the host. The search is limited to the host’s organization and location. |
SSH User |
root |
Default user to use for SSH.
You can override per host by setting the |
Effective User |
root |
Default user to use for executing the script. If the user differs from the SSH user, su or sudo is used to switch the user. |
Effective User Method |
sudo |
The command used to switch to the effective user.
One of [ |
Effective user password |
***** |
Effective user password. See Effective User. |
Sync Job Templates |
Yes |
Whether to sync templates from disk when running |
SSH Port |
22 |
Port to use for SSH communication.
Default port 22.
You can override per host by setting the |
Connect by IP |
No |
Whether the IP addresses on host interfaces are preferred over the FQDN.
It is useful when the DNS is not resolving the FQDNs properly.
You can override this per host by setting the |
Prefer IPv6 over IPv4 |
No |
When connecting using an IP address, are IPv6 addresses preferred?
If no IPv6 address is set, it falls back to IPv4 automatically.
You can override this per host by setting the |
Default SSH password |
***** |
Default password to use for SSH.
You can override per host by setting the |
Default SSH key passphrase |
***** |
Default key passphrase to use for SSH.
You can override per host by setting the |
Workers pool size |
5 |
Number of workers in the pool to handle the execution of the remote execution jobs.
Restart of the |
Cleanup working directories |
Yes |
Whether working directories are removed after task completion.
You can override this per host by setting the |
Cockpit URL |
Where to find the Cockpit instance for the Web Console button. By default, no button is shown. |
|
Form Job Template |
Run Command - SSH Default |
Choose a job template that is pre-selected in job invocation form. |
Job Invocation Report Template |
Jobs - Invocation report template |
Select a report template used for generating a report for a particular remote execution job. |
Time to pickup |
86400 |
Time in seconds within which the host has to pick up a job. If the job is not picked up within this limit, the job will be cancelled. Applies only to pull-mqtt based jobs. Defaults to one day. |
A.14. Ansible settings
Setting | Default Value | Description |
---|---|---|
Private Key Path |
Use this to supply a path to an SSH Private Key that Ansible uses instead of a password.
Override with the |
|
Connection type |
ssh |
Use this connection type by default when running Ansible Playbooks.
You can override this on hosts by adding the |
WinRM cert Validation |
validate |
Enable or disable WinRM server certificate validation when running Ansible Playbooks.
You can override this on hosts by adding the |
Default verbosity level |
Disabled |
Foreman adds this level of verbosity for additional debugging output when running Ansible Playbooks. |
Post-provision timeout |
360 |
Timeout (in seconds) to set when Foreman triggers an Ansible roles task playbook after a host is fully provisioned. Set this to the maximum time you expect a host to take until it is ready after a reboot. |
Ansible report timeout |
30 |
Timeout (in minutes) when hosts should have reported. |
Ansible out of sync disabled |
No |
Disable host configuration status turning to out of sync for Ansible after a report does not arrive within the configured interval. |
Default Ansible inventory report template |
Ansible - Ansible Inventory |
Foreman uses this template to schedule the report with Ansible inventory. |
Ansible roles to ignore |
[] |
The roles to exclude when importing roles from Smart Proxy.
The expected input is comma separated values and you can use * wildcard metacharacters.
For example: |
Proxy tasks batch size for Ansible |
Number of tasks which should be sent to the Smart Proxy in one request if |