Satellite 6.0 features automatic bare-metal discovery which is implemented as a PXE-boot live image with minimized Red Hat Enterprise Linux that is running from memory. Once Satellite 6.0 is configured to boot the discovery image for all unknown hosts, new nodes calls home during the start and wait until they are provisioned.

Installation and Setup

Before we start setting up the plugin and the image, verify the following prerequisites are met:

1. Satellite 6.0.5 with bare-metal provisioning setup.
2. At least one Capsule with DHCP and TFTP services enabled.
3. Host(s) to be discovered with at least 1 GB RAM.

First of all we need to be sure that the discovery plugin is installed and enabled on the target Satellite 6.0 host. It should be installed by default if Satellite 6.0 installer was executed already on the host:

# rpm -q ruby193-rubygem-foreman_discovery
ruby193-rubygem-foreman_discovery-1.3.0-2.el6sat.noarch

The discovery image resides in foreman-discovery-image package.

# yum -y install foreman-discovery-image
# rpm -ql foreman-discovery-image
/usr/share/foreman-discovery-image
/usr/share/foreman-discovery-image/foreman-discovery-image-6.5-20140620.2.el6sat.iso

The package itself contains ISO image and during installation linux kernel and initial RAM disk image are extracted to the TFTP directory:

# ls /var/lib/tftpboot/boot/foreman*
/var/lib/tftpboot/boot/foreman-discovery-image-latest.el6.iso-img
/var/lib/tftpboot/boot/foreman-discovery-image-latest.el6.iso-vmlinuz

Some versions of the image have “el6” in the filename while newer versions might be named just “latest.iso-img”. Note the above filenames, we will need them later on.

Before you proceed with the Discovery plugin setup, make sure the bare metal provisioning works. Refer to the chapter 9 in the Red Hat Satellite 6.0 User Guide named Configuring the Provisioning Environment. To test bare-metal provisioning, create a new host entry with MAC address and power on a server to provision it. With the Discovery plugin, the host creation will be automated.

The Discovery pluginrelies on intercepting the normal boot process for machines not registered in Satellite 6. To achieve this, the PXE default.cfg file needs to be altered to instruct new machines to boot the discovery image.

A prerequisite is that the network's DHCP server can serve unknown clients and that it points those clients to the TFTP server from which they will load the discovery boot image. If you installed your ISC DHCP via our capsule-installer on Red Hat Enterprise Linux, this works out-of-box. When using different configuration or different DHCP server, make sure your “next-server” configuration option is properly configured to return the proper TFTP server which is under Red Hat Satellite’s control.

Satellite 6.0 has a template locking capability which prevents some templates from being edited or renamed because the application relies on their presence and name. Due to bug (RHBZ#1142160 to be fixed in 6.1) the locked default PXELinux template prevents from setting up Discovery. As a workaround, start Rails console on the Satellite node and execute the following statement:

# foreman-rake console
> ct = ConfigTemplate.find_by_name("PXELinux global default"); ct.locked = false; ct.save!
> exit

In the Satellite 6 user interface, go to Provisioning Templates, edit the PXELinux global default template and add a new menu entry:

LABEL discovery
MENU LABEL Foreman Discovery
MENU DEFAULT
KERNEL boot/foreman-discovery-image-latest.el6.iso-vmlinuz
APPEND rootflags=loop initrd=boot/foreman-discovery-image-latest.el6.iso-img root=live:/foreman.iso rootfstype=auto ro rd.live.image rd.live.check rd.lvm=0 rootflags=ro crashkernel=128M elevator=deadline max_loop=256 rd.luks=0 rd.md=0 rd.dm=0 rd.bootif=0 rd.neednet=0 nomodeset selinux=0 stateless foreman.url=FOREMAN_URL
IPAPPEND 2

Note the foreman.url option on the APPEND line, which defines where foreman instance is. For 6.0 release, you can't use foreman_url variable and you need to hardcode the value in the template. Then make this the default by altering the ONTIMEOUT option:

ONTIMEOUT discovery

Alternatively, the Discovery image also searches for DNS SRV record named _x-foreman._tcp. If the DNS server is configured for this, then it is not required to provide foreman.url at all, otherwise it would override the DNS SRV record. Example configuration for ISC DNS server:

_x-foreman._tcp SRV 0 5 443 foreman

It is important to have IPAPPEND 2 option which adds BOOTIF=MAC option which is then reported via facter as discovery_bootif which is key fact which is used for provisioning. It is expected that the interface which was booted from will be the provisioning interface as well. Also, the same interface will be used as the primary interface and will be used to retrieve DNS configuration from DHCP.

Also note that the Discovery plugin in Satellite 6.0 does not support SELinux yet, therefore option selinux=0 must be provided. The image is read only, but we plan to add full SELinux support for the discovery images as well.

Once the template has been edited, important step is to click on Build PXE Default button on the Provisioning Templates page which will deploy the configuration file on the TFTP server.

Basic usage

The workflow with Satellite 6.0 Discovery plugin is simple. Once an unknown host is booted, it reports and registers with Satellite 6. The new Host should show up in More>Provisioning>Discovered Hosts menu. When you want to use the host, select a Discovered Host and choose Provision. This will redirect to the normal Edit page for a Host, with the discovered data filled in where possible (MAC address for example). Fill in the details as normal and on save, a reboot is sent to the discovered host, after which it should reboot into the installer for the chosen OS, and finally into the installed OS. Delete a machine and reboot it to have it move back to the Discovery Pool.

Troubleshooting

If the booted machine fails to register with Satellite 6, then there are a number of common causes:

1. Machine did not boot the correct image: check your /var/lib/tftp/pxelinux.cfg/default has the right config as above
2. Machine booted image but failed to contact Foreman: check the foreman.url option on the kernel command line. Check DNS is working for that image, or use an IP in foreman.ip. Check DHCP is handing IPs to the booted image correctly
3. Root account is locked on the image and ssh access is disabled, but there is still possibility to log on on the terminal. You need to provide rootpw option on the kernel command line. To generate salted password use

$ openssl passwd -salt RH redhat
RHhwCLrQXB8zE