Foreman Discovery 4.1 Manual This plugin enables Foreman to do automatic bare-metal discovery of unknown nodes on the provisioning network. New nodes self-register into Foreman and upload facts collected by Facter (serial id, network interfaces, memory, disks).

The registered nodes show up on Discovered Hosts page and provisioning can be initiated either manually (via UI/CLI or API) or automatically via predefined Discovery Rules. All communication can be optionally passed through Smart Proxy which has direct access both to the provisioning network and Foreman instance: 1.1 Release Notes For each Foreman version there is particular version of Foreman Discovery plugin: Foreman version Plugin version Proxy version Image version CLI version. # apt-get install ruby-smart-proxy-discovery on Debian and Ubuntu systems. Smart Proxy must be restarted after plugin installation and features must be refreshed for the given Proxy in the Foreman interface ( Infrastructure Smart Proxies a proxy Refresh features). 2.3 Foreman Discovery Image The image is based on CentOS 7 and about 150 MB in size.

There are two ways to install the image. 2.3.1 Download via installer (recommended) As of Foreman 1.8+, the foreman-installer is able to automatically download latest stable image.

For this, re-run the installer with the following option. # foreman-installer -foreman-plugin-discovery-source-url= -foreman-plugin-discovery-install-images=true Check the version number in foreman-plugin-discovery-source-url option against the table above.

Some image-plugin combinations are not compatible. Tip: It is possible to install both Discovery plugin and image in one installer run by providing both the options. Important note: Executing foreman-installer will re-deploy all foreman-related configuration files. In case some changes have been made, proceed with manual download described below.

2.3.2 Manual download Images are available To download the latest release to the expected location, do the following on Fedora and Red Hat systems. # cat /var/lib/tftpboot/boot/fdi-image/SHA256SUM beb3cfba7d9fb9d71481c0c8f. Initrd0.img f03bce150d2473a. Vmlinuz0 # sha256sum /var/lib/tftpboot/boot/fdi-image/.

On Debian systems, use /srv/tftp/boot instead of /var/tftpboot/boot. 2.3.4 Building own image To build a discovery image, please visit the foreman-discovery-image git and find the README for further instructions. 2.4 Hammer CLI Foreman Discovery 2.4.1 Installation Before installing make sure you have installed the, On Red Hat compatible systems: yum install tfm-rubygem-hammercliforemandiscovery On Debian/Ubuntu compatible systems: apt-get install ruby-hammer-cli-foreman-discovery Or install from rubygems: gem install hammercliforemandiscovery. 2.5 Upgrade To upgrade Foreman Discovery follow the standard procedure of upgrading all the Foreman packages. Check Foreman Discovery global settings and PXELinux Default template.

After each upgrade, it is required to reboot all discovered hosts to load new discovery image which is compatible with the recent features added in the Foreman plugin. To do this, click on Reboot All button in the UI or do this via CLI. Configuration The following chapter covers configuration of all the components installed. 3.1 Foreman Discovery plugin 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. 3.1.1 Default PXE template 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 rd.debug=1 nomodeset proxy.url=proxy.type=foreman 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. For backward compatibility, foreman.url is an alias for this setting. In case Smart Proxy Discovery plugin is configured to forward communication, configure the APPEND line in the following way: APPEND proxy.url=proxy.type=proxy Once the APPEND line is modified properly, set the entry to be default via the ONTIMEOUT option. x-foreman.tcp SRV 0 5 443 foreman You can mix both approaches and override SRV record with the command line.

It is important to keep IPAPPEND 2 option which is key configuration option to detect interface connected to provisioning network. Also never change or remove root option, otherwise image will not boot properly. It is important to know that DNS servers from DHCP are taken into acount for only for the interface that was specified via the BOOTIF option. This means when a system has multiple NICs, DNS will work for the correct interface - the one that was booted from. 3.1.2 Update PXE default template 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.

Repeat this step every time a change is made to the default template. 3.1.3 Organizations and Locations If Locations and/or Organizations are enabled, Foreman assigns Organization and Location to discovered hosts according to the following rules from top to bottom:. According to the discoveryorganization or discoverylocation, if present.

Heads Up Issues With Access Gateway Plug-in For Mac

These can be set under Administer Settings Discovered. If foremanorganization or foremanlocation fact is present, set accordingly. Fact names which are looked up can be configured in Administer Settings Puppet section as Organization/Location fact setting. If Subnet was determined for particular discovered host, use the first Organization and Location associated with the Subnet.

