Preparing networking

Each provisioning type requires some network configuration. Use this chapter to configure network services on your orcharhino Proxies.

New hosts must have access to either your orcharhino Server or any orcharhino Proxy Server. If your hosts are on isolated networks and cannot connect to orcharhino Server directly, you must provision your hosts from orcharhino Proxy Servers. Provisioning by using orcharhino Proxy Servers can save on network bandwidth.

Configuring orcharhino Proxies 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 orcharhino Server to help configure network interfaces on new hosts.

The following instructions have similar applications to configuring orcharhino Proxy Servers managing a specific network.

Facts and NIC filtering

Facts describe aspects such as total memory, operating system version, or architecture as reported by the host. You can find facts in Monitor > Facts and search hosts through facts or use facts in templates.

orcharhino collects facts from multiple sources:

subscription manager
ansible
puppet

orcharhino is an inventory system for hosts and network interfaces. For hypervisors or container hosts, adding thousands of interfaces per host and updating the inventory every few minutes is inadequate. For each individual NIC reported, orcharhino creates a NIC entry and those entries are never removed from the database. Parsing all the facts and comparing all records in the database makes orcharhino extremely slow and unusable. To optimize the performance of various actions, most importantly fact import, you can use the options available on the Facts tab under Administer > Settings.

Optimizing performance by removing NICs from database

Filter and exclude the connections using the Exclude pattern for facts stored in orcharhino and Ignore interfaces with matching identifier option. By default, these options are set to most common hypervisors. If you name the virtual interfaces differently, you can update this filter to use it according to your requirements.

Procedure

In the orcharhino management UI, navigate to Administer > Settings and select the Facts tab.
To filter out all interfaces starting with specific names, for example, blu, add blu* to the Ignore interfaces with matching identifier option.
To prevent databases from storing facts related to interfaces starting with specific names, for example, blu, add blu* to the Exclude pattern for facts stored in orcharhino option.

By default, it contains the same list as the Ignore interfaces with matching identifier option. You can override it based on the your requirements. This filters out facts completely without storing them.
To remove facts from the database, enter the following command:
```
$ foreman-rake facts:clean
```
This command removes all facts matching with the filter added in Administer > Settings > Facts > the Exclude pattern for facts stored in orcharhino option.
To remove interfaces from the database, enter the following command:
```
$ foreman-rake interfaces:clean
```
This command removes all interfaces matching with the filter added in Administer > Settings > Facts > the Ignore interfaces with matching identifier option.

Network resources

orcharhino contains networking resources that you must set up and configure to create a host. It includes the following networking resources:

Domain

You must assign every host that is managed by orcharhino to a domain. Using the domain, orcharhino can manage A, AAAA, and PTR records. Even if you do not want orcharhino to manage your DNS servers, you still must create and associate at least one domain. Domains are included in the naming conventions orcharhino hosts, for example, a host with the name test123 in the example.com domain has the fully qualified domain name test123.example.com.

Subnet

You must assign every host managed by orcharhino to a subnet. Using subnets, orcharhino 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 orcharhino, you cannot create DHCP records for that subnet outside of orcharhino. In orcharhino, you can use IP Address Management (IPAM) to manage IP addresses with one of the following options:

DHCP: DHCP orcharhino Proxy 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, orcharhino Proxy 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, orcharhino 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 orcharhino controls and that do not have any hosts created externally.

The orcharhino Proxy 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: orcharhino finds the next available IP address from the Subnet range by excluding all IP addresses from the orcharhino 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: orcharhino finds the next available IP address from the Subnet range by excluding all IP addresses from the orcharhino 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 orcharhino Proxy feature. orcharhino currently does not ship with any external IPAM implementations, but several plugins 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 orcharhino control.

For more information about adding a subnet, see Adding a Subnet to Server.

DHCP Ranges

You can define the same DHCP range in orcharhino Server for both discovered and provisioned systems, but use a separate range for each service within the same subnet.

Options in managed DHCPv4

When orcharhino manages the DHCP service and can update the DHCP configuration, orcharhino sets the next-server and filename DHCP options.

