Administering Foreman

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. Logging in to Foreman

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

Procedure

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.2. Navigation Tabs in the Foreman web UI

Use the navigation tabs to browse the Foreman web UI.

Navigation Tabs	Description
Any Context	Clicking this tab changes the organization and location. If no organization or location is selected, the default organization is Any Organization and the default location is Any Location. Use this tab to change to different values.
Monitor	Provides summary dashboards and reports.
Content	Provides content management tools. This includes Content Views, Activation Keys, and Life Cycle Environments.
Hosts	Provides host inventory and provisioning configuration tools.
Configure	Provides general configuration tools and data including Host Groups and Puppet data.
Infrastructure	Provides tools on configuring how Foreman interacts with the environment.
*User Name*	Provides user administration where users can edit their personal information.
	Provides event notifications to keep administrators informed of important environment changes.
Administer	Provides advanced configuration for settings such as Users and RBAC, as well as general settings.

Navigation Tabs

Description

Any Context

Clicking this tab changes the organization and location. If no organization or location is selected, the default organization is Any Organization and the default location is Any Location. Use this tab to change to different values.

Monitor

Provides summary dashboards and reports.

Content

Provides content management tools. This includes Content Views, Activation Keys, and Life Cycle Environments.

Hosts

Provides host inventory and provisioning configuration tools.

Configure

Provides general configuration tools and data including Host Groups and Puppet data.

Infrastructure

Provides tools on configuring how Foreman interacts with the environment.

User Name

Provides user administration where users can edit their personal information.

notification bell

Provides event notifications to keep administrators informed of important environment changes.

Administer

Provides advanced configuration for settings such as Users and RBAC, as well as general settings.

1.3. Changing the Password

These steps show how to change your password.

Procedure

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 the Submit button to save your new password.

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

To Reset the Administrative User Password

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.

To Set a New Administrative User Password

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.5. Setting a Custom Message on the Login Page

Procedure

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. Managing Foreman with Ansible Collections

Foreman Ansible Collections is a set of Ansible modules that interact with the Foreman API. You can use Foreman Ansible Collections to manage and automate many aspects of Foreman.

2.1. Installing the Foreman Ansible Modules

Use this procedure to install the Foreman Ansible modules.

Procedure

Install the package using the following command:

# apt-get install ansible-collection-theforeman-foreman

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

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

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

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

Procedure

In the Foreman web UI, navigate to Administer > Users.
Click Create User.
In the Login field, enter a username for the user.
In the Firstname and Lastname fields, enter the real first name and last name of the user.
In the Mail field, enter the user’s email address.
In the Description field, add a description of the new user.
Select a specific language for the user from the Language list.
Select a timezone for the user from the Timezone list.

By default, Foreman server uses the language and timezone settings of the user’s browser.
Set a password for the user:
1. From the Authorized by list, select the source by which the user is authenticated.
  - INTERNAL: to enable the user to be managed inside Foreman server.
  - EXTERNAL: to configure external authentication as described in Configuring External Authentication in Installing Foreman 3.3 Server on Debian/Ubuntu.
2. Enter an initial password for the user in the Password field and the Verify field.
Click Submit to create the user.

CLI procedure

To create a user, enter the following command:
```
# 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 using the update subcommand.

For more information about user related subcommands, enter hammer user --help.

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

Procedure

In the Foreman web UI, navigate to Administer > Users.
Click the username of the user to be assigned one or more roles.

Note

If 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 Admin 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.

CLI procedure

To assign roles to a user, enter the following command:

# hammer user add-role --id user_id --role role_name

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

Prerequisites

Ensure that you are logged on to the Foreman web UI as a user with administrator privileges for Foreman.

Procedure

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.

3.1.4. Creating an API-Only User

You can create users that can interact only with the Foreman API.

Prerequisite

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.

Procedure

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.

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

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

Prerequisites

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.

Procedure

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
  1. Prepare the content of the public SSH key in a clipboard.
  2. Click Add SSH Key.
  3. In the Key field, paste the public SSH key content from the clipboard.
  4. In the Name field, enter a name for the SSH key.
  5. Click Submit.
- To Remove SSH key
  1. Click Delete on the row of the SSH key to be deleted.
  2. Click OK in the confirmation prompt.

CLI procedure

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

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

3.3.1. Creating a Personal Access Token

Use this procedure to create a Personal Access Token.

Procedure

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.

Important

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

Verification

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

3.3.2. Revoking a Personal Access Token

Use this procedure to revoke a Personal Access Token before its expiration date.

Procedure

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.

Verification

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"}
}

3.4. Creating and Managing User Groups

3.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 3.3 Server on Debian/Ubuntu.

User groups are defined in an organizational context, meaning that you must select an organization before you can access user groups.

3.4.2. Creating a User Group

Use this procedure to create a user group.

Procedure

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.

CLI procedure

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

3.4.3. Removing a User Group

Use the Foreman web UI to remove a user group.

Procedure

In the Foreman web UI, navigate to Administer > User Groups.
Click Delete to the right of the user group you want to delete.
In the alert box that appears, click OK to delete a user group.

3.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 plug-ins create roles automatically.

3.5.1. Creating a Role

Use this procedure to create a role.

Procedure

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.

CLI procedure

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.

3.5.2. Cloning a Role

Use the Foreman web UI to clone a role.

Procedure

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.

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

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.

CLI procedure

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.

3.5.4. Viewing Permissions of a Role

Use the Foreman web UI to view the permissions of a role.

Procedure

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.

3.5.5. Creating a Complete Permission Table

Use the Foreman CLI to create a permission table.

Procedure

Ensure that the required packages are installed. Execute the following command on Foreman server:
```
# apt-get 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.

