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
Since the bootable image runs from memory, keep in mind the following minimum requirements on the hardware that is being discovered:
- 700 MB RAM for the CentOS image
- 900 MB RAM for the Fedora image
When testing those images on virtual machines, make sure they have allocated enough memory, otherwise kernel panic can be seen during boot sequence.
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.
| Foreman Version | Plugin Version | oVirt 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 |
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"
The image is based on CentOS 6 & Fedora 18 (there is an image for each) and it leverages the oVirt Node open-source project. The download site provides stable releases as well as nightly builds for those who want to live on the edge, or alternatively a local image can be rebuilt by the user.
The recommended option is to download a prebuilt image from the Foreman repositories.
Nightly builds have the ssh daemon enabled and root password set to "redhat"; logging is also increased. Conversely, releases have the root account locked and there is no ssh access. Note that the first console (tty1) is reserved for Discovery output. For a login prompt (nightly images only) use tty2.
As of Foreman 1.6, the foreman-installer is able to automatically download latest stable CentOS6 images. For this, re-run the installer with the following option:
# foreman-installer --foreman-plugin-discovery-install-images=true
Images are available from:
A choice of using an ISO or a kernel/initrd pair is available.
Kernel/initrd (recommended):
- ovirt-node-iso-3.X.0-0.999.201404XXXXXX.el6.iso-img
- ovirt-node-iso-3.X.0-0.999.201404XXXXXX.el6.iso-vmlinuz
or ISO file:
- ovirt-node-iso-3.X.0-0.999.201404XXXXXX.el6.iso
When downloading the ISO file, it must be extracted before proceeding:
# yum -y install livecd-tools
# ln -sf ovirt-node-iso-3.X.0-0.999.201404170648.el6.iso foreman.iso
# sudo livecd-iso-to-pxeboot foreman.iso
# find tftpboot/
tftpboot/
tftpboot/vmlinuz0
tftpboot/pxelinux.0
tftpboot/pxelinux.cfg
tftpboot/pxelinux.cfg/default
tftpboot/initrd0.img
Once the initrd/vmlinuz pair (whether from direct download or from ISO extraction) is available, copy them to the TFTP BOOT directory and rename them to vmlinuz0 and initrd0.img.
To build a discovery image, please visit the ovirt-node-plugin-foreman page for further instructions.
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:
LABEL discovery
MENU LABEL Foreman Discovery
MENU DEFAULT
KERNEL boot/tftpboot/vmlinuz0
APPEND rootflags=loop initrd=boot/tftpboot/initrd0.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 nomodeset selinux=0 stateless foreman.url=https://foreman.example.com
IPAPPEND 2
to the end of the file. Note the foreman.url option on the APPEND line,
which defines where foreman instance is. Make sure this is set correctly or
discovered hosts will not register to Foreman. 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 (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.
An example complete PXELinux global default template for Discovery might look like this:
DEFAULT menu
PROMPT 0
MENU TITLE PXE Menu
TIMEOUT 200
TOTALTIMEOUT 6000
ONTIMEOUT discovery
LABEL discovery
MENU LABEL Foreman Discovery
KERNEL boot/tftpboot/vmlinuz0
APPEND rootflags=loop initrd=boot/tftpboot/initrd0.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 nomodeset selinux=0 stateless foreman.url=https://foreman.example.com
IPAPPEND 2
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->Discovery Settings
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.
Boot a machine using the new PXE config above. It should register with Foreman.
The new Host should show up in More->Provisioning->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.
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.
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/defaulthas the right config as above
- check your
- Machine booted image but failed to contact Foreman
- Check the
foreman.urloption inpxelinux.cfg/defaultis 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
- Check the
When working with production images (no root password set), it is still possible to log on as root. Generate some root password:
$ openssl passwd -salt RH redhat
RHhwCLrQXB8zE
And then provide it as an kernel command line option:
... stateless rootpw=RHhwCLrQXB8zE
see the API README
We use RedMine instance instead of github.com issues. Please report issues there.
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.
- Support for downloading shell script for oVirt Node image
- Add more Tests
- Add proper Location/Organization handling (via a Wizard maybe?)
- Add per-subnet discovery
- Rake Task for ISO build
- Easy way to add custom facts to build/runtime
Copyright (c) 2012-2013 Greg Sutcliffe
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/.