Red Hat Training

A Red Hat training course is available for Red Hat Satellite

Chapter 11. Discovering Bare-metal Hosts on Satellite

Red Hat Satellite 6.2 ships with the Discovery plug-in already installed. The Discovery plug-in enables automatic bare-metal discovery of unknown hosts on the provisioning network. These new hosts are registered to the Satellite Server and the Puppet agent on the client uploads system facts collected by Facter, such as serial ID, network interface, memory, and disk information. After registration, the hosts are displayed on the Discovered Hosts page in the Satellite web UI. You can then initiate provisioning either manually (using the web UI, CLI, or API) or automatically, using predefined discovery rules.
The Discovery plug-in communicates through the Satellite Capsule Server, which has direct access both to the provisioning network and the Satellite Server instance. It is possible to discover hosts directly from the Satellite Server, but Red Hat recommends the following scheme be used: 
Satellite Server (Satellite Server Discovery plug-in) <--> Satellite Capsule (Satellite Capsule Discovery plug-in) <--> Discovered Host (Satellite Discovery image)
The Satellite Discovery plug-in consists of three different components:
The Satellite Server Discovery plug-in
This runs on the Satellite Server and provides API and UI functionality for working with discovered hosts. The tfm-rubygem-foreman_discovery package contains this plug-in.
The Satellite Capsule Server Discovery plug-in
This is a communication proxy between discovered hosts on a provisioning network and the Satellite Server. The rubygem-smart_proxy_discovery package contains this plug-in.
The Satellite Discovery image
This is the minimal operating system based on Red Hat Enterprise Linux that is PXE-booted on hosts to acquire initial hardware information and to check in to the Satellite Server. Discovered hosts keep running the Satellite Discovery image until they are rebooted into Anaconda, which then initiates the provisioning process. The foreman-discovery-image package contains this image. It must be installed on the Satellite Capsule Server that provides TFTP services.

11.1. Configuring the Satellite Discovery Plug-in

The following sections describe how to configure the Satellite Discovery plug-in and how to prepare the PXE-boot template on the Satellite Server.

11.1.1. Deploying the Satellite Discovery Image

Install the package containing the Satellite Discovery image on the Satellite Capsule Server that provides TFTP services (not on the Satellite Server itself): 
# yum install foreman-discovery-image
This package contains the Linux kernel and initial RAM disk image as a bootable ISO file which is used for PXE-booting discovered hosts. You can run the following command to investigate the contents of the package. This produces output similar to the following: 
$ rpm -ql foreman-discovery-image
/usr/share/foreman-discovery-image
/usr/share/foreman-discovery-image/fdi-image-rhel_7-2.1.0-20150212.1.iso
When you install this package, it extracts the kernel and image from the ISO file into the TFTP directory and creates symbolic links to the latest versions of the image and kernel. Use the symbolic links in the PXE-boot provisioning template to make sure that you do not need to change the version in the template every time the foreman-discovery-image package is upgraded. For example: 
$ find /var/lib/tftpboot/boot
/var/lib/tftpboot/boot
/var/lib/tftpboot/boot/fdi-image-rhel_7-2.1.0-20150212.1-img
/var/lib/tftpboot/boot/fdi-image-rhel_7-2.1.0-20150212.1-vmlinuz
/var/lib/tftpboot/boot/fdi-image-rhel_7-img
/var/lib/tftpboot/boot/fdi-image-rhel_7-vmlinuz
The last two lines in the above output contain symbolic links to be used in the PXE-boot provisioning template. For more information see Section 11.1.2, “Configuring PXE-booting”.

Note

Currently, only Red Hat Enterprise Linux 7 Discovery images are provided, even for Satellite 6 installations on Red Hat Enterprise Linux 6. If there are discovered hosts running during the upgrade of the foreman-discovery-image package, reboot them all to load the updated version of the image as soon as possible. This can be done through the Satellite 6 web UI, CLI, or API.

11.1.2. Configuring PXE-booting