Select the first Organization / Location ordered by title (name the org/loc was created with). This is a workaround until we fix provisioning of discovered hosts. Organization or Location can be changed via the “bulk actions” menu which appears once once or more discovered hosts are selected. 3.1.4 Global settings There is also setting called discoveryfact which defaults to discoverybootif. It specify which incoming fact should be used to get the MAC address. By default, the PXELinux BOOTIF kernel command line option is used which gives the MAC address of the interface which was booted from. Note that autodiscovery option is set to false by default.

If you want to trigger provisioning automatically with rules, you need to turn this setting on. It’s recommended to try provision manually first to test before proceeding. It is possible to add any fact reported by Facter via discoveryfactcolumn global option onto the Discovered Hosts page table as a new column. To do that, set the value of this setting to name of a fact reported. To hide the new column, set to a blank value.

To show multiple columns, separate fact names by comma. # grep foremanurl /etc/foreman-proxy/settings.yml:foremanurl: This should by done automatically by our installer.

It is a good idea to check if the host responds properly and there are no firewalls blocking the communication. 3.2.1 Subnet proxy setup All subnets with discovered nodes need this specified in Foreman so it connects via the Smart Proxy.

To do this, go to Infrastructure Smart Proxies and verify if the desired proxy lists Discovery feature. If not, click on Refresh features button and it will appear immediately. In Infrastructure Subnets select the desired Discovery Proxy for each appropriate Subnet. Make sure that lease pool (defined in ISC DHCP configuration) and reservation pool (defined in Infrastructure Subnets) are disjoint. More on that topic in the section. 3.3 Hammer CLI Foreman Discovery plugin The plugin must be enabled in cli.modules.d/foremandiscovery.yml (see ) as follows.

:foremandiscovery::enablemodule: true 3.4 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 performdiscovery permission to an existing Role. Usage Foreman Discovery plugin provides user interface, API and CLI.

4.1 Hardware discovery Boot a machine in any provisioning network that was configured with the default PXE configuration above. It should register with Foreman and appear in Hosts Discovered Hosts. 4.2 Manual provisioning 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, Foreman modifies the host’s PXELinux file on the TFTP server and reboots the discovered host, after which it boots into an 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. 4.3 Automatic provisioning Starting with version 2.0, it is possible to predefine provisioning rules which will assign host group to provisioned hosts and trigger provisioning automatically. To do that, head over to Configure Discovery rules and create such a rule:. Name represents rule name shown to the users.

It must not contain spaces or non-alphanumeric characters. Search statement is used to match discovered hosts for the particular rule. Use Scoped Search syntax to define it. Examples are shown below.

Host Group is assigned to a matching host before starting provisioning process. It is very important the selected Host Group has all the required parameters set (domain, subnet, root password), otherwise provisioning process will fail. Hostname defines a pattern to assign human-readable hostnames to the matching hosts. When left empty, hostname is assigned in a form of macMACADDRESS by default.

The same syntax as for provisioning templates is used. See below for more information and examples. Hosts limit enables to limit maximum amount of provisioned hosts per rule. If a limit was reached, the rule will not take effect until one or more hosts are deleted. Typical use case are rules per server rack or row when it is necessary to change provisioning parameters like hostname or host group per each entry.

Priority puts the rules in order. Must be greater than zero and low numbers go first. Rules are always matched by priority given. Enabled flag is used for temporary shutdown of rules.

Organizations Locations discovered hosts can only auto provision from rules in the same organization/location as the discovered host. Host group taxonomy is enforced, therefore it is not possible to provision into a host group that is not associated with the discovery rule. Once some rules are defined, the good practice is to discover a host and apply the rules using Auto discover button on the host. By default, Foreman does not trigger auto discovery automatically. This must be explicitly turned on in Administer Settings Discovered discoveryauto.

4.3.1 Search syntax Easiest way of testing search patterns is in Discovered hosts list, because the search box gives the same results. Typical search fields are facts, they all start with “facts.”. Auto completion can be used to browse the facts as well as discovered hosts detail screen. Typical search queries. Application-server-<%= rand(99999)% load-balancer-<%= @host.facts'biosvendor' + '-' + rand(99999)% wwwsrv-<%= @host.hostgroup.name% minion-<%= @host.discoveryrule.name% db-server-<%= @host.ip.gsub('.' ,'-') + '-' + @host.hostgroup.subnet.name% When creating hostname patterns, make sure the resulting host names are unique. This is very important.

Hostnames must not start with numbers. A good approach is to use unique information provided by facter (MAC address, BIOS or serial ID) or to randomize the hostname somehow. 4.4 Hammer CLI Foreman Discovery plugin Confirm your setup by running hammer -h and check that the discovery command is listed. $ hammer discovery reboot -h Usage: hammer discovery reboot OPTIONS Options: -id ID -name NAME Name to search by -h, -help print help $ hammer discovery reboot -id 130 Host reboot started 5.

