foreman_discovery

This plugin enables MaaS hardware discovery in Foreman. There are two artifacts (and terms) used in this document:

  • foreman_discovery plugin - software installed in Foreman that adds Discovered Hosts menu entry, API and required configuration
  • discovery image - net-bootable image that needs to be installed in the TFTP server and configured in Foreman for new (unknown) hosts to boot from over PXE

Minimal hardware requirements

Since the bootable image runs from memory, keep in mind the minimum requirement of 500 MB RAM otherwise kernel panic can be seen during boot sequence.

Installation (plugin)

Please see the Foreman wiki for appropriate instructions:

The gem name is "foreman_discovery".

RPM users can install the "ruby193-rubygem-foreman_discovery" or "rubygem-foreman_discovery" packages.

Compatibility

Foreman Version Plugin Version Image Version
<= 1.2 1.0.2 N/A
= 1.3 1.1.0 0.1.0
= 1.4 1.2.0 0.3.0-1
= 1.5 1.3.0 0.5.0-1
>= 1.6 1.4.0 0.6 or 2.0

Latest code

If a source-based install of Foreman is in use, the develop branch of the plugin can be obtained by updating the Gemfile in this way:

gem 'foreman_discovery', :git => "https://github.com/theforeman/foreman_discovery.git"

Installation (image)

The image is based on CentOS 7 and about 150 MB in size. The recommended option is to download a prebuilt image from the Foreman repositories.

Downloading an image

Download via installer

As of Foreman 1.6, the foreman-installer is able to automatically download latest stable image. For this, re-run the installer with the following option:

# foreman-installer \
    --enable-foreman-plugin-discovery \
    --foreman-plugin-discovery-install-images=true

Manual download

Images are available from:

To download the latest release to the expected location, do the following:

# wget http://downloads.theforeman.org/discovery/releases/latest/fdi-image-latest.tar \
  -O - | tar x --overwrite -C /var/lib/tftpboot/boot

After download, verify checksums:

# cat /var/lib/tftpboot/boot/fdi-image/SHA256SUM
beb3cfba7d9fb9d71481c0c8f... initrd0.img
f03bce150d2473a28697d2988... vmlinuz0
# sha256sum /var/lib/tftpboot/boot/fdi-image/*

Building an image

To build a discovery image, please visit the foreman-discovery-image git repository and find the README for further instructions.

Configuration (image)

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

In the Foreman UI, go to Provisioning Templates, edit PXELinux global default template and add the following after the "LABEL local" block of options:

LABEL discovery
MENU LABEL Foreman Discovery
MENU DEFAULT
KERNEL boot/fdi-image/vmlinuz0
APPEND initrd=boot/fdi-image/initrd0.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=http://xyz proxy.type=proxy
IPAPPEND 2

The proxy.type option can be either proxy or foreman. In the first case all communication goes through Smart Proxy, in the latter case the communication goes directly to Foreman (legacy mode). This is the default when not specified.

The proxy.url specifies URL of the Smart Proxy or Foreman depending on the previous setting. Both http and https schemes are supported. For backward compatibility, foreman.url is an alias for this setting.

Once the APPEND line is modified properly, set the entry to be default via 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 (see the example for ISC BIND below), then it is not required to provide foreman.url at all.

_x-foreman._tcp SRV 0 5 443 foreman

This can still be overriden with the command line opts.

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. Without this line, DNS will not work properly as well.

It is important to know that DNS servers from DHCP are enabled only for the interface that was specified via the BOOTIF option. This means when a system have multiple NICs, DNS will work for the correct interface - the one that was booted from.

Warning: For now, the selinux=0 option must be provided, the image is read only anyway but we plan to enable and test with SELinux too.

Updating the on-disk default file

Once the template has been updated, click the Build PXE Default button at the top of the Provisioning Templates page. This will instruct the TFTP proxy to rewrite the pxelinux.cfg/default file.

Configuration (plugin)

No configuration of the plugin in the Foreman UI is required, but some configuration is available.

If Locations and/or Organisations are enabled, Foreman will default to using the first Location and first Organisation for Discovered hosts. If hosts should be placed in some other Location/Organization, alter the default Loc/Org in More->Settings->Discovered

There is also setting called discovery_fact which defaults to discovery_bootif which specifies which incoming fact should be used to get the MAC address. By default PXELinux BOOTIF kernel command line option is used which gives a MAC address of the interface which was booted from. Make sure the IPAPPEND 2 option is set correctly in the Foreman template.

Usage

Boot a machine using the new PXE config above. It should register with Foreman. The new Host should show up in Hosts->Discovered Hosts. Then 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. Fill in the details as normal.

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.

Permissions

The plugin will create a Role called Discovery when first started. This can be assigned to roles for non-admins to allow them to use the discovery plugin. Alternatively assign the :perform_discovery permission to an existing Role.

Troubleshooting

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

  • Machine did not boot the correct image
    • check your pxelinux.cfg/default has the right config as above
  • Machine booted image but failed to contact Foreman
    • Check the foreman.url option in pxelinux.cfg/default is correctly defined
    • Check DNS is working for that image, or use an IP in foreman.url
    • Check DHCP is handing IPs to the booted image correctly

To log in the running image you need to set root password which is locked by default. In addition, you can enable ssh server as well. To do this, provide the following kernel command line options:

APPEND ... fdi.ssh=1 fdi.rootpw=redhat

API

see the API README

Reporting bugs

We use RedMine instance instead of github.com issues. Please report issues there.

Grace Note: Testing

If you only wish to test the plugin code itself, you don't need to create the PXE boot image above, or have a TFTP server to run it from. Simply POST a hash of Host Facts to /api/v2/discovered_hosts/facts to create a Discovered Host in the UI.

Copyright

Copyright (c) 2012-2014 Greg Sutcliffe and The Foreman developers

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.