1. Configuring DNS integration

You can integrate DNS with Foreman to automate the creation and management of DNS records when provisioning, modifying, and decommissioning hosts. This helps to ensure a consistent and error-free network configuration.

1.1. DNS service providers

Smart Proxy supports the following DNS providers that you can use to integrate Foreman with your existing DNS infrastructure or deploy a new one:

dns_nsupdate

Dynamic DNS updates on an RFC 2136-compatible DNS server by using the nsupdate utility. See:

dns_nsupdate_gss

Dynamic DNS updates on an RFC 2136-compatible DNS server by using the nsupdate utility with Generic Security Service algorithm for Transaction Signature (GSS-TSIG) authentication. See Integrating FreeIPA DNS with GSS-TSIG authentication.

dns_infoblox

Dynamic DNS updates on an Infoblox DNS server. See Integrating Infoblox DNS.

dns_libvirt

Dynamic DNS updates on a dnsmasq DNS server by using the libvirt API. See Integrating the libvirt API to manage DNS records.

dns_powerdns

Dynamic DNS updates on a PowerDNS server. See Integrating PowerDNS.

dns_route53

Dynamic DNS updates on an Amazon Route 53 DNS server. See Integrating Route 53 DNS.

1.2. Enabling the installer-managed DNS service

If you do not have a DNS server available in your network, you can use the installer-managed DNS service. This feature enables you to provide a DNS service with low maintenance overhead.

Procedure

  1. Configure Foreman or Smart Proxy as DNS server:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider nsupdate \
--foreman-proxy-dns-managed true \
--reset-foreman-proxy-dns-server

  2. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.3. Integrating a local self-managed DNS service

The installer exposes a limited feature set for the Foreman installer-managed DNS service. For example, you can configure only a single forward DNS zone. As an alternative, you can first use the installer-managed DNS and later convert it to a self-managed DNS server to bypass the limitations.

Prerequisites

  • You installed and configured a DNS service on the Foreman server or Smart Proxy server host.

  • The DNS service supports RFC 2136-compatible updates

Procedure

  1. Set the local, self-managed DNS service on your Foreman server or Smart Proxy server:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider nsupdate \
--foreman-proxy-dns-managed false \
--foreman-proxy-dns-server "127.0.0.1"

  2. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.4. Integrating a generic RFC 2136-compatible remote DNS server

If you have a DNS service in your network and it supports RFC 2136-compatible dynamic updates, you can integrate this service into your Foreman server. The integration enables you to continue using your existing DNS server, and Foreman manages DNS records for hosts during their life cycle.

With this type of integration, Foreman uses a transaction signature (TSIG) key to authenticate to the DNS server and the nsupdate utility to manage DNS records.

Prerequisites

  • The remote DNS service is configured and can be queried.

  • The remote DNS service supports RFC 2136-compatible dynamic updates

  • The Remote Name Daemon Control (RNDC) key file to connect to the remote DNS server is placed in /etc/foreman-proxy/rndc.key on your Foreman server or Smart Proxy server.

Procedure

  1. Update the permissions on /etc/foreman-proxy/rndc.key to enable members of the foreman-proxy group to read this file:

    # chown -v root:foreman-proxy /etc/foreman-proxy/rndc.key
# chmod -v 640 /etc/foreman-proxy/rndc.key

  2. Restore the SELinux context on /etc/foreman-proxy/rndc.key:

    # restorecon -v /etc/foreman-proxy/rndc.key

  3. Optional: Verify if you can use the key file to manually manage DNS entries:

    1. Create a test DNS entry. For example, host test.example.com with an A record of 192.168.25.20 on the DNS server at 192.168.25.1.

      # echo -e "server 192.168.25.1\n \
update add test.example.com 3600 IN A 192.168.25.20\n \
send\n" | nsupdate -k /etc/foreman-proxy/rndc.key

    2. Verify that you can query the new DNS entry:

      # host test.example.com 192.168.25.1

      Example output:

      Using domain server:
Name: 192.168.25.1
Address: 192.168.25.1#53
Aliases:

test.example.com has address 192.168.25.20

    3. If resolved successfully, remove the test DNS entry:

      # echo -e "server 192.168.25.1\n \
update delete test.example.com 3600 IN A 192.168.25.20\n \
send\n" | nsupdate -k /etc/foreman-proxy/rndc.key

    4. Confirm that the DNS entry was removed:

      # host test.example.com 192.168.25.1

      If the command returns Host test.example.com not found: 3(NXDOMAIN), the record was successfully deleted.

  4. Configure Foreman server or Smart Proxy server to use the DNS server:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider nsupdate \
--foreman-proxy-dns-managed false \
--foreman-proxy-dns-server "dns_server_ip_address" \
--foreman-proxy-keyfile /etc/foreman-proxy/rndc.key

  5. For the affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.5. Integrating FreeIPA DNS with TSIG authentication

