Using PXE to Provision Hosts

You can provision bare metal instances with orcharhino using one of the following methods:

Unattended Provisioning: New hosts are identified by a MAC address and orcharhino Server provisions the host using a PXE boot process.
Unattended Provisioning with Discovery: New hosts use PXE boot to load the orcharhino Discovery service. This service identifies hardware information about the host and lists it as an available host to provision. For more information, see Configuring the Discovery Service.
PXE-less Provisioning: New hosts are provisioned with a boot disk or PXE-less discovery image that orcharhino Server generates.
PXE-less Provisioning with Discovery: New hosts use an ISO boot disk that loads the orcharhino Discovery service. This service identifies hardware information about the host and lists it as an available host to provision. For more information, see Implementing PXE less Discovery.

Discovery workflows are only available when the Discovery plug-in is installed. For more information, see Configuring the Discovery Service.

BIOS and UEFI Support

With orcharhino, you can perform both BIOS and UEFI based PXE provisioning. Both BIOS and UEFI interfaces work as interpreters between the computer’s operating system and firmware, initializing the hardware components and starting the operating system at boot time.

In orcharhino provisioning, the PXE loader option defines the DHCP filename option to use during provisioning. For BIOS systems, use the PXELinux BIOS option to enable a provisioned node to download the pxelinux.0 file over TFTP. For UEFI systems, use the PXEGrub2 UEFI option to enable a TFTP client to download grub2/grubx64.efi file, or use the PXEGrub2 UEFI HTTP option to enable an UEFI HTTP client to download grubx64.efi from orcharhino Proxy with the HTTP Boot feature. Use SecureBoot options to enable a client to download the shim.efi bootstrap bootloader that then loads the signed grubx64.efi. Other PXE loaders like PXELinux UEFI, Grub2 ELF or iPXE Chain, require additional configuration. These workflows are not documented at the moment.

For BIOS provisioning, you must associate a PXELinux template with the operating system. For UEFI provisioning, you must associate a PXEGrub2 template with the operating system. If you associate both PXELinux and PXEGrub2 templates, orcharhino can deploy configuration files for both on a TFTP server, so that you can switch between PXE loaders easily.

Prerequisites for Bare Metal Provisioning

The requirements for bare metal provisioning include:

A orcharhino Proxy managing the network for bare metal hosts. For unattended provisioning and discovery-based provisioning, orcharhino Server requires PXE server settings.

For more information about networking requirements, see Configuring Networking.

For more information about the Discovery service, Configuring the Discovery Service.
A bare metal host or a blank VM.
Provide the installation medium for the operating systems that you want to use to provision hosts. For more information, see Syncing Repositories in Managing Content.
Provide an activation key for host registration. For more information, see Creating An Activation Key in Managing Content.

For information about the security token for unattended and PXE-less provisioning, see Configuring the Security Token Validity Duration.

Configuring the Security Token Validity Duration

When performing any kind of provisioning, as a security measure, orcharhino automatically generates a unique token and adds this token to the OS installer recipe URL in the PXE configuration file (PXELinux, Grub2). By default, the token is valid for 360 minutes. When you provision a host, ensure that you reboot the host within this time frame. If the token expires, it is no longer valid and you receive a 404 error and the operating system installer download fails.

Procedure

In the orcharhino management UI, navigate to Administer > Settings, and click the Provisioning tab.
Find the Token duration option and click the edit icon and edit the duration, or enter 0 to disable token generation. If token generation is disabled, an attacker can spoof client IP address and download OS installer recipe from orcharhino Server, including the encrypted root password.

Creating Hosts with Unattended Provisioning

Unattended provisioning is the simplest form of host provisioning. You enter the host details on orcharhino Server and boot your host. orcharhino Server automatically manages the PXE configuration, organizes networking services, and provides the operating system and configuration for the host.

This method of provisioning hosts uses minimal interaction during the process.

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

Procedure

In the orcharhino management UI, navigate to Hosts > Create Host.
In the Name field, enter a name for the host.
Click the Organization and Location tabs and change the context to match your requirements.
From the Host Group list, select a host group that you want to use to populate the form.
Click the Interface tab, and on the host’s interface, click Edit.
Verify that the fields are populated with values. Note in particular:
- The Name from the Host tab becomes the DNS name.
- orcharhino Server automatically assigns an IP address for the new host.
In the MAC address field, enter a MAC address for the host. This ensures the identification of the host during the PXE boot process.
Ensure that orcharhino Server automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
In the MAC address field, enter a MAC address of the host’s provisioning interface. This ensures the identification of the host during the PXE boot process.
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
Click the Operating System tab, and verify that all fields contain values. Confirm each aspect of the operating system.
Optional: Click Resolve in Provisioning template to check the new host can identify the right provisioning templates to use.

For more information about associating provisioning templates, see provisioning templates.
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
Click Submit to save the host details.

For more information about network interfaces, see Adding network interfaces.

This creates the host entry and the relevant provisioning settings. This also includes creating the necessary directories and files for PXE booting the bare metal host. If you start the physical host and set its boot mode to PXE, the host detects the DHCP service of orcharhino Server’s integrated orcharhino Proxy, receives HTTP endpoint of the Kickstart tree and installs the operating system.