3.5.6. Removing a Role

Use the Foreman web UI to remove a role.

Procedure

In the Foreman web UI, navigate to Administer > Roles.
Select Delete from the drop-down list to the right of the role to be deleted.
In an alert box that appears, click OK to delete the role.

3.6. Predefined Roles Available in Foreman

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

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

Table 1. Permissions provided by role
Role	Permissions Provided by Role
Access Insights Admin	Add and edit Insights rules.
Access Insights Viewer	View Insight reports.
Ansible Roles Manager	Play roles on hosts and host groups. View, destroy, and import Ansible roles. View, edit, create, destroy, and import Ansible variables.
Ansible Tower Inventory Reader	View facts, hosts, and host groups.
Bookmarks manager	Create, edit, and delete bookmarks.
Boot disk access	Download the boot disk.
Compliance manager	View, create, edit, and destroy SCAP content files, compliance policies, and tailoring files. View compliance reports.
Compliance viewer	View compliance reports.
Create ARF report	Create compliance reports.
Default role	The set of permissions that every user is granted, irrespective of any other roles.
Discovery Manager	View, provision, edit, and destroy discovered hosts and manage discovery rules.
Discovery Reader	View hosts and discovery rules.
Edit hosts	View, create, edit, destroy, and build hosts.
Edit partition tables	View, create, edit and destroy partition tables.
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.
Red Hat Access Logs	View the log viewer and the logs.
Remote Execution Manager	Control which roles have permission to run infrastructure jobs.
Remote Execution User	Run remote execution jobs against hosts.
Site manager	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. Therefore, ensure to give this role only to trusted users.
Tasks manager	View and edit Foreman tasks.
Tasks reader	A role that can only view Foreman tasks.
Viewer	A passive role that provides the ability to view the configuration of every element of the Foreman structure, logs, reports, and statistics.
View hosts	A role that can only view hosts.
Virt-who Manager	A role with full virt-who permissions.
Virt-who Reporter	Upload reports generated by virt-who to Foreman. It can be used if you configure virt-who manually and require a user role that has limited virt-who permissions.
Virt-who Viewer	View virt-who configurations. Users with this role can deploy virt-who instances using existing virt-who configurations.

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

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

Procedure

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.

CLI procedure

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.

3.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 life cycle, 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.

Procedure

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.

3.7.3. Supported Operators for Granular Search

Table 2. Logical Operators
Operator	Description
and	Combines search criteria.
not	Negates an expression.
has	Object must have a specified property.

Table 3. Symbolic Operators
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.

4. 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 3.3 Server on Debian/Ubuntu.

4.1. Email Notification Types

Foreman can create the following email notifications:

Audit summary: A summary of all activity audited by Foreman server.
Host built: A notification sent when a host is built.
Host errata advisory: A summary of applicable and installable errata for hosts managed by the user.
Compliance policy summary: A summary of OpenSCAP policy reports and their results.
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.
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.

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

Procedure

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.

Note

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

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

Procedure

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.

4.4. Testing Email Notifications

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

Procedure

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.

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

Procedure

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.

Note

If you want to receive email notifications, ensure that you have an email address set in your user settings.

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

5.1. Deleting Audit Records Manually

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

Procedure

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.

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

Procedure

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.

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

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

