1. Foreman overview and concepts

Foreman is a centralized tool for provisioning, remote management, and monitoring of multiple Enterprise Linux deployments. With Foreman, you can deploy, configure, and maintain your systems across physical, virtual, and cloud environments.

1.1. Provisioning management with Foreman

With Foreman, you can provision hosts on various compute resources with many provisioning methods from a unified interface.

1.1.1. Provisioning methods in Foreman

With Foreman, you can provision hosts by using the following methods.

Bare-metal hosts

Foreman provisions bare-metal hosts primarily by using PXE boot and MAC address identification. When provisioning bare-metal hosts with Foreman, you can do the following:

  • Create host entries and specify the MAC address of the physical host to provision.

  • Boot blank hosts to use the Foreman Discovery service, which creates a pool of hosts that are ready for provisioning.

  • Provision hosts with UEFI Secure Boot.

  • Boot and provision hosts by using PXE-less methods.

Cloud providers

Foreman connects to private and public cloud providers to provision instances of hosts from images stored in the cloud environment. When provisioning from cloud with Foreman, you can do the following:

  • Select which hardware profile to use.

  • Provision cloud instances from specific providers by using their APIs.

Virtualization infrastructure

Foreman connects to virtualization infrastructure services, such as oVirt and VMware. When provisioning virtual machines with Foreman, you can do the following:

  • Provision virtual machines from virtual image templates.

  • Use the same PXE-based boot methods that you use to provision bare-metal hosts.

1.1.2. Additional resources

1.2. Major Foreman components

A typical Foreman deployment consists of the following components: a Foreman server, Smart Proxy servers that mirror content from Foreman server, and hosts that receive content and configuration from Foreman server and Smart Proxy servers.

1.2.1. Foreman server overview

Foreman server is the central component of a Foreman deployment where you plan and manage the content lifecycle.

A typical Foreman deployment includes one Foreman server on which you perform the following operations:

  • Content lifecycle management

  • Configuration of Smart Proxy servers

  • Configuration of hosts

  • Host provisioning

  • Patch management

  • Subscription management

Foreman server delegates content distribution, host provisioning, and communication to Smart Proxy servers. Foreman server itself also includes a Smart Proxy.

Foreman server also contains a fine-grained authentication system. You can grant Foreman users permissions to access precisely the parts of the infrastructure for which they are responsible.

Additional resources

1.2.2. Smart Proxy overview

With Smart Proxy servers, you can extend the reach and scalability of your Foreman deployment. Smart Proxy servers provide the following functionalities in a Foreman deployment:

  • Running localized services to discover, provision, control, and configure hosts.

1.2.3. 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.2.4. List of key open source components of Foreman

Foreman consists of several open source projects integrated with each other, such as the following:

Foreman

Foreman is a lifecycle management application for physical and virtual systems. It helps manage hosts throughout their lifecycle, from provisioning and configuration to orchestration and monitoring.

Katello

Katello is an optional plugin of Foreman that extends Foreman capabilities with additional features for content, subscription, and repository management. Katello enables Foreman to subscribe to repositories and to download content.

Candlepin

Candlepin is a service for subscription management.

Pulp

Pulp is a service for repository and content management.

1.2.5. Smart Proxy features

Smart Proxy servers provide local host management services.

Smart Proxies provide the following functionalities:

DHCP

Smart Proxy can manage a DHCP server, including integration with an existing solution, such as ISC DHCP servers, Active Directory, and Libvirt instances.

DNS

Smart Proxy can manage a DNS server, including integration with an existing solution, such as ISC BIND and Active Directory.

TFTP

Smart Proxy can integrate with any UNIX-based TFTP server.

Realm

Smart Proxy can manage Kerberos realms or domains so that hosts can join them automatically during provisioning. Smart Proxy can integrate with an existing infrastructure, including FreeIPA and Active Directory.

Puppet server

Smart Proxy can act as a configuration management server by running a Puppet server.

Puppet Certificate Authority

Smart Proxy can integrate with the Puppet certificate authority (CA) to provide certificates to hosts.

Baseboard Management Controller (BMC)

Smart Proxy can provide power management for hosts by using the Intelligent Platform Management Interface (IPMI) or Redfish standards.

Provisioning template proxy

Smart Proxy can serve provisioning templates to hosts.

OpenSCAP

Smart Proxy can perform security compliance scans on hosts.

Remote Execution (REX)

Smart Proxy can run remote job execution on hosts.

You can configure a Smart Proxy server for a specific limited purpose by enabling only selected features on that Smart Proxy. Common configurations include the following:

Infrastructure Smart Proxies: DNS + DHCP + TFTP

Smart Proxies with these services provide infrastructure services for hosts and have all necessary services for provisioning new hosts.

1.2.6. Smart Proxy networking

The communication between Foreman server and hosts registered to a Smart Proxy server is routed through that Smart Proxy server. Smart Proxy server also provides Foreman services to hosts.

Many of the services that Smart Proxy server manages use dedicated network ports. However, Smart Proxy server ensures that all communications from the host to Foreman server use a single source IP address, which simplifies firewall administration.

Foreman topology with hosts connecting to a Smart Proxy

In this topology, Smart Proxy provides a single endpoint for all host network communications so that in remote network segments, only firewall ports to the Smart Proxy itself must be open.

Foreman topology with hosts connecting directly to Foreman server

In this topology, hosts connect to Foreman server rather than a Smart Proxy. This applies also to Smart Proxies themselves because the Smart Proxy server is a host of Foreman server.