When the installation completes, the host also registers to orcharhino Server using the activation key and installs the necessary configuration and management tools from the orcharhino Client for CentOS repository.

CLI procedure

Create the host with the hammer host create command:

# hammer host create --name "My_Unattended_Host" --organization "My_Organization" \
--location "My_Location" --hostgroup "My_Host_Group" --mac "aa:aa:aa:aa:aa:aa" \
--build true --enabled true --managed true

Ensure the network interface options are set using the hammer host interface update command:

# hammer host interface update --host "test1" --managed true \
--primary true --provision true

Creating Hosts with PXE-less Provisioning

Some hardware does not provide a PXE boot interface. In orcharhino, you can provision a host without PXE boot. This is also known as PXE-less provisioning and involves generating a boot ISO that hosts can use. Using this ISO, the host can connect to orcharhino Server, boot the installation media, and install the operating system.

orcharhino also provides a PXE-less discovery service that operates without PXE-based services, such as DHCP and TFTP. For more information, see Implementing PXE less Discovery.

Boot ISO Types

There are the following types of boot ISOs:

Host image: A boot ISO for the specific host. This image contains only the boot files that are necessary to access the installation media on orcharhino Server. The user defines the subnet data in orcharhino and the image is created with static networking. The image is based on iPXE boot firmware, only a limited number of network cards is supported.
Full host image: A boot ISO that contains the kernel and initial RAM disk image for the specific host. This image is useful if the host fails to chainload correctly. The provisioning template still downloads from orcharhino Server.
Generic image: A boot ISO that is not associated with a specific host. The ISO sends the host’s MAC address to orcharhino Server, which matches it against the host entry. The image does not store IP address details and requires access to a DHCP server on the network to bootstrap. This image is also available from the /bootdisk/disks/generic URL on your orcharhino Server, for example, https://orcharhino.example.com/bootdisk/disks/generic.
Subnet image: A boot ISO that is not associated with a specific host. The ISO sends the host’s MAC address to orcharhino Proxy, which matches it against the host entry. The image does not store IP address details and requires access to a DHCP server on the network to bootstrap. This image is generic to all hosts with a provisioning NIC on the same subnet. The image is based on iPXE boot firmware, only a limited number of network cards is supported.

The Full host image is based on SYSLINUX and Grub and works with most network cards. When using a Host image, Generic image, or Subnet image, see supported hardware on ipxe.org for a list of network card drivers expected to work with an iPXE-based boot disk.

Host image and Full host image contain provisioning tokens, therefore the generated image has limited lifespan. For more information about configuring security tokens, read Configuring the Security Token Validity Duration.

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

Procedure

In the orcharhino management UI, navigate to Hosts > Create Host.
In the Name field, enter a name that you want to become the provisioned system’s host name.
Click the Organization and Location tabs and change the context to match your requirements.
From the Host Group list, select a host group that you want to use to populate the form.
Click the Interface tab, and on the host’s interface, click Edit.
Verify that the fields are populated with values. Note in particular:
- The Name from the Host tab becomes the DNS name.
- orcharhino Server automatically assigns an IP address for the new host.
In the MAC address field, enter a MAC address for the host.
Ensure that orcharhino Server automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
Click the Operating System tab, and verify that all fields contain values. Confirm each aspect of the operating system.
Click Resolve in Provisioning Templates to check the new host can identify the right provisioning templates to use.

For more information about associating provisioning templates, see provisioning templates.
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
Click Submit to save the host details. This creates a host entry and the host details page appears.
Download the boot disk from orcharhino Server.
- For Host image, on the host details page, click the vertical ellipsis and select Host 'My_Host_Name' image.
- For Full host image, on the host details page, click the vertical ellipsis and select Full host 'My_Host_Name' image.
- For Generic image, navigate to Infrastructure > Subnets, click Boot disk and select Generic image.
- For Subnet image, navigate to Infrastructure > Subnets, click the dropdown menu in the Actions column of the required subnet and select Subnet generic image.
Write the ISO to a USB storage device using the dd utility or livecd-tools if required.
When you start the host and boot from the ISO or the USB storage device, the host connects to orcharhino Server and starts installing operating system from its kickstart tree.

When the installation completes, the host also registers to orcharhino Server using the activation key and installs the necessary configuration and management tools from the orcharhino Client for CentOS repository.

CLI procedure

Create the host using the hammer host create command.

# hammer host create --name "My_Host_Name" --organization "My_Organization" \
--location "My_Location" --hostgroup "My_Host_Group" --mac "aa:aa:aa:aa:aa:aa" \
--build true --enabled true --managed true

Ensure that your network interface options are set using the hammer host interface update command.

# hammer host interface update --host "My_Host_Name" --managed true \
--primary true --provision true

Download the boot disk from orcharhino Server using the hammer bootdisk command:

For Host image:

# hammer bootdisk host --host My_Host_Name.example.com

For Full host image:

# hammer bootdisk host --host My_Host_Name.example.com --full true

