1. Overview of hosts in Foreman
A host is any Linux client that Foreman manages. Hosts can be physical or virtual.
You can deploy virtual hosts on any platform supported by Foreman, such as Amazon EC2, Google Compute Engine, KVM, libvirt, Microsoft Azure, OpenStack, oVirt, Proxmox, Rackspace Cloud Services, or VMware vSphere.
With Foreman, you can manage hosts at scale, including monitoring, provisioning, remote execution, configuration management, software management, and subscription management.
1.1. Browsing Hosts in Foreman web UI
In the Foreman web UI, you can browse all hosts recognized by Foreman, grouped by type:
-
All Hosts – a list of all hosts recognized by Foreman.
-
Discovered Hosts – a list of bare-metal hosts detected on the provisioning network by the Discovery plugin.
-
Content Hosts – a list of hosts that manage tasks related to content and subscriptions.
-
Host Collections – a list of user-defined collections of hosts used for bulk actions such as errata installation.
To search for a host, type in the Search field, and use an asterisk (*) to perform a partial string search.
For example, if searching for a content host named server.example.com
, click the Content Hosts page and type server*
in the Search field.
Alternatively, *ver*
will also find the content host server.example.com
.
Warning
|
Foreman server is listed as a host itself even if it is not self-registered. Do not delete Foreman server from the list of hosts. |
2. Administering hosts
This chapter describes creating, registering, administering, and removing hosts.
2.1. Creating a host in Foreman
Use this procedure to create a host in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
On the Host tab, enter the required details.
-
Click the Ansible Roles tab, and from the Ansible Roles list, select one or more roles that you want to add to the host. Use the arrow icon to manage the roles that you add or remove.
-
On the Puppet Classes tab, select the Puppet classes you want to include.
-
On the Interfaces tab:
-
For each interface, click Edit in the Actions column and configure the following settings as required:
-
Type — For a Bond or BMC interface, use the Type list and select the interface type.
-
MAC address — Enter the MAC address.
-
DNS name — Enter the DNS name that is known to the DNS server. This is used for the host part of the FQDN.
-
Domain — Select the domain name of the provisioning network. This automatically updates the Subnet list with a selection of suitable subnets.
-
IPv4 Subnet — Select an IPv4 subnet for the host from the list.
-
IPv6 Subnet — Select an IPv6 subnet for the host from the list.
-
IPv4 address — If IP address management (IPAM) is enabled for the subnet, the IP address is automatically suggested. Alternatively, you can enter an address. The address can be omitted if provisioning tokens are enabled, if the domain does not manage DNS, if the subnet does not manage reverse DNS, or if the subnet does not manage DHCP reservations.
-
IPv6 address — If IP address management (IPAM) is enabled for the subnet, the IP address is automatically suggested. Alternatively, you can enter an address.
-
Managed — Select this checkbox to configure the interface during provisioning to use the Smart Proxy provided DHCP and DNS services.
-
Primary — Select this checkbox to use the DNS name from this interface as the host portion of the FQDN.
-
Provision — Select this checkbox to use this interface for provisioning. This means TFTP boot will take place using this interface, or in case of image based provisioning, the script to complete the provisioning will be executed through this interface. Note that many provisioning tasks, such as downloading packages by anaconda or Puppet setup in a
%post
script, will use the primary interface. -
Virtual NIC — Select this checkbox if this interface is not a physical device. This setting has two options:
-
Tag — Optionally set a VLAN tag. If unset, the tag will be the VLAN ID of the subnet.
-
Attached to — Enter the device name of the interface this virtual interface is attached to.
-
-
-
Click OK to save the interface configuration.
-
Optionally, click Add Interface to include an additional network interface. For more information, see Adding network interfaces.
-
Click Submit to apply the changes and exit.
-
-
On the Operating System tab, enter the required details. For Red Hat operating systems, select Synced Content for Media Selection. If you want to use non Red Hat operating systems, select All Media, then select the installation media from the Media Selection list. You can select a partition table from the list or enter a custom partition table in the Custom partition table field. You cannot specify both.
-
On the Parameters tab, click Add Parameter to add any parameter variables that you want to pass to job templates at run time. This includes all Puppet Class, Ansible Playbook parameters and host parameters that you want to associate with the host. To use a parameter variable with an Ansible job template, you must add a Host Parameter.
If you want to create a host with pull mode for remote job execution, add the
enable-remote-execution-pull
parameter with typeboolean
set totrue
. For more information, see Transport modes for remote execution. -
On the Additional Information tab, enter additional information about the host.
-
Click Submit to complete your provisioning request.
-
To create a host associated to a host group, enter the following command:
# hammer host create \ --ask-root-password yes \ --hostgroup "My_Host_Group" \ --interface="primary=true, \ provision=true, \ mac=My_MAC_Address, \ ip=My_IP_Address" \ --location "My_Location" \ --name "My_Host_Name" \ --organization "My_Organization"
This command prompts you to specify the root password. It is required to specify the host’s IP and MAC address. Other properties of the primary network interface can be inherited from the host group or set using the
--subnet
, and--domain
parameters. You can set additional interfaces using the--interface
option, which accepts a list of key-value pairs. For the list of available interface settings, enter thehammer host create --help
command.
2.2. Cloning hosts
You can clone existing hosts.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
In the Actions menu, click Clone.
-
On the Host tab, ensure to provide a Name different from the original host.
-
On the Interfaces tab, ensure to provide a different IP address.
-
Click Submit to clone the host.
For more information, see Creating a host in Foreman.
2.3. Associating a virtual machine with Foreman from a hypervisor
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select a compute resource.
-
On the Virtual Machines tab, click Associate VM from the Actions menu.
2.4. Changing a module stream for a host
If you have a host running Enterprise Linux 8, you can modify the module stream for the repositories you install.
You can enable, disable, install, update, and remove module streams from your host in the Foreman web UI.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click the Content tab, then click the Module streams tab.
-
Click the vertical ellipsis next to the module and select the action you want to perform. You get a REX job notification once the remote execution job is complete.
2.5. Enabling custom repositories on content hosts
You can enable all custom repositories on content hosts using the Foreman web UI.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select a host.
-
Select the Content tab, then select Repository sets.
-
From the dropdown, you can filter the Repository type column to Custom.
-
Select the desired number of repositories or click the Select All checkbox to select all repositories, then click the vertical ellipsis, and select Override to Enabled.
2.6. Using the Details tab
In Foreman, you can view details of a host name in the Details tab. You can expand and collapse individual cards and all links. Your browser remembers the card expansion and collapse state.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to view.
-
Select the Details tab.
The cards in the Details tab show details for the System properties, BIOS, Networking interfaces, Operating system, Provisioning templates, and Provisioning. Registered content hosts show additional cards for Registration details, Installed products, and HW properties providing information about Model, Number of CPU(s), Sockets, Cores per socket and RAM.
In the Operating system card, you can see details for the Architecture, OS, Boot time, and Kernel release.
There are interactive features for the following Details cards:
-
Click to collapse and expand each network interface.
-
Click the link to edit all network interfaces.
-
Click to copy values to clipboard including Name, Subscription UUID, and Domain.
-
For hosts with virtual guests, click the chip to see the list of guests.
-
For hosts that are virtual guests, click the Virtual host link to view its host.
-
Click to view a template in a pop-up modal without leaving the page.
-
Click the pencil icon to edit a template.
-
Click the pop-out button in modal to view the template in a new tab.
-
Click the link in modal to edit the template.
-
Click the Copy to clipboard button in modal to get the template into clipboard.
2.7. Changing the content source of a host
A content source is a Smart Proxy that a host consumes content from. Use this procedure to change the content source for a host.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click the vertical ellipsis icon next to the Edit button and select Change content source.
-
Select Content Source, Lifecycle Content View, and Content Source from the lists.
-
Click Change content source.
NoteSome lifecycle environments can be unavailable for selection if they are not synced on the selected content source. For more information, see Adding lifecycle environments to Smart Proxy servers in Managing content.
You can either complete the content source change using remote execution or manually. To update configuration on host using remote execution, click Run job invocation. For more information about running remote execution jobs, see Configuring and Setting up Remote Jobs. To update the content source manually, execute the autogenerated commands from Change content source on the host.
2.8. Changing the environment of a host
Use this procedure to change the environment of a host.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click the vertical ellipsis in the Content view details card and select Edit content view assignment.
-
Select the environment.
-
Select the content view.
-
Click Save.
2.9. Changing the managed status of a host
Hosts provisioned by Foreman are Managed by default. When a host is set to Managed, you can configure additional host parameters from Foreman server. These additional parameters are listed on the Operating System tab. If you change any settings on the Operating System tab, they will not take effect until you set the host to build and reboot it.
If you need to obtain reports about configuration management on systems using an operating system not supported by Foreman, set the host to Unmanaged.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click Edit.
-
Click Manage host or Unmanage host to change the host’s status.
-
Click Submit.
2.10. Enabling Tracer on a host
Use this procedure to enable Tracer on Foreman and access Traces. Tracer displays a list of services and applications that need to be restarted. Traces is the output generated by Tracer in the Foreman web UI.
-
Foreman Client repository for the operating system version of the host is synchronized on Foreman server, available in the content view and the lifecycle environment of the host, and enabled for the host. For more information, see Changing the repository sets status for a host in Foreman in Managing content.
-
Remote execution is enabled.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
On the Traces tab, click Enable Traces.
-
Select the provider to install
katello-host-tools-tracer
from the list. -
Click Enable Tracer. You get a REX job notification after the remote execution job is complete.
2.11. Restarting applications on a host
Use this procedure to restart applications from the Foreman web UI.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the hosts you want to modify.
-
Select the Traces tab.
-
Select applications that you want to restart.
-
Select Restart via remote execution from the Restart app list. You will get a REX job notification once the remote execution job is complete.
2.12. Assigning a host to a specific organization
Use this procedure to assign a host to a specific organization. For general information about organizations and how to configure them, see Managing Organizations in Managing organizations and locations in Foreman.
Note
|
If your host is already registered with a different organization, you must first unregister the host before assigning it to a new organization.
To unregister the host, run |
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Select the checkbox of the host you want to change.
-
From the Select Action list, select Assign Organization. A new option window opens.
-
From the Select Organization list, select the organization that you want to assign your host to. Select the checkbox Fix Organization on Mismatch.
NoteA mismatch happens if there is a resource associated with a host, such as a domain or subnet, and at the same time not associated with the organization you want to assign the host to. The option Fix Organization on Mismatch will add such a resource to the organization, and is therefore the recommended choice. The option Fail on Mismatch will always result in an error message. For example, reassigning a host from one organization to another will fail, even if there is no actual mismatch in settings.
-
Click Submit.
2.13. Assigning a host to a specific location
Use this procedure to assign a host to a specific location. For general information about locations and how to configure them, see Creating a Location in Managing content.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Select the checkbox of the host you want to change.
-
From the Select Action list, select Assign Location. A new option window opens.
-
Navigate to the Select Location list and choose the location that you want for your host. Select the checkbox Fix Location on Mismatch.
NoteA mismatch happens if there is a resource associated with a host, such as a domain or subnet, and at the same time not associated with the location you want to assign the host to. The option Fix Location on Mismatch will add such a resource to the location, and is therefore the recommended choice. The option Fail on Mismatch will always result in an error message. For example, reassigning a host from one location to another will fail, even if there is no actual mismatch in settings.
-
Click Submit.
2.14. Switching between hosts
When you are on a particular host in the Foreman web UI, you can navigate between hosts without leaving the page by using the host switcher. Click ⇄ next to the hostname. This displays a list of hosts in alphabetical order with a pagination arrow and a search bar to find the host you are looking for.
2.15. Viewing host details from a content host
Use this procedure to view the host details page from a content host.
-
In the Foreman web UI, navigate to Hosts > Content Hosts
-
Click the content host you want to view.
-
Select the Details tab to see the host details page.
The cards in the Details tab show details for the System properties, BIOS, Networking interfaces, Operating system, Provisioning templates, and Provisioning. Registered content hosts show additional cards for Registration details, Installed products, and HW properties providing information about Model, Number of CPU(s), Sockets, Cores per socket, and RAM.
2.16. Selecting host columns
You can select what columns you want to see in the host table on the Hosts > All Hosts page. For a complete list of host columns, see Overview of the host columns.
Note
|
It is not possible to deselect the Name column. The Name column serves as a primary identification method of the host. |
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click Manage columns.
-
Select columns that you want to display. You can select individual columns or column categories. Selecting or deselecting a category selects or deselects all columns in that category.
NoteSome columns are included in more than one category, but you can display a column of a specific type only once. By selecting or deselecting a specific column, you select or deselect all instances of that column.
-
You can now see the selected columns in the host table.
2.17. Removing a host from Foreman
Use this procedure to remove a host from Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > All Hosts or Hosts > Content Hosts. Note that there is no difference from what page you remove a host, from All Hosts or Content Hosts. In both cases, Foreman removes a host completely.
-
Select the hosts that you want to remove.
-
From the Select Action list, select Delete Hosts.
-
Click Submit to remove the host from Foreman permanently.
Warning
|
By default, the To delete a virtual machine on the compute resource, navigate to Administer > Settings and select the Provisioning tab.
Setting |
-
Delete your host from Foreman:
$ hammer host delete \ --id My_Host_ID \ --location-id My_Location_ID \ --organization-id My_Organization_ID
Alternatively, you can use
--name My_Host_Name
instead of--id My_Host_ID
.
2.17.1. Disassociating a virtual machine from Foreman without removing it from a hypervisor
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Select the checkbox to the left of the hosts that you want to disassociate.
-
From the Select Action list, click Disassociate Hosts.
-
Optional: Select the checkbox to keep the hosts for future action.
-
Click Submit.
2.18. Installing the Snapshot Management plugin
You can install the Snapshot Management plugin on your Foreman.
-
Install the Snapshot Management plugin on your Foreman server:
# foreman-installer --enable-foreman-plugin-snapshot-management
2.19. Creating snapshots of a host
You can use the Snapshot Management plugin to create snapshots of hosts.
-
You have installed the Snapshot Management plugin successfully. For more information, see Installing the Snapshot Management plugin.
-
Your host is running on VMware vSphere or Proxmox.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select a host.
-
In the Snapshots card, click Create Snapshot.
-
Enter a Name.
-
Optional: Enter a Description.
-
Optional: In the Snapshot Mode field, select Memory if you want to include the RAM in your snapshot or Quiesce if you want to ensure the full state of the VM is written to disk before creating the snapshot.
-
Click Submit to create a snapshot.
Caution
|
Keeping more than three snapshots per host slows down the creation and rollback process. Consider deleting older snapshots when creating new ones. |
2.20. Lifecycle status of RHEL hosts
Foreman provides multiple mechanisms to display information about upcoming End of Support (EOS) events for your Red Hat Enterprise Linux hosts:
-
Notification banner
-
A column on the Hosts index page
-
Alert on the Hosts index page for each host that runs Red Hat Enterprise Linux with an upcoming EOS event in a year as well as when support has ended
-
Ability to Search for hosts by EOS on the Hosts index page
-
Host status card on the host details page
For any hosts that are not running Red Hat Enterprise Linux, Foreman displays Unknown in the RHEL Lifecycle status and Last report columns.
When either the end of maintenance support or the end of extended lifecycle support approaches in a year, you will see a notification banner in the Foreman web UI if you have hosts with that Red Hat Enterprise Linux version. The notification provides information about the Red Hat Enterprise Linux version, the number of hosts running that version in your environment, the lifecycle support, and the expiration date. Along with other information, the Red Hat Enterprise Linux lifecycle column is visible in the notification.
2.20.1. Displaying RHEL lifecycle status
You can display the status of the end of support (EOS) for your Red Hat Enterprise Linux hosts in the table on the Hosts index page.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click Manage columns.
-
Select the Content column to expand it.
-
Select RHEL Lifecycle status.
-
Click Save to generate a new column that displays the Red Hat Enterprise Linux lifecycle status.
3. Working with host groups
A host group acts as a template for common host settings. Instead of defining the settings individually for each host, use host groups to define common settings once and apply them to multiple hosts.
3.1. Host group settings and nested host groups
A host group can define many settings for hosts, such as lifecycle environment, content view, or Ansible roles that are available to the hosts.
Important
|
When you change the settings of an existing host group, the new settings do not propagate to the hosts assigned to the host group. Only Puppet class settings get updated on hosts after you change them in the host group. |
You can create a hierarchy of host groups. Aim to have one base level host group that represents all hosts in your organization and provides general settings, and then nested groups that provide specific settings.
Foreman applies host settings in the following order when nesting host groups:
-
Host settings take priority over host group settings.
-
Nested host group settings take priority over parent host group settings.
You create a top-level host group named Base and two nested host groups named Webserver and Storage.
The nested host groups are associated with multiple hosts.
You also create host custom.example.com
that is not associated with any host group.
You define the operating system on the top-level host group (Base) and Ansible roles on the nested host groups (Webservers and Storage).
Top-level host group | Nested host group | Hosts | Settings inherited from host groups |
---|---|---|---|
Base This host group applies the |
Webservers This host group applies the |
webserver1.example.com |
Hosts use the following settings:
|
webserver2.example.com |
|||
Storage This host group applies the |
storage1.example.com |
Hosts use the following settings:
|
|
storage2.example.com |
|||
[No host group] |
custom.example.com |
No settings inherited from host groups. |
You create a top-level host group named Base and two nested host groups named Webserver and Storage.
You also create host custom.example.com
that is associated with the top-level host group Base, but no nested host group.
You define different values for the operating system and Ansible role settings on the top-level host group (Base) and nested host groups (Webserver and Storage).
Top-level host group | Nested host group | Host | Settings inherited from host groups |
---|---|---|---|
Base This host group applies these settings:
|
Webservers This host group applies these settings:
|
webserver1.example.com |
Hosts use the following settings:
|
webserver2.example.com |
|||
Storage This host group applies these settings:
|
storage1.example.com |
Hosts use the following settings:
|
|
storage2.example.com |
|||
[No nested host group] |
custom.example.com |
Host uses the following settings:
|
3.2. Creating a host group
Create a host group to be able to apply host settings to multiple hosts.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Configure > Host Groups and click Create Host Group.
-
If you have an existing host group that you want to inherit attributes from, you can select a host group from the Parent list. If you do not, leave this field blank.
-
Enter a Name for the new host group.
-
Enter any further information that you want future hosts to inherit.
-
Click the Ansible Roles tab, and from the Ansible Roles list, select one or more roles that you want to add to the host. Use the arrow icon to manage the roles that you add or remove.
-
Click the additional tabs and add any details that you want to attribute to the host group.
NotePuppet fails to retrieve the Puppet CA certificate while registering a host with a host group associated with a Puppet environment created inside a
Production
environment.To create a suitable Puppet environment to be associated with a host group, manually create a directory:
# mkdir /etc/puppetlabs/code/environments/example_environment
-
Click Submit to save the host group.
-
Create the host group with the
hammer hostgroup create
command. For example:# hammer hostgroup create --name "Base" \ --architecture "My_Architecture" \ --content-source-id _My_Content_Source_ID_ \ --content-view "_My_Content_View_" \ --domain "_My_Domain_" \ --lifecycle-environment "_My_Lifecycle_Environment_" \ --locations "_My_Location_" \ --medium-id _My_Installation_Medium_ID_ \ --operatingsystem "_My_Operating_System_" \ --organizations "_My_Organization_" \ --partition-table "_My_Partition_Table_" \ --puppet-ca-proxy-id _My_Puppet_CA_Proxy_ID_ \ --puppet-environment "_My_Puppet_Environment_" \ --puppet-proxy-id _My_Puppet_Proxy_ID_ \ --root-pass "My_Password" \ --subnet "_My_Subnet_"
3.3. Creating a host group for each lifecycle environment
Use this procedure to create a host group for the Library lifecycle environment and add nested host groups for other lifecycle environments.
To create a host group for each lifecycle environment, run the following Bash script:
MAJOR="My_Major_OS_Version"
ARCH="My_Architecture"
ORG="My_Organization"
LOCATIONS="My_Location"
PTABLE_NAME="My_Partition_Table"
DOMAIN="My_Domain"
hammer --output csv --no-headers lifecycle-environment list --organization "${ORG}" | cut -d ',' -f 2 | while read LC_ENV; do
[[ ${LC_ENV} == "Library" ]] && continue
hammer hostgroup create --name "rhel-${MAJOR}server-${ARCH}-${LC_ENV}" \
--architecture "${ARCH}" \
--partition-table "${PTABLE_NAME}" \
--domain "${DOMAIN}" \
--organizations "${ORG}" \
--query-organization "${ORG}" \
--locations "${LOCATIONS}" \
--lifecycle-environment "${LC_ENV}"
done
3.4. Adding a host to a host group
You can add a host to a host group in the Foreman web UI.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click Edit.
-
Select the host group from the Host Group list.
-
Click Submit.
-
The Details card under the Overview tab now shows the host group your host belongs to.
3.5. Changing the host group of a host
Use this procedure to change the Host Group of a host.
If you reprovision a host after changing the host group, the fresh values that the host inherits from the host group will be applied.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click Edit.
-
Select the new host group from the Host Group list.
-
Click Submit.
-
The Details card under the Overview tab now shows the host group your host belongs to.
4. Registering hosts and setting up host integration
You must register hosts that have not been provisioned through Foreman to be able to manage them with Foreman. You can register hosts through Foreman server or Smart Proxy server.
You must also install and configure tools on your hosts, depending on which integration features you want to use. Use the following procedures to install and configure host tools:
4.1. Supported clients in registration
Foreman supports the following operating systems and architectures for registration.
Note
|
The following combinations have been tested. Global registration is a provisioning template for a shell script, which can be extended for additional systems. If you decide to extend the template, please submit your changes to our repository. Thanks for your contribution! |
- Supported Host Operating Systems
-
The hosts can use the following operating systems:
-
Amazon Linux
-
Debian
-
Enterprise Linux 9, 8, 7
-
Fedora
-
OpenSUSE
-
SUSE Linux Enterprise Server
-
Ubuntu
-
- Supported Host Architectures
-
The hosts can use the following architectures:
-
x86_64/amd64
-
4.2. Registering hosts by using global registration
You can register a host to Foreman by generating a curl
command on Foreman and running this command on hosts.
This method uses two provisioning templates: Global Registration template and Linux host_init_config default template.
That gives you complete control over the host registration process.
You can also customize the default templates if you need greater flexibility. For more information, see Customizing the registration templates.
-
You can extend registration options by plugins. For more information, see How to Create a Plugin and Slot and Fill.
4.2.1. Global parameters for registration
You can configure the following global parameters by navigating to Configure > Global Parameters:
-
The
host_registration_insights
parameter is used in theinsights
snippet. If the parameter is set totrue
, the registration installs and enables the Red Hat Insights client on the host. If the parameter is set tofalse
, it prevents Foreman and the Red Hat Insights client from uploading Inventory reports to your Red Hat Hybrid Cloud Console. The default value isfalse
. When overriding the parameter value, set the parameter type toboolean
. -
The
host_packages
parameter is for installing packages on the host. -
The
host_registration_remote_execution
parameter is used in theremote_execution_ssh_keys
snippet. If it is set totrue
, the registration enables remote execution on the host. The default value istrue
. -
The
remote_execution_ssh_keys
,remote_execution_ssh_user
,remote_execution_create_user
, andremote_execution_effective_user_method
parameters are used in theremote_execution_ssh_keys
snippet. For more details, see the snippet.
You can navigate to snippets in the Foreman web UI through Hosts > Templates > Provisioning Templates.
4.2.2. Registering a host
You can register a host by using registration templates and set up various integration features and host tools during the registration process.
-
Your user account has a role assigned that has the
create_hosts
permission. -
You must have root privileges on the host that you want to register.
-
Foreman server, any Smart Proxy servers, and all hosts must be synchronized with the same NTP server, and have a time synchronization tool enabled and running.
-
An activation key must be available for the host. For more information, see Managing Activation Keys in Managing content.
-
Foreman Client repository for the operating system version of the host is synchronized on Foreman server and enabled in the activation key you use. For more information, see Importing Content in Managing content. This repository is required for the remote execution pull client, Puppet agent, Tracer, and other tools.
-
If you want to use Smart Proxy servers instead of your Foreman server, ensure that you have configured your Smart Proxy servers accordingly. For more information, see Configuring Smart Proxy for Host Registration and Provisioning in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
-
If your Foreman server or Smart Proxy server is behind an HTTP proxy, configure the Subscription Manager on your host to use the HTTP proxy for connection.
-
You have configured the operating system entry on Foreman for Enterprise Linux.
-
In the Foreman web UI, navigate to Hosts > Register Host.
-
Optional: Select a different Organization.
-
Optional: Select a different Location.
-
Optional: From the Host Group list, select the host group to associate the hosts with. Fields that inherit value from Host group: Operating system, Activation Keys and Lifecycle environment.
-
Optional: From the Operating system list, select the operating system of hosts that you want to register. Specifying an operating system is required when you register machines without
subscription-manager
, such as Debian or Ubuntu. -
Optional: From the Smart Proxy list, select the Smart Proxy to register hosts through.
NoteA Smart Proxy behind a load balancer takes precedence over a Smart Proxy selected in the Foreman web UI as the host’s content source.
-
In the Activation Keys field, enter one or more activation keys to assign to hosts.
-
Optional: Select the Insecure option, if you want to make the first call insecure. During this first call, hosts download the CA file from Foreman. Hosts will use this CA file to connect to Foreman with all future calls making them secure.
Foreman community recommends that you avoid insecure calls.
If an attacker, located in the network between Foreman and a host, fetches the CA file from the first insecure call, the attacker will be able to access the content of the API calls to and from the registered host and the JSON Web Tokens (JWT). Therefore, if you have chosen to deploy SSH keys during registration, the attacker will be able to access the host using the SSH key.
Instead, you can manually copy and install the CA file on each host before registering the host.
To do this, find where Foreman stores the CA file by navigating to Administer > Settings > Authentication and locating the value of the SSL CA file setting.
Copy the CA file to the
/etc/pki/ca-trust/source/anchors/
directory on hosts and enter the following commands:# update-ca-trust enable # update-ca-trust
Then register the hosts with a secure
curl
command, such as:# curl -sS https://foreman.example.com/register ...
The following is an example of the
curl
command with the--insecure
option:# curl -sS --insecure https://foreman.example.com/register ...
-
Select the Advanced tab.
-
Optional: From the Setup REX list, select whether you want to deploy Foreman SSH keys to hosts or not.
If set to
Yes
, public SSH keys will be installed on the registered host. The inherited value is based on thehost_registration_remote_execution
parameter. It can be inherited, for example from a host group, an operating system, or an organization. When overridden, the selected value will be stored on host parameter level. -
Optional: From the Setup Insights list, select whether you want to install
insights-client
and register the hosts to Insights.The Insights tool is available for Red Hat Enterprise Linux only. It has no effect on other operating systems.
You must enable the following repositories on a registered machine:
-
Red Hat Enterprise Linux 6:
rhel-6-server-rpms
-
Red Hat Enterprise Linux 7:
rhel-7-server-rpms
-
Red Hat Enterprise Linux 8:
rhel-8-for-x86_64-appstream-rpms
The
insights-client
package is installed by default on Red Hat Enterprise Linux 8 except in environments whereby Red Hat Enterprise Linux 8 was deployed with "Minimal Install" option.
-
-
Optional: In the Install packages field, list the packages (separated with spaces) that you want to install on the host upon registration. This can be set by the
host_packages
parameter. -
Optional: Select the Update packages option to update all packages on the host upon registration. This can be set by the
host_update_packages
parameter. -
Optional: In the Repository field, enter a repository to be added before the registration is performed. For example, it can be useful to make the
subscription-manager
package available for the purpose of the registration. For Red Hat family distributions, enter the URL of the repository, for examplehttp://rpm.example.com/
. For Debian OS families, enter the whole line of list file content, for exampledeb http://deb.example.com/ bookworm 1.0
. -
Optional: In the Repository GPG key URL field, specify the public key to verify the signatures of GPG-signed packages. It needs to be specified in the ASCII form with the GPG public key header.
-
Optional: In the Token lifetime (hours) field, change the validity duration of the JSON Web Token (JWT) that Foreman uses for authentication. The duration of this token defines how long the generated
curl
command works. You can set the duration to 0 – 999 999 hours or unlimited.Note that Foreman applies the permissions of the user who generates the
curl
command to authorization of hosts. If the user loses or gains additional permissions, the permissions of the JWT change too. Therefore, do not delete, block, or change permissions of the user during the token duration.The scope of the JWTs is limited to the registration endpoints only and cannot be used anywhere else.
-
Optional: In the Remote Execution Interface field, enter the identifier of a network interface that hosts must use for the SSH connection. If you keep this field blank, Foreman uses the default network interface.
-
Optional: From the REX pull mode list, select whether you want to deploy Foreman remote execution pull client.
If set to
Yes
, the remote execution pull client is installed on the registered host. The inherited value is based on thehost_registration_remote_execution_pull
parameter. It can be inherited, for example from a host group, an operating system, or an organization. When overridden, the selected value is stored on the host parameter level.The registered host must have access to the Foreman Client repository.
For more information about the pull mode, see Transport modes for remote execution.
-
Optional: Select the Ignore errors option if you want to ignore subscription manager errors.
-
Optional: Select the Force option if you want to remove any
katello-ca-consumer
packages before registration and runsubscription-manager
with the--force
argument. If you register Enterprise Linux hosts, in the Activation Keys field, enter one or more activation keys to assign to registered hosts. -
Click Generate.
-
Copy the generated
curl
command. -
On the host that you want to register, run the
curl
command asroot
.
4.2.3. Customizing host registration by using snippets
You can customize the registration process by creating snippets with pre-defined names.
The Global Registration
template includes these snippets automatically.
Therefore, you do not have to edit the template.
To add custom steps to registration, create one or both of the following snippets:
before_registration
-
This snippet is loaded and executed by the
Global Registration
template before registering your host to Foreman. after_registration
-
This snippet is loaded and executed by the
Global Registration
template after registering your host to Foreman.
Ensure you name the snippets precisely.
Otherwise, the Global Registration
template cannot load them.
-
Your Foreman account has a role that grants the permissions
view_provisioning_templates
,create_provisioning_templates
,assign_organizations
, andassign_locations
. -
You have selected a particular organization and location context.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Click Create Template.
-
In the Name field, enter the name of the required snippet:
before_registration
orafter_registration
. -
In the template editor, create your snippet.
-
On the Type tab, select Snippet.
-
On the Locations tab, assign the snippet to required locations.
-
On the Organizations tab, assign the snippet to required organizations.
-
Click Submit.
4.2.4. Customizing the registration templates
You can customize the registration process by editing the provisioning templates. Note that all default templates in Foreman are locked. If you want to customize the registration templates, you must clone the default templates and edit the clones.
Note
|
Foreman community only provides support for the original unedited templates. Customized templates do not receive updates released by Foreman community. |
The registration process uses the following provisioning templates:
-
The Global Registration template contains steps for registering hosts to Foreman. This template renders when hosts access the
/register
Foreman API endpoint. -
The Linux host_init_config default template contains steps for initial configuration of hosts after they are registered.
-
Navigate to Hosts > Templates > Provisioning Templates.
-
Search for the template you want to edit.
-
In the row of the required template, click Clone.
-
Edit the template as needed. For more information, see Template writing reference.
-
Click Submit.
-
Navigate to Administer > Settings > Provisioning.
-
Change the following settings as needed:
-
Point the Default Global registration template setting to your custom global registration template,
-
Point the Default 'Host initial configuration' template setting to your custom initial configuration template.
-
4.3. Installing Tracer
Use this procedure to install Tracer on Foreman and access Traces. Tracer displays a list of services and applications that are outdated and need to be restarted. Traces is the output generated by Tracer in the Foreman web UI.
-
The host is registered to Foreman.
-
Foreman Client repository for the operating system version of the host is synchronized on Foreman server, available in the content view and the lifecycle environment of the host, and enabled for the host. For more information, see Changing the repository sets status for a host in Foreman in Managing content.
-
On the content host, install the
katello-host-tools-tracer
RPM package:# yum install katello-host-tools-tracer
-
Enter the following command:
# katello-tracer-upload
-
In the Foreman web UI, navigate to Hosts > All Hosts, then click the required host name.
-
Click the Traces tab to view Traces. If it is not installed, an Enable Traces button initiates a remote execution job that installs the package.
4.4. Installing and configuring Puppet agent during host registration
You can install and configure the Puppet agent on the host during registration. A configured Puppet agent is required on the host for Puppet integration with your Foreman. For more information about Puppet, see Configuring hosts by using Puppet.
-
You created a product and repository for the upstream Puppet agent, such as
https://yum.puppet.com
orhttps://apt.puppet.com
, and synchronized the repository to Foreman. For more information, see Importing Content in Managing content. -
You created an activation key that enables the Puppet agent repository for hosts. For more information, see Managing Activation Keys in Managing content.
-
In the Foreman web UI, navigate to Configure > Global Parameters to add host parameters globally. Alternatively, you can navigate to Configure > Host Groups and edit or create a host group to add host parameters only to a host group.
-
Enable the Puppet agent using a host parameter in global parameters or a host group. Add a host parameter named
enable-puppet7
, select the boolean type, and set the value totrue
. -
Specify configuration for the Puppet agent using the following host parameters in global parameters or a host group:
-
Add a host parameter named
puppet_server
, select the string type, and set the value to the hostname of your Puppet server, such aspuppet.example.com
. -
Optional: Add a host parameter named
puppet_ca_server
, select the string type, and set the value to the hostname of your Puppet CA server, such aspuppet-ca.example.com
. Ifpuppet_ca_server
is not set, the Puppet agent will use the same server aspuppet_server
. -
Optional: Add a host parameter named
puppet_environment
, select the string type, and set the value to the Puppet environment you want the host to use.
Until the BZ2177730 is resolved, you must use host parameters to specify the Puppet agent configuration even in integrated setups where the Puppet server is a Smart Proxy server.
-
-
Navigate to Hosts > Register Host and register your host using an appropriate activation key. For more information, see Registering Hosts in Managing hosts.
-
Navigate to Infrastructure > Smart Proxies.
-
From the list in the Actions column for the required Smart Proxy server, select Certificates.
-
Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.
4.5. Installing and configuring Puppet agent manually
You can install and configure the Puppet agent on a host manually. A configured Puppet agent is required on the host for Puppet integration with your Foreman. For more information about Puppet, see Configuring hosts by using Puppet.
-
The host must have a Puppet environment assigned to it.
-
Ensure a repository containing the Puppet agent is enabled on the host, for example apt.puppet.com or yum.puppet.com.
-
Log in to the host as the
root
user. -
Install the Puppet agent package.
-
On hosts running Enterprise Linux 8 and above:
# dnf install puppet-agent
-
On hosts running Debian:
# apt install puppet-agent
-
On hosts running SUSE Linux Enterprise Server:
# zypper install puppet-agent
-
-
Add the Puppet agent to
PATH
in your current shell using the following script:. /etc/profile.d/puppet-agent.sh
-
Configure the Puppet agent. Set the
environment
parameter to the name of the Puppet environment to which the host belongs:# puppet config set server foreman.example.com --section agent # puppet config set environment My_Puppet_Environment --section agent
-
Start the Puppet agent service:
# puppet resource service puppet ensure=running enable=true
-
Create a certificate for the host:
# puppet ssl bootstrap
-
In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
-
From the list in the Actions column for the required Smart Proxy server, select Certificates.
-
Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.
-
On the host, run the Puppet agent again:
# puppet ssl bootstrap
4.6. Using SSL certificate for hosts
You can use SSL certificate on your hosts to enable encrypted communications between Foreman server, Smart Proxy server, and hosts. Before deploying it to your hosts, ensure that you have configured the SSL certificate to your Foreman server.
4.6.1. Deploying a SSL certificate to hosts
After you configure Foreman to use a SSL certificate, you must deploy the certificate to hosts registered to Foreman.
-
Update the SSL certificate on each host:
-
On Debian and Ubuntu:
# wget http://foreman.example.com/pub/katello-rhsm-consumer # chmod +x katello-rhsm-consumer # ./katello-rhsm-consumer
-
On Enterprise Linux 8+:
# dnf install http://foreman.example.com/pub/katello-ca-consumer-latest.noarch.rpm
-
On Enterprise Linux 7:
# yum install http://foreman.example.com/pub/katello-ca-consumer-latest.noarch.rpm
-
On OpenSUSE and SUSE Linux Enterprise Server:
# zypper install http://foreman.example.com/pub/katello-ca-consumer-latest.noarch.rpm
-
4.7. Resetting SSL certificate to default self-signed certificate on hosts
To reset the SSL certificate on your hosts to default self-signed certificate, you must re-register your hosts through Global Registration. For more information, see Registering hosts by using global registration.
-
Reset SSL certificate to default self-signed certificate on Foreman server in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
Reset SSL certificate to default self-signed certificate on Smart Proxy server in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
5. Adding network interfaces
Foreman supports specifying multiple network interfaces for a single host. You can configure these interfaces when creating a new host as described in Creating a host in Foreman or when editing an existing host.
There are several types of network interfaces that you can attach to a host. When adding a new interface, select one of:
-
Interface: Allows you to specify an additional physical or virtual interface. There are two types of virtual interfaces you can create. Use VLAN when the host needs to communicate with several (virtual) networks using a single interface, while these networks are not accessible to each other. Use alias to add an additional IP address to an existing interface.
For more information about adding a physical interface, see Adding a physical interface.
For more information about adding a virtual interface, see Adding a virtual interface.
-
Bond: Creates a bonded interface. NIC bonding is a way to bind multiple network interfaces together into a single interface that appears as a single device and has a single MAC address. This enables two or more network interfaces to act as one, increasing the bandwidth and providing redundancy. For more information, see Adding a bonded interface.
-
BMC: Baseboard Management Controller (BMC) allows you to remotely monitor and manage the physical state of machines. For more information about BMC, see Enabling Power Management on Hosts in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux. For more information about configuring BMC interfaces, see Adding a baseboard management controller (BMC) interface.
Note
|
Additional interfaces have the Managed flag enabled by default, which means the new interface is configured automatically during provisioning by the DNS and DHCP Smart Proxy servers associated with the selected subnet.
This requires a subnet with correctly configured DNS and DHCP Smart Proxy servers.
If you use a Kickstart method for host provisioning, configuration files are automatically created for managed interfaces in the post-installation phase at |
Note
|
Virtual and bonded interfaces currently require a MAC address of a physical device. Therefore, the configuration of these interfaces works only on bare-metal hosts. |
5.1. Adding a physical interface
Use this procedure to add an additional physical interface to a host.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click Edit next to the host you want to edit.
-
On the Interfaces tab, click Add Interface.
-
Keep the Interface option selected in the Type list.
-
Specify a MAC address. This setting is required.
-
Specify the Device Identifier, for example eth0. The identifier is used to specify this physical interface when creating bonded interfaces, VLANs, and aliases.
-
Specify the DNS name associated with the host’s IP address. Foreman saves this name in Smart Proxy server associated with the selected domain (the "DNS A" field) and Smart Proxy server associated with the selected subnet (the "DNS PTR" field). A single host can therefore have several DNS entries.
-
Select a domain from the Domain list. To create and manage domains, navigate to Infrastructure > Domains.
-
Select a subnet from the Subnet list. To create and manage subnets, navigate to Infrastructure > Subnets.
-
Specify the IP address. Managed interfaces with an assigned DHCP Smart Proxy server require this setting for creating a DHCP lease. DHCP-enabled managed interfaces are automatically provided with a suggested IP address.
-
Select whether the interface is Managed. If the interface is managed, configuration is pulled from the associated Smart Proxy server during provisioning, and DNS and DHCP entries are created. If using kickstart provisioning, a configuration file is automatically created for the interface.
-
Select whether this is the Primary interface for the host. The DNS name from the primary interface is used as the host portion of the FQDN.
-
Select whether this is the Provision interface for the host. TFTP boot takes place using the provisioning interface. For image-based provisioning, the script to complete the provisioning is executed through the provisioning interface.
-
Select whether to use the interface for Remote execution.
-
Leave the Virtual NIC checkbox clear.
-
Click OK to save the interface configuration.
-
Click Submit to apply the changes to the host.
5.2. Adding a virtual interface
Use this procedure to configure a virtual interface for a host. This can be either a VLAN or an alias interface.
An alias interface is an additional IP address attached to an existing interface.
An alias interface automatically inherits a MAC address from the interface it is attached to; therefore, you can create an alias without specifying a MAC address.
The interface must be specified in a subnet with boot mode set to static
.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click Edit next to the host you want to edit.
-
On the Interfaces tab, click Add Interface.
-
Keep the Interface option selected in the Type list.
-
Specify the general interface settings. The applicable configuration options are the same as for the physical interfaces described in Adding a physical interface.
Specify a MAC address for managed virtual interfaces so that the configuration files for provisioning are generated correctly. However, a MAC address is not required for virtual interfaces that are not managed.
If creating a VLAN, specify ID in the form of eth1.10 in the Device Identifier field. If creating an alias, use ID in the form of eth1:10.
-
Select the Virtual NIC checkbox. Additional configuration options specific to virtual interfaces are appended to the form:
-
Tag: Optionally set a VLAN tag to trunk a network segment from the physical network through to the virtual interface. If you do not specify a tag, managed interfaces inherit the VLAN tag of the associated subnet. User-specified entries from this field are not applied to alias interfaces.
-
Attached to: Specify the identifier of the physical interface to which the virtual interface belongs, for example eth1. This setting is required.
-
-
Click OK to save the interface configuration.
-
Click Submit to apply the changes to the host.
5.3. Adding a bonded interface
Use this procedure to configure a bonded interface for a host. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click Edit next to the host you want to edit.
-
On the Interfaces tab, click Add Interface.
-
Select Bond from the Type list. Additional type-specific configuration options are appended to the form.
-
Specify the general interface settings. The applicable configuration options are the same as for the physical interfaces described in Adding a physical interface.
Bonded interfaces use IDs in the form of bond0 in the Device Identifier field.
A single MAC address is sufficient.
If you are adding a secondary interface, select Managed. Otherwise, Foreman does not apply the configuration.
-
Specify the configuration options specific to bonded interfaces:
-
Mode: Select the bonding mode that defines a policy for fault tolerance and load balancing. See Bonding modes available in Foreman for a brief description of each bonding mode.
-
Attached devices: Specify a comma-separated list of identifiers of attached devices. These can be physical interfaces or VLANs.
-
Bond options: Specify a space-separated list of configuration options, for example miimon=100.
-
-
Click OK to save the interface configuration.
-
Click Submit to apply the changes to the host.
-
To create a host with a bonded interface, enter the following command:
# hammer host create \ --ask-root-password yes \ --hostgroup My_Host_Group \ --ip=My_IP_Address \ --mac=My_MAC_Address \ --managed true \ --interface="identifier=My_NIC_1, mac=_My_MAC_Address_1, managed=true, type=Nic::Managed, domain_id=My_Domain_ID, subnet_id=My_Subnet_ID" \ --interface="identifier=My_NIC_2, mac=My_MAC_Address_2, managed=true, type=Nic::Managed, domain_id=My_Domain_ID, subnet_id=My_Subnet_ID" \ --interface="identifier=bond0, ip=My_IP_Address_2, type=Nic::Bond, mode=active-backup, attached_devices=[My_NIC_1,My_NIC_2], managed=true, domain_id=My_Domain_ID, subnet_id=My_Subnet_ID" \ --location "My_Location" \ --name "My_Host_Name" \ --organization "My_Organization" \ --subnet-id=My_Subnet_ID
5.4. Bonding modes available in Foreman
Bonding Mode | Description |
---|---|
balance-rr |
Transmissions are received and sent sequentially on each bonded interface. |
active-backup |
Transmissions are received and sent through the first available bonded interface. Another bonded interface is only used if the active bonded interface fails. |
balance-xor |
Transmissions are based on the selected hash policy. In this mode, traffic destined for specific peers is always sent over the same interface. |
broadcast |
All transmissions are sent on all bonded interfaces. |
802.a3 |
Creates aggregation groups that share the same settings. Transmits and receives on all interfaces in the active group. |
balance-tlb |
The outgoing traffic is distributed according to the current load on each bonded interface. |
balance-alb |
Receive load balancing is achieved through Address Resolution Protocol (ARP) negotiation. |
5.5. Adding a baseboard management controller (BMC) interface
You can control the power status of bare-metal hosts from Foreman. Use this procedure to configure a baseboard management controller (BMC) interface for a host that supports this feature.
-
You know the MAC address, IP address, and other details of the BMC interface on the host, and authentication credentials for that interface.
NoteYou only need the MAC address for the BMC interface if the BMC interface is managed, so that it can create a DHCP reservation.
-
Enable BMC power management on your Smart Proxy:
# foreman-installer \ --foreman-proxy-bmc-default-provider=ipmitool \ --foreman-proxy-bmc=true
-
In the Foreman web UI, navigate to Infrastructure > Subnets.
-
Select the subnet of your host.
-
On the Proxies tab, select your Smart Proxy as BMC Proxy.
-
Click Submit.
-
Navigate to Hosts > All Hosts.
-
Click Edit next to the host you want to edit.
-
On the Interfaces tab, click Add Interface.
-
Select BMC from the Type list. Type-specific configuration options are appended to the form.
-
Specify the general interface settings. The applicable configuration options are the same as for the physical interfaces described in Adding a physical interface.
-
Specify the configuration options specific to BMC interfaces:
-
Username and Password: Specify any authentication credentials required by BMC.
-
Provider: Specify the BMC provider.
-
-
Click OK to save the interface configuration.
-
Click Submit to apply the changes to the host.
6. Upgrading hosts to next major Enterprise Linux release
You can use a job template to upgrade your Enterprise Linux hosts to the next major release. Below upgrade paths are possible:
-
Enterprise Linux 7 to Enterprise Linux 8
-
Enterprise Linux 8 to Enterprise Linux 9
-
Ensure that your Enterprise Linux hosts meet the requirements for the upgrade.
-
For Enterprise Linux 7 to Enterprise Linux 8 upgrade, see Planning an upgrade in Upgrading from RHEL 7 to RHEL 8.
-
For Enterprise Linux 8 to Enterprise Linux 9 upgrade, see Planning an upgrade to RHEL 9 in Upgrading from RHEL 8 to RHEL 9.
-
-
Prepare your Enterprise Linux hosts for the upgrade.
-
For Enterprise Linux 7 to Enterprise Linux 8 upgrade, see Preparing a RHEL 7 system for the upgrade in Upgrading from RHEL 7 to RHEL 8.
-
For Enterprise Linux 8 to Enterprise Linux 9 upgrade, see Preparing a RHEL 8 system for the upgrade in Upgrading from RHEL 8 to RHEL 9.
-
-
Enable remote execution feature on Foreman. For more information, see Configuring and setting up remote jobs.
-
Distribute Foreman SSH keys to the hosts that you want to upgrade. For more information, see Distributing SSH keys for remote execution.
-
On Foreman, enable the Leapp plugin:
# foreman-installer --enable-foreman-plugin-leapp
-
If you are using a custom job template for the Leapp pre-upgrade check, configure the leapp_preupgrade remote execution feature to point to your template:
-
In the Foreman web UI, navigate to Administer > Remote Execution Features.
-
Click leapp_preupgrade.
-
In the Job Template dropdown menu, select your template.
-
Click Submit.
-
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Select the hosts that you want to upgrade to the next major Enterprise Linux version.
-
From the Schedule Remote Job list, select Preupgrade check with Leapp.
-
When the check is finished, click the Leapp preupgrade report tab to see if Leapp has found any issues on your hosts. Issues that have the Inhibitor flag are considered crucial and are likely to break the upgrade procedure. Issues that have the Has Remediation flag contain remediation that can help you fix the issue.
-
Click an issue that is flagged as Has Remediation to expand it.
-
If the issue contains a remediation Command, you can fix it directly from Foreman using remote execution. Select the issue.
-
If the issue contains only a remediation Hint, use the hint to fix the issue on the host manually.
Repeat this step for other issues.
-
-
After you selected any issues with remediation commands, click Fix Selected and submit the job.
-
After the issues are fixed, click Rerun, and then click Submit to run the pre-upgrade check again to verify that the hosts you are upgrading do not have any issues and are ready to be upgraded.
-
-
If the pre-upgrade check verifies that the hosts do not have any issues, click Run Upgrade and click Submit to start the upgrade. Alternatively, you can upgrade your host by selecting Upgrade with Leapp in the Schedule Remote Job drop down menu.
7. Converting a host to Red Hat Enterprise Linux
You can convert Red Hat Enterprise Linux derivative distributions into a supportable Red Hat Enterprise Linux on a host while retaining installed applications and configurations. Foreman provides Convert2RHEL utilities to simplify the conversion process.
The Convert2RHEL utilities in Foreman contain an Ansible role and Ansible Playbook. You use the Ansible role to generate conversion data on Foreman server, which includes enabling required repositories and creating products, activation keys, and host groups. Then you perform the actual conversion on the host using the Ansible Playbook, which installs the Convert2RHEL CLI tool on the host and runs it.
You can use the Ansible role to generate conversion data for the following conversions:
-
CentOS Linux 7 to Red Hat Enterprise Linux 7
-
Oracle Linux 7 to Red Hat Enterprise Linux 7
-
Oracle Linux 8 to Red Hat Enterprise Linux 8
These conversions are supported by Red Hat. You can use the Ansible Playbook for other conversions as well, but in those cases you must enable required repositories and configure activation keys manually instead of using the Ansible role and variables. However, this approach was not tested and is not supported.
The conversion process is similar to a minor release upgrade of Red Hat Enterprise Linux in which every RPM package on the system is replaced. Third-party packages and non-Red Hat packages that are not available in Red Hat Enterprise Linux are retained.
The Convert2RHEL utility removes unnecessary packages such as logos or packages known to cause issues during the conversion.
The utility replaces the CentOS-release
or Oracle-release
package with the rhel-release
package, and all packages signed by CentOS or Oracle with their Red Hat equivalents.
The utility also subscribes the host to Foreman community Subscription Management.
The duration of the conversion process depends on the number of packages that have to be replaced, network speed, storage speed, and similar factors.
-
Review Supported conversion paths in Red Hat Enterprise Linux 8 Converting from a Linux distribution to RHEL using the Convert2RHEL utility.
-
You must have completed the steps 1. – 5. of the procedure Preparing for a RHEL conversion in Red Hat Enterprise Linux 8 Converting from a Linux distribution to RHEL using the Convert2RHEL utility.
-
Ensure you have a subscription manifest uploaded to your Foreman and that there are sufficient Red Hat Enterprise Linux entitlements allocated for the conversions you intend. Alternatively, you can use Ansible variables to tell the role to import the manifest from disk. The manifest must be imported to the organization to which you will register hosts for conversion.
You can update your allocations and download the updated manifest from the Red Hat Customer Portal. For more information, see Exporting and downloading a manifest in Creating and managing manifests for a connected Satellite Server.
-
Ensure that you have enabled and synchronized Red Hat repositories in Foreman for the minor Red Hat Enterprise Linux version to which you convert your hosts. For more information, see Enabling Red Hat Repositories and Synchronizing Repositories in Managing content.
-
Import the
theforeman.foreman.convert2rhel
Ansible role and variables. For more information, see Importing Ansible Roles and Variables in Configuring hosts by using Ansible. -
Configure Ansible variables for generation of conversion data. For more information, see Ansible variables for conversion.
-
Assign the
theforeman.foreman.convert2rhel
role to the host that represents Foreman server. For more information, see Assigning Ansible Roles to an Existing Host in Configuring hosts by using Ansible. -
Run the Ansible role on Foreman server. For more information, see Running Ansible Roles on a Host in Configuring hosts by using Ansible.
The Ansible role generates data required for host conversion, that is, repositories, certificates, activation keys, and host groups. The role enables the
rhel-7-server-rpms
repository with the 7Server release and x86_64 architecture, orrhel-8-for-x86_64-baseos-rpms
andrhel-8-for-x86_64-appstream-rpms
, or both, depending on which variables you have set in the previous steps. -
Register a host for conversion using a generated host group.
Use the global registration template to register and subscribe your host before the conversion. Select the host group that was generated for the conversion you intend, such as
CentOS 7 converting
if you convert the host from CentOS 7. For more information, see Registering hosts by using global registration. -
Run the pre-conversion analysis on the host group to verify if your hosts are ready for the conversion. Execute a remote job with the following settings:
-
Job category:
Convert 2 RHEL
-
Job template:
Convert2RHEL analyze
For more information, see Executing a remote job.
Review pre-conversion analysis reports and resolve all issues that are blocking the conversion. Repeat this step until you resolve all blocking issues. For more information, see Reviewing the pre-conversion analysis report in Red Hat Enterprise Linux 8 Converting from a Linux distribution to RHEL using the Convert2RHEL utility.
-
-
Run the Convert2RHEL playbook on the host group. Execute a remote job with the following settings:
-
Job category:
Convert 2 RHEL
-
Job template:
Convert to RHEL
-
Activation key:
-
convert2rhel_rhel7
if you convert to Red Hat Enterprise Linux 7 -
convert2rhel_rhel8
if you convert to Red Hat Enterprise Linux 8
-
For more information, see Executing a remote job.
-
-
How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL in the Red Hat Knowledgebase
-
Convert2RHEL CLI tool on GitHub
7.1. Ansible variables for conversion
Before you run the Ansible role to generate conversion data, configure values of the following required Ansible variables.
Foreman imports most of the required Ansible variables from the theforeman.foreman.convert2rhel
role.
However, some variables are not imported.
These variables are marked with an asterisk *
in the tables below.
You must create those additional variables manually and assign them to the theforeman.foreman.convert2rhel
role.
Name | Type | Intent and value |
---|---|---|
|
string |
URL of your Foreman server, such as |
|
string |
Your user name |
|
string |
Your password |
|
string |
Name of your organization |
|
boolean |
Set to |
|
boolean |
Set to |
|
boolean |
Set to |
|
boolean |
Enables Red Hat Enterprise Linux 7 repositories.
Set to |
|
boolean |
Set to |
|
boolean |
Enables Red Hat Enterprise Linux 8 repositories.
Set to |
|
boolean |
Set to |
Name | Type | Intent and value |
---|---|---|
|
string |
Path to a manifest to upload from disk, such as |
|
string |
Minor release version, such as |
8. Host management and monitoring using Cockpit
You can use the Cockpit interactive web interface to perform actions and monitor Enterprise Linux hosts. You can enable a remote-execution feature to integrate Foreman with Cockpit. When you install Cockpit on a host that you manage with Foreman, you can view the Cockpit dashboards of that host from within the Foreman web UI. You can also use the features that are integrated with Cockpit, for example, Lorax Composer.
8.1. Enabling Cockpit on Foreman
By default, Cockpit integration is disabled in Foreman. If you want to access Cockpit features for your hosts from within Foreman, you must first enable Cockpit on Foreman server.
-
Enable Cockpit on your Foreman server:
# foreman-installer --enable-foreman-plugin-remote-execution-cockpit --reset-foreman-plugin-remote-execution-cockpit-ensure
8.2. Managing and monitoring hosts using Cockpit
You can access the Cockpit UI through the Foreman web UI and use the functionality to manage and monitor hosts in Foreman.
-
You have enabled Cockpit in Foreman.
-
You have installed Cockpit on the host that you want to view:
-
For more information, see Running Cockpit.
-
-
Foreman or Smart Proxy can authenticate to the host with SSH keys. For more information, see Distributing SSH keys for remote execution.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select the host that you want to manage and monitor with Cockpit.
-
In the upper right of the host window, click the vertical ellipsis and select Web Console.
You can now access the full range of features available for host monitoring and management, for example, Lorax Composer, through Cockpit.
8.3. Disabling Cockpit on Foreman
Perform the following procedure if you want to disable Cockpit on Foreman.
-
Disable Cockpit on your Foreman server:
# foreman-installer --foreman-plugin-remote-execution-cockpit-ensure absent
Important
|
You can enable or disable Cockpit integration independently on Smart Proxy servers. To prevent enabling Cockpit integration on a Smart Proxy server, enter the following command after completing the procedure: # foreman-installer --foreman-proxy-plugin-remote-execution-script-cockpit-integration false |
9. Using the KernelCare plugin
You can use the KernelCare plugin to patch the Linux kernel on hosts without rebooting them. The plugin provides job templates to view and live-patch the Linux kernel on hosts and ensures hosts do not report to Foreman server that a reboot is required through tracer. For more information, see tuxcare.com/live-patching-services and docs.tuxcare.com/live-patching-services.
Important
|
The KernelCare plugin is a technical preview. Foreman community does not recommend running this in your production environment. |
9.1. Installing the KernelCare plugin
Use the following procedure to install the KernelCare plugin.
-
Install the plugin on your Foreman server:
# foreman-installer --enable-foreman-plugin-kernel-care
9.2. KernelCare client
You need to provide the KernelCare client to your hosts. Synchronize the required repositories depending on the operating system of your hosts.
After synchronization, ensure to make the content consumable to your hosts.
9.2.1. Creating KernelCare repositories for Enterprise Linux 9
You need to provide the KernelCare client on your hosts to live-patch their Linux kernel.
-
In the Foreman web UI, navigate to Content > Products.
-
Click Create Product to create a product named
KernelCare Enterprise Linux
. For more information, see Creating a product in Managing content. -
On the Repositories tab, click New Repository to create a repository of type
yum
as follows:-
Name:
KernelCare Enterprise Linux 9
-
Upstream URL:
https://repo.cloudlinux.com/kernelcare/9/x86_64/
-
Optional: Add the KernelCare GPG pub key as content credential:
https://repo.cloudlinux.com/kernelcare/RPM-GPG-KEY-KernelCare
.
For more information, see Adding RPM Repositories in Managing content.
-
9.2.2. Creating KernelCare repositories for Enterprise Linux 8
You need to provide the KernelCare client on your hosts to live-patch their Linux kernel.
-
In the Foreman web UI, navigate to Content > Products.
-
Click Create Product to create a product named
KernelCare Enterprise Linux
. For more information, see Creating a product in Managing content. -
On the Repositories tab, click New Repository to create a repository of type
yum
as follows:-
Name:
KernelCare Enterprise Linux 8
-
Upstream URL:
https://repo.cloudlinux.com/kernelcare/8/x86_64/
-
Optional: Add the KernelCare GPG pub key as content credential:
https://repo.cloudlinux.com/kernelcare/RPM-GPG-KEY-KernelCare
.
For more information, see Adding RPM Repositories in Managing content.
-
9.2.3. Creating KernelCare repositories for Enterprise Linux 7
You need to provide the KernelCare client on your hosts to live-patch their Linux kernel.
-
In the Foreman web UI, navigate to Content > Products.
-
Click Create Product to create a product named
KernelCare Enterprise Linux
. For more information, see Creating a product in Managing content. -
On the Repositories tab, click New Repository to create a repository of type
yum
as follows:-
Name:
KernelCare Enterprise Linux 7
-
Upstream URL:
https://repo.cloudlinux.com/kernelcare/7/x86_64/
-
Optional: Add the KernelCare GPG pub key as content credential:
https://repo.cloudlinux.com/kernelcare/RPM-GPG-KEY-KernelCare
.
For more information, see Adding RPM Repositories in Managing content.
-
9.3. Installing the KernelCare package on hosts
You can use kernelcare
to patch the Linux kernel on hosts without rebooting them.
-
Your hosts have access to the KernelCare repository. For more information, see KernelCare client.
-
In the Foreman web UI, navigate to Monitor > Jobs and click Run job.
-
Select Katello as Job category and Install Package – Katello Script Default as Job template and click Next.
-
Select hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.
-
In the package field, enter
kernelcare
and click Next. -
Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Advanced settings in the job wizard.
-
Click Next.
-
Select Immediate execution to execute the job immediately and click Next.
-
Review job details. You have the option to return to any part of the job wizard and edit the information.
-
Click Run to install
kernelcare
on your hosts.
9.4. Viewing patched kernel version
You can use a job template to view the patched kernel version on hosts.
-
Ensure the
kernelcare
package is installed on your hosts. For more information, see Installing the KernelCare package on hosts.
-
In the Foreman web UI, navigate to Monitor > Jobs and click Run job.
-
Select LivePatching – Script Default as Job category and LivePatching – Kernel version as Job template and click Next.
-
Select hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.
-
Click Next.
-
Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Advanced settings in the job wizard.
-
Click Next.
-
Select Immediate execution to execute the job immediately and click Next.
-
Review job details. You have the option to return to any part of the job wizard and edit the information.
-
Click Run to view the running Kernel version on your hosts.
9.5. Live patching hosts using KernelCare plugin
You can use kcarectl
provided by TuxCare to live-patch the Linux kernel on your hosts.
By default, kcarectl
checks for updates every four hours.
If the automatic installation of patches is disabled or if you want to install patches manually at a certain time, you can start the process using a remote execution job.
-
Ensure your hosts have the
kernelcare
package installed. -
Ensure your hosts run Enterprise Linux 7, Enterprise Linux 8, or Enterprise Linux 9.
-
Ensure your hosts have access to the internet to connect to cloudlinux.com.
If your host is in a disconnected environment, you can use ePortal by Tuxcare to provide Linux kernel patches. For more information, see docs.tuxcare.com/eportal.
-
In the Foreman web UI, navigate to Monitor > Jobs and click Run job.
-
Select LivePatching – Script Default as Job category and LivePatching – Update kernel as Job template and click Next.
-
Select hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.
-
Click Next.
-
Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Advanced settings in the job wizard.
-
Click Next.
-
Select Immediate execution to execute the job immediately and click Next.
-
Review job details. You have the option to return to any part of the job wizard and edit the information.
-
Click Run to update to the latest Linux kernel on your hosts.
-
For more information on live-patching hosts, see docs.tuxcare.com/live-patching-services.
10. Using report templates to monitor hosts
You can use report templates to query Foreman data to obtain information about, for example, host status, registered hosts, applicable errata, applied errata, and user activity. You can use the report templates that ship with Foreman or write your own custom report templates to suit your requirements. The reporting engine uses the embedded Ruby (ERB) syntax. For more information about writing templates and ERB syntax, see Template writing reference.
You can create a template, or clone a template and edit the clone. For help with the template syntax, click a template and click the Help tab.
10.1. Generating host monitoring reports
To view the report templates in the Foreman web UI, navigate to Monitor > Reports > Report Templates. To schedule reports, configure a cron job or use the Foreman web UI.
-
In the Foreman web UI, navigate to Monitor > Reports > Report Templates. For example, the Host – Installed Products template generates a report with installed product information along with other metrics, including system purpose attributes.
-
To the right of the report template that you want to use, click Generate.
-
Optional: To schedule a report, to the right of the Generate at field, click the icon to select the date and time you want to generate the report at.
-
Optional: To send a report to an e-mail address, select the Send report via e-mail checkbox, and in the Deliver to e-mail addresses field, enter the required e-mail address.
-
Optional: Apply search query filters. To view all available results, do not populate the filter field with any values.
-
Click Submit. A CSV file that contains the report is downloaded. If you have selected the Send report via e-mail checkbox, the host monitoring report is sent to your e-mail address.
-
List all available report templates:
# hammer report-template list
-
Generate a report:
# hammer report-template generate --id My_Template_ID
This command waits until the report fully generates before completing. If you want to generate the report as a background task, you can use the
hammer report-template schedule
command.NoteIf you want to generate the Subscription - General report, you have to use the
Days from Now
option to specify the latest expiration time of general subscriptions.Show all subscriptions# hammer report-template generate \ --inputs "Days from Now=no limit" \ --name "Subscription - General Report"
Show all subscriptions that are going to expire within 60 days# hammer report-template generate \ --inputs "Days from Now=60" \ --name "Subscription - General Report"
10.2. Creating a report template
In Foreman, you can create a report template and customize the template to suit your requirements. You can import existing report templates and further customize them with snippets and template macros.
Report templates use Embedded Ruby (ERB) syntax. To view information about working with ERB syntax and macros, in the Foreman web UI, navigate to Monitor > Reports > Report Templates, and click Create Template, and then click the Help tab.
When you create a report template in Foreman, safe mode is enabled by default.
-
In the Foreman web UI, navigate to Monitor > Reports > Report Templates.
-
Click Create Template.
-
In the Name field, enter a unique name for your report template.
-
If you want the template to be available to all locations and organizations, select Default.
-
Create the template directly in the template editor or import a template from a text file by clicking Import. For more information about importing templates, see Importing report templates.
-
Optional: In the Audit Comment field, you can add any useful information about this template.
-
Click the Input tab, and in the Name field, enter a name for the input that you can reference in the template in the following format:
input('name')
. Note that you must save the template before you can reference this input value in the template body. -
Select whether the input value is mandatory. If the input value is mandatory, select the Required checkbox.
-
From the Value Type list, select the type of input value that the user must input.
-
Optional: If you want to use facts for template input, select the Advanced checkbox.
-
Optional: In the Options field, define the options that the user can select from. If this field remains undefined, the users receive a free-text field in which they can enter the value they want.
-
Optional: In the Default field, enter a value, for example, a host name, that you want to set as the default template input.
-
Optional: In the Description field, you can enter information that you want to display as inline help about the input when you generate the report.
-
Optional: Click the Type tab, and select whether this template is a snippet to be included in other templates.
-
Click the Location tab and add the locations where you want to use the template.
-
Click the Organizations tab and add the organizations where you want to use the template.
-
Click Submit to save your changes.
-
For more information about safe mode, see Report template safe mode.
-
For more information about writing templates, see Template writing reference.
-
For more information about macros you can use in report templates, see Template macros.
10.3. Exporting report templates
You can export report templates that you create in Foreman.
-
In the Foreman web UI, navigate to Monitor > Reports > Report Templates.
-
Locate the template that you want to export, and from the list in the Actions column, select Export.
-
Repeat this action for every report template that you want to download.
An .erb
file that contains the template downloads.
-
To view the report templates available for export, enter the following command:
# hammer report-template list
Note the template ID of the template that you want to export in the output of this command.
-
To export a report template, enter the following command:
# hammer report-template dump --id My_Template_ID > example_export.erb
10.4. Exporting report templates using the Foreman API
You can use the Foreman report_templates
API to export report templates from Foreman.
-
Use the following request to retrieve a list of available report templates:
Example request:$ curl --insecure --user admin:redhat \ --request GET \ --config https://foreman.example.com/api/report_templates \ | json_reformat
In this example, the
json_reformat
tool is used to format the JSON output.Example response:{ "total": 6, "subtotal": 6, "page": 1, "per_page": 20, "search": null, "sort": { "by": null, "order": null }, "results": [ { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Applicable errata", "id": 112 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Applied Errata", "id": 113 }, { "created_at": "2019-11-30 16:15:24 UTC", "updated_at": "2019-11-30 16:15:24 UTC", "name": "Hosts - complete list", "id": 158 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Host statuses", "id": 114 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Registered hosts", "id": 115 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Subscriptions", "id": 116 } ] }
-
Note the
id
of the template that you want to export, and use the following request to export the template:Example request:$ curl --insecure --output /tmp/_Example_Export_Template.erb_ \ --user admin:password --request GET --config \ https://foreman.example.com/api/report_templates/My_Template_ID/export
Note that
158
is an example ID of the template to export.In this example, the exported template is redirected to
host_complete_list.erb
.
10.5. Importing report templates
You can import a report template into the body of a new template that you want to create. Note that using the Foreman web UI, you can only import templates individually. For bulk actions, use the Foreman API. For more information, see Importing report templates using the Foreman API.
-
You must have exported templates from Foreman to import them to use in new templates. For more information see Exporting report templates.
-
In the Foreman web UI, navigate to Monitor > Reports > Report Templates.
-
In the upper right of the Report Templates window, click Create Template.
-
On the upper right of the Editor tab, click the folder icon, and select the
.erb
file that you want to import. -
Edit the template to suit your requirements.
-
Click Submit.
For more information about customizing your new template, see Template writing reference.
10.6. Importing report templates using the Foreman API
You can use the Foreman API to import report templates into Foreman. Importing report templates using the Foreman API automatically parses the report template metadata and assigns organizations and locations.
-
Create a template using
.erb
syntax or export a template from another Foreman.For more information about writing templates, see Template writing reference.
For more information about exporting templates from Foreman, see Exporting report templates using the Foreman API.
-
Use the following example to format the template that you want to import to a
.json
file:# cat Example_Template.json { "name": "Example Template Name", "template": " Enter ERB Code Here " }
Example JSON file with ERB template:{ "name": "Hosts - complete list", "template": " <%# name: Hosts - complete list snippet: false template_inputs: - name: host required: false input_type: user advanced: false value_type: plain resource_type: Katello::ActivationKey model: ReportTemplate -%> <% load_hosts(search: input('host')).each_record do |host| -%> <% report_row( 'Server FQDN': host.name ) -%> <% end -%> <%= report_render %> " }
-
Use the following request to import the template:
$ curl --insecure --user admin:redhat \ --data @Example_Template.json --header "Content-Type:application/json" \ --request POST --config https://foreman.example.com/api/report_templates/import
-
Use the following request to retrieve a list of report templates and validate that you can view the template in Foreman:
$ curl --insecure --user admin:redhat \ --request GET --config https://foreman.example.com/api/report_templates | json_reformat
10.7. Generating a list of installed packages
Use this procedure to generate a list of installed packages in Report Templates.
-
In the Foreman web UI, navigate to Monitor > Reports > Report Templates.
-
To the right of Host - All Installed Packages, click Generate.
-
Optional: Use the Hosts filter search field to search for and apply specific host filters.
-
Click Generate.
-
If the download does not start automatically, click Download.
-
You have the spreadsheet listing the installed packages for the selected hosts downloaded on your machine.
10.8. Report template safe mode
When you create report templates in Foreman, safe mode is enabled by default. Safe mode limits the macros and variables that you can use in the report template. Safe mode prevents rendering problems and enforces best practices in report templates. The list of supported macros and variables is available in the Foreman web UI.
To view the macros and variables that are available, in the Foreman web UI, navigate to Monitor > Reports > Report Templates and click Create Template. In the Create Template window, click the Help tab and expand Safe mode methods.
While safe mode is enabled, if you try to use a macro or variable that is not listed in Safe mode methods, the template editor displays an error message.
To view the status of safe mode in Foreman, in the Foreman web UI, navigate to Administer > Settings and click the Provisioning tab. Locate the Safemode rendering row to check the value.
11. Configuring host collections
A host collection is a group of content hosts. This feature enables you to perform the same action on multiple hosts at once. These actions can include the installation, removal, and update of packages and errata, change of assigned lifecycle environment, and change of content view. You can create host collections to suit your requirements, and those of your company. For example, group hosts in host collections by function, department, or business unit.
11.1. Creating a host collection
The following procedure shows how to create host collections.
-
In the Foreman web UI, navigate to Hosts > Host Collections.
-
Click New Host Collection.
-
Add the Name of the host collection.
-
Clear Unlimited Content Hosts, and enter the desired maximum number of hosts in the Limit field.
-
Add the Description of the host collection.
-
Click Save.
-
To create a host collection, enter the following command:
# hammer host-collection create \ --name "My_Host_Collection" \ --organization "My_Organization"
11.2. Cloning a host collection
The following procedure shows how to clone a host collection.
-
In the Foreman web UI, navigate to Hosts > Host Collections.
-
On the left hand panel, click the host collection you want to clone.
-
Click Copy Collection.
-
Specify a name for the cloned collection.
-
Click Create.
11.3. Removing a host collection
Use the following procedure to remove a host collection from Foreman.
-
In the Foreman web UI, navigate to Hosts > Host Collections.
-
Select the host collection that you want to remove.
-
Under Select Action, click Remove.
-
Click Delete to remove the host collection.
11.4. Adding a host to a host collection
You can add a host to a host collection in the Foreman web UI.
A host must be registered to Foreman to add it to a Host Collection.
Note that if you add a host to a host collection, the Foreman auditing system does not log the change.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
In the Host collections card, click the vertical ellipsis and select Add host to collections.
-
Select the host collection.
-
Click Add.
-
To add a host to a host collection, enter the following command:
# hammer host-collection add-host \ --host-ids My_Host_ID_1 \ --id My_Host_Collection_ID
11.5. Adding hosts to a host collection in bulk
You can add multiple hosts to a host collection.
A host must be registered to Foreman to add it to a host collection.
Note that if you add a host to a host collection, the Foreman auditing system does not log the change.
-
In the Foreman web UI, navigate to Hosts > Host Collections.
-
Select the host collection where the host should be added.
-
On the Hosts tab, select the Add subtab.
-
Select the hosts to be added from the table and click Add Selected.
-
To add multiple hosts to a host collection, enter the following command:
# hammer host-collection add-host \ --host-ids My_Host_ID_1,My_Host_ID_2 \ --id My_Host_Collection_ID
11.6. Removing a host from a host collection
The following procedure shows how to remove hosts from host collections.
Note that if you remove a host from a host collection, the host collection record in the database is not modified so the Foreman auditing system does not log the change.
-
In the Foreman web UI, navigate to Hosts > Host Collections.
-
Choose the desired host collection.
-
On the Hosts tab, select the List/Remove subtab.
-
Select the hosts you want to remove from the host collection and click Remove Selected.
11.7. Adding content to a host collection
These steps show how to add content to host collections in Foreman.
11.7.1. Adding packages to a host collection
The following procedure shows how to add packages to host collections.
-
The content to be added should be available in one of the existing repositories or added prior to this procedure.
-
Content should be promoted to the environment where the hosts are assigned.
-
In the Foreman web UI, navigate to Hosts > Host Collections.
-
Select the host collection where the package should be added.
-
On the Collection Actions tab, click Package Installation, Removal, and Update.
-
To update all packages, click Update All Packages to use the default method. Alternatively, select the drop-down icon to the right of the button to select a method to use. Selecting the via remote execution – customize first menu entry will take you to the Job invocation page where you can customize the action.
-
Select the Package or Package Group radio button as required.
-
In the field provided, specify the package or package group name. Then click:
-
Install – to install a new package using the default method. Alternatively, select the drop-down icon to the right of the button and select a method to use. Selecting the via remote execution – customize first menu entry will take you to the Job invocation page where you can customize the action.
-
Update – to update an existing package in the host collection using the default method. Alternatively, select the drop-down icon to the right of the button and select a method to use. Selecting the via remote execution – customize first menu entry will take you to the Job invocation page where you can customize the action.
-
11.7.2. Viewing installed packages
Use the following procedure to view the installed packages of a host.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select the name of the host.
-
On the Content tab, Packages displays a list of installed packages.
-
To see details of a package, select that package.
-
The Details tab displays details of the selected package.
-
The Files tab lists the files contained in the package.
-
The Dependencies tab lists the dependencies of the package.
-
The Repositories tab lists the repositories that contain the selected package.
-
-
You can filter these by Library or Default organization.
11.7.3. Upgrading a package
Use the following procedure to view the installed packages of a host.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select the name of the host that contains the package you want to upgrade.
-
On the Content tab, select Packages.
The Status column displays whether the package is upgradable or Up-to date. You cannot update an up-to-date package.
-
From the list of packages, choose the package you want to upgrade and click the vertical ellipsis icon at the end of the line.
-
Choose the Apply via Remote Execution to use Remote Execution, or Apply via customized remote execution if you want to customize the remote execution, for example, to set a time when it should be applied.
-
Click Submit to upgrade the package.
11.7.4. Removing a package from a host
Use the following procedure to remove an installed package from a host.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select the host containing the package you want to remove.
-
On the Content tab, select Packages.
-
Click the vertical ellipsis icon at the end of the line for the package you want to remove, and choose the Remove option.
-
Click Submit.
11.7.5. Adding errata to a host collection
The following procedure shows how to add errata to host collections.
-
The errata to be added should be available in one of the existing repositories or added prior to this procedure.
-
Errata should be promoted to the environment where the hosts are assigned.
-
In the Foreman web UI, navigate to Hosts > Host Collections.
-
Select the host collection where the errata should be added.
-
On the Collection Actions tab, click Errata Installation.
-
Select the errata you want to add to the host collection and click Install Selected to use the default method. Alternatively, select the drop-down icon to the right of the button to select a method to use. Selecting the via remote execution – customize first menu entry takes you to the Job invocation page where you can customize the action.
11.7.6. Adding errata to a single host
Use the following procedure to add errata to a host.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Select the host you want to add errata to.
-
Click Content and select the Errata tab.
-
Select the errata you want to add to the host, or select the checkbox at the top of the list to add all installable errata. Click the checkbox next to any errata you wish to remove from a full list.
-
Using the vertical ellipsis icon next to the errata you want to add to the host, select Apply via Remote Execution to use Remote Execution, or select Apply via customized remote execution if you want to customize the remote execution.
-
Click Submit.
11.7.7. Applying installable errata
Use the following procedure to view a list of installable errata and select errata to install.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select the host you require.
-
If there are errata associated with the host, they are displayed in an Installable Errata card on the new Host page.
-
On the Content tab, Errata displays installable errata for the chosen host.
-
Click the checkbox for any errata you wish to install.
-
Using the vertical ellipsis icon next to the errata you want to add to the host, select Apply via Remote Execution to use Remote Execution. Select Apply via customized remote execution if you want to customize the remote execution.
-
Click Submit.
11.7.8. Filter errata by type and severity
Use the following procedure to filter errata by type or severity.
-
In the Foreman web UI, navigate to Hosts > All Hosts and click the name of the host.
-
On the Contents tab, Errata lists the errata associated with the selected host.
-
Click Type to filter errata by type.
-
You can filter to display errata of type Security, Bugfix, or Enhancement
-
Click Severity to filter by severity.
-
You can filter to display errata of severity N/A, Low, Moderate, Important, or Critical.
-
To deselect your choice, return to the list of options and click the selected option again.
You can also use the Errata card on the host page to pre-filter errata for type before display.
11.7.9. Viewing errata by applicable and installable
Use the following procedure to view errata by applicable or installable.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Select the host name.
-
Click the Overview tab. Under the Errata card, there are two types of Errata.
-
Click Applicable to view errata that apply to a package installed on your host.
-
Click Installable to view applicable errata that are available in the host content view and lifecycle environment.
-
Click the link with number of errata under each type to see the list of all available errata of that type.
-
Click security advisories, bug fixes, or enhancements under each type to view only the respective type of errata.
11.7.10. Generating a report for installable and applicable errata
Use the following procedure to generate a report of installable or applicable errata on hosts.
-
In the Foreman web UI, navigate to Monitor > Reports > Report Templates.
-
Click Generate for the Host – Applicable Errata template.
-
Optional: To schedule a report, click the calendar icon to the right of the Generate at field and choose the date and time you want for the generated report.
-
Optional: To send a report to an e-mail address, select the Send report via e-mail checkbox, and in the Deliver to e-mail addresses field, enter the required e-mail address.
-
Optional: Select another Output format for the report file. The default is CSV.
-
Optional: To limit the report only to hosts found by the search query, click on Hosts filter and search from the available list of hosts. For a report on all available hosts, leave Hosts filter empty.
-
Optional: To limit the report only to errata found by the search query, click on Errata filter and search from the available list of errata. For a report on all available errata, leave Errata filter empty.
-
From the Installability list, select one of these options:
-
Applicable to show all applicable errata.
-
Installable to limit the report exclusively to errata that are accessible in the content view environments of your host that may be installed.
-
-
Click Generate. Your browser automatically downloads the report file after Foreman creates it. If you have selected the Send report via e-mail option, the report is sent to your e-mail address.
11.7.11. Removing content from a host collection
The following procedure shows how to remove packages from host collections.
-
Click Hosts > Host Collections.
-
Click the host collection where the package should be removed.
-
On the Collection Actions tab, click Package Installation, Removal, and Update.
-
Select the Package or Package Group radio button as required.
-
In the field provided, specify the package or package group name.
-
Click Remove to remove the package or package group using the default method. Alternatively, select the drop-down icon to the right of the button and select a method to use. Selecting the via remote execution - customize first menu entry will take you to the Job invocation page where you can customize the action.
11.7.12. Changing the lifecycle environment or content view of a host collection
The following procedure shows how to change the assigned lifecycle environment or content view of host collections.
-
In the Foreman web UI, navigate to Hosts > Host Collection.
-
Selection the host collection where the lifecycle environment or content view should be changed.
-
On the Collection Actions tab, click Change assigned Lifecycle Environment or Content View.
-
Select the lifecycle environment to be assigned to the host collection.
-
Select the required content view from the list.
-
Click Assign.
NoteThe changes take effect in approximately 4 hours. To make the changes take effect immediately, on the host, enter the following command:
# subscription-manager refresh
You can use remote execution to run this command on multiple hosts at the same time.
12. Configuring and setting up remote jobs
Foreman supports remote execution of commands on hosts. Using remote execution, you can perform various tasks on multiple hosts simultaneously.
12.1. Remote execution in Foreman
With remote execution, you can run jobs on hosts remotely from Smart Proxies using shell scripts or Ansible tasks and playbooks.
Use remote execution for the following benefits in Foreman:
-
Run jobs on multiple hosts at once.
-
Use variables in your commands for more granular control over the jobs you run.
-
Use host facts and parameters to populate the variable values.
-
Specify custom values for templates when you run the command.
Communication for remote execution occurs through Smart Proxy server, which means that Foreman server does not require direct access to the target host, and can scale to manage many hosts.
To use remote execution, you must define a job template. A job template is a command that you want to apply to remote hosts. You can execute a job template multiple times.
Foreman uses ERB syntax job templates. For more information, see Template writing reference.
By default, Foreman includes several job templates for shell scripts and Ansible. For more information, see Setting up Job Templates in Managing hosts.
-
See Executing a Remote Job in Managing hosts.
12.2. Remote execution workflow
For custom Ansible roles that you create, or roles that you download, you must install the package containing the roles on your Smart Proxy server. Before you can use Ansible roles, you must import the roles into Foreman from the Smart Proxy where they are installed.
When you run a remote job on hosts, for every host, Foreman performs the following actions to find a remote execution Smart Proxy to use.
Foreman searches only for Smart Proxies that have the remote execution feature enabled.
-
Foreman finds the host’s interfaces that have the Remote execution checkbox selected.
-
Foreman finds the subnets of these interfaces.
-
Foreman finds remote execution Smart Proxies assigned to these subnets.
-
From this set of Smart Proxies, Foreman selects the Smart Proxy that has the least number of running jobs. By doing this, Foreman ensures that the jobs load is balanced between remote execution Smart Proxies.
If you have enabled Prefer registered through Smart Proxy for remote execution, Foreman runs the REX job using the Smart Proxy the host is registered to.
By default, Prefer registered through Smart Proxy for remote execution is set to No.
To enable it, in the Foreman web UI, navigate to Administer > Settings, and on the Content tab, set Prefer registered through Smart Proxy for remote execution
to Yes.
This ensures that Foreman performs REX jobs on hosts by the Smart Proxy to which they are registered to.
If Foreman does not find a remote execution Smart Proxy at this stage, and if the Fallback to Any Smart Proxy setting is enabled, Foreman adds another set of Smart Proxies to select the remote execution Smart Proxy from. Foreman selects the most lightly loaded Smart Proxy from the following types of Smart Proxies that are assigned to the host:
-
DHCP, DNS and TFTP Smart Proxies assigned to the host’s subnets
-
DNS Smart Proxy assigned to the host’s domain
-
Realm Smart Proxy assigned to the host’s realm
-
Puppet server Smart Proxy
-
Puppet CA Smart Proxy
-
OpenSCAP Smart Proxy
If Foreman does not find a remote execution Smart Proxy at this stage, and if the Enable Global Smart Proxy setting is enabled, Foreman selects the most lightly loaded remote execution Smart Proxy from the set of all Smart Proxies in the host’s organization and location to execute a remote job.
12.3. Permissions for remote execution
You can control which roles can run which jobs within your infrastructure, including which hosts they can target. The remote execution feature provides two built-in roles:
-
Remote Execution Manager: Can access all remote execution features and functionality.
-
Remote Execution User: Can only run jobs.
You can clone the Remote Execution User role and customize its filter for increased granularity.
If you adjust the filter with the view_job_templates
permission on a customized role, you can only see and trigger jobs based on matching job templates.
You can use the view_hosts
and view_smart_proxies
permissions to limit which hosts or Smart Proxies are visible to the role.
The execute_template_invocation
permission is a special permission that is checked immediately before execution of a job begins.
This permission defines which job template you can run on a particular host.
This allows for even more granularity when specifying permissions.
You can run remote execution jobs against Foreman and Smart Proxy registered as hosts to Foreman with the execute_jobs_on_infrastructure_hosts
permission.
Standard Manager and Site Manager roles have this permission by default.
If you use either the Manager or Site Manager role, or if you use a custom role with the execute_jobs_on_infrastructure_hosts
permission, you can execute remote jobs against registered Foreman and Smart Proxy hosts.
For more information on working with roles and permissions, see Creating and Managing Roles in Administering Foreman.
The following example shows filters for the execute_template_invocation
permission:
name = Reboot and host.name = staging.example.com name = Reboot and host.name ~ *.staging.example.com name = "Restart service" and host_group.name = webservers
Use the first line in this example to apply the Reboot template to one selected host.
Use the second line to define a pool of hosts with names ending with .staging.example.com
.
Use the third line to bind the template with a host group.
Note
|
Permissions assigned to users with these roles can change over time. If you have already scheduled some jobs to run in the future, and the permissions change, this can result in execution failure because permissions are checked immediately before job execution. |
12.4. Transport modes for remote execution
You can configure your Foreman to use two different modes of transport for remote job execution. You can configure single Smart Proxy to use either one mode or the other but not both.
- Push-based transport
-
On Smart Proxies in
ssh
mode, remote execution uses the SSH service to transport job details. This is the default transport mode. The SSH service must be enabled and active on the target hosts. The remote execution Smart Proxy must have access to the SSH port on the target hosts. Unless you have a different setting, the standard SSH port is 22.This transport mode supports both Script and Ansible providers.
- Pull-based transport
-
On Smart Proxies in
pull-mqtt
mode, remote execution uses Message Queueing Telemetry Transport (MQTT) to initiate the job execution it receives from Foreman server. The host subscribes to the MQTT broker on Smart Proxy for job notifications using theyggdrasil
pull client. After the host receives a notification from the MQTT broker, it pulls job details from Smart Proxy over HTTPS, runs the job, and reports results back to Smart Proxy.This transport mode supports the Script provider only.
To use the
pull-mqtt
mode, you must enable it on Smart Proxy server and configure the pull client on hosts.
Note
|
If your Smart Proxy already uses the # foreman-installer --foreman-proxy-plugin-remote-execution-script-mode=ssh |
-
To enable pull mode on Smart Proxy server, see Configuring pull-based transport for remote execution in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
-
To enable pull mode on a registered host, continue with Configuring a host to use the pull client.
-
To enable pull mode on a new host, continue with the following:
12.5. Configuring a host to use the pull client
For Smart Proxies configured to use pull-mqtt
mode, hosts can subscribe to remote jobs using the remote execution pull client.
Hosts do not require an SSH connection from their Smart Proxy server.
-
You have registered the host to Foreman.
-
The Smart Proxy through which the host is registered is configured to use
pull-mqtt
mode. For more information, see Configuring pull-based transport for remote execution in Installing a Smart Proxy Server 3.11 on Enterprise Linux. -
Foreman Client repository for the operating system version of the host is synchronized on Foreman server, available in the content view and the lifecycle environment of the host, and enabled for the host. For more information, see Changing the repository sets status for a host in Foreman in Managing content.
-
The host can communicate with its Smart Proxy over MQTT using port
1883
. -
The host can communicate with its Smart Proxy over HTTPS.
-
Install the
katello-pull-transport-migrate
package on your host:-
On Enterprise Linux 9 and Enterprise Linux 8 hosts:
# dnf install katello-pull-transport-migrate
-
On Enterprise Linux 7 hosts:
# yum install katello-pull-transport-migrate
-
On Debian/Ubuntu hosts:
# apt install katello-pull-transport-migrate
-
On SUSE Linux Enterprise Server hosts:
# zypper install katello-pull-transport-migrate
The package installs
foreman_ygg_worker
andyggdrasil
as dependencies, configures theyggdrasil
client, and starts the pull client worker on the host. -
-
Check the status of the
yggdrasild
service:# systemctl status yggdrasild
12.6. Creating a job template
Use this procedure to create a job template. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Templates > Job templates.
-
Click New Job Template.
-
Click the Template tab, and in the Name field, enter a unique name for your job template.
-
Select Default to make the template available for all organizations and locations.
-
Create the template directly in the template editor or upload it from a text file by clicking Import.
-
Optional: In the Audit Comment field, add information about the change.
-
Click the Job tab, and in the Job category field, enter your own category or select from the default categories listed in Default Job Template Categories in Managing hosts.
-
Optional: In the Description Format field, enter a description template. For example,
Install package %{package_name}
. You can also use%{template_name}
and%{job_category}
in your template. -
From the Provider Type list, select SSH for shell scripts and Ansible for Ansible tasks or playbooks.
-
Optional: In the Timeout to kill field, enter a timeout value to terminate the job if it does not complete.
-
Optional: Click Add Input to define an input parameter. Parameters are requested when executing the job and do not have to be defined in the template. For examples, see the Help tab.
-
Optional: Click Foreign input set to include other templates in this job.
-
Optional: In the Effective user area, configure a user if the command cannot use the default
remote_execution_effective_user
setting. -
Optional: If this template is a snippet to be included in other templates, click the Type tab and select Snippet.
-
Optional: If you use the Ansible provider, click the Ansible tab. Select Enable Ansible Callback to allow hosts to send facts, which are used to create configuration reports, back to Foreman after a job finishes.
-
Click the Location tab and add the locations where you want to use the template.
-
Click the Organizations tab and add the organizations where you want to use the template.
-
Click Submit to save your changes.
You can extend and customize job templates by including other templates in the template syntax. For more information, see Template Writing Reference and Job Template Examples and Extensions in Managing hosts.
-
To create a job template using a template-definition file, enter the following command:
# hammer job-template create \ --file "Path_to_My_Template_File" \ --job-category "My_Category_Name" \ --name "My_Template_Name" \ --provider-type SSH
12.7. Importing an Ansible Playbook by name
You can import Ansible Playbooks by name to Foreman from collections installed on Smart Proxy.
Foreman creates a job template from the imported playbook and places the template in the Ansible Playbook - Imported
job category.
If you have a custom collection, place it in /etc/ansible/collections/ansible_collections/My_Namespace/My_Collection
.
-
Ansible plugin is enabled.
-
Your Foreman account has a role that grants the
import_ansible_playbooks
permission.
-
Fetch the available Ansible Playbooks by using the following API request:
# curl -X GET -H 'Content-Type: application/json' https://foreman.example.com/ansible/api/v2/ansible_playbooks/fetch?proxy_id=My_smart-proxy_ID
-
Select the Ansible Playbook you want to import and note its name.
-
Import the Ansible Playbook by its name:
# curl -X PUT -H 'Content-Type: application/json' -d '{ "playbook_names": ["My_Playbook_Name"] }' https://foreman.example.com/ansible/api/v2/ansible_playbooks/sync?proxy_id=My_smart-proxy_ID
You get a notification in the Foreman web UI after the import completes.
-
You can run the playbook by executing a remote job from the created job template. For more information, see Executing a remote job.
12.8. Importing all available Ansible Playbooks
You can import all the available Ansible Playbooks to Foreman from collections installed on Smart Proxy.
Foreman creates job templates from the imported playbooks and places the templates in the Ansible Playbook - Imported
job category.
If you have a custom collection, place it in /etc/ansible/collections/ansible_collections/My_Namespace/My_Collection
.
-
Ansible plugin is enabled.
-
Your Foreman account has a role that grants the
import_ansible_playbooks
permission.
-
Import the Ansible Playbooks by using the following API request:
# curl -X PUT -H 'Content-Type: application/json' https://foreman.example.com/ansible/api/v2/ansible_playbooks/sync?proxy_id=My_smart-proxy_ID
You get a notification in the Foreman web UI after the import completes.
-
You can run the playbooks by executing a remote job from the created job templates. For more information, see Executing a remote job.
12.9. Configuring the fallback to any Smart Proxy remote execution setting in Foreman
You can enable the Fallback to Any Smart Proxy setting to configure Foreman to search for remote execution Smart Proxies from the list of Smart Proxies that are assigned to hosts. This can be useful if you need to run remote jobs on hosts that have no subnets configured or if the hosts' subnets are assigned to Smart Proxies that do not have the remote execution feature enabled.
If the Fallback to Any Smart Proxy setting is enabled, Foreman adds another set of Smart Proxies to select the remote execution Smart Proxy from. Foreman also selects the most lightly loaded Smart Proxy from the set of all Smart Proxies assigned to the host, such as the following:
-
DHCP, DNS and TFTP Smart Proxies assigned to the host’s subnets
-
DNS Smart Proxy assigned to the host’s domain
-
Realm Smart Proxy assigned to the host’s realm
-
Puppet server Smart Proxy
-
Puppet CA Smart Proxy
-
OpenSCAP Smart Proxy
-
In the Foreman web UI, navigate to Administer > Settings.
-
Click Remote Execution.
-
Configure the Fallback to Any Smart Proxy setting.
-
Enter the
hammer settings set
command on Foreman to configure the Fallback to Any Smart Proxy setting. To set the value totrue
, enter the following command:# hammer settings set \ --name=remote_execution_fallback_proxy \ --value=true
12.10. Configuring the global Smart Proxy remote execution setting in Foreman
By default, Foreman searches for remote execution Smart Proxies in hosts' organizations and locations regardless of whether Smart Proxies are assigned to hosts' subnets or not. You can disable the Enable Global Smart Proxy setting if you want to limit the search to the Smart Proxies that are assigned to hosts' subnets.
If the Enable Global Smart Proxy setting is enabled, Foreman adds another set of Smart Proxies to select the remote execution Smart Proxy from. Foreman also selects the most lightly loaded remote execution Smart Proxy from the set of all Smart Proxies in the host’s organization and location to execute a remote job.
-
In the Foreman web UI, navigate to Administer > Settings.
-
Click Remote Execution.
-
Configure the Enable Global Smart Proxy setting.
-
Enter the
hammer settings set
command on Foreman to configure theEnable Global Smart Proxy
setting. To set the value totrue
, enter the following command:# hammer settings set \ --name=remote_execution_global_proxy \ --value=true
12.11. Setting an alternative directory for remote execution jobs in push mode
By default, Foreman uses the /var/tmp
directory on hosts for remote execution jobs in push mode.
If the /var/tmp
directory on your host is mounted with the noexec
flag, Foreman cannot execute remote execution job scripts in this directory.
You can use foreman-installer
to set an alternative directory for executing remote execution jobs in push mode.
-
On your host, create a new directory:
# mkdir /My_Remote_Working_Directory
-
Copy the SELinux context from the default
/var/tmp
directory:# chcon --reference=/var/tmp /My_Remote_Working_Directory
-
Configure your Foreman server or Smart Proxy server to use the new directory:
# foreman-installer \ --foreman-proxy-plugin-remote-execution-script-remote-working-dir /My_Remote_Working_Directory
12.12. Setting an alternative directory for remote execution jobs in pull mode
By default, Foreman uses the /run
directory on hosts for remote execution jobs in pull mode.
If the /run
directory on your host is mounted with the noexec
flag, Foreman cannot execute remote execution job scripts in this directory.
You can use the yggdrasild
service to set an alternative directory for executing remote execution jobs in pull mode.
On your host, perform these steps:
-
Create a new directory:
# mkdir /My_Remote_Working_Directory
-
Access the
yggdrasild
service configuration:# systemctl edit yggdrasild
-
Specify the alternative directory by adding the following line to the configuration:
Environment=FOREMAN_YGG_WORKER_WORKDIR=/My_Remote_Working_Directory
-
Restart the
yggdrasild
service:# systemctl restart yggdrasild
12.13. Altering the privilege elevation method
By default, push-based remote execution uses sudo
to switch from the SSH user to the effective user that executes the script on your host.
In some situations, you might require to use another method, such as su
or dzdo
.
You can globally configure an alternative method in your Foreman settings.
-
Your user account has a role assigned that grants the
view_settings
andedit_settings
permissions. -
If you want to use
dzdo
for Ansible jobs, ensure thecommunity.general
Ansible collection, which contains the required dzdo become plugin, is installed. For more information, see Installing collections in Ansible documentation.
-
Navigate to Administer > Settings.
-
Select the Remote Execution tab.
-
Click the value of the Effective User Method setting.
-
Select the new value.
-
Click Submit.
12.14. Distributing SSH keys for remote execution
For Smart Proxies in ssh
mode, remote execution connections are authenticated using SSH.
The public SSH key from Smart Proxy must be distributed to its attached hosts that you want to manage.
Ensure that the SSH service is enabled and running on the hosts. Configure any network or host-based firewalls to enable access to port 22.
Use one of the following methods to distribute the public SSH key from Smart Proxy to target hosts:
-
Using the Foreman API to obtain SSH keys for remote execution.
-
Configuring a Kickstart template to distribute SSH keys during provisioning.
-
For new Foreman hosts, you can deploy SSH keys to Foreman hosts during registration using the global registration template. For more information, see Registering a Host to Foreman Using the Global Registration Template in Managing hosts.
Foreman distributes SSH keys for the remote execution feature to the hosts provisioned from Foreman by default.
If the hosts are running on Amazon Web Services, enable password authentication. For more information, see New User Accounts.
12.15. Distributing SSH keys for remote execution manually
To distribute SSH keys manually, complete the following steps:
-
Copy the SSH pub key from your Smart Proxy to your target host:
# ssh-copy-id -i ~foreman-proxy/.ssh/id_rsa_foreman_proxy.pub root@client.example.com
Repeat this step for each target host you want to manage.
-
To confirm that the key was successfully copied to the target host, enter the following command on Smart Proxy:
# ssh -i ~foreman-proxy/.ssh/id_rsa_foreman_proxy root@client.example.com
12.16. Adding a passphrase to SSH key used for remote execution
By default, Smart Proxy uses a non-passphrase protected SSH key to execute remote jobs on hosts. You can protect the SSH key with a passphrase by following this procedure.
-
On your Foreman server or Smart Proxy server, use
ssh-keygen
to add a passphrase to your SSH key:# ssh-keygen -p -f ~foreman-proxy/.ssh/id_rsa_foreman_proxy
-
Users now must use a passphrase when running remote execution jobs on hosts.
12.17. Using the Foreman API to obtain SSH keys for remote execution
To use the Foreman API to download the public key from Smart Proxy, complete this procedure on each target host.
-
On the target host, create the
~/.ssh
directory to store the SSH key:# mkdir ~/.ssh
-
Download the SSH key from Smart Proxy:
# curl https://smartproxy.example.com:9090/ssh/pubkey >> ~/.ssh/authorized_keys
-
Configure permissions for the
~/.ssh
directory:# chmod 700 ~/.ssh
-
Configure permissions for the
authorized_keys
file:# chmod 600 ~/.ssh/authorized_keys
12.18. Configuring a AutoYaST template to distribute SSH keys during provisioning
You can add a remote_execution_ssh_keys
snippet to your custom AutoYaST template to deploy SSH keys to hosts during provisioning.
AutoYaST templates that Foreman ships include this snippet by default.
Foreman copies the SSH key for remote execution to the systems during provisioning.
-
To include the public key in newly-provisioned hosts, add the following snippet to the AutoYaST template that you use:
<%= snippet 'remote_execution_ssh_keys' %>
12.19. Configuring a Kickstart template to distribute SSH keys during provisioning
You can add a remote_execution_ssh_keys
snippet to your custom Kickstart template to deploy SSH keys to hosts during provisioning.
Kickstart templates that Foreman ships include this snippet by default.
Foreman copies the SSH key for remote execution to the systems during provisioning.
-
To include the public key in newly-provisioned hosts, add the following snippet to the Kickstart template that you use:
<%= snippet 'remote_execution_ssh_keys' %>
12.20. Configuring a Preseed template to distribute SSH keys during provisioning
You can add a remote_execution_ssh_keys
snippet to your custom Preseed template to deploy SSH keys to hosts during provisioning.
Preseed templates that Foreman ships include this snippet by default.
Foreman copies the SSH key for remote execution to the systems during provisioning.
-
To include the public key in newly-provisioned hosts, add the following snippet to the Preseed template that you use:
<%= snippet 'remote_execution_ssh_keys' %>
12.21. Configuring a keytab for Kerberos ticket granting tickets
Use this procedure to configure Foreman to use a keytab to obtain Kerberos ticket granting tickets. If you do not set up a keytab, you must manually retrieve tickets.
-
Find the ID of the
foreman-proxy
user:# id -u foreman-proxy
-
Modify the
umask
value so that new files have the permissions600
:# umask 077
-
Create the directory for the keytab:
# mkdir -p "/var/kerberos/krb5/user/My_User_ID"
-
Create a keytab or copy an existing keytab to the directory:
# cp My_Client.keytab /var/kerberos/krb5/user/My_User_ID/client.keytab
-
Change the directory owner to the
foreman-proxy
user:# chown -R foreman-proxy:foreman-proxy "/var/kerberos/krb5/user/My_User_ID"
-
Ensure that the keytab file is read-only:
# chmod -wx "/var/kerberos/krb5/user/My_User_ID/client.keytab"
-
Restore the SELinux context:
# restorecon -RvF /var/kerberos/krb5
12.22. Configuring Kerberos authentication for remote execution
You can use Kerberos authentication to establish an SSH connection for remote execution on Foreman hosts.
-
Enroll Foreman server on the Kerberos server
-
Enroll the Foreman target host on the Kerberos server
-
Configure and initialize a Kerberos user account for remote execution
-
Ensure that the foreman-proxy user on Foreman has a valid Kerberos ticket granting ticket
-
To install and enable Kerberos authentication for remote execution, enter the following command:
# foreman-installer --foreman-proxy-plugin-remote-execution-script-ssh-kerberos-auth true
-
To edit the default user for remote execution, in the Foreman web UI, navigate to Administer > Settings and click the Remote Execution tab. In the SSH User row, edit the second column and add the user name for the Kerberos account.
-
Navigate to remote_execution_effective_user and edit the second column to add the user name for the Kerberos account.
-
To confirm that Kerberos authentication is ready to use, run a remote job on the host. For more information, see Executing a Remote Job in Managing hosts.
12.23. Setting up job templates
Foreman provides default job templates that you can use for executing jobs. To view the list of job templates, navigate to Hosts > Templates > Job templates. If you want to use a template without making changes, proceed to Executing a Remote Job in Managing hosts.
You can use default templates as a base for developing your own. Default job templates are locked for editing. Clone the template and edit the clone.
-
To clone a template, in the Actions column, select Clone.
-
Enter a unique name for the clone and click Submit to save the changes.
Job templates use the Embedded Ruby (ERB) syntax. For more information about writing templates, see the Template Writing Reference in Managing hosts.
To create an Ansible job template, use the following procedure and instead of ERB syntax, use YAML syntax.
Begin the template with ---
.
You can embed an Ansible Playbook YAML file into the job template body.
You can also add ERB syntax to customize your YAML Ansible template.
You can also import Ansible Playbooks in Foreman.
For more information, see Synchronizing Repository Templates in Managing hosts.
At run time, job templates can accept parameter variables that you define for a host. Note that only the parameters visible on the Parameters tab at the host’s edit page can be used as input parameters for job templates.
12.24. Executing a remote job
You can execute a job that is based on a job template against one or more hosts.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Monitor > Jobs and click Run job.
-
Select the Job category and the Job template you want to use, then click Next.
-
Select hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.
NoteIf you want to select a host group and all of its subgroups, it is not sufficient to select the host group as the job would only run on hosts directly in that group and not on hosts in subgroups. Instead, you must either select the host group and all of its subgroups or use this search query:
hostgroup_fullname ~ "My_Host_Group*"
Replace My_Host_Group with the name of the top-level host group.
-
If required, provide inputs for the job template. Different templates have different inputs and some templates do not have any inputs. After entering all the required inputs, click Next.
-
Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Advanced settings in the job wizard.
-
Click Next.
-
Schedule time for the job.
-
To execute the job immediately, keep the pre-selected Immediate execution.
-
To execute the job in future time, select Future execution.
-
To execute the job on regular basis, select Recurring execution.
-
-
Optional: If you selected future or recurring execution, select the Query type, otherwise click Next.
-
Static query means that job executes on the exact list of hosts that you provided.
-
Dynamic query means that the list of hosts is evaluated just before the job is executed. If you entered the list of hosts based on some filter, the results can be different from when you first used that filter.
Click Next after you have selected the query type.
-
-
Optional: If you selected future or recurring execution, provide additional details:
-
For Future execution, enter the Starts at date and time. You also have the option to select the Starts before date and time. If the job cannot start before that time, it will be canceled.
-
For Recurring execution, select the start date and time, frequency, and the condition for ending the recurring job. You can choose the recurrence to never end, end at a certain time, or end after a given number of repetitions. You can also add Purpose - a special label for tracking the job. There can only be one active job with a given purpose at a time.
Click Next after you have entered the required information.
-
-
Review job details. You have the option to return to any part of the job wizard and edit the information.
-
Click Submit to schedule the job for execution.
-
Enter the following command on Foreman:
# hammer settings set \ --name=remote_execution_global_proxy \ --value=false
-
Find the ID of the job template you want to use:
# hammer job-template list
-
Show the template details to see parameters required by your template:
# hammer job-template info --id My_Template_ID
-
Execute a remote job with custom parameters:
# hammer job-invocation create \ --inputs My_Key_1="My_Value_1",My_Key_2="My_Value_2",... \ --job-template "My_Template_Name" \ --search-query "My_Search_Query"
Replace
My_Search_Query
with the filter expression that defines hosts, for example"name ~ My_Pattern"
. For more information about executing remote commands with hammer, enterhammer job-template --help
andhammer job-invocation --help
.
12.25. Advanced settings in the job wizard
Some job templates require you to enter advanced settings. Some of the advanced settings are only visible to certain job templates. Below is the list of general advanced settings.
- SSH user
-
A user to be used for connecting to the host through SSH.
- Effective user
-
A user to be used for executing the job. By default it is the SSH user. If it differs from the SSH user, su or sudo, depending on your settings, is used to switch the accounts.
-
If you set an effective user in the advanced settings, Ansible sets
ansible_become_user
to your input value andansible_become
totrue
. This means that if you use the parametersbecome: true
andbecome_user: My_User
within a playbook, these will be overwritten by Foreman. -
If your SSH user and effective user are identical, Foreman does not overwrite the
become_user
. Therefore, you can set a custombecome_user
in your Ansible Playbook.
-
- Description
-
A description template for the job.
- Timeout to kill
-
Time in seconds from the start of the job after which the job should be killed if it is not finished already.
- Time to pickup
-
Time in seconds after which the job is canceled if it is not picked up by a client. This setting only applies to hosts using
pull-mqtt
transport. - Password
-
Is used if SSH authentication method is a password instead of the SSH key.
- Private key passphrase
-
Is used if SSH keys are protected by a passphrase.
- Effective user password
-
Is used if effective user is different from the ssh user.
- Concurrency level
-
Defines the maximum number of jobs executed at once. This can prevent overload of system resources in a case of executing the job on a large number of hosts.
- Execution ordering
-
Determines the order in which the job is executed on hosts. It can be alphabetical or randomized.
12.26. Using extended cron lines
When scheduling a cron job with remote execution, you can use an extended cron line to specify the cadence of the job.
The standard cron line contains five fields that specify minute, hour, day of the month, month, and day of the week.
For example, 0 5 * * *
stands for every day at 5 AM.
If you want to learn more about the standard cron line, check crontab guru.
The extended cron line provides the following features:
- You can use
#
to specify a concrete week day in a month -
For example:
-
0 0 * * mon#1
specifies first Monday of the month -
0 0 * * fri#3,fri#4
specifies 3rd and 4th Fridays of the month -
0 7 * * fri#-1
specifies the last Friday of the month at 07:00 -
0 7 * * fri#L
also specifies the last Friday of the month at 07:00 -
0 23 * * mon#2,tue
specifies the 2nd Monday of the month and every Tuesday, at 23:00
-
- You can use
%
to specify every n-th day of the month -
For example:
-
9 0 * * sun%2
specifies every other Sunday at 00:09 -
0 0 * * sun%2+1
specifies every odd Sunday -
9 0 * * sun%2,tue%3
specifies every other Sunday and every third Tuesday
-
- You can use
&
to specify that the day of the month has to match the day of the week -
For example:
-
0 0 30 * 1&
specifies 30th day of the month, but only if it is Monday
-
12.27. Scheduling a recurring Ansible job for a host
You can schedule a recurring job to run Ansible roles on hosts.
-
Ensure you have the
view_foreman_tasks
,view_job_invocations
, andview_recurring_logics
permissions.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select the target host on which you want to execute a remote job.
-
On the Ansible tab, select Jobs.
-
Click Schedule recurring job.
-
Define the repetition frequency, start time, and date of the first run in the Create New Recurring Ansible Run window.
-
Click Submit.
-
Optional: View the scheduled Ansible job in host overview or by navigating to Ansible > Jobs.
12.28. Scheduling a recurring Ansible job for a host group
You can schedule a recurring job to run Ansible roles on host groups.
-
In the Foreman web UI, navigate to Configure > Host groups.
-
In the Actions column, select Configure Ansible Job for the host group you want to schedule an Ansible roles run for.
-
Click Schedule recurring job.
-
Define the repetition frequency, start time, and date of the first run in the Create New Recurring Ansible Run window.
-
Click Submit.
12.29. Monitoring jobs
You can monitor the progress of a job while it is running. This can help in any troubleshooting that may be required.
Ansible jobs run on batches of 100 hosts, so you cannot cancel a job running on a specific host. A job completes only after the Ansible playbook runs on all hosts in the batch.
-
In the Foreman web UI, navigate to Monitor > Jobs. This page is automatically displayed if you triggered the job with the
Execute now
setting. To monitor scheduled jobs, navigate to Monitor > Jobs and select the job run you wish to inspect. -
On the Job page, click the Hosts tab. This displays the list of hosts on which the job is running.
-
In the Host column, click the name of the host that you want to inspect. This displays the Detail of Commands page where you can monitor the job execution in real time.
-
Click Back to Job at any time to return to the Job Details page.
-
Find the ID of a job:
# hammer job-invocation list
-
Monitor the job output:
# hammer job-invocation output \ --host My_Host_Name \ --id My_Job_ID
-
Optional: To cancel a job, enter the following command:
# hammer job-invocation cancel \ --id My_Job_ID
12.30. Using Ansible provider for package and errata actions
By default, Foreman is configured to use the Script provider templates for remote execution jobs. If you prefer using Ansible job templates for your remote jobs, you can configure Foreman to use them by default for remote execution features associated with them.
Note
|
Remember that Ansible job templates only work when remote execution is configured for |
-
In the Foreman web UI, navigate to Administer > Remote Execution Features.
-
Find each feature whose name contains
by_search
. -
Change the job template for these features from
Katello Script Default
toKatello Ansible Default
. -
Click Submit.
Foreman now uses Ansible provider templates for remote execution jobs by which you can perform package and errata actions.
This applies to job invocations from the Foreman web UI as well as by using hammer job-invocation create
with the same remote execution features that you have changed.
12.31. Setting the job rate limit on Smart Proxy
You can limit the maximum number of active jobs on a Smart Proxy at a time to prevent performance spikes. The job is active from the time Smart Proxy first tries to notify the host about the job until the job is finished on the host.
The job rate limit only applies to mqtt based jobs.
Note
|
The optimal maximum number of active jobs depends on the computing resources of your Smart Proxy server. By default, the maximum number of active jobs is unlimited. |
-
Set the maximum number of active jobs using
foreman-installer
:# foreman-installer \ --foreman-proxy-plugin-remote-execution-script-mqtt-rate-limit MAX_JOBS_NUMBER
For example:
# foreman-installer \ --foreman-proxy-plugin-remote-execution-script-mqtt-rate-limit 200
13. Host status in Foreman
In Foreman, each host has a global status that indicates which hosts need attention. Each host also has sub-statuses that represent status of a particular feature. With any change of a sub-status, the global status is recalculated and the result is determined by statuses of all sub-statuses.
13.1. Host global status overview
The global status represents the overall status of a particular host. The status can have one of three possible values: OK, Warning, or Error. You can find global status on the Hosts Overview page. The status displays a small icon next to host name and has a color that corresponds with the status. Hovering over the icon renders a tooltip with sub-status information to quickly find out more details. To view the global status for a host, in the Foreman web UI, navigate to Hosts > All Hosts.
- OK
-
No errors were reported by any sub-status. This status is highlighted with the color green.
- Warning
-
While no error was detected, some sub-status raised a warning. For example, there are no configuration management reports for the host even though the host is configured to send reports. It is a good practice to investigate any warnings to ensure that your deployment remains healthy. This status is highlighted with the color yellow.
- Error
-
Some sub-status reports a failure. For example, a run contains some failed resources. This status is highlighted with the color red.
If you want to search for hosts according to their status, use the syntax for searching in Foreman that is outlined in the Searching and Bookmarking in Administering Foreman, and then build your searches out using the following status-related examples:
To search for hosts that have an OK status:
global_status = ok
To search for all hosts that deserve attention:
global_status = error or global_status = warning
13.2. Host sub-status overview
A sub-status monitors only a part of a host’s capabilities.
To view the sub-statuses of a host, in the Foreman web UI, navigate to Hosts > All Hosts and click on the host whose full status you want to inspect. You can view the global host status next to the name of the host and the host sub-statuses on the Host status card.
Each sub-status has its own set of possible values that are mapped to the three global status values.
Below are listed sub-statuses that Foreman contains. There can be more sub-statuses depending on which plugins you add to your Foreman.
- Configuration
-
This sub-status is only relevant if Foreman uses a configuration management system like Ansible, Puppet, or Salt.
Possible values:
Label Global host status Alerts disabled
OK
Active
OK
Pending
OK
No changes
OK
No reports
OK / Warning
Out of sync
Warning
Error
Error
Additional information about the values of this sub-status:
-
Active: During the last configuration, some resources were applied.
-
Pending: During the last configuration, some resources would be applied but your configuration management integration was configured to run in
noop
mode. -
No changes: During the last configuration, nothing changed.
-
No reports: This can be both a Warning or OK status. When there are no reports but the host uses an associated Smart Proxy for configuration management or the
always_show_configuration_status
setting is set totrue
, it maps to Warning. Otherwise it maps to OK. -
Error: This indicates an error during configuration. For example, a configuration run failed to install a package.
-
Out of sync: A configuration report was not received within the expected interval, based on the
outofsync_interval
setting. Reports are identified by an origin and can have different intervals based upon it.
-
- Build
-
This sub-status is only relevant for hosts provisioned from Foreman or hosts registered through global registration.
Possible values:
Label Global host status Number value Installed
OK
0
Pending installation
OK
1
Token expired
Error
2
Installation error
Error
3
- Compliance
-
Indicates if the host is compliant with OpenSCAP policies.
Possible values:
Label Global host status Number value Compliant
OK
0
Inconclusive
Warning
1
At least one incompliant
Error
2
- Execution
-
Status of the last completed remote execution job.
Possible values:
Label Global host status Number value Last execution succeeded / No execution finished yet
OK
0
Last execution failed
Error
1
Unknown execution status
OK
2 or 3
Last execution cancelled
OK
4
- Errata
-
Indicates if Errata is available on the host.
Possible values:
Label Global host status Number value Up to date
OK
0
Unknown
Warning
1
Needed errata
Error
2
Needed security errata
Error
3
- RHEL Lifecycle
-
Indicates the current state of the Red Hat Enterprise Linux operating system installed on the host.
Possible values:
Label Global host status Number value Unknown
OK
0
Full support
OK
1
Maintenance support
OK
2
Approaching end of maintenance support
Warning
3
Extended support
OK
4
Approaching end of support
Warning
5
Support ended
Error
6
- Traces
-
Indicates if the host needs a reboot or a process restart.
Possible values:
Label Global host status Number value Unknown
Warning
-1
Up to date
OK
0
Required process restart
Error
1
Required reboot
Error
2
If you want to search for hosts according to their sub-status, use the syntax for searching in Foreman that is outlined in the Searching and Bookmarking chapter of the Administering Foreman guide, and then build your searches out using the following status-related examples:
You search for hosts' configuration sub-statuses based on their last reported state.
For example, to find hosts that have at least one pending resource:
status.pending > 0
To find hosts that restarted some service during last run:
status.restarted > 0
To find hosts that have an interesting last run that might indicate something has happened:
status.interesting = true
14. Synchronizing template repositories
In Foreman, you can synchronize repositories of job templates, provisioning templates, report templates, and partition table templates between Foreman server and a version control system or local directory. In this chapter, a Git repository is used for demonstration purposes.
This section details the workflow for installing and configuring the TemplateSync plugin and performing exporting and importing tasks.
14.1. Enabling the TemplateSync plugin
-
To enable the plugin on your Foreman server, enter the following command:
# foreman-installer --enable-foreman-plugin-templates
-
To verify that the plugin is installed correctly, ensure Administer > Settings includes the TemplateSync menu.
14.2. Configuring the TemplateSync plugin
In the Foreman web UI, navigate to Administer > Settings > TemplateSync to configure the plugin. The following table explains the parameters.
Note
|
Some parameters are used only for importing or exporting. |
Parameter | API parameter name | Meaning on importing | Meaning on exporting |
---|---|---|---|
Associate |
Accepted values: |
Associates templates with an operating system, organization, and location based on metadata. |
N/A |
Branch |
|
Specifies the default branch in Git repository to read from. |
Specifies the default branch in Git repository to write to. |
Dirname |
|
Specifies the subdirectory under the repository to read from. |
Specifies the subdirectory under the repository to write to. |
Filter |
|
Imports only templates with names that match this regular expression. |
Exports only templates with names that match this regular expression. |
Force import |
|
Imported templates overwrite locked templates with the same name. |
N/A |
Lock templates |
|
Do not overwrite existing templates when you import a new template with the same name, unless Force import is enabled. |
N/A |
Metadata export mode |
Accepted values: |
N/A |
Defines how metadata is handled when exporting:
|
Negate |
Accepted values: |
Imports templates ignoring the filter attribute. |
Exports templates ignoring the filter attribute. |
Prefix |
|
Adds specified string to the beginning of the template if the template name does not start with the prefix already. |
N/A |
Repo |
|
Defines the path to the repository to synchronize from. |
Defines the path to a repository to export to. |
Verbosity |
Accepted values: |
Enables writing verbose messages to the logs for this action. |
N/A |
14.3. Using repository sources
You can use existing repositories or local directories to synchronize templates with your Foreman server.
14.3.1. Synchronizing templates with an existing repository
Use this procedure to synchronize templates between your Foreman server and an existing repository.
-
If you want to use HTTPS to connect to the repository and you use a self-signed certificate authority (CA) on your Git server:
-
Create a new directory under the
/usr/share/foreman/
directory to store the Git configuration for the certificate:# mkdir --parents /usr/share/foreman/.config/git
-
Create a file named
config
in the new directory:# touch /usr/share/foreman/.config/git/config
-
Allow the
foreman
user access to the.config
directory:# chown --recursive foreman /usr/share/foreman/.config
-
Update the Git global configuration for the
foreman
user with the path to your self-signed CA certificate:# sudo --user foreman git config --global http.sslCAPath Path_To_CA_Certificate
-
-
If you want to use SSH to connect to the repository:
-
Create an SSH key pair if you do not already have it. Do not specify a passphrase.
# sudo --user foreman ssh-keygen
-
Configure your version control server with the public key from your Foreman, which resides in
/usr/share/foreman/.ssh/id_rsa.pub
. -
Accept the Git SSH host key as the
foreman
user:# sudo --user foreman ssh git.example.com
-
-
Configure the TemplateSync plugin settings on a TemplateSync tab.
-
Change the Branch setting to match the target branch on a Git server.
-
Change the Repo setting to match the Git repository. For example, for the repository located in
git@git.example.com/templates.git
set the setting intogit@git.example.com/templates.git
.
-
14.3.2. Synchronizing templates with a local directory
Synchronizing templates with a local directory is useful if you have configured a version control repository in the local directory. That way, you can edit templates and track the history of edits in the directory. You can also synchronize changes to Foreman server after editing the templates.
-
Each template must contain the location and organization that the template belongs to. This applies to all template types. Before you import a template, ensure that you add the following section to the template:
<%# kind: provision name: My_Provisioning_Template oses: - My_first_OS - My_second_OS locations: - My_first_Location - My_second_Location organizations: - My_first_Organization - My_second_Organization %>
-
In
/var/lib/foreman
, create a directory for storing templates:# mkdir /var/lib/foreman/My_Templates_Dir
NoteYou can place your templates to a custom directory outside
/var/lib/foreman
, but you have to ensure that theForeman
service can read its contents. The directory must have the correct file permissions and theforeman_lib_t
SELinux label. -
Change the owner of the new templates directory to the
foreman
user:# chown foreman /var/lib/foreman/My_Templates_Dir
-
Change the Repo setting on the TemplateSync tab to match the
/var/lib/foreman/My_Templates_Dir/
directory.
14.4. Importing and exporting templates
You can import and export templates using the Foreman web UI, Hammer CLI, or Foreman API. Foreman API calls use the role-based access control system, which enables the tasks to be executed as any user. You can synchronize templates with a version control system, such as Git, or a local directory.
14.4.1. Importing templates
You can import templates from a repository of your choice.
You can use different protocols to point to your repository, for example /tmp/dir
, git://example.com
, https://example.com
, and ssh://example.com
.
Note
|
The templates provided by Foreman are locked and you cannot import them by default.
To overwrite this behavior, change the |
-
Each template must contain the location and organization that the template belongs to. This applies to all template types. Before you import a template, ensure that you add the following section to the template:
<%# kind: provision name: My_Provisioning_Template oses: - My_first_OS - My_second_OS locations: - My_first_Location - My_second_Location organizations: - My_first_Organization - My_second_Organization %>
To use the CLI instead of the Foreman web UI, see the CLI procedure. To use the API, see the API procedure.
-
In the Foreman web UI, navigate to Hosts > Templates > Sync Templates.
-
Click Import.
-
Each field is populated with values configured in Administer > Settings > TemplateSync. Change the values as required for the templates you want to import. For more information about each field, see Configuring the TemplateSync plugin.
-
Click Submit.
The Foreman web UI displays the status of the import. The status is not persistent; if you leave the status page, you cannot return to it.
-
To import a template from a repository, enter the following command:
$ hammer import-templates \ --branch "My_Branch" \ --filter '.*Template Name$' \ --organization "My_Organization" \ --prefix "[Custom Index] " \ --repo "https://git.example.com/path/to/repository"
For better indexing and management of your templates, use
--prefix
to set a category for your templates. To select certain templates from a large repository, use--filter
to define the title of the templates that you want to import. For example--filter '.*Ansible Default$'
imports various Ansible Default templates.
-
Send a
POST
request toapi/v2/templates/import
:# curl -H "Accept:application/json" \ -H "Content-Type:application/json" \ -u login:password \ -k https://foreman.example.com/api/v2/templates/import \ -X POST
If the import is successful, you receive
{"message":"Success"}
.
14.4.2. Exporting templates
Use this procedure to export templates to a git repository.
To use the CLI instead of the Foreman web UI, see the CLI procedure. To use the API, see the API procedure.
-
In the Foreman web UI, navigate to Hosts > Templates > Sync Templates.
-
Click Export.
-
Each field is populated with values configured in Administer > Settings > TemplateSync. Change the values as required for the templates you want to export. For more information about each field, see Configuring the TemplateSync plugin.
-
Click Submit.
The Foreman web UI displays the status of the export. The status is not persistent; if you leave the status page, you cannot return to it.
-
To export the templates to a repository, enter the following command:
# hammer export-templates \ --organization "My_Organization" \ --repo "https://git.example.com/path/to/repository"
NoteThis command clones the repository, makes changes in a commit, and pushes back to the repository. You can use the
--branch "My_Branch"
option to export the templates to a specific branch.
-
Send a
POST
request toapi/v2/templates/export
:# curl -H "Accept:application/json" \ -H "Content-Type:application/json" \ -u login:password \ -k https://foreman.example.com/api/v2/templates/export \ -X POST
If the export is successful, you receive
{"message":"Success"}
.
Note
|
You can override default API settings by specifying them in the request with the # curl -H "Accept:application/json" \ -H "Content-Type:application/json" \ -u login:password \ -k https://foreman.example.com/api/v2/templates/export \ -X POST \ -d "{\"repo\":\"git.example.com/templates\"}" |
14.5. Uninstalling the Foreman templates plugin
Use the following procedure to avoid errors after removing the foreman_templates plugin.
-
Disable the plugin using the Foreman installer:
# foreman-installer --no-enable-foreman-plugin-templates
-
Clean custom data of the plugin. The command does not affect any templates that you created.
# foreman-rake templates:cleanup
-
Uninstall the plugin:
# dnf remove foreman-plugin-templates
15. Managing packages
You can use Foreman to install, upgrade, and remove packages on hosts, as well as to enable or disable repositories on hosts.
15.1. Enabling and disabling repositories on hosts
Use this procedure to enable and disable repositories on hosts for Foreman.
-
In the Foreman web UI, navigate to Hosts > All Hosts,
-
Select the host name.
-
Click the Content tab.
-
Click the Repository Sets tab.
-
Click the vertical ellipsis to choose Override to disabled or Override to enabled to disable or enable repositories on hosts.
15.2. Installing packages on a host
Use this procedure to review and install packages on a host using the Foreman web UI. The list of packages available for installation depends on the content view and lifecycle environment assigned to the host.
-
In the Foreman web UI, navigate to Hosts > All Hosts and select the host you want to install packages on.
-
On the Content tab, select the Packages tab.
-
On the vertical ellipsis icon next to the upgrade button, click Install Packages.
-
In the Install packages window, select the package or packages that you want to install on the host.
-
Click Install.
By default, the packages are installed using remote execution. For more information about running remote execution jobs, see Configuring and Setting up Remote Jobs in Managing hosts.
Create a body of the API request in the JSON format by following the instructions below.
-
Create the
"job_invocation"
object and place rest of the body inside this object. -
Create the
"inputs"
object with the"package"
field of the string type specifying the packages you want to install. If you are specifying multiple packages, separate them with a whitespace. -
Create a
"feature"
field of the string type with value"katello_package_install"
. -
Create a
"search_query"
field of the string type and input a search query matching the hosts on which you want to install the packages. -
Optional: If you want to install packages as a specific user, create an
ssh
object with the following fields of the string type:-
"effective_user"
with the name of the ssh user -
"effective_user_password"
with the password of the ssh user if this password is required
-
-
Optional: If you want to install packages at a later time, create the
"scheduling"
object. The object can contain one or both of the following fields of the string type with date, time, and a timezone in the ISO 8601 format:-
"start_at"
- sets the time to install the packages -
"start_before"
- sets the latest time to install the packages. If it is not possible to install the packages by this time, then this action is cancelled.
If you omit time, it defaults to 00:00:00. If you omit timezone, it defaults to UTC.
-
-
Optional: If you want to limit the number of hosts on which the job is run concurrently, create the
"concurrency_control"
object with the"concurrency_level"
field of the integer type. Assign the number of hosts as the field value. -
Optional: If you want to install packages at a later time and you want the host search query to be evaluated at a time of running the job, create a
"targeting_type"
field of the string type with the"dynamic_query"
value. This is useful if you expect the result of the search query to be different at the time of running the job due to changed status of the hosts. If you omit this field, it defaults to"static_query"
. -
Send a
POST
request with the created body to the/api/job_invocations
endpoint of your Foreman server and use a tool like Python to see a formatted response.Example API request:
curl https://foreman.example.com/api/job_invocations \ -H "content-type: application/json" \ -X POST \ -d @Path_To_My_API_Request_Body \ -u My_Username:My_Password | python3 -m json.tool
-
In the Foreman web UI, navigate to Monitor > Jobs and see the report of the scheduled or completed remote execution job to install the packages on the selected hosts.
{
"job_invocation" : {
"concurrency_control" : {
"concurrency_level" : 100
},
"feature" : "katello_package_install",
"inputs" : {
"package" : "nano vim"
},
"scheduling" : {
"start_at" : "2023-09-21T19:00:00+00:00",
"start_before" : "2023-09-23T00:00:00+00:00"
},
"search_query" : "*",
"ssh" : {
"effective_user" : "My_Username",
"effective_user_password" : "My_Password"
},
"targeting_type" : "dynamic_query"
}
}
15.3. Upgrading packages on a host
You can upgrade packages on a host in bulk in the Foreman web UI.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click the Content tab, then click the Packages tab.
-
Select Upgradable from the Status list.
-
Select upgrade version from the dropdown menu in Upgradable to column where applicable.
-
Select the packages you want to upgrade.
-
Click Upgrade. You get a REX job notification once the remote execution job is complete.
Create a body of the API request in the JSON format by following the instructions below.
-
Create the
"job_invocation"
object and place rest of the body inside this object. -
Create the
"inputs"
object with the"package"
field of the string type specifying the packages you want to update. If you are specifying multiple packages, separate them with a whitespace. -
Create a
"feature"
field of the string type with value"katello_package_update"
. -
Create a
"search_query"
field of the string type and input a search query matching the hosts on which you want to update the packages. -
Optional: If you want to update packages as a specific user, create an
ssh
object with the following fields of the string type:-
"effective_user"
with the name of the ssh user -
"effective_user_password"
with the password of the ssh user if this password is required
-
-
Optional: If you want to update packages at a later time, create the
"scheduling"
object. The object can contain one or both of the following fields of the string type with date, time, and a timezone in the ISO 8601 format:-
"start_at"
- sets the time to update the packages -
"start_before"
- sets the latest time to update the packages. If it is not possible to update the packages by this time, then this action is cancelled.
If you omit time, it defaults to 00:00:00. If you omit timezone, it defaults to UTC.
-
-
Optional: If you want to limit the number of hosts on which the job is run concurrently, create the
"concurrency_control"
object with the"concurrency_level"
field of the integer type. Assign the number of hosts as the field value. -
Optional: If you want to update packages at a later time and you want the host search query to be evaluated at a time of running the job, create a
"targeting_type"
field of the string type with the"dynamic_query"
value. This is useful if you expect the result of the search query to be different at the time of running the job due to changed status of the hosts. If you omit this field, it defaults to"static_query"
. -
Send a
POST
request with the created body to the/api/job_invocations
endpoint of your Foreman server and use a tool like Python to see a formatted response.Example API request:
curl https://foreman.example.com/api/job_invocations \ -H "content-type: application/json" \ -X POST \ -d @Path_To_My_API_Request_Body \ -u My_Username:My_Password | python3 -m json.tool
-
In the Foreman web UI, navigate to Monitor > Jobs and see the report of the scheduled or completed remote execution job to update the packages on the selected hosts.
{
"job_invocation" : {
"concurrency_control" : {
"concurrency_level" : 100
},
"feature" : "katello_package_update",
"inputs" : {
"package" : "nano vim"
},
"scheduling" : {
"start_at" : "2023-09-21T19:00:00+00:00",
"start_before" : "2023-09-23T00:00:00+00:00"
},
"search_query" : "*",
"ssh" : {
"effective_user" : "My_Username",
"effective_user_password" : "My_Password"
},
"targeting_type" : "dynamic_query"
}
}
15.4. Removing packages from a host
You can remove packages from a host in the Foreman web UI.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
Click the name of the host you want to modify.
-
Click the Content tab, then click the Packages tab.
-
Click the vertical ellipsis for the package you want to remove and select Remove. You get a REX job notification once the remote execution job is complete.
Create a body of the API request in the JSON format by following the instructions below.
-
Create the
"job_invocation"
object and place rest of the body inside this object. -
Create the
"inputs"
object with the"package"
field of the string type specifying the packages you want to remove. If you are specifying multiple packages, separate them with a whitespace. -
Create a
"feature"
field of the string type with value"katello_package_remove"
. -
Create a
"search_query"
field of the string type and input a search query matching the hosts on which you want to remove the packages. -
Optional: If you want to remove packages as a specific user, create an
ssh
object with the following fields of the string type:-
"effective_user"
with the name of the ssh user -
"effective_user_password"
with the password of the ssh user if this password is required
-
-
Optional: If you want to remove packages at a later time, create the
"scheduling"
object. The object can contain one or both of the following fields of the string type with date, time, and a timezone in the ISO 8601 format:-
"start_at"
- sets the time to remove the packages -
"start_before"
- sets the latest time to remove the packages. If it is not possible to remove the packages by this time, then this action is cancelled.
If you omit time, it defaults to 00:00:00. If you omit timezone, it defaults to UTC.
-
-
Optional: If you want to limit the number of hosts on which the job is run concurrently, create the
"concurrency_control"
object with the"concurrency_level"
field of the integer type. Assign the number of hosts as the field value. -
Optional: If you want to remove packages at a later time and you want the host search query to be evaluated at a time of running the job, create a
"targeting_type"
field of the string type with the"dynamic_query"
value. This is useful if you expect the result of the search query to be different at the time of running the job due to changed status of the hosts. If you omit this field, it defaults to"static_query"
. -
Send a
POST
request with the created body to the/api/job_invocations
endpoint of your Foreman server and use a tool like Python to see a formatted response.Example API request:
curl https://foreman.example.com/api/job_invocations \ -H "content-type: application/json" \ -X POST \ -d @Path_To_My_API_Request_Body \ -u My_Username:My_Password | python3 -m json.tool
-
In the Foreman web UI, navigate to Monitor > Jobs and see the report of the scheduled or completed remote execution job to remove the packages on the selected hosts.
{
"job_invocation" : {
"concurrency_control" : {
"concurrency_level" : 100
},
"feature" : "katello_package_remove",
"inputs" : {
"package" : "nano vim"
},
"scheduling" : {
"start_at" : "2023-09-21T19:00:00+00:00",
"start_before" : "2023-09-23T00:00:00+00:00"
},
"search_query" : "*",
"ssh" : {
"effective_user" : "My_Username",
"effective_user_password" : "My_Password"
},
"targeting_type" : "dynamic_query"
}
}
Appendix A: Template writing reference
Embedded Ruby (ERB) is a tool for generating text files based on templates that combine plain text with Ruby code. Foreman uses ERB syntax in the following cases:
- Provisioning templates
-
For more information, see Creating Provisioning Templates in Provisioning hosts.
- Remote execution job templates
-
For more information, see Configuring and setting up remote jobs.
- Report templates
-
For more information, see Using report templates to monitor hosts.
- Templates for partition tables
-
For more information, see Creating Partition Tables in Provisioning hosts.
- Smart Class Parameters
-
For more information, see Configuring Puppet Smart Class Parameters in Configuring hosts by using Puppet.
This section provides an overview of Foreman-specific macros and variables that can be used in ERB templates along with some usage examples. Note that the default templates provided by Foreman (Hosts > Templates > Provisioning Templates, Hosts > Templates > Job templates, Monitor > Reports > Report Templates ) also provide a good source of ERB syntax examples.
When provisioning a host or running a remote job, the code in the ERB is executed and the variables are replaced with the host specific values. This process is referred to as rendering. Foreman server has the safemode rendering option enabled by default, which prevents any harmful code being executed from templates.
Accessing the template writing reference in the Foreman web UI
You can access the template writing reference document in the Foreman web UI.
-
Log in to the Foreman web UI.
-
In the Foreman web UI, navigate to Administer > About.
-
Click the Templates DSL link in the Support section.
Using autocompletion in templates
You can access a list of available macros and usage information in the template editor with the autocompletion option. This works for all templates within Foreman.
-
In the Foreman web UI, navigate to either Hosts > Templates > Partition tables, Hosts > Templates > Provisioning Templates, or Hosts > Templates > Job templates.
-
Click the settings icon at the top right corner of the template editor and select Autocompletion.
-
Press
Ctrl
+Space
in the template editor to access a list of all available macros. You can narrow down the list of macros by typing in more information about what you are looking for. For example, if you are looking for a method to list the ID of the content source for a host, you can typehost
and check the list of available macros for content source. -
A window next to the dropdown provides a description of the macro, its usage, and the value it will return.
-
When you find the method you are looking for, hit
Enter
to input the method.
You can also enable Live Autocompletion in the settings menu to view a list of macros that match the pattern whenever you type something. However, this might input macros in unintended places, like package names in a provisioning template.
Writing ERB templates
The following tags are the most important and commonly used in ERB templates:
All Ruby code is enclosed within <% %>
in an ERB template.
The code is executed when the template is rendered.
It can contain Ruby control flow structures as well as Foreman-specific macros and variables.
For example:
<% if @host.operatingsystem.family == "Redhat" && @host.operatingsystem.major.to_i > 6 -%> systemctl <%= input("action") %> <%= input("service") %> <% else -%> service <%= input("service") %> <%= input("action") %> <% end -%>
Note that this template silently performs an action with a service and returns nothing at the output.
This provides the same functionality as <% %>
but when the template is executed, the code output is inserted into the template.
This is useful for variable substitution, for example:
Example input:
echo <%= @host.name %>
Example rendering:
host.example.com
Example input:
<% server_name = @host.fqdn %> <%= server_name %>
Example rendering:
host.example.com
Note that if you enter an incorrect variable, no output is returned. However, if you try to call a method on an incorrect variable, the following error message returns:
Example input:
<%= @example_incorrect_variable.fqdn -%>
Example rendering:
undefined method `fqdn' for nil:NilClass
By default, a newline character is inserted after a Ruby block if it is closed at the end of a line:
Example input:
<%= "line1" %> <%= "line2" %>
Example rendering:
line1 line2
To change the default behavior, modify the enclosing mark with -%>
:
Example input:
<%= "line1" -%> <%= "line2" %>
Example rendering:
line1line2
This is used to reduce the number of lines, where Ruby syntax permits, in rendered templates. White spaces in ERB tags are ignored.
An example of how this would be used in a report template to remove unnecessary newlines between a FQDN and IP address:
Example input:
<%= @host.fqdn -%> <%= @host.ip -%>
Example rendering:
host.example.com10.10.181.216
Encloses a comment that is ignored during template rendering:
Example input:
<%# A comment %>
This generates no output.
Because of the varying lengths of the ERB tags, indenting the ERB syntax might seem messy. ERB syntax ignore white space. One method of handling the indentation is to declare the ERB tag at the beginning of each new line and then use white space within the ERB tag to outline the relationships within the syntax, for example:
<%- load_hosts.each do |host| -%> <%- if host.build? %> <%= host.name %> build is in progress <%- end %> <%- end %>
Troubleshooting ERB templates
The Foreman web UI provides two ways to verify the template rendering for a specific host:
-
Directly in the template editor – when editing a template (under Hosts > Templates > Partition tables, Hosts > Templates > Provisioning Templates, or Hosts > Templates > Job templates), on the Template tab click Preview and select a host from the list. The template then renders in the text field using the selected host’s parameters. Preview failures can help to identify issues in your template.
-
At the host’s details page – select a host at Hosts > All Hosts and click the Templates tab to list templates associated with the host. Select Review from the list next to the selected template to view it’s rendered version.
Generic Foreman-specific macros
This section lists Foreman-specific macros for ERB templates. You can use the macros listed in the following table across all kinds of templates.
Name | Description |
---|---|
indent(n) |
Indents the block of code by n spaces, useful when using a snippet template that is not indented. |
foreman_url(kind) |
Returns the full URL to host-rendered templates of the given kind.
For example, templates of the "provision" type usually reside at |
snippet(name) |
Renders the specified snippet template. Useful for nesting provisioning templates. |
snippets(file) |
Renders the specified snippet found in the Foreman database, attempts to load it from the |
snippet_if_exists(name) |
Renders the specified snippet, skips if no snippet with the specified name is found. |
Template macros
If you want to write custom templates, you can use some of the following macros. Depending on the template type, some of the following macros have different requirements.
For more information about the available macros for report templates, in the Foreman web UI, navigate to Monitor > Reports > Report Templates, and click Create Template. In the Create Template window, click the Help tab.
For more information about the available macros for job templates, in the Foreman web UI, navigate to Hosts > Templates > Job templates, and click the New Job Template. In the New Job Template window, click the Help tab.
- input
-
Using the
input
macro, you can customize the input data that the template can work with. You can define the input name, type, and the options that are available for users. For report templates, you can only use user inputs. When you define a new input and save the template, you can then reference the input in the ERB syntax of the template body.<%= input('cpus') %>
This loads the value from user input
cpus
. - load_hosts
-
Using the
load_hosts
macro, you can generate a complete list of hosts.<%- load_hosts().each_record do |host| -%> <%= host.name %>
Use the
load_hosts
macro with theeach_record
macro to load records in batches of 1000 to reduce memory consumption.If you want to filter the list of hosts for the report, you can add the option
search: input(‘Example_Host’)
:<% load_hosts(search: input('Example_Host')).each_record do |host| -%> <%= host.name %> <% end -%>
In this example, you first create an input that you then use to refine the search criteria that the
load_hosts
macro retrieves. - report_row
-
Using the
report_row
macro, you can create a formatted report for ease of analysis. Thereport_row
macro requires thereport_render
macro to generate the output.Example input:<%- load_hosts(search: input('Example_Host')).each_record do |host| -%> <%- report_row( 'Server FQDN': host.name ) -%> <%- end -%> <%= report_render -%>
Example rendering:Server FQDN host1.example.com host2.example.com host3.example.com host4.example.com host5.example.com host6.example.com
You can add extra columns to the report by adding another header. The following example adds IP addresses to the report:
Example input:<%- load_hosts(search: input('host')).each_record do |host| -%> <%- report_row( 'Server FQDN': host.name, 'IP': host.ip ) -%> <%- end -%> <%= report_render -%>
Example rendering:Server FQDN,IP host1.example.com,10.8.30.228 host2.example.com,10.8.30.227 host3.example.com,10.8.30.226 host4.example.com,10.8.30.225 host5.example.com,10.8.30.224 host6.example.com,10.8.30.223
- report_render
-
This macro is available only for report templates.
Using the
report_render
macro, you create the output for the report. During the template rendering process, you can select the format that you want for the report. YAML, JSON, HTML, and CSV formats are supported.<%= report_render -%>
- render_template()
-
This macro is available only for job templates.
Using this macro, you can render a specific template. You can also enable and define arguments that you want to pass to the template.
- truthy
-
Using the
truthy
macro, you can declare if the value passed is true or false, regardless of whether the value is an integer or boolean or string.This macro helps to avoid confusion when your template contains multiple value types. For example, the boolean value
true
is not the same as the string value"true"
. With this macro, you can declare how you want the template to interpret the value and avoid confusion.You can use
truthy
to declare values as follows:truthy?("true") => true truthy?(1) => true truthy?("false") => false truthy?(0) => false
- falsy
-
The falsy macro serves the same purpose as the truthy macro.
Using the
falsy
macro, you can declare if the value passed in is true or false, regardless of whether the value is an integer or boolean or string.You can use
falsy
to declare values as follows:falsy?("true") => false falsy?(1) => false falsy?("false") => true falsy?(0) => true
Host-specific variables
The following variables enable using host data within templates.
Note that job templates accept only @host
variables.
Name | Description |
---|---|
@host.architecture |
The architecture of the host. |
@host.bond_interfaces |
Returns an array of all bonded interfaces. See Parsing arrays. |
@host.capabilities |
The method of system provisioning, can be either build (for example kickstart) or image. |
@host.certname |
The SSL certificate name of the host. |
@host.diskLayout |
The disk layout of the host. Can be inherited from the operating system. |
@host.domain |
The domain of the host. |
@host.environment Deprecated Use the |
The Puppet environment of the host. |
@host.facts |
Returns a Ruby hash of facts from Facter. For example to access the 'ipaddress' fact from the output, specify @host.facts['ipaddress']. |
@host.grub_pass |
Returns the host’s bootloader password. |
@host.hostgroup |
The host group of the host. |
host_enc['parameters'] |
Returns a Ruby hash containing information on host parameters. For example, use host_enc['parameters']['lifecycle_environment'] to get the lifecycle environment of a host. |
@host.image_build? |
Returns |
@host.interfaces |
Contains an array of all available host interfaces including the primary interface. See Parsing arrays. |
@host.interfaces_with_identifier('IDs') |
Returns array of interfaces with given identifier. You can pass an array of multiple identifiers as an input, for example @host.interfaces_with_identifier(['eth0', 'eth1']). See Parsing arrays. |
@host.ip |
The IP address of the host. |
@host.location |
The location of the host. |
@host.mac |
The MAC address of the host. |
@host.managed_interfaces |
Returns an array of managed interfaces (excluding BMC and bonded interfaces). See Parsing arrays. |
@host.medium |
The assigned operating system installation medium. |
@host.name |
The full name of the host. |
@host.operatingsystem.family |
The operating system family. |
@host.operatingsystem.major |
The major version number of the assigned operating system. |
@host.operatingsystem.minor |
The minor version number of the assigned operating system. |
@host.operatingsystem.name |
The assigned operating system name. |
@host.operatingsystem.boot_files_uri(medium_provider) |
Full path to the kernel and initrd, returns an array. |
@host.os.medium_uri(@host) |
The URI used for provisioning (path configured in installation media). |
host_param('parameter_name') |
Returns the value of the specified host parameter. |
host_param_false?('parameter_name') |
Returns |
host_param_true?('parameter_name') |
Returns |
@host.primary_interface |
Returns the primary interface of the host. |
@host.provider |
The compute resource provider. |
@host.provision_interface |
Returns the provisioning interface of the host. Returns an interface object. |
@host.ptable |
The partition table name. |
@host.puppet_ca_server Deprecated Use the |
The Puppet CA server the host must use. |
@host.puppetmaster Deprecated Use the |
The Puppet server the host must use. |
@host.pxe_build? |
Returns |
@host.shortname |
The short name of the host. |
@host.sp_ip |
The IP address of the BMC interface. |
@host.sp_mac |
The MAC address of the BMC interface. |
@host.sp_name |
The name of the BMC interface. |
@host.sp_subnet |
The subnet of the BMC network. |
@host.subnet.dhcp |
Returns |
@host.subnet.dns_primary |
The primary DNS server of the host. |
@host.subnet.dns_secondary |
The secondary DNS server of the host. |
@host.subnet.gateway |
The gateway of the host. |
@host.subnet.mask |
The subnet mask of the host. |
@host.url_for_boot(:initrd) |
Full path to the initrd image associated with this host. Not recommended, as it does not interpolate variables. |
@host.url_for_boot(:kernel) |
Full path to the kernel associated with this host. Not recommended, as it does not interpolate variables, prefer boot_files_uri. |
@provisioning_type |
Equals to 'host' or 'hostgroup' depending on type of provisioning. |
@static |
Returns |
@template_name |
Name of the template being rendered. |
grub_pass |
Returns a bootloader argument to set the encrypted bootloader password, such as --md5pass=#{@host.grub_pass}. |
ks_console |
Returns a string assembled using the port and the baud rate of the host which can be added to a kernel line. For example console=ttyS1,9600. |
root_pass |
Returns the root password configured for the system. |
The majority of common Ruby methods can be applied on host-specific variables. For example, to extract the last segment of the host’s IP address, you can use:
<% @host.ip.split('.').last %>
Kickstart-specific variables
The following variables are designed to be used within kickstart provisioning templates.
Name | Description |
---|---|
@arch |
The host architecture name, same as @host.architecture.name. |
@dynamic |
Returns |
@epel |
A command which will automatically install the correct version of the epel-release rpm. Use in a %post script. |
@mediapath |
The full kickstart line to provide the URL command. |
@osver |
The operating system major version number, same as @host.operatingsystem.major. |
Conditional statements
In your templates, you might perform different actions depending on which value exists. To achieve this, you can use conditional statements in your ERB syntax.
In the following example, the ERB syntax searches for a specific host name and returns an output depending on the value it finds:
<% load_hosts().each_record do |host| -%> <% if @host.name == "host1.example.com" -%> <% result="positive" -%> <% else -%> <% result="negative" -%> <% end -%> <%= result -%>
host1.example.com positive
Parsing arrays
While writing or modifying templates, you might encounter variables that return arrays.
For example, host variables related to network interfaces, such as @host.interfaces
or @host.bond_interfaces
, return interface data grouped in an array.
To extract a parameter value of a specific interface, use Ruby methods to parse the array.
The following procedure is an example that you can use to find the relevant methods to parse arrays in your template. In this example, a report template is used, but the steps are applicable to other templates.
-
To retrieve the NIC of a content host, in this example, using the
@host.interfaces
variable returns class values that you can then use to find methods to parse the array.Example input:<%= @host.interfaces -%>
Example rendering:<Nic::Base::ActiveRecord_Associations_CollectionProxy:0x00007f734036fbe0>
-
In the Create Template window, click the Help tab and search for the
ActiveRecord_Associations_CollectionProxy
andNic::Base
classes. -
For
ActiveRecord_Associations_CollectionProxy
, in the Allowed methods or members column, you can view the following methods to parse the array:[] each find_in_batches first map size to_a
-
For
Nic::Base
, in the Allowed methods or members column, you can view the following method to parse the array:alias? attached_devices attached_devices_identifiers attached_to bond_options children_mac_addresses domain fqdn identifier inheriting_mac ip ip6 link mac managed? mode mtu nic_delay physical? primary provision shortname subnet subnet6 tag virtual? vlanid
-
To iterate through an interface array, add the relevant methods to the ERB syntax:
Example input:<% load_hosts().each_record do |host| -%> <% host.interfaces.each do |iface| -%> iface.alias?: <%= iface.alias? %> iface.attached_to: <%= iface.attached_to %> iface.bond_options: <%= iface.bond_options %> iface.children_mac_addresses: <%= iface.children_mac_addresses %> iface.domain: <%= iface.domain %> iface.fqdn: <%= iface.fqdn %> iface.identifier: <%= iface.identifier %> iface.inheriting_mac: <%= iface.inheriting_mac %> iface.ip: <%= iface.ip %> iface.ip6: <%= iface.ip6 %> iface.link: <%= iface.link %> iface.mac: <%= iface.mac %> iface.managed?: <%= iface.managed? %> iface.mode: <%= iface.mode %> iface.mtu: <%= iface.mtu %> iface.physical?: <%= iface.physical? %> iface.primary: <%= iface.primary %> iface.provision: <%= iface.provision %> iface.shortname: <%= iface.shortname %> iface.subnet: <%= iface.subnet %> iface.subnet6: <%= iface.subnet6 %> iface.tag: <%= iface.tag %> iface.virtual?: <%= iface.virtual? %> iface.vlanid: <%= iface.vlanid %> <%- end -%>
Example rendering:host1.example.com iface.alias?: false iface.attached_to: iface.bond_options: iface.children_mac_addresses: [] iface.domain: iface.fqdn: host1.example.com iface.identifier: ens192 iface.inheriting_mac: 00:50:56:8d:4c:cf iface.ip: 10.10.181.13 iface.ip6: iface.link: true iface.mac: 00:50:56:8d:4c:cf iface.managed?: true iface.mode: balance-rr iface.mtu: iface.physical?: true iface.primary: true iface.provision: true iface.shortname: host1.example.com iface.subnet: iface.subnet6: iface.tag: iface.virtual?: false iface.vlanid:
Example template snippets
The following example checks if the host has the Puppet and Puppetlabs repositories enabled:
<% pm_set = @host.puppetmaster.empty? ? false : true puppet_enabled = pm_set || host_param_true?('force-puppet') puppetlabs_enabled = host_param_true?('enable-puppetlabs-repo') %>
The following example shows how to capture the minor and major version of the host’s operating system, which can be used for package related decisions:
<% os_major = @host.operatingsystem.major.to_i os_minor = @host.operatingsystem.minor.to_i %> <% if ((os_minor < 2) && (os_major < 14)) -%> ... <% end -%>
The following example imports the subscription_manager_registration snippet to the template and indents it by four spaces:
<%= indent 4 do snippet 'subscription_manager_registration' end %>
The following example imports the kickstart_networking_setup
snippet if the host’s subnet has the DHCP boot mode enabled:
<% subnet = @host.subnet %> <% if subnet.respond_to?(:dhcp_boot_mode?) -%> <%= snippet 'kickstart_networking_setup' %> <% end -%>
You can use the host.facts
variable to parse values from a host’s facts and custom facts.
In this example luks_stat
is a custom fact that you can parse in the same manner as dmi::system::serial_number
, which is a host fact:
'Serial': host.facts['dmi::system::serial_number'], 'Encrypted': host.facts['luks_stat'],
In this example, you can customize the Applicable Errata report template to parse for custom information about the kernel version of each host:
<%- report_row( 'Host': host.name, 'Operating System': host.operatingsystem, 'Kernel': host.facts['uname::release'], 'Environment': host.single_lifecycle_environment ? host.single_lifecycle_environment.name : nil, 'Erratum': erratum.errata_id, 'Type': erratum.errata_type, 'Published': erratum.issued, 'Applicable since': erratum.created_at, 'Severity': erratum.severity, 'Packages': erratum.package_names, 'CVEs': erratum.cves, 'Reboot suggested': erratum.reboot_suggested, ) -%>
Appendix B: Job template examples and extensions
Use this section as a reference to help modify, customize, and extend your job templates to suit your requirements.
Customizing job templates
When creating a job template, you can include an existing template in the template editor field. This way you can combine templates, or create more specific templates from the general ones.
The following template combines default templates to install and start the nginx service on clients:
<%= render_template 'Package Action - SSH Default', :action => 'install', :package => 'nginx' %>
<%= render_template 'Service Action - SSH Default', :action => 'start', :service_name => 'nginx' %>
The above template specifies parameter values for the rendered template directly. It is also possible to use the input() method to allow users to define input for the rendered template on job execution. For example, you can use the following syntax:
<%= render_template 'Package Action - SSH Default', :action => 'install', :package => input("package") %>
With the above template, you have to import the parameter definition from the rendered template. To do so, navigate to the Jobs tab, click Add Foreign Input Set, and select the rendered template from the Target template list. You can import all parameters or specify a comma separated list.
Default job template categories
Job template category | Description |
---|---|
Packages |
Templates for performing package related actions. Install, update, and remove actions are included by default. |
Puppet |
Templates for executing Puppet runs on target hosts. |
Power |
Templates for performing power related actions. Restart and shutdown actions are included by default. |
Commands |
Templates for executing custom commands on remote hosts. |
Services |
Templates for performing service related actions. Start, stop, restart, and status actions are included by default. |
Katello |
Templates for performing content related actions. These templates are used mainly from different parts of the Foreman web UI (for example bulk actions UI for content hosts), but can be used separately to perform operations such as errata installation. |
Example restorecon template
This example shows how to create a template called Run Command - restorecon that restores the default SELinux context for all files in the selected directory on target hosts.
-
In the Foreman web UI, navigate to Hosts > Templates > Job templates.
-
Click New Job Template.
-
Enter Run Command - restorecon in the Name field. Select Default to make the template available to all organizations. Add the following text to the template editor:
restorecon -RvF <%= input("directory") %>
The
<%= input("directory") %>
string is replaced by a user-defined directory during job invocation. -
On the Job tab, set Job category to
Commands
. -
Click Add Input to allow job customization. Enter
directory
to the Name field. The input name must match the value specified in the template editor. -
Click Required so that the command cannot be executed without the user specified parameter.
-
Select User input from the Input type list. Enter a description to be shown during job invocation, for example
Target directory for restorecon
. -
Click Submit. For more information, see Executing a restorecon Template on Multiple Hosts in Managing hosts.
Rendering a restorecon template
This example shows how to create a template derived from the Run command - restorecon template created in Example restorecon Template.
This template does not require user input on job execution, it will restore the SELinux context in all files under the /home/
directory on target hosts.
Create a new template as described in Setting up Job Templates, and specify the following string in the template editor:
<%= render_template("Run Command - restorecon", :directory => "/home") %>
Executing a restorecon template on multiple hosts
This example shows how to run a job based on the template created in Example restorecon Template on multiple hosts.
The job restores the SELinux context in all files under the /home/
directory.
-
In the Foreman web UI, navigate to Monitor > Jobs and click Run job.
-
Select Commands as Job category and Run Command – restorecon as Job template and click Next.
-
Select the hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.
-
In the directory field, provide a directory, for example
/home
, and click Next. -
Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Advanced settings in the job wizard. When you are done entering the advanced settings or if it is not required, click Next.
-
Schedule time for the job.
-
To execute the job immediately, keep the pre-selected Immediate execution.
-
To execute the job in future time, select Future execution.
-
To execute the job on regular basis, select Recurring execution.
-
-
Optional: If you selected future or recurring execution, select the Query type, otherwise click Next.
-
Static query means that the job executes on the exact list of hosts that you provided.
-
Dynamic query means that the list of hosts is evaluated just before the job is executed. If you entered the list of hosts based on some filter, the results can be different from when you first used that filter.
Click Next after you have selected the query type.
-
-
Optional: If you selected future or recurring execution, provide additional details:
-
For Future execution, enter the Starts at date and time. You also have the option to select the Starts before date and time. If the job cannot start before that time, it will be canceled.
-
For Recurring execution, select the start date and time, frequency, and condition for ending the recurring job. You can choose the recurrence to never end, end at a certain time, or end after a given number of repetitions. You can also add Purpose - a special label for tracking the job. There can only be one active job with a given purpose at a time.
Click Next after you have entered the required information.
-
-
Review job details. You have the option to return to any part of the job wizard and edit the information.
-
Click Submit to schedule the job for execution.
Including power actions in templates
This example shows how to set up a job template for performing power actions, such as reboot. This procedure prevents Foreman from interpreting the disconnect exception upon reboot as an error, and consequently, remote execution of the job works correctly.
Create a new template as described in Setting up Job Templates, and specify the following string in the template editor:
<%= render_template("Power Action - SSH Default", :action => "restart") %>
Appendix C: Overview of the host columns
Below is the complete overview of columns that can be displayed in the host table divided into content categories. Some columns fall under more than one category. For more information on how to customize columns in the host table, see Selecting host columns.
- General
-
-
Power – Whether the host is turned on or off, if available
-
Name – name of the host
-
Operating system – operating system of the host
-
Model – host hardware model (or compute resource in case of virtual hosts)
-
Owner – user or group owning the host
-
Host group – host group of the host
-
Last report – time of the last host report
-
Comment – comment given to host
-
- Content
-
-
Name – name of the host
-
Operating system – operating system of the host
-
Installable updates – numbers of installable updates divided into four categories: security, bugfix, enhancement, total
-
Lifecycle environment – lifecycle environment of the host
-
Content view – content view of the host
-
Registered – time when the host was registered to Foreman
-
Last checkin – last time of the communication between the host and the Foreman server
-
- Network
-
-
IPv4 – IPv4 address of the host
-
IPv6 – IPv6 address of the host
-
MAC – MAC address of the host
-
- Reported data
-
-
Sockets – number of host sockets
-
Cores – number of host processor cores
-
RAM – amount of memory
-
Boot time – last boot time of the host
-
Virtual – whether or not the host is recognized as a virtual machine
-
Disks total space – total host storage space
-
Kernel Version – Kernel version of the host operating system
-
BIOS vendor – vendor of the host BIOS
-
BIOS release date – release date of the host BIOS
-
BIOS version – version of the host BIOS
-
- Puppet (only if the Puppet plugin is installed)
-
-
Environment name – name of the Puppet environment of the host
-