Additional resources

1.2.7. Additional resources

1.3. Foreman infrastructure organization concepts

You can use several elements to structure and organize the resources within your Foreman environment.

1.3.1. Organizations and locations in Foreman

On your Foreman server, you can define organizations and locations to help organize content, hosts, and configurations. Organizations and locations enable you to arrange Foreman resources into logically structured groups. For example, you can create groups based on ownership, purpose, content, or security level. You can create and manage multiple organizations through Foreman, then divide and assign subscriptions to each individual organization.

Organizations

Organizations typically represent different business units, departments, or teams, such as Finance, Marketing, or Web Development. To manage Red Hat content, each organization requires a separate Red Hat subscription manifest.

By creating organizations, you can create logical containers to isolate and manage their configurations separately according to their specific requirements.

Locations

Locations typically represent physical locations, such as countries or cities.

By creating locations, you can define geographical sites where hosts are located. For example, this is useful in environments with multiple data centers.

You can use locations to map the network infrastructure to prevent incorrect host placement or configuration. While you cannot assign a subnet, domain, or compute resources directly to a Smart Proxy server, you can assign them to a location.

Unlike organizations, locations can have a hierarchical structure.

Foreman server defines all locations and organizations. Each Smart Proxy server synchronizes content and handles configuration of hosts in a different location.

Your Foreman server retains the management function, while the content and configuration is synchronized between your Foreman server and Smart Proxy servers assigned to certain locations.

Example 1. Example of using organizations and locations in Foreman

The structure of a multi-national company includes the Finance, Marketing, and Sales departments. The company operates across United States, United Kingdom, and Japan.

The system administrator creates the following organizations on their Foreman server:

  • Finance

  • Marketing

  • Sales

Additionally, the administrator creates the following locations on their Foreman server:

  • United States

  • United Kingdom

  • Japan

The administrator can define a nested location hierarchy to divide the United States location into additional locations based on specific cities:

  • Boston

  • Phoenix

  • San Francisco

1.3.2. Host groups overview

A host group acts as a template for common host settings.

With host groups, you can define many settings for hosts, such as host parameters or operating system settings that are available to the hosts. Instead of defining the settings individually for each host, you can use host groups to define common settings once and apply them to multiple hosts.

You can create nested host groups.

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.

1.3.3. Additional resources

1.4. Tools for administration of Foreman

You can use multiple tools to manage Foreman.

1.4.1. Foreman web UI overview

You can manage and monitor your Foreman infrastructure from a browser with the Foreman web UI. For example, you can use the following navigation features in the Foreman web UI:

Navigation feature Description

Organization dropdown

Choose the organization you want to manage.

Location dropdown

Choose the location you want to manage.

Monitor

Provides summary dashboards and reports.

Hosts

Provides host inventory and provisioning configuration tools.

Configure

Provides general configuration tools and data, including host groups and Ansible content.

Infrastructure

Provides tools on configuring how Foreman interacts with the environment.

notification bell

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

Administer

Provides advanced configuration for settings such as users, role-based access control (RBAC), and general settings.

1.4.2. Hammer CLI overview

You can configure and manage your Foreman server with CLI commands by using Hammer.

Using Hammer has the following benefits:

  • Create shell scripts based on Hammer commands for basic task automation.

  • Redirect output from Hammer to other tools.

  • Use the --debug option with Hammer to test responses to API calls before applying the API calls in a script. For example: hammer --debug organization list.

To issue Hammer commands, a user must have access to your Foreman server.

Note

To ensure a user-friendly and intuitive experience, the Foreman web UI takes priority when developing new functionality. Therefore, some features that are available in the Foreman web UI might not yet be available for Hammer.

In the background, each Hammer command first establishes a binding to the API, then sends a request. This can have performance implications when executing a large number of Hammer commands in sequence. In contrast, scripts that use API commands communicate directly with the Foreman API and they establish the binding only once.

Additional resources

1.4.3. Foreman API overview

You can write custom scripts and external applications that access the Foreman API over HTTP with the Representational State Transfer (REST) API provided by Foreman server. Use the REST API to integrate with enterprise IT systems and third-party applications, perform automated maintenance or error checking tasks, and automate repetitive tasks with scripts.

Using the REST API has the following benefits:

  • Configure any programming language, framework, or system with support for HTTP protocol to use the API.

  • Create client applications that require minimal knowledge of the Foreman infrastructure because users discover many details at runtime.

  • Adopt the resource-based REST model for intuitively managing a virtualization platform.

Scripts based on API commands communicate directly with the Foreman API, which makes them faster than scripts based on Hammer commands or Ansible Playbooks relying on modules within theforeman.foreman.

Important

API commands differ between versions of Foreman. When you prepare to upgrade Foreman server, update all the scripts that contain Foreman API commands.
Additional resources

1.4.4. Remote execution in Foreman

With remote execution, you can run jobs on hosts from Smart Proxies by using shell scripts or Ansible roles 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 in Managing hosts.

By default, Foreman includes several job templates for shell scripts and Ansible.

Additional resources

1.4.5. Managing Foreman with Ansible

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

Additional resources

1.5. Supported usage and versions of Foreman components

Foreman supports the following use cases, architectures, and versions.

1.5.1. Foreman server operating system

Foreman has packages for Enterprise Linux 9, Debian 12, and Ubuntu 22.04. Katello plugin packages, which provide content management capabilities, are only available for Enterprise Linux.

