Chapter 3. Configuring Networking
Each provisioning type requires some network configuration. Use this chapter to configure network services in your integrated Capsule on Satellite Server.
New hosts must have access to your Capsule Server. Capsule Server can be either your integrated Capsule on Satellite Server or an external Capsule Server. You might want to provision hosts from an external Capsule Server when the hosts are on isolated networks and cannot connect to Satellite Server directly, or when the content is synchronized with Capsule Server. Provisioning using the external Capsule Server can save on network bandwidth.
Configuring Capsule Server has two basic requirements:
Configuring network services. This includes:
- Content delivery services
- Network services (DHCP, DNS, and TFTP)
- Puppet configuration
- Defining network resource data in Satellite Server to help configure network interfaces on new hosts.
The following instructions have similar applications to configuring standalone Capsules managing a specific network. To configure Satellite to use external DHCP, DNS, and TFTP services, see Configuring External Services in Installing Satellite Server from a Connected Network.
3.1. Network Resources
Satellite contains networking resources that you must set up and configure to create a host. Satellite includes the following networking resources:
- Domain
-
You must assign every host that is managed by Satellite to a domain. Using the domain, Satellite can manage A, AAAA, and PTR records. Even if you do not want Satellite to manage your DNS servers, you still must create and associate at least one domain. Domains are included in the naming conventions Satellite hosts, for example, a host with the name
test123in theexample.comdomain has the fully qualified domain nametest123.example.com. - Subnet
You must assign every host managed by Satellite to a subnet. Using subnets, Satellite can then manage IPv4 reservations. If there are no reservation integrations, you still must create and associate at least one subnet. When you manage a subnet in Satellite, you cannot create DHCP records for that subnet outside of Satellite. In Satellite, you can use IP Address Management (IPAM) to manage IP addresses with one of the following options:
DHCP: DHCP Capsule manages the assignment of IP addresses by finding the next available IP address starting from the first address of the range and skipping all addresses that are reserved. Before assigning an IP address, Capsule sends an ICMP and TCP pings to check whether the IP address is in use. Note that if a host is powered off, or has a firewall configured to disable connections, Satellite makes a false assumption that the IP address is available. This check does not work for hosts that are turned off, therefore, the DHCP option can only be used with subnets that Satellite controls and that do not have any hosts created externally.
The Capsule DHCP module retains the offered IP addresses for a short period of time to prevent collisions during concurrent access, so some IP addresses in the IP range might remain temporarily unused.
- Internal DB: Satellite finds the next available IP address from the Subnet range by excluding all IP addresses from the Satellite database in sequence. The primary source of data is the database, not DHCP reservations. This IPAM is not safe when multiple hosts are being created in parallel; in that case, use DHCP or Random DB IPAM instead.
- Random DB: Satellite finds the next available IP address from the Subnet range by excluding all IP addresses from the Satellite database randomly. The primary source of data is the database, not DHCP reservations. This IPAM is safe to use with concurrent host creation as IP addresses are returned in random order, minimizing the chance of a conflict.
- EUI-64: Extended Unique Identifier (EUI) 64bit IPv6 address generation, as per RFC2373, is obtained through the 48-bit MAC address.
- External IPAM: Delegates IPAM to an external system through Capsule feature. Satellite currently does not ship with any external IPAM implementations, but several plug-ins are in development.
None: IP address for each host must be entered manually.
Options DHCP, Internal DB and Random DB can lead to DHCP conflicts on subnets with records created externally. These subnets must be under exclusive Satellite control.
For more information about adding a subnet, see Section 3.7, “Adding a Subnet to Satellite Server”.
- DHCP Ranges
- You can define the same DHCP range in Satellite Server for both discovered and provisioned systems, but use a separate range for each service within the same subnet.
3.2. Satellite and DHCP Options
Satellite manages DHCP reservations through a DHCP Capsule. Satellite also sets the next-server and filename DHCP options.
The next-server option
The next-server option provides the IP address of the TFTP server to boot from. This option is not set by default and must be set for each TFTP Capsule. You can use the satellite-installer command with the --foreman-proxy-tftp-servername option to set the TFTP server in the /etc/foreman-proxy/settings.d/tftp.yml file:
# satellite-installer --foreman-proxy-tftp-servername 1.2.3.4Each TFTP Capsule then reports this setting through the API and Satellite can retrieve the configuration information when it creates the DHCP record.
When the PXE loader is set to none, Satellite does not populate the next-server option into the DHCP record.
If the next-server option remains undefined, Satellite uses reverse DNS search to find a TFTP server address to assign, but you might encounter the following problems:
- DNS timeouts during provisioning
- Querying of incorrect DNS server. For example, authoritative rather than caching
-
Errors about incorrect IP address for the TFTP server. For example,
PTR record was invalid
If you encounter these problems, check the DNS setup on both Satellite and Capsule, specifically the PTR record resolution.
The filename option
The filename option contains the full path to the file that downloads and executes during provisioning. The PXE loader that you select for the host or host group defines which filename option to use. When the PXE loader is set to none, Satellite does not populate the filename option into the DHCP record. Depending on the PXE loader option, the filename changes as follows:
| PXE loader option | filename entry | Notes |
|---|---|---|
| PXELinux BIOS |
| |
| PXELinux UEFI |
| |
| iPXE Chain BIOS |
| |
| PXEGrub2 UEFI |
| x64 can differ depending on architecture |
| iPXE UEFI HTTP |
|
Requires the |
| Grub2 UEFI HTTP |
|
Requires the |
3.3. Troubleshooting DHCP Problems in Satellite
Satellite can manage an ISC DHCP server on internal or external DHCP Capsule. Satellite can list, create, and delete DHCP reservations and leases. However, there are a number of problems that you might encounter on occasions.
Out of sync DHCP records
When an error occurs during DHCP orchestration, DHCP records in the Satellite database and the DHCP server might not match. To fix this, you must add missing DHCP records from the Satellite database to the DHCP server and then remove unwanted records from the DHCP server as per the following steps:
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
If you are satisfied by the preview changes in the previous step, apply them by entering the above command with the
perform=1argument:# foreman-rake orchestration:dhcp:add_missing subnet_name=NAME perform=1
To keep DHCP records in Satellite and in the DHCP server synchronized, you can remove unwanted DHCP records from the DHCP server. Note that Satellite 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
If you are satisfied by the preview changes in the previous step, apply them by entering the above command with the
perform=1argument:# 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.
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 Capsule cannot read the required information.
For more information, see DHCP error while provisioning host from Satellite server Error ERF12-6899 ProxyAPI::ProxyException: Unable to set DHCP entry RestClient::ResourceNotFound 404 Resource Not Found on Red Hat Knowledgebase.
Changing the DHCP Capsule entry
Satellite manages DHCP records only for hosts that are assigned to subnets with a DHCP Capsule set. If you create a host and then clear or change the DHCP Capsule, when you attempt to delete the host, the action fails.
If you create a host without setting the DHCP Capsule and then try to set the DHCP Capsule, 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.4. Prerequisites for Image Based Provisioning
Post-Boot Configuration Method
Images that use the finish post-boot configuration scripts require a managed DHCP server, such as Satellite’s integrated Capsule or an external Capsule. The host must be created with a subnet associated with a DHCP Capsule, and the IP address of the host must be a valid IP address from the DHCP range.
It is possible to use an external DHCP service, but IP addresses must be entered manually. The SSH credentials corresponding to the configuration in the image must be configured in Satellite to enable the post-boot configuration to be made.
Check the following items when troubleshooting a virtual machine booted from an image that depends on post-configuration scripts:
- The host has a subnet assigned in Satellite Server.
- The subnet has a DHCP Capsule assigned in Satellite Server.
- The host has a valid IP address assigned in Satellite Server.
- The IP address acquired by the virtual machine using DHCP matches the address configured in Satellite Server.
- The virtual machine created from an image responds to SSH requests.
- The virtual machine created from an image authorizes the user and password, over SSH, which is associated with the image being deployed.
- Satellite Server has access to the virtual machine via SSH keys. This is required for the virtual machine to receive post-configuration scripts from Satellite Server.
Pre-Boot Initialization Configuration Method
Images that use the cloud-init scripts require a DHCP server to avoid having to include the IP address in the image. A managed DHCP Capsule is preferred. The image must have the cloud-init service configured to start when the system boots and fetch a script or configuration data to use in completing the configuration.
Check the following items when troubleshooting a virtual machine booted from an image that depends on initialization scripts included in the image:
- There is a DHCP server on the subnet.
-
The virtual machine has the
cloud-initservice installed and enabled.
For information about the differing levels of support for finish and cloud-init scripts in virtual-machine images, see the Red Hat Knowledgebase Solution What are the supported compute resources for the finish and cloud-init scripts on the Red Hat Customer Portal.
3.5. Configuring Network Services
Some provisioning methods use Capsule Server services. For example, a network might require Capsule Server to act as a DHCP server. A network can also use PXE boot services to install the operating system on new hosts. This requires configuring Capsule Server to use the main PXE boot services: DHCP, DNS, and TFTP.
Use the satellite-installer command with the options to configure these services on Satellite Server.
To configure these services on an external Capsule Server, run satellite-installer --scenario capsule.
Satellite Server uses eth0 for external communication, such as connecting to Red Hat’s CDN.
Procedure
To configure network services on Satellite’s integrated Capsule, complete the following steps:
Enter the
satellite-installercommand to configure the required network services:# satellite-installer --foreman-proxy-dhcp true \ --foreman-proxy-dhcp-managed true \ --foreman-proxy-dhcp-gateway "192.168.140.1" \ --foreman-proxy-dhcp-interface "eth1" \ --foreman-proxy-dhcp-nameservers "192.168.140.2" \ --foreman-proxy-dhcp-range "192.168.140.10 192.168.140.110" \ --foreman-proxy-dhcp-server "192.168.140.2" \ --foreman-proxy-dns true \ --foreman-proxy-dns-managed true \ --foreman-proxy-dns-forwarders "8.8.8.8; 8.8.4.4" \ --foreman-proxy-dns-interface "eth1" \ --foreman-proxy-dns-reverse "140.168.192.in-addr.arpa" \ --foreman-proxy-dns-server "127.0.0.1" \ --foreman-proxy-dns-zone "example.com" \ --foreman-proxy-tftp true \ --foreman-proxy-tftp-managed true
Find Capsule Server that you configure:
# hammer proxy list
Refresh features of Capsule Server to view the changes:
# hammer proxy refresh-features --name "satellite.example.com"Verify the services configured on Capsule Server:
# hammer proxy info --name "satellite.example.com"
3.5.1. Multiple Subnets or Domains via Installer
The satellite-installer options allow only for a single DHCP subnet or DNS domain. One way to define more than one subnet is by using a custom configuration file.
For every additional subnet or domain, create an entry in /etc/foreman-installer/custom-hiera.yaml file:
dhcp::pools:
isolated.lan:
network: 192.168.99.0
mask: 255.255.255.0
gateway: 192.168.99.1
range: 192.168.99.5 192.168.99.49
dns::zones:
# creates @ SOA $::fqdn root.example.com.
# creates $::fqdn A $::ipaddress
example.com: {}
# creates @ SOA test.example.net. hostmaster.example.com.
# creates test.example.net A 192.0.2.100
example.net:
soa: test.example.net
soaip: 192.0.2.100
contact: hostmaster.example.com.
# creates @ SOA $::fqdn root.example.org.
# does NOT create an A record
example.org:
reverse: true
# creates @ SOA $::fqdn hostmaster.example.com.
2.0.192.in-addr.arpa:
reverse: true
contact: hostmaster.example.com.
Execute satellite-installer to perform the changes and verify that the /etc/dhcp/dhcpd.conf contains appropriate entries. Subnets must be then defined in Satellite database.
3.5.2. DHCP, DNS, and TFTP Options for Network Configuration
DHCP Options
- --foreman-proxy-dhcp
-
Enables the DHCP service. You can set this option to
trueorfalse. - --foreman-proxy-dhcp-managed
-
Enables Foreman to manage the DHCP service. You can set this option to
trueorfalse. - --foreman-proxy-dhcp-gateway
- The DHCP pool gateway. Set this to the address of the external gateway for hosts on your private network.
- --foreman-proxy-dhcp-interface
-
Sets the interface for the DHCP service to listen for requests. Set this to
eth1. - --foreman-proxy-dhcp-nameservers
-
Sets the addresses of the nameservers provided to clients through DHCP. Set this to the address for Satellite Server on
eth1. - --foreman-proxy-dhcp-range
- A space-separated DHCP pool range for Discovered and Unmanaged services.
- --foreman-proxy-dhcp-server
- Sets the address of the DHCP server to manage.
DNS Options
- --foreman-proxy-dns
-
Enables DNS service. You can set this option to
trueorfalse. - --foreman-proxy-dns-managed
-
Enables Foreman to manage the DNS service. You can set this option to
trueorfalse. - --foreman-proxy-dns-forwarders
- Sets the DNS forwarders. Set this to your DNS servers.
- --foreman-proxy-dns-interface
-
Sets the interface to listen for DNS requests. Set this to
eth1. - --foreman-proxy-dns-reverse
- The DNS reverse zone name.
- --foreman-proxy-dns-server
- Sets the address of the DNS server to manage.
- --foreman-proxy-dns-zone
- Sets the DNS zone name.
TFTP Options
- --foreman-proxy-tftp
-
Enables TFTP service. You can set this option to
trueorfalse. - --foreman-proxy-tftp-managed
-
Enables Foreman to manage the TFTP service. You can set this option to
trueorfalse. - --foreman-proxy-tftp-servername
- Sets the TFTP server to use. Ensure that you use Capsule’s IP address.
Run satellite-installer --help to view more options related to DHCP, DNS, TFTP, and other Satellite Capsule services
3.5.3. Using TFTP Services through NAT
You can use Satellite TFTP services through NAT. To do this, on all NAT routers or firewalls, you must enable a TFTP service on UDP port 69 and enable the TFTP state tracking feature. For more information, see the documentation for your NAT device.
Using NAT on Red Hat Enterprise Linux 7:
Use the following command to allow TFTP service on UDP port 69, load the kernel TFTP state tracking module, and make the changes persistent:
# firewall-cmd --add-service=tftp && firewall-cmd --runtime-to-permanent
For a NAT running on Red Hat Enterprise Linux 6:
Configure the firewall to allow TFTP service UDP on port 69.
# iptables -A OUTPUT -i eth0 -p udp --sport 69 -m state \ --state ESTABLISHED -j ACCEPT # service iptables save
Load the
ip_conntrack_tftpkernel TFTP state module. In the/etc/sysconfig/iptables-configfile, locateIPTABLES_MODULESand addip_conntrack_tftpas follows:IPTABLES_MODULES="ip_conntrack_tftp"
3.6. Adding a Domain to Satellite Server
Satellite Server defines domain names for each host on the network. Satellite Server must have information about the domain and Capsule Server responsible for domain name assignment.
Checking for Existing Domains
Satellite Server might already have the relevant domain created as part of Satellite Server installation. Switch the context to Any Organization and Any Location then check the domain list to see if it exists.
DNS Server Configuration Considerations
During the DNS record creation, Satellite performs conflict DNS lookups to verify that the host name is not in active use. This check runs against one of the following DNS servers:
- The system-wide resolver if Administer > Settings > Query local nameservers is set to true.
- The nameservers that are defined in the subnet associated with the host.
- The authoritative NS-Records that are queried from the SOA from the domain name associated with the host.
If you experience timeouts during DNS conflict resolution, check the following settings:
- The subnet nameservers must be reachable from Satellite Server.
- The domain name must have a Start of Authority (SOA) record available from Satellite Server.
-
The system resolver in the
/etc/resolv.conffile must have a valid and working configuration.
To use the CLI instead of the web UI, see the CLI procedure.
Procedure
To add a domain to Satellite, complete the following steps:
- In the Satellite web UI, navigate to Infrastructure > Domains and click Create Domain.
- In the DNS Domain field, enter the full DNS domain name.
- In the Fullname field, enter the plain text name of the domain.
- Click the Parameters tab and configure any domain level parameters to apply to hosts attached to this domain. For example, user defined Boolean or string parameters to use in templates.
- Click Add Parameter and fill in the Name and Value fields.
- Click the Locations tab, and add the location where the domain resides.
- Click the Organizations tab, and add the organization that the domain belongs to.
- Click Submit to save the changes.
CLI procedure
Use the
hammer domain createcommand to create a domain:# hammer domain create --name "domain_name.com" \ --description "My example domain" --dns-id 1 \ --locations "My_Location" --organizations "My_Organization"
In this example, the --dns-id option uses 1, which is the ID of your integrated Capsule on Satellite Server.
3.7. Adding a Subnet to Satellite Server
You must add information for each of your subnets to Satellite Server because Satellite configures interfaces for new hosts. To configure interfaces, Satellite Server must have all the information about the network that connects these interfaces.
To use the CLI instead of the web UI, see the CLI procedure.
Procedure
- In the Satellite web UI, navigate to Infrastructure > Subnets, and in the Subnets window, click Create Subnet.
- In the Name field, enter a name for the subnet.
- In the Description field, enter a description for the subnet.
- In the Network address field, enter the network address for the subnet.
- In the Network prefix field, enter the network prefix for the subnet.
- In the Network mask field, enter the network mask for the subnet.
- In the Gateway address field, enter the external gateway for the subnet.
- In the Primary DNS server field, enter a primary DNS for the subnet.
- In the Secondary DNS server, enter a secondary DNS for the subnet.
- From the IPAM list, select the method that you want to use for IP address management (IPAM). For more information about IPAM, see Section 3.1, “Network Resources”.
- Enter the information for the IPAM method that you select. Click the Remote Execution tab and select the Capsule that controls the remote execution.
- Click the Domains tab and select the domains that apply to this subnet.
- Click the Capsules tab and select the Capsule that applies to each service in the subnet, including DHCP, TFTP, and reverse DNS services.
- Click the Parameters tab and configure any subnet level parameters to apply to hosts attached to this subnet. For example, user defined Boolean or string parameters to use in templates.
- Click the Locations tab and select the locations that use this Capsule.
- Click the Organizations tab and select the organizations that use this Capsule.
- Click Submit to save the subnet information.
CLI procedure
Create the subnet with the following command:
# hammer subnet create --name "My_Network" \ --description "your_description" \ --network "192.168.140.0" --mask "255.255.255.0" \ --gateway "192.168.140.1" --dns-primary "192.168.140.2" \ --dns-secondary "8.8.8.8" --ipam "DHCP" \ --from "192.168.140.111" --to "192.168.140.250" --boot-mode "DHCP" \ --domains "example.com" --dhcp-id 1 --dns-id 1 --tftp-id 1 \ --locations "My_Location" --organizations "My_Organization"
In this example, the --dhcp-id, --dns-id, and --tftp-id options use 1, which is the ID of the integrated Capsule in Satellite Server.