If you use FreeIPA to centrally manage hosts in your domain, you can integrate the FreeIPA DNS service into Foreman server. The integration enables you to continue using your existing FreeIPA DNS service, and Foreman manages DNS records for hosts during their life cycle.

If Foreman server or Smart Proxy server is not a member of a FreeIPA domain, use a transaction signature (TSIG) key to authenticate to the DNS server. This method provides a lower security and an increased key management effort compared to dynamic updates with generic security service transaction signature (GSS-TSIG) authentication. For more information, see Integrating FreeIPA DNS with GSS-TSIG authentication.

Prerequisites

  • The FreeIPA server is deployed and functional.

  • The firewall on the FreeIPA server allows access to the required ports. See Port requirements for FreeIPA in the Red Hat Enterprise Linux 9 Installing Identity Management guide.

  • You have root access on the FreeIPA server.

Procedure

  1. Perform the following steps on the FreeIPA Server:

    1. Insert the following settings at the top of the /etc/named.conf file:

      include "/etc/rndc.key";
controls {
    inet FreeIPA_server_ip_address port 953 allow { Foreman_ip_address; } keys { "rndc-key"; };
};

    2. Reload the named service:

      # systemctl reload named

  2. In the FreeIPA web UI:

    1. Navigate to Network Services > DNS > DNS Zones

    2. Click the name of the zone.

    3. Open the Settings tab.

    4. Enter in the BIND update policy field:

      grant "rndc-key" zonesub ANY;

    5. Set Dynamic update to True.

    6. Click Update to save the changes.

  3. Configure dynamic DNS updates in Foreman server or Smart Proxy server. For more information, see Integrating a generic RFC 2136-compatible remote DNS server.

1.6. Integrating FreeIPA DNS with GSS-TSIG authentication

If you use FreeIPA to centrally manage hosts in your domain, you can integrate the FreeIPA DNS service into Foreman server. The integration enables you to continue using your existing FreeIPA DNS service, and Foreman manages DNS records for hosts during their life cycle.

If Foreman server or Smart Proxy server is a member of a FreeIPA domain, use generic security service transaction signature (GSS-TSIG) authentication. This method provides an increased security and a low key management effort compared to TSIG authentication.

1.6.1. Configuring FreeIPA to use with Foreman server

Before you can integrate an existing FreeIPA DNS server, you must prepare the FreeIPA environment. The preparation work enables Foreman server to use generic security service transaction signature (GSS-TSIG) authentication to update DNS entries.

Prerequisites

  • The FreeIPA domain is deployed and functional.

  • FreeIPA is configured with its integrated DNS service.

  • The firewall on the FreeIPA servers allow access to the required ports. For more information, see Port requirements for IdM in Red Hat Enterprise Linux 9 Installing Identity Management.

Procedure

  1. On a host that is a member of the FreeIPA domain, obtain a Kerberos ticket for the admin user:

    # kinit admin

  2. Create a new Kerberos principal Foreman server to be used for authentication on the FreeIPA server:

    # ipa service-add smartproxy/foreman.example.com

  3. Optional: Add a forward DNS zone:

    # ipa dnszone-add example.com

  4. Display the BIND update policy of the forward zone:

    # ipa dnszone-show example.com --all | \
grep "BIND update policy"

    Example output:

    BIND update policy: grant EXAMPLE.COM krb5-self * A; grant EXAMPLE.COM krb5-self * AAAA; grant EXAMPLE.COM krb5-self * SSHFP;

    Note the value of the setting.

  5. Update the forward zone settings:

    # ipa dnszone-mod example.com \
--dynamic-update=TRUE \
--allow-sync-ptr=TRUE \
--update-policy="<existing_policy> grant smartproxy\047foreman.example.com@EXAMPLE.COM wildcard * ANY;"

    This command modifies the zone settings as follows:

    • Dynamic zone updates are enabled.

    • FreeIPA updates the corresponding PTR record in the reverse DNS zone if an A or AAAA record is updated in the forward zone.

    • The Kerberos principal created in an earlier step is authorized to modify any type of any data record. Note that you must append this setting to the existing value.

  6. Optional: Add a reverse DNS zone:

    # ipa dnszone-add 0.168.192.in-addr.arpa

  7. Display the BIND update policy of the reverse zone:

    # ipa dnszone-show 0.168.192.in-addr.arpa --all | \
grep "BIND update policy"

    Example output:

    BIND update policy: grant EXAMPLE.COM krb5-subdomain 0.168.192.in-addr.arpa. PTR;

    Note the value of the setting.

  8. Update the reverse zone settings:

    # ipa dnszone-mod 0.168.192.in-addr.arpa \
--dynamic-update=TRUE \
--update-policy="<existing_policy> grant smartproxy\047foreman.example.com@EXAMPLE.COM wildcard * ANY;"

    Note that you must append the update policy to the existing value.