When an unknown host is booted on the provisioning network, the Satellite Server provides a PXELinux boot menu with a single option; to boot from the local hard drive. The following procedure describes how to change this behavior in order to enable hardware discovery. This requires changing several variables in the PXE Linux global default template. These variables are described below:
  • The KERNEL and APPEND lines in the template use symbolic links, created when installing the foreman-discovery-image package (see Section 11.1.1, “Deploying the Satellite Discovery Image”). The URLs are relative to the /var/lib/tftpboot/ directory. Ensure the APPEND parameters are specified on a single line.
  • The proxy.type variable can be set to either proxy (recommended) or foreman. When the variable is set to proxy, all communication goes through the Satellite Capsule Server. When the variable is set to foreman, the communication goes directly to Satellite Server. Examples in this chapter assume proxy.type is set to proxy.
  • The proxy.url variable specifies the URL of the Satellite Capsule Server or Satellite Server, depending on the proxy.type setting. Both HTTP and HTTPS schemes are supported. The default port is 9090 for accessing the Satellite Capsule Server (proxy.type=proxy), and 80 for for direct communication with the Satellite Server (proxy.type=foreman).
  • The IPAPPEND 2 setting detects interfaces connected to the provisioning network. The image will not boot correctly if this option is removed or modified.

Procedure 11.1. To Configure PXE-booting:

  1. In the Satellite web UI, navigate to Hosts → Provisioning Templates.
  2. Edit the PXELinux global default template. Add the following menu entry to the template: 
    LABEL discovery
MENU LABEL Foreman Discovery
MENU DEFAULT
KERNEL boot/fdi-image-rhel_7-vmlinuz
APPEND initrd=boot/fdi-image-rhel_7-img rootflags=loop root=live:/fdi.iso rootfstype=auto ro rd.live.image acpi=force rd.luks=0 rd.md=0 rd.dm=0 rd.lvm=0 rd.bootif=0 rd.neednet=0 nomodeset proxy.url=https://SATELLITE_CAPSULE_URL:9090 proxy.type=proxy
IPAPPEND 2
  3. Set the new menu entry to be the default by modifying the ONTIMEOUT variable: 
    ONTIMEOUT discovery
  4. Click Build PXE Default at the top of the Provisioning Templates page. This instructs the TFTP proxy to rewrite the pxelinux.cfg/default file. Repeat this step every time a change is made to the default template to ensure that the changes are deployed on the TFTP Satellite Capsule Server.
As an alternative to the above procedure, you can omit the proxy.url variable from the PXE-boot template. In this case, the Discovery image searches the DNS configuration file for an SRV record named x-foreman.tcp. The proxy.url variable must be set to proxy in this case. The DNS server must also be suitably configured. For example, the following configuration statement specifies the Capsule Server to be used with HTTPS: 
_x-foreman._tcp SRV 0 5 9090 capsule
Here, capsule is the name of the Capsule Server that is included in the DNS configuration.

Note

Satellite 6.2 only allows you to specify one Capsule Server URL for all subnets where hosts can be discovered. Because templates cannot be used per subnet, use a DNS alias name on all networks. Alternatively, use an SRV record.

Important

The DNS servers from the DHCP settings are taken into account only for the interface that is specified via the BOOTIF variable. BOOTIF is set automatically by the IPAPPEND variable in the PXE template. This means that when a system has multiple NICs, DNS will only work for the interface that it was booted from.

11.1.3. Reviewing Global Discovery Settings

You can review global settings related to the Discovery plug-in in the Satellite web UI. Navigate to Administer → Settings and open the Discovered tab. Notable settings are:
discovery_organization, discovery_location
These variables specify where to place the discovered hosts. By default, the discovered hosts are automatically placed under the first organization and location created.
discovery_fact
This variable specifies which incoming fact to use to determine the MAC address of the discovered host. By default, the PXELinux BOOTIF kernel command line option is used.
discovery_auto
This variable enables automatic provisioning according to specified rules. Set to false by default. Red Hat recommends that you test the configuration with manual provisioning before enabling discovery_auto. See Section 11.3, “Provisioning Discovered Hosts” for more information.
discovery_fact_column
This variable allows you to add any fact reported by Facter as an additional column in the list of discovered hosts.