Heads Up Issues With Access Gateway Plug-in For Mac Pro

Extending the image It is possible to extend the Foreman Discovery Image with custom facts, software or device drivers easily. There are two ways of doing that. 5.1 Runtime extensions It’s possible to provide a zip file containing extra code for the image to use. First, create a directory structure like.

├── autostart.d │ └── 01zip.sh ├── bin │ └── ntpdate ├── facts │ └── test.rb └── lib ├── libcrypto.so.1.0.0 └── ruby └── test.rb autostart.d contains scripts that will be executed in POSIX order by the image as it starts up, before the host is registered to Foreman. Bin is added to PATH, you can place binaries here and use them in the autostart scripts. Facts is added to FACTERLIB so that custom facts may be configured and sent to Foreman. Lib is added to LDLIBRARYPATH and lib/ruby is added to RUBYLIB, so that binaries in bin can be executed properly. Environment variables (PATH, LDLIBRARYPATH, RUBYLIB and FACTERLIB) are appended to.

If you need to specify the path to something explicitly in your scripts, the zip contents are extracted to /opt/extension on the image. An example structure is provided in examplezip in this repo. You can zip up your structure with zip -r myextension.zip. You can create multiple zip files, but be aware they will be extracted to the same place on the discovery image, so files in later zips will overwrite earlier ones if they have the same filename. To inform the image of the extensions it should use, place your zip(s) on your TFTP server along with the discovery image, and then update your PXELinux APPEND line with fdi.zips=, where the paths are relative to the TFTP root. So if you have two zips at $TFTP/zip1.zip and $TFTP/boot/zip2.zip, you would use fdi.zips=zip1.zip,boot/zip2.zip.

5.2 Image building with extensions The very same ZIP file with the structure described above can be injected into your own image. This is useful for network drivers when there is a chicken and egg problem. To build a discovery image with extensions, please visit the foreman-discovery-image git and find the README for further instructions. 5.3 PXE-less discovery It is possible to use the Discovery image directly as a CDROM/DVDROM ISO that can be also transferred to hard drive or USB stick.

Download the image from our site and transfer it onto a flash drive. Wget dd if=fdi-bootable-3.0.X.iso of=/dev/sdx In this case, automatic discovery process is not started automatically and the user can select the primary network interface interactively.

On the next couple of screens, the user configures network credentials (IPv4 supported at the moment), the URL and type (Foreman or Smart Proxy), and fills custom user facts which are then uploaded to the server. These custom facts can be used with pre-defined discovery rules to let users automatically build hosts. Image sends special “kexec” fact (flag) along standard and user facts which is a signal to Discovery plugin to initiate kexec reload instead of reboot. When the host is provisioned either manually or via discovery rule, instance loads installer via kexec utility.

This interactive mode is also available when image is PXE booted, user must cancel initial splash screen countdown with a key to get there. Currently there is no authentication in the workflow (the same applies for normal discovery process), but it is possible to define own custom facts named “token” or “password” to secure PXE-less provisioning. Before a system can be discovered without PXE there must be a discovery rule associated with a hostgroup having an OS associated with a “kexec” template kind. This template is used to pass in parameters for kexec call (kernel, initrd, append line). Discovery ships with templates for Red Hat and Debian distributions at the moment. Make sure the associated provisioning template is configured with static networking, if the deployment does not provide DHCP services, otherwise Anaconda will fail to install the system after kernel reload.

Also check if netmask, gateway and primary DNS server is present on the associated Subnet. 5.3.1 Unattended and semi-automatic mode All interactive screens can be fully automated via kernel command line that can be either entered during SYSLINUX/Grub2 boot screen or burnt into the image (see below). Options are self-explanatory. Proxy.url=proxy.type=foreman fdi.pxmac=aa:bb:cc:dd:ee:ff fdi.pxip=192.168.122.42/24 fdi.pxgw=192.168.1.1 fdi.pxdns=192.168.1.1 fdi.pxfactname1=security-token fdi.pxfactvalue1=987123 fdi.pxfactname2=deployment fdi.pxfactvalue2=db-server fdi.pxfactnameN= fdi.pxfactvalueN= When px.ip and/or px.gw are omitted, image tries to acquire network credentials over DHCP, which can be useful in PXE-less environments with DHCP server deployed. Therefore the absolute minimum set of options in this case is. Fdi.pxauto=1 When fdi.pxauto is not provided, Ok/Next buttons are always focused first on all screens therefore it is easier to walk through. The pxmac option defines the provisioning interface to be used to acquire network credentials (optionally) and send facts.