Foreman community only packages Foreman for x86_64.

1.5.2. Client operating systems

Using Foreman, you can manage multiple operating systems that have Foreman clients:

  • Amazon Linux

  • Debian

  • Enterprise Linux 10, 9, and 8

  • Fedora

  • OpenSUSE

  • SUSE Linux Enterprise Server

  • Ubuntu

Foreman can integrate with the following client features:

  • Ansible

  • OpenSCAP

  • OpenSSH

  • Puppet

  • Salt

  • Windows Remote Management (WinRM)

  • Operating system installers that can perform unattended installations, such as Anaconda or Debian-installer

2. Foreman deployment planning

2.1. Deployment path for Foreman

During installation and initial configuration of Foreman, you can customize your deployment to fit your specific needs and operational environment. By customizing each stage of the deployment process, you can choose deployment options that meet the requirements of your organization.

2.1.1. Installing a Foreman server

Installing an instance of Foreman server on a dedicated server is the first step to a working Foreman infrastructure.

Additional resources
Configuring Foreman server with external database

Running the foreman-installer command, used to install a Foreman server, also installs PostgreSQL databases on the server. However, you can configure your Foreman server to use external databases instead. Moving to external databases distributes the workload and can reduce overall Foreman memory usage.

Consider using external databases if you plan to use your Foreman deployment for the following scenarios:

  • Frequent remote execution tasks. This requires a high volume of records in PostgreSQL and generates heavy database workloads.

  • High disk I/O workloads from frequent repository synchronization or content view publishing. This requires Foreman to create a record in PostgreSQL for each job.

  • High volume of hosts.

  • High volume of synchronized content.

Additional resources
Configuring DNS, DHCP, and TFTP

You can manage DNS, DHCP, and TFTP centrally within the Foreman environment, or you can manage them independently after disabling their maintenance on Foreman.

Additional resources

  • For more information about configuring DNS, DHCP, and TFTP on Foreman server, see Configuring DNS, DHCP, and TFTP in Installing Foreman Server nightly on Debian/Ubuntu.

2.1.2. Configuring external authentication in Foreman

Foreman includes native support for authentication with a username and password. If you require additional methods of authentication, configure your Foreman server to use an external authentication source.

Table 1. External authentication sources supported by Foreman and the authentication features they provide
Username and password Single sign-on (SSO) One-time password (OTP) Time-based one-time password (TOTP) PIV cards

Active Directory (direct integration)

Yes

Yes

No

No

No

FreeIPA

Yes (Linux and Active Directory users)

Yes (Linux users only)

No

No

No

Quarkus-based Keycloak

Yes

Yes

Yes

Yes

Yes

Wildfly-based Keycloak

Yes

Yes

Yes

Yes

Yes

LDAP

Yes

No

No

No

No
Additional resources

2.1.3. Planning organization and location context

Context in Foreman consists of organizations and locations. You can associate most resources, for example hosts, subnets, and domains, with at least one organization and location context.

Resources and users can generally only access resources within their own context, which makes configuring organizations and locations an integral part of access management in Foreman.

Important

If you use host groups to bundle provisioning and configuration information, avoid mismatching resources from mutually exclusive contexts. For example, setting a subnet from one organization or location and a compute resource from a different organization or location creates an invalid host group.

Some resources in Foreman, such as Ansible roles and operating systems, are not part of any organization or location context.

Additional resources

2.1.4. Installing Smart Proxy servers

By installing Smart Proxy servers, you extend the reach and scalability of your Foreman deployment. Setting up a Smart Proxy server registers the base operating system on which you are installing to Foreman server and configures the new Smart Proxy server to provide the required services within your Foreman deployment.

You can install a Smart Proxy server in each of your geographic locations. By assigning a Smart Proxy to each location, you decrease the load on Foreman server, increase redundancy, and reduce bandwidth usage.

Note

The maximum number of Smart Proxy servers that Foreman server can support has no fixed limit. It was tested that a Foreman server can support 17 Smart Proxy servers with 2 vCPUs.

Decide what services you want to enable on each Smart Proxy server. You can configure the DNS, DHCP, and TFTP services on one of your Smart Proxy servers or you can use an external server to provide these services to your Smart Proxy servers.

Additional resources

2.1.5. Defining role-based access control policies

Users in Foreman can have one or more roles assigned. These roles are associated with permissions that enable users to perform specified administrative actions in Foreman. Permission filters define the actions allowed for a certain resource type.

Foreman provides a set of predefined roles with permissions sufficient for standard tasks. You can also configure custom roles.

Note

One of the predefined roles is the Default role. Foreman assigns the Default role to every user in the system. By default, the Default role grants only a limited set of permissions. Be aware that if you add a permission to the Default role, every Foreman users will gain that permission. Assigning a different role to a user does not remove the Default role from the user.

The following types of roles are commonly defined within various Foreman deployments:

Roles related to applications or parts of infrastructure

For example, roles for owners of Enterprise Linux as the operating system as opposed to roles for owners of application servers and database servers.

Roles related to a particular stage of the software lifecycle

For example, roles divided among the development, testing, and production phases, where each phase has one or more owners.

Roles related to specific tasks

For example, you can create a role for security managers and a role for license managers, depending on the specific tasks users need to be able to perform within your organization.

Additional resources

  • For more information, including details about creating custom roles and granting permissions to roles, see Managing users and roles in Administering Foreman.