next-server

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 orcharhino Proxy. You can use the orcharhino-installer command with the --foreman-proxy-tftp-servername argument to set the TFTP server in the /etc/foreman-proxy/settings.d/tftp.yml file:

$ orcharhino-installer --foreman-proxy-tftp-servername 1.2.3.4

Each TFTP orcharhino Proxy then reports this setting through the API and orcharhino can retrieve the configuration information when it creates the DHCP record.

When the PXE loader is set to none, orcharhino does not populate the next-server option into the DHCP record.

If the next-server option remains undefined, orcharhino calls the orcharhino Proxy API to retrieve the server name as specified by the --foreman-proxy-tftp-servername argument in a orcharhino-installer run. If the orcharhino Proxy API call does not return a server name, orcharhino uses the hostname of the orcharhino Proxy.

filename

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, orcharhino 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

PXE loader option	filename entry	Notes
PXELinux BIOS	`pxelinux.0`
PXELinux UEFI	`pxelinux.efi`
iPXE Chain BIOS	`undionly.kpxe`
PXEGrub2 UEFI	`grub2/grubx64.efi`	x64 can differ depending on architecture
iPXE UEFI HTTP	`http://orcharhino-proxy.network2.example.com:8000/httpboot/ipxe-x64.efi`	Requires the `httpboot` feature and renders the `filename` as a full URL where orcharhino-proxy.network2.example.com is a known host name of orcharhino Proxy in orcharhino.
Grub2 UEFI HTTP	`http://orcharhino-proxy.network2.example.com:8000/httpboot/grub2/grubx64.efi`	Requires the `httpboot` feature and renders the `filename` as a full URL where orcharhino-proxy.network2.example.com is a known host name of orcharhino Proxy in orcharhino.

PXELinux BIOS

pxelinux.0

PXELinux UEFI

pxelinux.efi

iPXE Chain BIOS

undionly.kpxe

PXEGrub2 UEFI

grub2/grubx64.efi

x64 can differ depending on architecture

iPXE UEFI HTTP

http://orcharhino-proxy.network2.example.com:8000/httpboot/ipxe-x64.efi

Requires the httpboot feature and renders the filename as a full URL where orcharhino-proxy.network2.example.com is a known host name of orcharhino Proxy in orcharhino.

Grub2 UEFI HTTP

http://orcharhino-proxy.network2.example.com:8000/httpboot/grub2/grubx64.efi

Requires the httpboot feature and renders the filename as a full URL where orcharhino-proxy.network2.example.com is a known host name of orcharhino Proxy in orcharhino.

Options in unmanaged DHCPv6

To provision hosts over TFTP in an IPv6-only network, configure the DHCP server to respond with the bootfile-url DHCP option. orcharhino cannot manage the DHCPv6 service, therefore, you have to configure your DHCP server manually.

bootfile-url

The URL value of this option has to point to a file on TFTP orcharhino Proxy that is a first-stage boot loader, such as pxelinux.0. Example configuration:

   "option-data": [
      {
         "name": "bootfile-url",
         "data": "tftp://2001:db8:1::1/pxelinux.0"
      }
   ],

Multiple subnets or domains using installer

The orcharhino-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 orcharhino-installer to perform the changes and verify that the /etc/dhcp/dhcpd.conf contains appropriate entries. Subnets must be then defined in orcharhino database.

DNS options for network configuration

--foreman-proxy-dns: Enables the DNS feature. You can set this option to true or false.
--foreman-proxy-dns-provider: Selects the provider to be used.
--foreman-proxy-dns-managed: Let the installer manage ISC BIND. This is only relevant when using the nsupdate and nsupdate_gss providers. You can set this option to true or false.
--foreman-proxy-dns-forwarders: Sets the DNS forwarders. Only used when ISC BIND is managed by the installer. Set this to your DNS recursors.
--foreman-proxy-dns-interface: Sets the interface to listen for DNS requests. Only used when ISC BIND is managed by the installer. Set this to eth1.
--foreman-proxy-dns-reverse: The DNS reverse zone name. Only used when ISC BIND is managed by the installer.
--foreman-proxy-dns-server: Sets the address of the DNS server. Only used by the nsupdate, nsupdate_gss, and infoblox providers.
--foreman-proxy-dns-zone: Sets the DNS zone name. Only used when ISC BIND is managed by the installer.