1.6.2. Configuring Smart Proxies for use with FreeIPA

After you have prepared the FreeIPA DNS server as described in Configuring FreeIPA to use with Foreman server, integrate the DNS server into your Foreman server or Smart Proxy server.

Prerequisites

  • You set the DNS search domain of the host to the FreeIPA DNS domain.

  • You know the Kerberos principal the host should use to authenticate to the FreeIPA DNS server, for example, smartproxy/foreman.example.com.

Procedure

  1. If your Foreman server or Smart Proxy server is not yet a member of the FreeIPA domain:

    1. Install the ipa-client package:

      # dnf install ipa-client

    2. Install the FreeIPA client:

      # ipa-client-install

      Follow the on-screen prompts.

  2. Obtain a Kerberos ticket for the admin user:

    # kinit admin

  3. Remove the /etc/foreman-proxy/dns.keytab file:

    # rm --force /etc/foreman-proxy/dns.keytab

  4. Obtain a Kerberos keytab file for your Smart Proxy and store it in the /etc/foreman-proxy/dns.keytab file:

    # ipa-getkeytab -p smartproxy/foreman.example.com@EXAMPLE.COM \
-k /etc/foreman-proxy/dns.keytab
    Important

    When adding a keytab to a standby system with the same host name as the original system in service, pass the -r option to the ipa-getkeytab command to prevent generating new credentials and rendering the credentials on the original system invalid.

  5. Set the owner and group of /etc/foreman-proxy/dns.keytab to foreman-proxy:

    # chown foreman-proxy:foreman-proxy /etc/foreman-proxy/dns.keytab

  6. Verify that the /etc/foreman-proxy/dns.keytab file is valid:

    1. Use the file to obtain a Kerberos ticket:

      # kinit -kt /etc/foreman-proxy/dns.keytab \
smartproxy/foreman.example.com@EXAMPLE.COM

    2. Display the Kerberos ticket:

      # klist

      Example output:

      Ticket cache: KCM:0:50473
Default principal: smartproxy/foreman.example.com@EXAMPLE.COM

Valid starting       Expires              Service principal
05/20/2025 12:12:35  05/21/2025 11:54:31  krbtgt/EXAMPLE.COM@EXAMPLE.COM

  7. Configure Foreman server or Smart Proxy server to connect to the FreeIPA DNS service:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider nsupdate_gss \
--foreman-proxy-dns-managed false \
--foreman-proxy-dns-server "freeipa-server.example.com" \
--foreman-proxy-dns-tsig-keytab /etc/foreman-proxy/dns.keytab \
--foreman-proxy-dns-tsig-principal "smartproxy/foreman.example.com@EXAMPLE.COM"

  8. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.7. Integrating Infoblox DNS

If you have an Infoblox appliance in your network, you can integrate this service into Foreman server and Smart Proxy server by using the Infoblox Web API (WAPI) The integration enables you to continue using your existing DNS server, and Foreman manages DNS records for hosts during their life cycle.

Limitations

  • You can manage DNS entries only in a single view, and you cannot edit the view after you create it.

  • Foreman server uses the standard HTTPS web API to communicate with Infoblox. By default, it communicates only with a single node. If you require high availability, configure this feature in Infoblox.

  • You cannot integrate the Foreman IP address management (IPAM) feature into Infoblox.

Prerequisites

  • You have an Infoblox account with the roles DHCP Admin and DNS Admin.

  • The Infoblox roles have permissions or belong to an admin group that permits the accounts to perform tasks through the Infoblox API.

Procedure

  1. Download the certificate from the Infoblox server, and store it in the /etc/pki/ca-trust/source/anchors/infoblox.crt file:

    # openssl s_client -showcerts -connect infoblox.example.com:443 </dev/null | \
openssl x509 -text >/etc/pki/ca-trust/source/anchors/infoblox.crt

    The hostname must match the one for the Infoblox application in the X.509 certificate.

  2. Add the Infoblox certificate to the system truststore:

    # update-ca-trust extract

  3. Test the CA certificate by using it in a query to the Infoblox API:

    # curl -u admin:password https://infoblox.example.com/wapi/v2.0/network

    Example of a positive response:

    [
    {
        "_ref": "network/ZG5zLm5ldHdvcmskMTkyLjE2OC4yMDIuMC8yNC8w:infoblox.example.com/24/default",
        "network": "192.168.202.0/24",
        "network_view": "default"
    }
]

  4. Configure Foreman server or Smart Proxy server to connect to the Infoblox DNS service:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider infoblox \
--enable-foreman-proxy-plugin-dns-infoblox \
--foreman-proxy-plugin-dns-infoblox-dns-server infoblox.example.com \
--foreman-proxy-plugin-dns-infoblox-username admin \
--foreman-proxy-plugin-dns-infoblox-password password \
--foreman-proxy-plugin-dns-infoblox-dns-view view_name

    Omit the --foreman-proxy-plugin-dns-infoblox-dns-view option if you use the default view in Infoblox DNS.

  5. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.8. Integrating the libvirt API to manage DNS records