Best practices for role-based access control in Foreman

  • Define the expected tasks and responsibilities: Define the subset of the Foreman infrastructure that you want the role to access as well as actions permitted on this subset. Think of the responsibilities of the role and how it differs from other roles.

  • Use predefined roles whenever possible: Foreman provides several sample roles that you can use. Copying and editing an existing role can be a good start for creating a custom role.

  • Adopt a granular approach to user role management: Define roles with specific and well-scoped permissions. Note that each user can have multiple roles assigned and that permissions from these roles are cumulative.

  • Add permissions gradually and test the results: When creating a custom role, start with a limited set of permissions and add permissions one by one, while testing continuously. Ensure to test your custom role to verify that it works as intended.

  • Consider areas of interest and granting read-only access: Even though a role has a limited area of responsibility, it might need a wider set of permissions. Therefore, you can grant the role a read-only access to parts of Foreman infrastructure that influence its area of responsibility.

2.1.6. Configuring provisioning

After your basic Foreman infrastructure is in place, you can start configuring provisioning to ensure that Foreman can seamlessly create, configure, and manage hosts.

The process depends on whether you want to provision bare-metal hosts, virtual machines, or cloud instances, but it includes defining installation media, configuring provisioning templates, and other tasks. If you are provisioning virtual machines or cloud instances, you must also integrate your compute provider with Foreman by connecting the provider as a compute resource to Foreman.

The following Foreman features support automating the provisioning of your hosts:

  • Provisioning templates enable you to define the way Foreman installs an operating system on your hosts.

  • The Discovery service enables you to detect unknown hosts and virtual machines on the provisioning network.

    This requires the Discovery plugin. For more information, see Installing the Discovery service in Provisioning hosts.

  • Host groups enable you to standardize provisioning of host configurations.

Additional resources

Choose a disaster recovery plan that best helps ensure the continuity of Foreman services in your deployment.

Snapshots of virtualized Foreman server
How do I back up?

Virtualize your Foreman server and use the hypervisor tools to take virtual machine snapshots of the server. This method is suitable if you can run Foreman in a virtual machine.

How will I recover in case of a disruptive event?

To recover Foreman services, restore a virtual machine snapshot.

Disadvantages and expected impact

Expect some amount of data inconsistency after recovery, based on how old your last snapshot is. You will lose data changes that have occurred since the snapshot you are using to recover was taken.

Active and passive Foreman server, with external storage
How do I back up?

Store the following critical data on network attached storage: database in /var/lib/pgsql. Replicate this storage into a different data center. Attach the storage to a Foreman server that is a clone of the primary Foreman server but runs passively.

How will I recover in case of a disruptive event?

To recover Foreman services, switch DNS records of the active Foreman server with the passive Foreman server. This ensures that the passive server becomes the active server. All hosts remain connected without configuration updates.

Disadvantages and expected impact

If the network attached storage is replicated to another location, expect some amount of data inconsistency after recovery based on the synchronization interval.

Active and passive Foreman server, with backup and restore
How do I back up?

Ensure periodic backups of your Foreman server. Copy this backup to a passive Foreman server and restore it on the passive server.

How will I recover in case of a disruptive event?

To recover Foreman services, switch DNS records of the active Foreman server with the passive Foreman server. This ensures that the passive server becomes the active server. All hosts remain connected without configuration updates.

Disadvantages and expected impact

Expect some amount of data inconsistency after recovery, based on how often you took and restored backups and on how long it takes to complete the restore process.

Dual active Foreman server
How do I back up?

Operate an active, independent Foreman server per data center. Hosts from each data center are registered to the Foreman server in that data center. Then configure automation to ensure recovery in case of a disruptive event. For example, you can periodically run a health check and if the health check discovers that the current Foreman server a host is registered to does not resolve, the host is re-registered to the other Foreman server.

To minimize downtime, you can automate the recovery in various ways. For example, you can use the Foreman Ansible collection. For more information, see Managing Foreman with Ansible in Administering Foreman.

How will I recover in case of a disruptive event?

To recover Foreman services, re-register all hosts to the Foreman server in the other data center.

Additional resources

2.1.8. Additional deployment tasks

Foreman offers a range of additional capabilities that you can use to further enhance your Foreman deployment. For example:

Remote execution commands on hosts

With remote execution, you can perform various tasks on multiple hosts simultaneously. Foreman supports the following modes of transport for remote execution: pull-based mode (over MQTT/HTTPS) and push-based mode (over SSH).

For more information, see Configuring and setting up remote jobs in Managing hosts.

Automating tasks with a configuration management tool

By integrating Foreman with a configuration management tool, you can automate repetitive tasks and ensure consistent configuration of your hosts.

You can use Ansible to configure hosts. For more information on using Ansible with Foreman, see Configuring hosts by using Ansible.

You can use Puppet to configure hosts. For more information on using Puppet with Foreman, see Configuring hosts by using Puppet.

Security management with OpenSCAP

You can enable the OpenSCAP plugin on your Foreman server and any Smart Proxy servers. With OpenSCAP, you can manage compliance policies and run security compliance scans on your hosts. After the scan completes, a compliance report is uploaded to your Foreman server.

For more information, see Managing security compliance.

Load balancing

With load balancing configured on your Smart Proxy servers, you can improve performance on Smart Proxy servers while also improving performance and stability for host connections to Foreman.

For more information, see Configuring Smart Proxies with a load balancer.

2.2. Common deployment scenarios

This section provides a brief overview of common deployment scenarios for Foreman. Note that many variations and combinations of the following layouts are possible.

