New feature in Satellite 6.1.5: PXE-less discovery

This article was originally published on the Red Hat Customer Portal. The information may no longer be current.

Provisioning in PXE-less or DHCP-less environments is a common scenario in the enterprise and Satellite 6 offered Bootdisk plugin to solve this problem partially. The Satellite 6.1.5 feature erratum introduces PXE-less discovery which is a great alternative with much broader hardware support.

Starting today, it is possible to boot provisioned hosts from the Discovery image directly as a CDROM/DVDROM ISO that can be also transferred to hard drive or USB stick. Since the Discovery image is based on Red Hat Enterprise Linux 7, it supports all kinds of hardware that was certified to work with it. Once the host is discovered, provisioning will be initiated remotely from the Satellite 6 web interface (or automatically via discovery rules). Instead of rebooting, the kernel on the discovered node will be reloaded live (via kexec tool) into Anaconda.

Thanks to a new text-based user interface, several new provisioning workflows are possible:

Provisioning without PXE/DHCP

• Setup auto-provisioning rules (optional)
• Transfer the ISO image onto an USB stick or CDROM and boot it.
• Select manual network setup
• Select primary (provisioning) interface if the host has multiple NICs
• Enter IPv4 credentials
• Enter Satellite Capsule endpoint credentials (hostname, port)
• Provide custom facts (optional) and click on Confirm
• The host is discovered
• The host reloads kernel into installer either manually or via auto-provisioning

Provisioning with DHCP (no PXE)

• Transfer the ISO image onto an USB stick or CDROM and boot it.
• Select Discover with DHCP
• Select primary (provisioning) interface if the host has multiple NICs
• Enter Satellite Capsule endpoint credentials (hostname, port)
• Provide custom facts (optional) and click on Confirm
• The host is discovered
• The host reloads kernel into installer either manually or via auto-provisioning

Semi-automated workflow w/o PXE/DHCP

• Re-master (modify) the discovery image ISO with network credentials and Capsule endpoint
• Transfer the ISO image onto an USB stick or CDROM and boot it.
• Select primary (provisioning) interface if the host has multiple NICs
• Enter IPv4 credentials (gateway and DNS is already populated)
• Select primary (provisioning) interface
• Enter Satellite Capsule endpoint credentials (hostname, port)
• Provide custom facts (optional) and click on Confirm
• The host is discovered
• The host reloads kernel into installer either manually or via auto-provisioning

Fully automated workflow w/o PXE/DHCP

• Modify the discovery ISO and set all required options including MAC and IP address
• Make sure the fdi.pxauto option is set to 1
• Transfer the ISO image onto an USB stick or CDROM and boot it.
• The host is discovered without any user interaction
• The host reloads kernel into installer either manually or via auto-provisioning

Preparing the environment

First of all, make sure Foreman Discovery plugin, Foreman Discovery Image and Smart Proxy Discovery Plugin are all upgraded both on Satellite 6 Server and all Capsules. Expected versions must be equal or higher than:

• ruby193-rubygem-foreman_discovery-2.0.0.23-1
• foreman-discovery-image-3.0.5-3
• rubygem-smart_proxy_discovery-1.0.3-2

All discovered nodes must be rebooted after upgrade because there was a change in the discovery REST API, therefore communication with old discovered nodes could fail.

Creating such a media is easy, make sure all capsules are updated and transfer the image to USB stick:

capsule$ rpm -ql foreman-discovery-image
/usr/share/foreman-discovery-image
/usr/share/foreman-discovery-image/fdi-image-rhel_7-2.1.0-2015XXYY.Z.iso

workstation$ scp root@capsule:/usr/share/foreman-discovery-image/fdi-image-rhel_7-2.1.0-2015XXYY.Z.iso .
workstation$ dd if=fdi-image-rhel_7-2.1.0-2015XXYY.Z.iso of=/dev/sdX

All Operating Systems which are supposed to work with PXE-less provisioning must be associated with the new Red Hat Kexec template that now ships with Satellite 6. Associate it with all Operating Systems in Provisioning Templates and then select it as the default one for each individual Operating System via Edit screen.

Ordinary (PXE) usage

Nothing changed in the traditional PXE-based discovery, except the new text-user interface. Initial countdown is shown where the process can be interrupted entering the PXE-less interactive menu. 

Once the node is discovered, status screen is available with some info. Reported facts can be listed, system log investigated and SSH daemon can be enabled to be able to log in remotely (it is disabled by default).

Attended usage