If you manage VMs through the libvirt API, you can integrate the API into Foreman server to manage DNS records. The integration enables you to continue using dnsmasq in libvirt, and Foreman manages DNS records for hosts during their life cycle.

Procedure

  1. Configure Foreman server or Smart Proxy server to connect to the libvirt API:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider libvirt \
--foreman-proxy-libvirt-network default \
--foreman-proxy-libvirt-url qemu:///system

    Note that you can only use one network and URL for both the dns_libvirt and dhcp_libvirt providers.

  2. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.9. Integrating PowerDNS

If you have a PowerDNS service in your network, you can integrate this service into Foreman server. The integration enables you to continue using your existing DNS server, and Foreman manages DNS records for hosts during their life cycle.

With this type of integration, Foreman uses the PowerDNS REST API to authenticate and manage DNS records in local or remote PowerDNS instances.

Procedure

  1. Configure Foreman server or Smart Proxy server to connect to the PowerDNS service:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider powerdns \
--enable-foreman-proxy-plugin-dns-powerdns \
--foreman-proxy-plugin-dns-powerdns-rest-api-key My_API_Key \
--foreman-proxy-plugin-dns-powerdns-rest-url http://powerdns.example.com:8081/api/v1/servers/localhost

  2. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.10. Integrating Route 53 DNS

If you have an Amazon Route 53 DNS service in your network, you can integrate this service into Foreman server. The integration enables you to continue using your existing DNS server, and Foreman manages DNS records for hosts during their life cycle.

With this type of integration, Foreman uses the Route 53 API to authenticate and manage DNS records in Amazon Web Services (AWS).

Procedure

  1. Configure Foreman server or Smart Proxy server to connect to the Amazon Route 53 DNS service:

    # foreman-installer \
--foreman-proxy-dns true \
--foreman-proxy-dns-provider route53 \
--enable-foreman-proxy-plugin-dns-route53 \
--foreman-proxy-plugin-dns-route53-aws-access-key My_AWS_Access_Key \
--foreman-proxy-plugin-dns-route53-aws-secret-key My_AWS_Secret_Key

  2. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DNS service with a domain and subnet.

1.11. Associating the DNS service with a domain and subnet

After you configured or changed the DNS provider, you must update the configuration of each affected Smart Proxy in the Foreman web UI.

Prerequisites

  • You configured a DNS provider.

Procedure

  1. Configure the domain:

    1. In the Foreman web UI, navigate to Infrastructure > Domains.

    2. Select the domain name.

    3. On the Domain tab, ensure DNS Smart Proxy is set to the Smart Proxy where the subnet is connected.

  2. Configure the subnet:

    1. Navigate to Infrastructure > Subnets.

    2. Select the subnet name.

    3. On the Domains tab, select the domains that are valid on the subnet.

    4. In the Smart Proxies tab, ensure Reverse DNS Smart Proxy is set to the Smart Proxy where the subnet is connected.

    5. Click Submit.

1.12. Disabling DNS for integration

If you want to manually manage a DNS service and not integrate it into Foreman server, you must prevent Foreman from maintaining this service on the operating system and disable orchestration to avoid errors.

Note

Disabling DNS in Foreman does not remove the related backend service on the operating system.
Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Subnets.

  2. For each subnet that is associated with the DNS Smart Proxy:

    1. Select the subnet.

    2. On the Smart Proxies tab, clear the Reverse DNS Smart Proxy field.

    3. Click Submit.

  3. Navigate to Infrastructure > Domains.

  4. For each domain that is associated with the DNS Smart Proxy:

    1. Select the domain.

    2. Clear the DNS Smart Proxy field.

    3. Click Submit.

  5. On Foreman server, enter:

    # foreman-installer --foreman-proxy-dns false
    Note

    Foreman does not perform orchestration when a Smart Proxy is not set for a given subnet and domain. When you disable Smart Proxy associations, orchestration commands for existing hosts can fail if the expected records and configuration files are not present.

2. Configuring DHCP integration

You can integrate DHCP with Foreman to automatically manage IP leases and boot configurations on a DHCP server during the provisioning of hosts. This helps to simplify the automated provisioning of hosts.

2.1. DHCP service providers

Smart Proxy supports the following DHCP providers that you can use to integrate Foreman with your existing DHCP infrastructure or deploy a new one:

dhcp_isc

Managing IP leases on an ISC DHCP server by using the Object Management Application Programming Interface (OMAPI). See Enabling the installer-managed DHCP service.

dhcp_remote_isc

Managing IP leases on a remote ISC dhcpd server by using OMAPI. This provider requires that you share the leases over the network, for example, with NFS. See Integrating a remote ISC DHCP server.

dhcp_infoblox

