Discovery Plugin

This guide describes how to install the discovery-plugin into orcharhino.

The discovery-plugin is used to provision already existing hosts. This can be very useful, when orcharhino is not able to create the hosts itself.

The discovery-plugin provides an additional option to the default network-boot-menu, which orcharhino provides for the networks it manages. When network-booting a host, select Foreman Discovery Image. This will boot a linux-system, which automatically sends facts about the system to orcharhino. These facts can be used to initiate an automatic provisioning of the host.

Installation

The following command installs the discovery-plugin on orcharhino and also installs the necessary fdi-boot-image.

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

On a Smart Proxy use:

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

Usage on Hosts

For hosts to be discovered by the plugin, they have to boot the Foreman Discovery Image. This image will automatically be added to the default network-boot-menu.

Discovery Boot Menu

Important

Hosts already managed by orcharhino might not have this boot-menu-entry. This is due to orcharhino creating a custom network-boot-menu for the managed hosts.

Note

Keep in mind that the host has to receive it’s IP address from orcharhino’s DHCP server to be able to boot from network. If the Foreman Discovery Image entry is not present, you might have to re-generate the default-menu by clicking Build PXE Default on the Provisioning Templates page. If network-boot is not an option, the Discovery Image can also be downloaded as an ISO-image from: http://downloads.theforeman.org/discovery/releases/latest/

Without intervention, the host configures the network interface via DHCP and automatically sends system-information to orcharhino. If the automatic report does not work for your setup, reboot the Foreman Discovery Image and press any key on the welcome screen of the image (see screenshot).

Welcome screen

This provides extended settings, such as:

  • IP-configuration: e.g. manual IP-setting, using a specific interface or adding a VLAN-ID
  • Credentials: defines the address of the orcharhino server to report to.
  • Custom facts: set your own facts about the host. This can be used for easier identification of the system later or (with Discovery Rules) to automatically decide what to deploy on this host.

If this was successful, the host will show a Discovery Status window showing the results and a menu of continuative actions:

  • Resend sends a new report to orcharhino
  • Status shows general status information about the report
  • Facts shows all the information reported to orcharhino
  • Logs provides debug-information
  • SSH allows you to enable/disable SSH-access to the host (also defines SSH root-password)
  • Reboot reboots the host

Warning

If SSH-access has been enabled and an SSH-session exists, the session will not automatically be terminated, if you disable the SSH-access again.

Usage on orcharhino

List of discovered hosts

After the host has reported itself successfully to orcharhino, it appears on the discovered hosts page (see also Discovered Hosts from the Management UI chapter). The Name column shows the generated name as well as an icon indicating when the host reported itself (details appear if the cursor is hovered over the icon). The default name of a newly discovered host is generated from it’s MAC-address. The prefix of the name can be customised in the Discovered-section on the Settings page by modifying the Hostname prefix-setting. By clicking on the provisional hostname, facts about the discovered host are shown. These facts can be used e.g. for generating the final hostname upon provisioning. Refreshing of this data can be done in two ways. Either from orcharhino by clicking on the Refresh facts button (the Provision button must be expanded for that). Or from the host itself by clicking on the aforementioned Resend button provided by the booted Foreman Discovery Image.

At this stage the hosts are discovered, but not yet deployed. A discovered host can be deployed by clicking on the Provision button. In the upcoming pop-up you may specify a Host Group to provision the host as well as the Organization and the Location. Then you can either click Create Host to start the provisioning (given there are no problems with the settings) or hit Customize Host to get to the Provision Host form, which is similar to the Create Host form. If a Host Group was selected, the Provision Host form is prefilled with the values defined in the Host Group.

There is also the possibility to automatically provision discovered hosts. It is essential that least one Discovery rule has been defined and matches the host that should be provisioned.

Discovery rule specification

Discovery rules are defined on the discovery rules page (see also Discovery Rules from the Management UI chapter). They are used to provision a set of hosts that have similar facts with the same configuration. A Discovery rule defines the following data that is used to provision the hosts that match the rule’s search-criteria:

The Hosts Limit value defines the maximum amount of hosts that can be provisioned using this rule. A value of 0 disables the limitation. Considering multiple rules were defined that match the same discovered hosts, the rule with the lowest Priority value will take precedence.

You can review the discovered hosts that would match a Discovery Rule by clicking on the rule’s Discovered Hosts button. To see the hosts that already have been provisioned with this rule, click on Associated Hosts. Furthermore, a rule can be temporarily disabled using the Disable button or deleted with the Delete button.

Auto provision

The Discovery Rules can be applied to the discovered hosts by clicking on one of the Auto Provision buttons on the Discovered Hosts page. This can be done for all discovered hosts (1) or a single one (2) either by initiating Auto Provision manually on the Discovered Hosts page or automatically as soon as they are discovered. Another way to Auto Provision hosts is to let orcharhino initiate it automatically as soon as the hosts report themselves.

Note

To enable automatic provisioning of newly discovered hosts, the Auto provisioning-setting in the Discovered-section on the Settings page must be set to yes.