Run orcharhino-installer --help to view more options related to DNS and other orcharhino Proxy services.

TFTP options for network configuration

--foreman-proxy-tftp: Enables TFTP service. You can set this option to true or false.
--foreman-proxy-tftp-managed: Enables Foreman to manage the TFTP service. You can set this option to true or false.
--foreman-proxy-tftp-servername: Sets the TFTP server to use. Ensure that you use orcharhino Proxy’s IP address.

Run orcharhino-installer --help to view more options related to TFTP and other orcharhino Proxy services.

Using TFTP services through NAT

You can use orcharhino 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 Linux with firewalld:

Allow the TFTP service in the firewall configuration:
```
$ firewall-cmd --add-service=tftp
```
Make the changes persistent:
```
$ firewall-cmd --runtime-to-permanent
```

Using NAT on linux with iptables:

Configure the firewall to allow TFTP service UDP on port 69:

$ iptables \
--sport 69 \
--state ESTABLISHED \
-A OUTPUT \
-i eth0 \
-j ACCEPT \
-m state \
-p udp
$ service iptables save

Load the ip_conntrack_tftp kernel TFTP state module. In the /etc/sysconfig/iptables-config file, locate IPTABLES_MODULES and add ip_conntrack_tftp as follows:
```
IPTABLES_MODULES="ip_conntrack_tftp"
```

Adding a domain to orcharhino Server

orcharhino Server defines domain names for each host on the network. orcharhino Server must have information about the domain and orcharhino Proxy Server responsible for domain name assignment.

Checking for existing domains

orcharhino Server might already have the relevant domain created as part of orcharhino 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, orcharhino 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 orcharhino Server.
The domain name must have a Start of Authority (SOA) record available from orcharhino Server.
The system resolver in the /etc/resolv.conf file must have a valid and working configuration.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure

In the orcharhino management 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 create command to create a domain:

$ hammer domain create \
--description "My_Domain" \
--dns-id My_DNS_orcharhino_Proxy_ID \
--locations "My_Location" \
--name "my-domain.tld" \
--organizations "My_Organization"

Adding a subnet to orcharhino Server

You must add information for each of your subnets to orcharhino Server because orcharhino configures interfaces for new hosts. To configure interfaces, orcharhino Server must have all the information about the network that connects these interfaces.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure

In the orcharhino management 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 Network Resources.
Enter the information for the IPAM method that you select. Click the Remote Execution tab and select the orcharhino Proxy that controls the remote execution.
Click the Domains tab and select the domains that apply to this subnet.
Click the orcharhino Proxies tab and select the orcharhino Proxy 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 orcharhino Proxy.
Click the Organizations tab and select the organizations that use this orcharhino Proxy.
Click Submit to save the subnet information.

CLI procedure

Create the subnet with the following command:

$ hammer subnet create \
--boot-mode "DHCP" \
--description "My_Description" \
--dhcp-id My_DHCP_orcharhino_Proxy_ID \
--dns-id My_DNS_orcharhino_Proxy_ID \
--dns-primary "192.168.140.2" \
--dns-secondary "8.8.8.8" \
--domains "my-domain.tld" \
--from "192.168.140.111" \
--gateway "192.168.140.1" \
--ipam "DHCP" \
--locations "_My_Location" \
--mask "255.255.255.0" \
--name "My_Network" \
--network "192.168.140.0" \
--organizations "My_Organization" \
--tftp-id My_TFTP_orcharhino_Proxy_ID \
--to "192.168.140.250"

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution Share Alike 4.0 International ("CC BY-SA 4.0") license. This page also contains text from the official Foreman documentation which uses the same license ("CC BY-SA 4.0").