Managing IP leases on an Infoblox DHCP server. See Integrating Infoblox DHCP.

dhcp_libvirt

Managing IP leases on a dnsmasq DHCP server by using the libvirt API. See Integrating the libvirt API to manage DHCP leases.

2.2. Enabling the installer-managed DHCP service

If you do not have a DHCP server available in your network, you can use the installer-managed DHCP service. This feature enables you to provide a DHCP service with low maintenance overhead.

Prerequisites

  • You know the following network information:

    • The range of IP addresses the DHCP should manage

    • The IP address of the default gateway in the subnet

    • The IP addresses of the name servers for the subnet

Procedure

  1. Configure Foreman server or Smart Proxy server as DHCP server:

    # foreman-installer \
--foreman-proxy-dhcp true \
--foreman-proxy-dhcp-provider isc \
--foreman-proxy-dhcp-managed true \
--foreman-proxy-dhcp-range "192.0.2.100 192.0.2.150" \
--foreman-proxy-dhcp-gateway 192.0.2.1 \
--foreman-proxy-dhcp-nameservers 192.0.2.2,192.0.2.3

  2. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. See Associating the DHCP service with a subnet.

  3. Optional: Secure the dhcpd API on the Smart Proxy by using an Object Management Application Programming Interface (OMAPI) key:

    1. Install the required package:

      # dnf install bind-utils

    2. Generate an OMAPI key:

      # tsig-keygen -a hmac-md5 omapi_key
key "omapi_key" {
	algorithm hmac-md5;
	secret "hJBge7QC5AaUkRVsZmFUlg==";
};

  4. Add the dhcpd API key to the Smart Proxy configuration:

    # foreman-installer \
--foreman-proxy-dhcp-key-name "omapi_key" \
--foreman-proxy-dhcp-key-secret "key_secret"

2.3. Integrating a remote ISC DHCP server

If you have an ISC DHCP server in your network, but not on the same host as your Foreman server, you can integrate this service into your Foreman server. The integration enables you to continue using your existing DHCP server, and Foreman manages IP leases and boot configurations on the DHCP server during the provisioning of hosts.

With this type of integration, Foreman uses an Object Management Application Programming Interface (OMAPI) key to update leases and the Network File System (NFS) protocol to access the ISC DHCP server’s configuration files and lease database.

2.3.1. Enabling OMAPI authentication in ISC DHCP

The integration of an existing remote ISC DHCP service requires that you enable the Object Management Application Programming Interface (OMAPI) in the DHCP service. Foreman uses OMAPI to remotely manage DHCP server objects.

Prerequisites

  • The ISC DHCP service is deployed and functional.

  • The firewall on the DHCP server allows access to the DHCP service (port 67/UDP).

Procedure

  1. Create a security token:

    # tsig-keygen -a hmac-md5 omapi_key

    Note that Foreman supports only the hmac-md5 algorithm for OMAPI authentication.

    Example output:

    key "omapi_key" {
	algorithm hmac-md5;
	secret "4z1jwYO0RGUTJbWDepFBdg==";
};

  2. Edit the /etc/dhcp/dhcpd.conf file, and append the following settings:

    key omapi_key {
	algorithm hmac-md5;
	secret "key_secret";
};
omapi-port 7911;
omapi-key omapi_key;

    The settings specified in the example include the following:

    key omapi_key

    Defines the key, its algorithm and encrypted password. Use the output of the tsig-keygen command for this directive.

    omapi-port 7911;

    Enables the OMAPI protocol in ISC DHCP and defines the port of the protocol.

    omapi-key omapi_key

    Defines the name of the key the OMAPI interface uses. The name must match the one you specified in the tsig-keygen command.

  3. Restart the dhcpd service:

    # systemctl restart dhcpd

  4. Open the OMAPI port in the firewalld service:

    # firewall-cmd --add-port=7911/tcp

  5. Make the changes persistent:

    # firewall-cmd --runtime-to-permanent

2.3.2. Sharing the DHCP configuration files and lease database over NFS

The integration of an existing remote ISC DHCP service requires that you share the configuration file and lease database of the service over network. For example, you can use the NFS service. Foreman then uses NFS to access configuration settings, such as subnet definitions. Read access to the lease database ensures efficient access to all lease information, which is not available over the ISC DHCP Object Management Application Programming Interface (OMAPI).

Prerequisites

  • The ISC DHCP service is deployed and functional.

Procedure

  1. On Foreman server, determine both the UID and the primary GID of the foreman-proxy user:

    # id -u foreman-proxy
# id -g foreman-proxy

    You require these IDs in the next steps.

  2. On the DHCP server, share the configuration of the DHCP service and lease database over NFS:

    1. Create the foreman-proxy group with the same group ID as on the Foreman server:

      # groupadd -g My_User_ID foreman-proxy

    2. Create the foreman-proxy user with the same user ID and primary group ID as on the Foreman server:

      # useradd -u My_User_ID -g My_Group_ID -s /sbin/nologin foreman-proxy

    3. Ensure that members of the foreman-proxy group can access the configuration file of the DHCP service:

      # chgrp -R foreman-proxy /etc/dhcp/