Thank to the new user interface, the usage is straighforward. Once the node is booted up from the media, select appropriate option to configure IPv4 manually, or use DHCP. Select primary interface if there are more than one found. Network cards with a link has "link up" tag. Network cards which were PXE-booted has "pxebooted" flag. Enter network credentials. The IPv4 address must be in the CIDR notation (1.2.3.4/N) with valid netmask. Enter Satellite 6 Server or Capsule endpoint. When connecting to Canspule (recommended), the default port is 9090 and connection type is Proxy. For Server, the default port is 443 and connection type is Server. Provide optional facts to be reported with this node. These facts can be used to trigger auto-provisioning rules, so typical usage is something like "deployment_type" or "security_token". Enter "discovery_organization" and/or "discovery_location" to assign taxonomy to the discovered node.

The node is registered and awaiting orders. Note the "kexec" word in the status line. This node will send "discovery_kexec" fact which tells Satellite 6 Server to order kexec command instead of reboot during provisioning.

Unattended usage

All interactive screens can be partially or fully automated via kernel command line that can be either entered during SYSLINUX/Grub2 boot screen or burnt into the image (using re-master script - shown below). Options are self-explanatory:

• proxy.url=https://capsule:9090
• proxy.type=proxy
• fdi.pxmac=aa:bb:cc:dd:ee:ff
• fdi.pxip=192.168.122.42/24
• fdi.pxgw=192.168.1.1
• fdi.pxdns=192.168.1.1
• fdi.pxfactname1=security-token
• fdi.pxfactvalue1=987123
• fdi.pxfactname2=deployment
• fdi.pxfactvalue2=db-server
• fdi.pxfactnameN=
• fdi.pxfactvalueN=

When px.ip and/or px.gw are omitted, image tries to acquire network credentials via DHCP, which can be useful in PXE-less environments with DHCP server deployed. Therefore the absolute minimum set of options in this case is:

• proxy.url=https://capsule:9090
• proxy.type=proxy
• fdi.pxmac=aa:bb:cc:dd:ee:ff

The pxmac option defines the provisioning interface to be used to acquire network credentials (optionally) and send facts. If omitted in unattended mode, the first NIC with link is picked up (in alphabetical order by network identifier in case of multiple items). In semi-automated mode, screen will appear to select the correct interface.

All values must be confirmed in the text-user interface first, which gives semi-automatic behavior. To initiate the provisioning without any question (unattended mode or fully automatic), add the following option:

• fdi.pxauto=1

When fdi.pxauto is not provided, Ok/Next buttons are always focused first on all screens therefore it is easier to walk through all screens.

Re-mastering the image

A helper script called discovery_remaster is currently not being shipped with Satellite 6. Until it is shipped, download it from: https://github.com/theforeman/foreman-discovery-image/blob/master/aux/r…

Usage is simple, accepted values are described above.

sudo discovery-remaster ISO_IMAGE "fdi.pxip=192.168.100.68/24 fdi.pxgw=192.168.100.1 fdi.pxdns=192.168.100.1 proxy.url=https://192.168.100.1:9090 proxy.type=proxy fdi.pxfactname1=myfact fdi.pxfactvalue1=somevalue fdi.pxmac=52:54:00:be:8e:8c fdi.pxauto=1"

The above command creates a copy in the same directory with date/time stamp in the name.

Troubleshooting

PXE-less node reboots instead kexec

Check if the Operating System that was used for provisioning is associated with Red Hat Kexec template. Without this association, Satellite 6 falls back to normal reboot which will not start provisioning process, but again boot from the media.

Error 404 when rebooting a discovered node

There was a change in the REST API on the discovery image, reboot and re-discover the node before initiating provisioning. Also check if package versions match as described in this article.

Discovered host is PXE-booting interactive

Make sure IPAPPEND 2 option is provided in the PXELinux global default template. Discovery image expects BOOTIF kernel option and if it's not present, it goes into interactive mode.

Endpoint is reported as N/A after discovery

After PXE-less discovery, endpoint on the overall status screen is not shown and appear as N/A. It only displays incorrect, it was configured properly. We track this bug as https://bugzilla.redhat.com/show_bug.cgi?id=1285980

Race condition with DHCP

In some circumstances when DHCP initialization is slow, a discovered node may attempt to register itself before the network is up. This can lead to race condition. Use Resend button or restart foreman-proxy and discovery-register services from the console. This issue is tracked as bug https://bugzilla.redhat.com/show_bug.cgi?id=1262950

RHEL6 Anaconda console is frozen

After kexec into RHEL6 kernel, the Anaconda operates normally, but there is no ouput as the console is frozen. Wait until provisioning finishes and reboot into the newly installed system. If the system does not reboot, there might be error in the kickstart. Try to provision the host normally with the same host or hostgroup options first.

Generic errors

When an error appears during interactive mode, the root account will be unlocked with a random password. Use tty2 to investigate system journal and tty3 to log in and call discovery-debug script which will create an output that can be copypasted for futher investigation.