2.2.1. Single location with segregated subnets

Your infrastructure might require multiple isolated subnets even if Foreman is deployed in a single geographic location. This can be achieved for example by deploying multiple Smart Proxy servers with DHCP and DNS services, but the recommended way is to create segregated subnets using a single Smart Proxy. This Smart Proxy is then used to manage hosts and compute resources in those segregated networks to ensure they only have to access the Smart Proxy for provisioning, configuration, errata, and general management. For more information on configuring subnets, see Managing hosts.

2.2.2. Multiple locations

Foreman community recommends to create at least one Smart Proxy server per geographic location. This practice can save bandwidth since hosts obtain content from a local Smart Proxy server. Synchronization of content from remote repositories is done only by the Smart Proxy, not by each host in a location. In addition, this layout makes the provisioning infrastructure more reliable and easier to configure.

Content flow in Foreman

2.2.3. Host group structures

The fact that host groups can be nested to inherit parameters from each other allows for designing host group hierarchies that fit particular workflows. A well planned host group structure can help to simplify the maintenance of host settings. This section outlines four approaches to organizing host groups.

Host group structuring examples
Figure 1. Host group structuring examples
Flat structure

The advantage of a flat structure is limited complexity, as inheritance is avoided. In a deployment with few host types, this scenario is the best option. However, without inheritance there is a risk of high duplication of settings between host groups.

Application based structure

This hierarchy is based on roles of hosts in a specific application. For example, it enables defining network settings for groups of back-end and front-end servers. The selected characteristics of hosts are segregated, which supports Puppet-focused management of complex configurations. However, the content views can only be assigned to host groups at the bottom level of this hierarchy.

Location based structure

In this hierarchy, the distribution of locations is aligned with the host group structure. In a scenario where the location or Smart Proxy server topology determines many other attributes, this approach is the best option. However, this structure complicates sharing parameters across locations, therefore in complex environments with a large number of applications, the number of host group changes required for each configuration change increases significantly.

2.3. Provisioning requirements

An important feature of Foreman is unattended provisioning of hosts. To achieve this, Foreman uses DNS and DHCP infrastructures, PXE booting, TFTP, and Kickstart. Use this chapter to understand the working principle of these concepts.

2.3.1. PXE booting

Preboot execution environment (PXE) provides the ability to boot a system over a network. Instead of using local hard drives or a CD-ROM, PXE uses DHCP to provide host with standard information about the network, to discover a TFTP server, and to download a boot image.

PXE sequence

  1. The host boots the PXE image if no other bootable image is found.

  2. A NIC of the host sends a broadcast request to the DHCP server.

  3. The DHCP server receives the request and sends standard information about the network: IP address, subnet mask, gateway, DNS, the location of a TFTP server, and a boot image.

  4. The host obtains the boot loader image/pxelinux.0 and the configuration file pxelinux.cfg/00:MA:CA:AD:D from the TFTP server.

  5. The host configuration specifies the location of a kernel image, initrd and Kickstart.

  6. The host downloads the files and installs the image.

Additional resources
PXE booting requirements

To provision machines using PXE booting, ensure that you meet the following requirements:

Network requirements

  • Optional: If the host and the DHCP server are separated by a router, configure the DHCP relay agent and point to the DHCP server.

Client requirements

  • Ensure that all the network-based firewalls are configured to allow clients on the subnet to access the Smart Proxy. For more information, see Smart Proxy networking.

  • Ensure that your client has access to the DHCP and TFTP servers.

Foreman requirements

  • Ensure that both Foreman server and Smart Proxy have DNS configured and are able to resolve provisioned host names.

  • Ensure that the UDP ports 67 and 68 are accessible by the client to enable the client to receive a DHCP offer with the boot options.

  • Ensure that the UDP port 69 is accessible by the client so that the client can access the TFTP server on the Smart Proxy.

  • Ensure that the TCP port 80 is accessible by the client to allow the client to download files and Kickstart templates from the Smart Proxy.

  • Ensure that the host provisioning interface subnet has a DHCP Smart Proxy set.

  • Ensure that the host provisioning interface subnet has a TFTP Smart Proxy set.

  • Ensure that the host provisioning interface subnet has a Templates Smart Proxy set.

  • Ensure that DHCP with the correct subnet is enabled using the Foreman installer.

  • Enable TFTP using the Foreman installer.

2.3.2. HTTP booting

You can use HTTP booting to boot systems over a network using HTTP.

HTTP booting requirements with managed DHCP

To provision machines through HTTP booting ensure that you meet the following requirements:

Client requirements

For HTTP booting to work, ensure that your environment has the following client-side configurations:

  • All the network-based firewalls are configured to allow clients on the subnet to access the Smart Proxy. For more information, see Smart Proxy networking.

  • Your client has access to the DHCP and DNS servers.

  • Your client has access to the HTTP UEFI Boot Smart Proxy.

Network requirements

  • Optional: If the host and the DHCP server are separated by a router, configure the DHCP relay agent and point to the DHCP server.

Foreman requirements

Although TFTP protocol is not used for HTTP UEFI Booting, Foreman uses TFTP Smart Proxy API to deploy boot loader configuration.