5.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
```

5.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'

5.7. Deleting a Task by ID

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

Procedure

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.

6. Logging and Reporting Problems

This chapter provides information on how to log and report problems in Foreman, including information on relevant log files, how to enable debug logging, how to open a support case and attach the relevant log tar files, and how to access support cases within the Foreman web UI.

For more information about Foreman logging settings, use foreman-installer with the --full-help option:

# foreman-installer --full-help | grep logging

6.1. Enabling Debug Logging

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

Procedure

To enable debug logging, enter the following command:
```
# foreman-installer --foreman-logging-level debug
```
After you complete debugging, reset the logging level to the default value:
```
# foreman-installer --reset-foreman-logging-level
```

6.2. Increasing the Logging Levels to Help with Debugging

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

6.2.1. Increasing the Logging Level For Hammer

You can find the log for Hammer in ~/.hammer/log/hammer.log. Edit /etc/hammer/cli_config.yml and set the :log_level::

:log_level: 'debug'

6.2.2. Increasing the Logging Level On Smart Proxy

You can find the log for Smart Proxy in /var/log/foreman-proxy/proxy.log. Uncomment the DEBUG line in /etc/foreman-proxy/settings.yml:

:log_level: DEBUG

Ensure to restart the foreman-proxy service afterwards:

# systemctl restart foreman-proxy

Caution

Running the installer will revert this change back.

6.2.3. Increasing the Logging Level On Foreman

You can find the log for Foreman in /var/log/foreman/production.log.

Foreman stores logs for Apache in:

/var/log/httpd/foreman_error.log
/var/log/httpd/foreman_access.log
/var/log/httpd/foreman_ssl_error.log
/var/log/httpd/foreman_ssl_access.log

Procedure

Set the logging level in /etc/foreman/settings.yaml:

:logging:
  :production:
    :type: file
    :layout: pattern
    :level: debug

Enable selected loggers in /etc/foreman/settings.yaml:
```
:loggers:
  :ldap:
    :enabled: true
  :permissions:
    :enabled: true
  :sql:
    :enabled: true
```
Note that to see logging from some area, debug logging has to be set.
Restart Foreman services:
```
# foreman-maintain service restart
```

You can find the complete list of loggers with their default values in /usr/share/foreman/config/application.rb in the Foreman::Logging.add_loggers command.

6.2.4. Increasing the Logging Level For Redis

You can find the log for Redis in /var/log/redis/redis.log. Set the log level in /etc/opt/rh/rh-redis5/redis.conf:

loglevel debug

Ensure to restart the Redis service afterwards:

# systemctl restart rh-redis5-redis

6.2.5. Increasing the Logging Level For Postgres

You can find the log for Postgres in /var/log/postgresql. Uncomment the log_statement in /etc/postgresql/13/main/postgresql.conf:

log_statement = 'all'

Ensure to restart Foreman services afterwards:

# foreman-maintain service restart

Caution

Based on the size of your Foreman installation, this can cause disk space to fill up very quickly. Only turn this on if absolutely needed.

For more debug log settings, refer to the Postgresql documentation.

6.2.6. Increasing the Logging Level For Foreman Installer

You can find the log files in /var/log/foreman-installer/. To increase the log level of the Foreman Installer during an install:

# foreman-installer --verbose-log-level debug

6.2.7. Increasing the Logging Level For Puppet Agent

You can increase the logging level for Puppet agent on your Foreman server.

Procedure

Add the following line to the [agent] block in the /etc/puppetlabs/puppet/puppet.conf file:
```
[agent]
    log_level = debug
```

You can find the logs in /var/log/puppetlabs/puppet/

6.2.8. Increasing the Logging Level For Puppet Server

You can increase the logging level for Puppet server on your Foreman server.

Procedure

Add the following line to the [master] block in /etc/puppetlabs/puppet/puppet.conf file:
```
[master]
    log_level = debug