# chmod g+rx /etc/dhcp/
# chmod g+r /etc/dhcp/dhcpd.conf

    4. Install the nfs-server package:

      # dnf install nfs-utils

    5. Edit the /etc/exports file, and append share entries for the /etc/dhcp/ and /var/lib/dhcpd/ directories:

      /etc/dhcp        foreman.example.com(ro)
/var/lib/dhcpd   foreman.example.com(ro)

      Share the directories in read-only mode and only with the Foreman server or Smart Proxy server.

    6. Enable and start the NFS server service:

      # systemctl enable --now nfs-server

    7. Open the NFSv4 port in the firewalld service:

      # firewall-cmd --add-service=nfs

    8. Make the changes persistent:

      # firewall-cmd --runtime-to-permanent
Next steps

2.3.3. Configuring Foreman server or Smart Proxy server for use with ISC DHCP

After you have prepared the DHCP server, integrate the ISC DHCP server into your Foreman server or Smart Proxy server.

Prerequisites
Procedure

  1. Install the required package:

    # dnf install nfs-utils

  2. Create the directories into which you later mount the NFS shares:

    # mkdir -p \
/srv/nfs/etc/dhcp \
/srv/nfs/var/lib/dhcpd

  3. Edit the /etc/fstab file, and add entries for the NFS shares to mount them automatically when the system boots:

    dhcp_server_fqdn:/etc/dhcp       /srv/nfs/etc/dhcp       nfs  ro,auto,context="system_u:object_r:dhcp_etc_t:s0"     0 0
dhcp_server_fqdn:/var/lib/dhcpd  /srv/nfs/var/lib/dhcpd  nfs  ro,auto,context="system_u:object_r:dhcpd_state_t:s0"  0 0

  4. Reload systemd so that this service uses the updated /etc/fstab file:

    # systemctl daemon-reload

  5. Mount the NFS shares:

    # mount /srv/nfs/etc/dhcp/
# mount /srv/nfs/var/lib/dhcpd/

  6. Verify that the foreman-proxy user can access the files on the NFS server. For example:

    1. Display the first 5 lines of the /srv/nfs/etc/dhcp/dhcpd.conf file:

      $ su - foreman-proxy -c 'head -5 /srv/nfs/etc/dhcp/dhcpd.conf'

    2. Display the first 5 lines of the /srv/nfs/var/lib/dhcpd/dhcpd.leases file:

      $ su - foreman-proxy -c 'head -5 /srv/nfs/var/lib/dhcpd/dhcpd.leases'

  7. Configure Foreman server or Smart Proxy server to use the DHCP server:

    # foreman-installer \
--foreman-proxy-dhcp true \
--foreman-proxy-dhcp-provider remote_isc \
--enable-foreman-proxy-plugin-dhcp-remote-isc \
--foreman-proxy-dhcp-server dhcp_server_fqdn \
--foreman-proxy-plugin-dhcp-remote-isc-dhcp-config /srv/nfs/etc/dhcp/dhcpd.conf \
--foreman-proxy-plugin-dhcp-remote-isc-dhcp-leases /srv/nfs/var/lib/dhcpd/dhcpd.leases \
--foreman-proxy-plugin-dhcp-remote-isc-key-name omapi_key \
--foreman-proxy-plugin-dhcp-remote-isc-key-secret key_secret \
--foreman-proxy-plugin-dhcp-remote-isc-omapi-port 7911

  8. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DHCP service with a subnet.

2.4. Integrating Infoblox DHCP

If you have an Infoblox appliance in your network, you can integrate this service into Foreman server and Smart Proxy server by using the Infoblox Web API (WAPI). The integration enables you to continue using your existing DHCP server, and Foreman manages IP leases and boot configurations on the DHCP server during the provisioning of hosts.

Limitations

  • You can manage DHCP entries only in a single network and view, and you cannot edit the view after you create it.

  • Foreman server uses the standard HTTPS web API to communicate with Infoblox. By default, it communicates only with a single node. If you require high availability, configure this feature in Infoblox.

Prerequisites

  • You have an Infoblox account with the roles DHCP Admin and DNS Admin.

  • The Infoblox roles have permissions or belong to an admin group that permits the accounts to perform tasks through the Infoblox API.

Procedure

  1. Download the certificate from the Infoblox server, and store it in the /etc/pki/ca-trust/source/anchors/infoblox.crt file:

    # openssl s_client -showcerts -connect infoblox.example.com:443 </dev/null | \