For HTTP booting to work, ensure that Foreman has the following configurations:

  • Both Foreman server and Smart Proxy have DNS configured and are able to resolve provisioned host names.

  • The UDP ports 67 and 68 are accessible by the client so that the client can send and receive a DHCP request and offer.

  • Ensure that the TCP port 8000 is open for the client to download the boot loader and Kickstart templates from the Smart Proxy.

  • The TCP port 8443 is open for the client to download the boot loader from the Smart Proxy using the HTTPS protocol.

  • The subnet that functions as the host’s provisioning interface has a DHCP Smart Proxy, an HTTP Boot Smart Proxy, a TFTP Smart Proxy, and a Templates Smart Proxy

HTTP booting requirements with unmanaged DHCP

To provision machines through HTTP booting without managed DHCP ensure that you meet the following requirements:

Client requirements

  • HTTP UEFI Boot URL must be set to one of:

    • http://smartproxy.example.com:8000

    • https://smartproxy.example.com:8443

  • Ensure that your client has access to the DHCP and DNS servers.

  • Ensure that your client has access to the HTTP UEFI Boot Smart Proxy.

  • Ensure that all the network-based firewalls are configured to allow clients on the subnet to access the Smart Proxy. For more information, see Smart Proxy networking.

Network requirements

  • An unmanaged DHCP server available for clients.

  • An unmanaged DNS server available for clients. In case DNS is not available, use IP address to configure clients.

Foreman requirements

Although TFTP protocol is not used for HTTP UEFI Booting, Foreman use TFTP Smart Proxy API to deploy boot loader configuration.

  • Ensure that both Foreman server and Smart Proxy have DNS configured and are able to resolve provisioned host names.

  • Ensure that the UDP ports 67 and 68 are accessible by the client so that the client can send and receive a DHCP request and offer.

  • Ensure that the TCP port 8000 is open for the client to download boot loader and Kickstart templates from the Smart Proxy.

  • Ensure that the TCP port 8443 is open for the client to download the boot loader from the Smart Proxy through HTTPS.

  • Ensure that the host provisioning interface subnet has an HTTP Boot Smart Proxy set.

  • Ensure that the host provisioning interface subnet has a TFTP Smart Proxy set.

  • Ensure that the host provisioning interface subnet has a Templates Smart Proxy set.

Appendix A: Technical users provided and required by Foreman

The Foreman installation process automatically creates system accounts. They manage files and process ownership of the components integrated into Foreman. Some of these accounts have fixed UIDs and GIDs, while others take the next available UID and GID on the system instead. To control the UIDs and GIDs assigned to accounts, you can define accounts before installing Foreman. Because some of the accounts have hard-coded UIDs and GIDs, it is not possible to do this with all accounts created during Foreman installation.

The following table lists all the accounts created by Foreman during installation. You can predefine accounts that have Yes in the Flexible UID and GID column with custom UID and GID before installing Foreman.

Do not change the home and shell directories of system accounts because they are requirements for Foreman.

Because of potential conflicts with local users that Foreman creates, you cannot use external identity providers for the system users of the Foreman base operating system.

Table 2. Technical users provided and required by Foreman
User name UID Group name GID Flexible UID and GID Home Shell

foreman

N/A

foreman

N/A

yes

/usr/share/foreman

/sbin/nologin

foreman-proxy

N/A

foreman-proxy

N/A

yes

/usr/share/foreman-proxy

/sbin/nologin

www-data

33

www-data

33

no

/var/www

/usr/sbin/nologin

postgres

26

postgres

26

no

/var/lib/postgresql

/bin/bash

puppet

52

puppet

52

no

/opt/puppetlabs/server/data/puppetserver

/sbin/nologin

Appendix B: Glossary of terms used in Foreman

Foreman is a complete lifecycle management tool for physical hosts, virtual machines, and cloud instances. Key features include automated host provisioning, configuration management, and content management including patch and errata management. You can automate tasks and quickly provision hosts, all through a single unified interface.

This alphabetically ordered glossary provides an overview of Foreman related technical terms.

Ansible

Ansible is an agentless open-source automation engine. For hosts running Linux, Ansible uses SSH to connect to hosts. For hosts running Microsoft Windows, Ansible relies on WinRM. It uses playbooks and roles to describe and bundle tasks. Within Foreman, you can use Ansible to configure hosts and perform remote execution.

For more information about using Ansible to configure hosts, see Configuring hosts by using Ansible. For more information about automating Foreman using Ansible, see Managing Foreman with Ansible in Administering Foreman.

Answer file

A configuration file that defines settings for an installation scenario. Answer files are defined in the YAML format and stored in the /etc/foreman-installer/scenarios.d/ directory. To see the default values for installation scenario parameters, use the foreman-installer --full-help command on your Foreman server.

ARF report

Asset Reporting Format (ARF) reports are the result of OpenSCAP compliance scans on hosts which have a policy assigned. Summarizes the security compliance of hosts managed by Foreman. They list compliance criteria and whether the scanned host has passed or failed.

Audits

Provide a report on changes made by a specific user. Audits can be viewed in the Foreman web UI under Monitor > Audits.

Baseboard management controller (BMC)

Enables remote power management of bare-metal hosts. In Foreman, you can create a BMC interface to manage selected hosts.

Boot disk

An ISO image used for PXE-less provisioning. This ISO enables the host to connect to Foreman server, boot the installation media, and install the operating system. There are several kinds of boot disks: host image, full host image, generic image, and subnet image.

Catalog

A document that describes the desired system state for one specific host managed by Puppet. It lists all of the resources that need to be managed, as well as any dependencies between those resources. Catalogs are compiled by a Puppet server from Puppet Manifests and data from Puppet agents.