```

Restart the Puppet server:

# foreman-maintain service restart --only puppetserver

You can find the logs in /var/log/puppetlabs/puppetserver/.

6.3. Retrieving the Status of Services

Procedure

In the Foreman web UI, navigate to Administer > About.
On the Smart Proxies tab, you can view the status of all Smart Proxies.
On the Compute Resources tab, you can view the status of attached compute resource providers.
In the Backend System Status table, you can view the status of all back-end services.

CLI procedure

Run hammer ping to get information from the database and Foreman services:
```
# hammer ping
```
Use foreman-maintain to check the status of the services running in systemd:
```
# foreman-maintain service status
```
Use foreman-maintain to perform a health check:
```
$ foreman-maintain health check
```

6.4. Restarting Services

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

Procedure

Use foreman-maintain to restart Foreman services:
```
# foreman-maintain service restart
```

Tip	Run `foreman-maintain --help` for more information.

6.5. Enabling Individual Loggers

You can enable individual loggers for selective logging. Foreman uses the following 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.

Important

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

Procedure

Enable the individual loggers that you want. For example, to enable sql and ldap loggers, enter the following command:
```
# foreman-installer \
--foreman-loggers ldap:true \
--foreman-loggers sql:true
```
Optional: To reset loggers to their default values, enter the following command:
```
# foreman-installer --reset-foreman-loggers
```

6.6. Configuring Logging to Journal or File-based Logging

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

Procedure for configuring logging with Journal

Enter the following foreman-installer command to configure logging to the journald service:

# foreman-installer \
--foreman-logging-layout pattern \
--foreman-logging-type journald \
--foreman-proxy-log JOURNAL

Optional: To inspect the log messages, use the journalctl utility. For example:
- journalctl --unit foreman and journalctl --unit foreman-proxy show messages for the foreman and foreman-proxy units
- journalctl REQUEST=request_ID shows messages for a specified request

Procedure for configuring file-based logging

Enter the following foreman-installer command to configure file-based logging:

# foreman-installer \
--reset-foreman-logging-layout \
--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

6.7. Log File Directories Provided by Foreman

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

Table 4. Log File Directories for Reporting and Troubleshooting
Log File Directories	Description of Log File Content
`/var/log/candlepin`	Subscription management
`/var/log/foreman-installer`	Installer
`/var/log/foreman-maintain`	Foreman maintain
`/var/log/foreman-proxy`	Foreman proxy
`/var/log/foreman`	Foreman
`/var/log/httpd`	Apache HTTP server
`/var/log/messages`	Various other log messages
`/var/log/puppetlabs/puppet`	Configuration management
`/var/log/rhsm`	Subscription management
`/var/log/tomcat`	Candlepin webservice logs

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

6.8. Utilities for Collecting Log Information

You can collect information from log files to troubleshoot Foreman.

foreman-debug: The foreman-debug command collects configuration and log file data for Foreman, its back-end services, and system information. This information is collected and written to a tar file. By default, the output tar file is located at /tmp/foreman-debug-xxx.tar.xz.

Additionally, the foreman-debug command exports tasks run during the last 60 days. By default, the output tar file is located at /tmp/task-export-xxx.tar.xz. If the file is missing, see the file /tmp/task-export.log to learn why task export was unsuccessful. There is no timeout when running this command.

For more information, run foreman-debug -h.

Important

The collection process 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. Foreman community recommends that you send this information directly to the intended recipient and not to a public target.

6.9. System Journal Metadata

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

Table 5. System Journal Metadata
Name	Description
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

7. Monitoring Resources

The following chapter details how to configure monitoring and reporting for managed systems. This includes host configuration, Content Views, compliance, subscriptions, registered hosts, promotions, and synchronization.

7.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, subscriptions and hosts currently registered, promotions and synchronization, and a list of the latest notifications.

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

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 6. 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 and subscription 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 plug-in.

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 Subscription Status

An overview of the subscriptions currently consumed by the hosts registered to Foreman. A subscription is a purchased certificate that unlocks access to software, upgrades, and security fixes for hosts. The following table shows the possible states of subscriptions.

Table 7. Host Subscription States
Icon	State	Description
	Invalid	Hosts that have products installed, but are not correctly subscribed. These hosts need attention immediately.
	Partial	Hosts that have a subscription and a valid entitlement, but are not using their full entitlements. These hosts should be monitored to ensure they are configured as expected.
	Valid	Hosts that have a valid entitlement and are using their full entitlements.

Click the subscription type to view hosts associated with subscriptions of the selected type.

Subscription Status

An overview of the current subscription totals that shows the number of active subscriptions, the number of subscriptions that expire in the next 120 days, and the number of subscriptions that have recently expired.

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

Note	It is not possible to change the date format displayed in the Foreman web UI.

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

To Adjust Timeout Settings:

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.

To Disable Checking for Services:

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.

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

To Configure RSS Feed Notifications:

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.

7.3. Monitoring Foreman server

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

Procedure

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
```

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

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

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

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

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

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

8.2. Installing Webhooks

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

Procedure

Install webhooks using the following command:

# foreman-installer --enable-foreman-plugin-webhooks

Optional: you can install the CLI plugin using the following command:
```
# foreman-installer --enable-foreman-cli-webhooks
```

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

Procedure

In the Foreman web UI, navigate to Administer > 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.

Examples

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 or Actions 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"
}

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

Procedure

In the Foreman web UI, navigate to Administer > 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 or text/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.

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

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 Capsule Upgrade Succeeded	Upgrade Capsules on given Capsule server hosts.	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: `@payload[:id]` (host id), `@payload[:hostname]` (host name).
Build Exited	A host build mode was canceled, either it was successfully provisioned or the user canceled the build manually.	Custom event: `@payload[:id]` (host id), `@payload[:hostname]` (host name).
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: `@payload[:id]` (host id), `@payload[:hostname]`, `@payload[:global_status]` (hash)
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

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.