Host Discovery Guide

The host discovery guide describes the installation and usage of the host discovery plugin in orcharhino.

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

The host 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.

This guide uses orcharhino specific terminology. If you are new to orcharhino or unsure about certain terms, have a look at our glossary.


During the installation of orcharhino with the orcharhino installer, select the host discovery plugin at the plugin installation step. This will automatically install and configure the host discovery plugin. The following installation steps are not necessary then.

Run the following command to add the host discovery plugin to your orcharhino:

foreman-installer --enable-foreman-plugin-discovery

On an orcharhino proxy, run the following command:

foreman-installer --enable-foreman-proxy-plugin-discovery

In case of installing the host discovery plugin manually, use the following command to install the Foreman Discovery Image:

yum install orcharhino-fdi

Usage on Hosts

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

Discovery Boot Menu

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.

Keep in mind that the host has to receive its 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 regenerate the default menu by clicking Build PXE Default on the provisioning templates page.

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:

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 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 to 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.

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. 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 its 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 host name, facts about the discovered host are shown. These facts can be used for generating the final host name 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 page. 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. Ensure you define at least one Discovery rule which matches the host that you want to provision.

Discovery rule specification

Discovery rules are defined on the discovery rules page. 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. Click on Associated Hosts to see the hosts that already have been provisioned with this rule. Furthermore, a rule can be temporarily disabled using the Disable button or deleted with the Delete button.

Auto provisioning

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.

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.