foreman_discovery
This plugin aims to enable MaaS hardware discovery in Foreman. It is of alpha quality right now ;)
Dependencies
- Foreman >= 1.2.0
Installation
Require the gem in Foreman.
bundler.d/Gemfile.local.rb:
gem 'foreman_discovery'
If you want to use the very latest code, use a git gem:
gem 'foreman_discovery', :git => "https://github.com/theforeman/foreman_discovery.git"
Update & Restart Foreman:
bundle update
Building the Discovery PXE Image
There is a rake task for the discovery image. It requires Ruby 1.8, but should appropriately detect and use ruby1.8 even if the system default is 1.9. If you have trouble building it, try a ruby1.8-only system.
Run this in the Foreman app root:
rake discovery:build_image
You image will be in ./discovery_image. Run the rake task as root, or with passwordless sudo, as the password prompts may get lost in the ruby->bash forking process.
Configuration
Image configuration
The PXE image has two configuration options during build:
- By default it will have an automatic login to the 'tc' user and start ssh so you can
ssh to
tc@<ip>
with password test1234. By specifyingmode=prod
on the rake task, you can disable both of these - the image will have no accounts that can be logged in - If you need to add additional files to the image, put them in
./additional_build_files/
- these will be copied to/additional_build_files/
in the image
Also, it will attempt todownload /discovery_init.sh
from your Foreman server and run
it. This is entirely optional - if the server cannot be reached or the file cannot be
found, the image has a fallback script built in.
You can find an example script here - place your
modified version in the public/
directory on your Foreman server.
PXE config
Configure the PXE default to boot the Discovery Image built above, eg:
DEFAULT menu
PROMPT 0
MENU TITLE PXE Menu
TIMEOUT 200
TOTALTIMEOUT 6000
ONTIMEOUT discovery
LABEL discovery
MENU LABEL Boot Discovery
TEXT HELP
Boot the Foreman Discovery Image
Use TAB to edit options for specific needs.
ENDTEXT
KERNEL /boot/TinyCore-vmlinuz
APPEND initrd=/boot/TinyCore-initrd.gz foreman.ip=192.168.122.1:3000
Be sure to alter the foreman.ip appropriately. You can also use foreman.server to
specify a DNS record (foreman.server=myforemanhost
) but in this case the port will
be assumed to be http (80). If all else fails (say, USB boot where we can't provide
options) it will look for a DNS record of foreman
Known Issues with the image
On some multi-core systems the TinyCore kernel may segfault on boot with an error message similar to :
"Fixing recursive fault but reboot is needed!"
If this happens, it can be fixed by changing the KERNEL line in the PXE config above to read :
KERNEL /boot/TinyCore-vmlinuz maxcpus=1
More information on the maxcpus kernel parameter can be found at https://www.kernel.org/doc/Documentation/kernel-parameters.txt
A currently unavoidable side effect of this setting is that the initial facts gathered during discovery will only show a single processor, since that is all that is visible to the kernel.
UI config
No configuration of the Foreman UI is required. If you are using Locations and/or Organisations,
Foreman will default to using the first Location and first Organisation for Discovered
hosts. If you wish to place them in some other Location/Organization, you can alter the
default Loc/Org in More->Settings->Discovery Settings
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
/fact_values/create?type=Host::Discovered
.The
script
in my PXE image that does this can be used as an example.
The uploaded hash will appear as a discovered host, and provisioning it should work.
Usage
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. You'll be taken 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. You can assign
this role to non-admins to allow them to use the discovery plugin. Alternatively
assign the :perform_discovery
permission to an existing Role.
TODO
- Add more Tests
- Add API
- 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
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/.