openssl x509 -text >/etc/pki/ca-trust/source/anchors/infoblox.crt

    The hostname must match the one for the Infoblox application in the X.509 certificate.

  2. Add the Infoblox certificate to the system truststore:

    # update-ca-trust extract

  3. Test the CA certificate by using it in a query to the Infoblox API:

    # curl -u admin:password https://infoblox.example.com/wapi/v2.0/network

    Example of a positive response:

    [
    {
        "_ref": "network/ZG5zLm5ldHdvcmskMTkyLjE2OC4yMDIuMC8yNC8w:infoblox.example.com/24/default",
        "network": "192.168.202.0/24",
        "network_view": "default"
    }
]

  4. Configure Foreman server or Smart Proxy server to connect to the Infoblox DHCP service:

    # foreman-installer \
--foreman-proxy-dhcp true \
--foreman-proxy-dhcp-provider infoblox \
--enable-foreman-proxy-plugin-dhcp-infoblox \
--foreman-proxy-dhcp-server infoblox.example.com \
--foreman-proxy-plugin-dhcp-infoblox-username admin \
--foreman-proxy-plugin-dhcp-infoblox-password password \
--foreman-proxy-plugin-dhcp-infoblox-record-type fixedaddress \
--foreman-proxy-plugin-dhcp-infoblox-dns-view default \
--foreman-proxy-plugin-dhcp-infoblox-network-view default
    Note

    If you want to use the DHCP and DNS Infoblox modules together, configure the DHCP Infoblox module with the fixedaddress record type only. The host record type is not supported in this scenario because it causes conflicts and you cannot rename hosts in Foreman.

  5. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DHCP service with a subnet.

2.5. Integrating the libvirt API to manage DHCP leases

If you manage VMs through the libvirt API, you can integrate the API into Foreman server to manage DHCP leases. The integration enables you to continue using dnsmasq in libvirt, and Foreman manages IP leases and boot configurations on the DHCP server during the provisioning of hosts.

With this type of integration, Foreman uses a local or remote libvirt API to manage DHCP leases in dnsmasq instances.

Procedure

  1. Configure Foreman server or Smart Proxy server to connect to the libvirt API:

    # foreman-installer \
--foreman-proxy-dhcp true \
--foreman-proxy-dhcp-provider libvirt \
--foreman-proxy-libvirt-network default \
--foreman-proxy-libvirt-url qemu:///system

    Note that you can only use one network and URL for both the dns_libvirt and dhcp_libvirt providers.

  2. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the DHCP service with a subnet.

2.6. Associating the DHCP service with a subnet

After you configured or changed the DHCP provider, you must update the configuration of each affected Smart Proxy in the Foreman web UI.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Subnets.

  2. Select the subnet name.

  3. On the Subnet tab, set IPAM to DHCP.

  4. On the Smart Proxy tab, set DHCP Proxy to your Smart Proxy.

  5. Click Submit.

2.7. Disabling DHCP for integration

If you want to manually manage a DHCP service and not integrate it into Foreman server, you must prevent Foreman from maintaining this service on the operating system and disable orchestration to avoid errors.

Note

Disabling DHCP in Foreman does not remove the related backend service on the operating system.
Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Subnets.

  2. For each subnet that is associated with the DHCP Smart Proxy:

    1. Select the subnet.

    2. On the Smart Proxies tab, clear the DHCP Smart Proxy field.

    3. Click Submit.

  3. On Foreman server and Smart Proxy server, enter:

    # foreman-installer --foreman-proxy-dhcp false
    Note

    Foreman does not perform orchestration when a Smart Proxy is not set for a given subnet. When you disable Smart Proxy associations, orchestration commands for existing hosts can fail if the expected records and configuration files are not present.

2.8. Troubleshooting DHCP problems

Foreman can manage an ISC DHCP server on Foreman server or Smart Proxy servers. Foreman can list, create, and delete DHCP reservations and leases. However, there are several problems that you might encounter on occasions.

Out of sync DHCP records

When an error occurs during DHCP orchestration, DHCP records in the Foreman database and the DHCP server might not match. To fix this, you must add missing DHCP records from the Foreman database to the DHCP server and then remove unwanted records from the DHCP server as per the following steps:

Procedure

  1. To preview the DHCP records that are going to be added to the DHCP server, enter the following command:

    # foreman-rake orchestration:dhcp:add_missing subnet_name=NAME

  2. If you are satisfied by the preview changes in the previous step, apply them by entering the above command with the perform=1 argument:

    # foreman-rake orchestration:dhcp:add_missing subnet_name=NAME perform=1

  3. To keep DHCP records in Foreman and in the DHCP server synchronized, you can remove unwanted DHCP records from the DHCP server. Note that Foreman assumes that all managed DHCP servers do not contain third-party records, therefore, this step might delete those unexpected records. To preview what records are going to be removed from the DHCP server, enter the following command:

    # foreman-rake orchestration:dhcp:remove_offending subnet_name=NAME

  4. If you are satisfied by the preview changes in the previous step, apply them by entering the above command with the perform=1 argument:

    # foreman-rake orchestration:dhcp:remove_offending subnet_name=NAME perform=1