For Generic image:
```
# hammer bootdisk generic
```

For Subnet image:

# hammer bootdisk subnet --subnet My_Subnet_Name

This creates a boot ISO for your host to use.

Write the ISO to a USB storage device using the dd utility or livecd-tools if required.
When you start the physical host and boot from the ISO or the USB storage device, the host connects to orcharhino Server and starts installing operating system from its kickstart tree.

When the installation completes, the host also registers to orcharhino Server using the activation key and installs the necessary configuration and management tools from the orcharhino Client for CentOS repository.

Creating Hosts with UEFI HTTP Boot Provisioning

You can provision hosts from orcharhino using the UEFI HTTP Boot. This is the only method with which you can provision hosts in IPv6 network.

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

Prerequisites

Ensure that you meet the requirements for HTTP booting.

Procedure

On orcharhino Proxy that you use for provisioning, update the grub2-efi package to the latest version:
```
# dnf update grub2-efi
```

Enable foreman-proxy-http, foreman-proxy-httpboot, and foreman-proxy-tftp features.

# orcharhino-installer --scenario katello \
--foreman-proxy-http true \
--foreman-proxy-httpboot true \
--foreman-proxy-tftp true

Ensure that the orcharhino Proxy has TFTP and HTTPBoot features recognized. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies and click on orcharhino Proxy to see the list of recognized features. Click Refresh Features if any of the features are missing.
Ensure that orcharhino Proxy is associated with the provisioning subnet. In the orcharhino management UI, navigate to Infrastructure > Subnets > Edit Subnet > orcharhino Proxies and select the orcharhino Proxy for both TFTP and HTTPBoot options.
Click OK to save.
In the orcharhino management UI, navigate to Hosts > Create Host.
In the Name field, enter a name for the host.
Click the Organization and Location tabs and change the context to match your requirements.
From the Host Group list, select a host group that you want to use to populate the form.
Click the Interface tab, and on the host’s interface, click Edit.
Verify that the fields are populated with values. Note in particular:
- The Name from the Host tab becomes the DNS name.
- orcharhino Server automatically assigns an IP address for the new host.
In the MAC address field, enter a MAC address of the host’s provisioning interface. This ensures the identification of the host during the PXE boot process.
Ensure that orcharhino Server automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
Click the Operating System tab, and verify that all fields contain values. Confirm each aspect of the operating system.
From the PXE Loader list, select Grub2 UEFI HTTP.
Optional: Click Resolve in Provisioning template to check the new host can identify the right provisioning templates to use.

For more information about associating provisioning templates, see creating provisioning templates.
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
Click Submit to save the host details.

For more information about network interfaces, see Adding network interfaces.
Set the host to boot in UEFI mode from network.
Start the host.
From the boot menu, select Kickstart default PXEGrub2.

This creates the host entry and the relevant provisioning settings. This also includes creating the necessary directories and files for UEFI booting the bare metal host. When you start the physical host and set its boot mode to UEFI HTTP, the host detects the defined DHCP service, receives HTTP endpoint of orcharhino Proxy with the Kickstart tree and installs the operating system.

CLI procedure

On orcharhino Proxy that you use for provisioning, update the grub2-efi package to the latest version:
```
# dnf update grub2-efi
```

Enable foreman-proxy-http, foreman-proxy-httpboot, and foreman-proxy-tftp true features:

# orcharhino-installer --scenario katello \
--foreman-proxy-http true \
--foreman-proxy-httpboot true \
--foreman-proxy-tftp true

Create the host with the hammer host create command.

# hammer host create --name "My_Host" \
--build true \
--enabled true \
--hostgroup "My_Host_Group" \
--location "My_Location" \
--mac "aa:aa:aa:aa:aa:aa" \
--managed true \
--organization "My_Organization" \
--pxe-loader "Grub2 UEFI HTTP"

Ensure the network interface options are set using the hammer host interface update command:

# hammer host interface update \
--host "My_Host" \
--managed true \
--primary true \
--provision true

Set the host to boot in UEFI mode from network.
Start the host.
From the boot menu, select Kickstart default PXEGrub2.

Deploying SSH Keys During Provisioning

Use this procedure to deploy SSH keys added to a user during provisioning. For information on adding SSH keys to a user, see Managing SSH Keys for a User in Administering orcharhino.

Procedure

In the orcharhino management UI, navigate to Hosts > Provisioning Templates.
Create a provisioning template, or clone and edit an existing template. For more information, see creating provisioning templates.
In the template, click the Template tab.
In the Template editor field, add the create_users snippet to the %post section:
```
<%= snippet('create_users') %>
```
Select the Default checkbox.
Click the Association tab.
From the Application Operating Systems list, select an operating system.
Click Submit to save the provisioning template.
Create a host that is associated with the provisioning template or rebuild a host using the OS associated with the modified template. For more information, see Creating a Host in Managing Hosts.

The SSH keys of the Owned by user are added automatically when the create_users snippet is executed during the provisioning process. You can set Owned by to an individual user or a user group. If you set Owned by to a user group, the SSH keys of all users in the user group are added automatically.

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