Heads Up Issues With Access Gateway Plug-in For Mac Windows 10

If omitted in unattended mode, the first NIC with link is picked up (in alphabetical order by network identifier in case of multiple items). In semi-automated mode, screen will appear to select the correct interface. 5.3.2 Remastering Discovery Image Unattended and semi-automatic mode described above requires some kernel command line options to be present. To avoid typing them in in PXELinux/Grub2 loaders, it is possible to re-master the discovery image “burning” the options into the image.

Helper script called is being shipped with the foremandiscovery plugin. It can be used to make a copy of the ISO image with additional kernel command line options.

Usage is simple. Sudo discovery-remaster fdi-bootable-3.0.X.iso 'fdi.pxip=192.168.100.68/24 fdi.pxgw=192.168.100.1 fdi.pxdns=192.168.100.1 proxy.url=proxy.type=proxy fdi.pxfactname1=myfact fdi.pxfactvalue1=somevalue fdi.pxmac=52:54:00:be:8e:8c fdi.pxauto=1' The above command creates a copy in the same directory with date/time stamp in the name. 5.3.2 Example workflows Provisioning without PXE/DHCP. Setup auto-provisioning rules (optional). Transfer the ISO image onto an USB stick or CDROM and boot it. Select Manual network setup. Select primary (provisioning) interface if the host has multiple NICs.

Enter IPv4 credentials. Enter Foreman (Smart Proxy) credentials. Provide custom facts and click on Confirm. The host is discovered. The host reloads kernel into installer either manually or via auto-provisioning Provisioning with DHCP (no PXE). Transfer the ISO image onto an USB stick or CDROM and boot it. Select Discover with DHCP.

Select primary (provisioning) interface if the host has multiple NICs. Enter Foreman (Smart Proxy) credentials.

Provide custom facts and click on Confirm. The rest is same as in the example above (without DHCP) Semi-automated workflow w/o PXE/DHCP. Modify the discovery ISO with the following options:. fdi.pxgw=192.168.1.1.

fdi.pxdns=192.168.1.1. proxy.url=. proxy.type=foreman. fdi.pxfactname1=deploymenttype. fdi.pxfactvalue1=databaseserver. Transfer the ISO image onto an USB stick or CDROM and boot it. Select primary (provisioning) interface if the host has multiple NICs.

Enter IPv4 credentials (gateway and DNS is already populated). Select primary (provisioning) interface. Enter Foreman (Smart Proxy) credentials. Provide custom facts (the first is pre-populated) and click on Confirm. The rest is same as in the examples above Fully automated workflow w/o PXE/DHCP. Modify the discovery ISO and set all required options including MAC and IP address.

Make sure the fdi.pxauto option is set to 1. Transfer the ISO image onto an USB stick or CDROM and boot it. Discovered node automatically uploads facts and reloads kernel into installer. 6 Help Please follow our. For problems with the image, send us the output of the following command for a running discovered node (see below how to get access to the shell). # discovery-debug 6.1 Troubleshooting If you find a bug, please file it in. See the in the Foreman manual for more info.

Fdi.ssh=1 fdi.rootpw=redhat Use tty2 console (or higher) to login onto a discovered host. 6.1.3 Blacklisting drivers Since the image is based on CentOS 7, all kernel options are valid and should work normally, including modprobe.blacklist to blacklist a driver in init RAM disk. 6.1.4 Maximum length of command line CentOS 7 distribution ships with COMMANDLINESIZE option set to 2048. Therefore kernel command line must not be longer than that. 6.1.5 Initial restart problem In typical Foreman workflow, hosts are set to always boot from the network via PXE.

Unknown hosts boot into Discovery while known hosts boot into installer or boot from hard drive when in operation mode. Some users use Discovery plugin on virtualized platforms. Hypervisors tend to treat the initial restart in a special way to allow comfortable OS installation. They usually attempt to change boot order to first hard drive instead of CD-ROM or PXE which was only used for the installation. There is a known issue with libvirt which turns VM off instead of rebooting it which causes problems when using Discovery. To avoid this behavior and to align with recommended workflow, new VMs must be created with PXE booting only.

In Virt Manager, click on Customize options and set the boot order explicitly. When using virt-install, do not provide -pxe option and set boot order explicitly with -boot network instead. 6.2 UEFI Discovery Image version 3.0.0 and older does support booting via EFI thanks to Grub 2 which is present on the media alongside SYSLINUX. Remastered images preserve this capability as well. 6.3 Contributing Follow the for contributing.