PXE loader option change

When the PXE loader option is changed for an existing host, this causes a DHCP conflict. The only workaround is to overwrite the DHCP entry.

This is a known issue. Until Issue 27877 is fixed, the only workaround is to overwrite the DHCP entry.

Incorrect permissions on DHCP files

An operating system update can update the dhcpd package. This causes the permissions of important directories and files to reset so that the DHCP Smart Proxy cannot read the required information.

For more information, see ERF12-6899 - Unable to set DHCP entry.

Changing the DHCP Smart Proxy entry

Foreman manages DHCP records only for hosts that are assigned to subnets with a DHCP Smart Proxy set. If you create a host and then clear or change the DHCP Smart Proxy, when you attempt to delete the host, the action fails.

If you create a host without setting the DHCP Smart Proxy and then try to set the DHCP Smart Proxy, this causes DHCP conflicts.

Deleted hosts entries in the dhcpd.leases file

Any changes to a DHCP lease are appended to the end of the dhcpd.leases file. Because entries are appended to the file, it is possible that two or more entries of the same lease can exist in the dhcpd.leases file at the same time. When there are two or more entries of the same lease, the last entry in the file takes precedence. Group, subgroup and host declarations in the lease file are processed in the same manner. If a lease is deleted, { deleted; } is appended to the declaration.

3. Configuring TFTP integration

You can integrate TFTP with Foreman to perform unattended installations by booting the operating system’s setup over the network.

3.1. Enabling the installer-managed TFTP service

If you do not have a TFTP server available in your network, you can use the installer-managed TFTP service to perform unattended installations. With the installer-managed TFTP service, you can run a TFTP server with a low maintenance effort because Foreman fully manages the TFTP service, including the files on that service.

Procedure

  • Configure your Foreman server or Smart Proxy server as the TFTP server:

    # foreman-installer \
--foreman-proxy-tftp true \
--foreman-proxy-tftp-managed true

3.2. Integrating a generic TFTP server

If you have a TFTP server in your network, you can integrate this service into your Foreman. The integration enables you to continue using your existing TFTP server. With this type of integration, Foreman uses the Network File System (NFS) protocol to access the root directory of the TFTP service.

Note

If you prefer a low maintenance solution that also manages files on the TFTP server, use the installer-managed TFTP service.

3.2.1. Configuring Foreman server for use with tftp

After you have prepared the TFTP server, integrate it into your Foreman server or Smart Proxy server.

Prerequisites

  • You shared the /exports/var/lib/tftpboot on the TFTP server with NFS.

Procedure

  1. Create the directory into which you later mount the NFS share:

    # mkdir -p /mnt/nfs/var/lib/tftpboot

  2. Edit the /etc/fstab file, and add entry for the NFS share to mount them automatically when the system boots:

    tftp_server_fqdn:/exports/var/lib/tftpboot  /mnt/nfs/var/lib/tftpboot  nfs  rw,vers=3,auto,nosharecache,context="system_u:object_r:tftpdir_rw_t:s0"  0 0

  3. Mount the NFS share:

    # mount /mnt/nfs/var/lib/tftpboot/

  4. Configure Foreman server or Smart Proxy server to use the TFTP server:

    # foreman-installer \
--foreman-proxy-tftp true \
--foreman-proxy-managed false \
--foreman-proxy-tftp-root /mnt/nfs/var/lib/tftpboot \
--foreman-proxy-tftp-servername tftp_server_fqdn

  5. For each affected Smart Proxy, update the configuration of that Smart Proxy in the Foreman web UI. For more information, see Associating the TFTP service with a subnet.

3.3. Associating the TFTP service with a subnet

After you configured or changed the TFTP provider, you must update the configuration of each affected Smart Proxy in the Foreman web UI.

Prerequisites

  • You configured a TFTP server.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Subnets.

  2. Select the subnet name.

  3. On the Smart Proxies tab, select the Smart Proxy for TFTP.

  4. Click Submit.

3.4. Disabling TFTP for integration

If you want to manually manage a TFTP service and not integrate it into Foreman, you must prevent Foreman from maintaining this service on the operating system and disable orchestration to avoid errors.

Note

Disabling TFTP in Foreman does not remove the related backend service on the operating system.
Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Subnets.

  2. For each subnet that is associated with the TFTP Smart Proxy:

    1. Select the subnet.

    2. On the Smart Proxies tab, clear the TFTP Smart Proxy field.

    3. Click Submit.

  3. On Foreman server, enter:

    # foreman-installer --foreman-proxy-tftp false
    Note

    Foreman does not perform orchestration when a Smart Proxy is not set for a given subnet. When you disable Smart Proxy associations, orchestration commands for existing hosts can fail if the expected records and configuration files are not present.