Compliance policy

Compliance policies refer to the application of SCAP content to hosts by using Foreman with its OpenSCAP plugin. You can create compliance policies by using the Foreman web UI, Hammer CLI, or API. A compliance policy requires the setting of a specific XCCDF profile from a SCAP content, optionally using a tailoring file. You can set up scheduled tasks on Foreman that check your hosts for compliance against SCAP content. When a compliance policy scan completes, the host sends an ARF report to Foreman.

Compute profile

Specifies default attributes for new virtual machines on a compute resource.

Compute resource

A compute resource is an external virtualization or cloud infrastructure that you can attach to Foreman. Foreman can provision, configure, and manage hosts within attached compute resources. Examples of compute resources include VMware or libvirt and cloud providers such as Microsoft Azure or Amazon EC2.

Configuration Management

Configuration management describes the task of configuring and maintaining hosts. In Foreman, you can use Ansible, Puppet, and Salt to configure and maintain hosts with Foreman as a single source of infrastructure truth.

Discovered host

A bare-metal host detected on the provisioning network by the Discovery plugin.

Discovery image

Refers to the minimal operating system based on Enterprise Linux that is PXE-booted on hosts to acquire initial hardware information and to communicate with Foreman server before starting the provisioning process.

Discovery plugin

Enables automatic bare-metal discovery of unknown hosts on the provisioning network. The plugin consists of three components: services running on Foreman server and Smart Proxy server, and the Discovery image running on host.

Discovery rule

A set of predefined provisioning rules which assigns a host group to discovered hosts and triggers provisioning automatically.

Enterprise Linux

An umbrella term for the following Red Hat Enterprise Linux-like operating systems:

  • AlmaLinux

  • CentOS Linux

  • CentOS Stream

  • Oracle Linux

  • Red Hat Enterprise Linux

  • Rocky Linux

Foreman is tested on AlmaLinux and CentOS Stream.

ERB

Embedded Ruby (ERB) is a template syntax used in provisioning and job templates.

External node classifier (ENC)

A construct that provides additional data for a server to use when configuring hosts. When Puppet obtains information about nodes from an external source instead of its own database, the external source is called External node classifier. If the Puppet plugin is installed, Foreman can act as an External node classifier to Puppet servers in a Foreman deployment.

Facter

A program that provides information (facts) about the system on which it is run; for example, Facter can report total memory, operating system version, architecture, and more. Puppet modules enable specific configurations based on host data gathered by Facter.

Facts

Host parameters such as total memory, operating system version, or architecture. Facts are reported by Facter and used by Puppet.

Foreman

Foreman is an open-source component to provision and manage hosts.

Full host image

A boot disk used for PXE-less provisioning of a specific host. The full host image contains an embedded Linux kernel and init RAM disk of the associated operating system installer.

Generic image

A boot disk for PXE-less provisioning that is not tied to a specific host. The generic image sends the MAC address of your host to Foreman server, which matches it against the host entry.

Hammer

Hammer is a command-line interface tool for Foreman. You can execute Hammer commands from the command line or utilize it in scripts. You can use Hammer to automate certain recurring tasks as an alternative to Foreman Ansible collection or Foreman API.

Host

A host is a physical, virtual, or cloud instance registered to Foreman.

Host collection

A user defined group of one or more Hosts used for bulk actions such as errata installation.

Host group

A host group is a template to build hosts that holds shared parameters, such as subnet or lifecycle environment. It helps to unify configuration management in Ansible, Puppet, and Salt by grouping hosts. You can nest host groups to create a hierarchical structure. For more information, see Working with host groups in Managing hosts.

Host image

A boot disk used for PXE-less provisioning of a specific host. The host image only contains the boot files necessary to access the installation media on Foreman server.

Incremental upgrade (of a content view)

The act of creating a new (minor) content view version in a lifecycle environment. Incremental upgrades provide a way to make in-place modification of an already published content view. Useful for rapid updates, for example when applying security errata.

Job

A command executed remotely on a host from Foreman server. Every job is defined in a job template.

Location

A collection of default settings that represent a physical place. Location is a tag mostly used for geographical separation of hosts within Foreman. Examples include different cities or different data centers.

Migrating Foreman

The process of moving an existing Foreman installation to a new instance.

OpenSCAP

A project implementing security compliance auditing according to the Security Content Automation Protocol (SCAP). OpenSCAP is integrated in Foreman to provide compliance auditing for hosts.

Organization

An isolated collection of systems, content, and other functionality within Foreman. Organization is a tag used for organizational separation of hosts within Foreman. Examples include different teams or business units.

Parameter

Defines the behavior of Foreman components during provisioning. Depending on the parameter scope, we distinguish between global, domain, host group, and host parameters. Depending on the parameter complexity, we distinguish between simple parameters (key-value pair) and smart parameters (conditional arguments, validation, overrides).

Parametrized class (smart class parameter)

A parameter created by importing a class from Puppet server.

Permission

Defines an action related to a selected part of Foreman infrastructure (resource type). Each resource type is associated with a set of permissions, for example the Architecture resource type has the following permissions: view_architectures, create_architectures, edit_architectures, and destroy_architectures. You can group permissions into roles and associate them with users or user groups.

Provisioning

The provisioning of a host is the deployment of the base operating system on the host and registration of the host to Foreman. Optionally, the process continues with the supply of content and configuration. This process is ideally automated. Provisioned hosts run on compute resources or bare metal, never Foreman server or Smart Proxy servers.

Provisioning template

Provisioning templates are templates that automate deployment of an operating system on hosts. Foreman contains provisioning templates for all supported host operating system families:

  • AutoYaST for SUSE Linux Enterprise Server

  • Kickstart for AlmaLinux, Amazon Linux, CentOS, Oracle Linux, Red Hat Enterprise Linux, and Rocky Linux

  • Preseed files for Debian and Ubuntu

Puppet

Puppet is a configuration management tool utilizing a declarative language in a server-client architecture. For more information about using Puppet to configure hosts, see Configuring hosts by using Puppet.

Puppet agent

A service running on a host that applies configuration changes to that host.

Puppet environment

An isolated set of Puppet agent nodes that can be associated with a specific set of Puppet Modules.

Puppet manifest

Refers to Puppet scripts, which are files with the .pp extension. The files contain code to define a set of necessary resources, such as packages, services, files, users and groups, and so on, using a set of key-value pairs for their attributes.

Do not confuse with Manifest (Red Hat subscription manifest).

Puppet server

A Smart Proxy server component that provides a Puppet catalog to hosts for execution by the Puppet agent.

Puppet module

A self-contained bundle of code (Puppet Manifests) and data (facts) that you can use to manage resources such as users, files, and services.

PXE

PXE stands for preboot execution environment and is used to boot operating systems received from the network rather than a local disk. It requires a compatible network interface card (NIC) and relies on DHCP and TFTP.

Recurring logic

A job executed automatically according to a schedule. In the Foreman web UI, you can view those jobs under Monitor > Recurring logics.

Remote execution (REX)

Remote execution is the process of using Foreman to run commands on registered hosts.

Resource type

Refers to a part of Foreman infrastructure, for example host, Smart Proxy, or architecture. Used in permission filtering.

Role

Specifies a collection of permissions that are applied to a set of resources, such as hosts. Roles can be assigned to users and user groups. Foreman provides a number of predefined roles.

Salt

Salt is a configuration management tool used to maintain hosts in certain defined states, for example have packages installed or services running. It is designed to be idempotent. For more information about using Salt to configure hosts, see Configuring hosts by using Salt.

SCAP content

SCAP stands for Security Content Automation Protocol and refers to .xml files containing the configuration and security baseline against which hosts are checked. Foreman uses SCAP content in compliance policies.

Smart Proxy server

Smart Proxy servers can provide DHCP, DNS, and TFTP services and act as an Ansible control node, Puppet server, or Salt Master in separate networks. They interact with Foreman server in a client-server model.

Smart Proxy servers are required in Foreman deployments that manage IT infrastructure spanning across multiple networks and useful for Foreman deployments across various geographical locations.

Subnet image

A type of generic image for PXE-less provisioning that communicates through Smart Proxy server.

Subscription Manager

Subscription Manager is a client application to register hosts to Foreman.

Tailoring files

Tailoring files specify a set of modifications to existing SCAP content. They adapt SCAP content to your particular needs without changing the original SCAP content itself.

Task

A background process executed on the Foreman or Smart Proxy server, such as repository synchronization or content view publishing. You can monitor the task status in the Foreman web UI under Monitor > Foreman Tasks > Tasks.

Trend

A means of tracking changes in specific parts of Foreman infrastructure. Configure trends in Foreman web UI under Monitor > Trends. Requires foreman_statistics plugin on your Foreman server.

Updating Foreman

The process of advancing your Foreman server and Smart Proxy server installations from one patch release to the next, for example Foreman nightly.0 to Foreman nightly.1.

Upgrading Foreman

The process of advancing your Foreman server and Smart Proxy server installations from one minor release to the next, for example Foreman 3.14 to Foreman nightly.

User group

A collection of roles which can be assigned to a collection of users.

User

Anyone registered to use Foreman. Authentication and authorization is possible through built-in logic, through external resources (LDAP, Identity Management, or Active Directory), or with Kerberos.

Virtualization

Virtualization describes the process of running multiple operating systems with various applications on a single hardware host using hypervisors like VMware, Proxmox, or libvirt. It facilitates scalability and cost savings. You can attach virtualization infrastructure as compute resources to Foreman. Enable appropriate plugins to access this feature.

virt-who

An agent for retrieving IDs of virtual machines from the hypervisor. When used with Foreman, virt-who reports those IDs to Foreman server so that it can provide subscriptions for hosts provisioned on virtual machines.

XCCDF profiles

Extensible configuration checklist description format (XCCDF) profiles are a component of SCAP content. XCCDF is a language to write security checklists and benchmarks. An XCCDF file contains security configuration rules for lists of hosts.

Appendix C: CLI help

Foreman offers multiple user interfaces: Foreman web UI, Hammer CLI, API, and through Ansible collection theforeman.foreman. If you want to administer Foreman on the command line, have a look at the following help output.

Foreman services

A set of services that Foreman server and Smart Proxy servers use for operation. You can use the foreman-maintain tool to manage these services. To see the full list of services, enter the foreman-maintain service list command on the machine where Foreman or Smart Proxy server is installed. For more information, run foreman-maintain --help on your Foreman server or Smart Proxy server.

Foreman plugins

You can extend Foreman by installing plugins. For more information, run foreman-installer --full-help on your Foreman server or Smart Proxy server.

Hammer CLI

You can manage Foreman on the command line using hammer. For more information on using Hammer CLI, see Using the Hammer CLI tool or run hammer --help on your Foreman server or Smart Proxy server.