Enlistment v. Commissioning

MAAS is built to manage machines, including the operating systems on those machines. Enlistment and commissioning are features that make it easier to start managing a machine – as long as that machine has been configured to netboot. Enlistment enables users to simply connect a machine, configure the firmware properly, and power it on so that MAAS can find it and add it.

Enlistment happens when MAAS starts; it reaches out on connected subnets to locate any nodes – that is, devices and machines – that reside on those subnets. MAAS finds a machine that’s configured to netboot (e.g., via PXE), boots that machine into Ubuntu, and then sends cloud-init user data which runs standard (i.e., built-in) commissioning scripts. The machine actually adds itself over the MAAS API, and then requests permission to send commissioning data.

Since MAAS doesn’t know whether you might intend to actually include these discovered machines in your cloud configuration, it won’t automatically take them over, but it will read them to get an idea how they’re set up. MAAS then presents these machines to you with a MAAS state of “New.” This allows you to examine them and decide whether or not you want MAAS to manage them.

When a machine boots, MAAS first instructs it to run cloud-init to set up SSH keys (during commissioning only), set up NTP, and execute a script that runs other commissioning scripts. Currently, the sequence of MAAS-provided commissioning scripts proceeds like this:

  • 00-maas-00-support-info: MAAS gathers information that helps to identify and characterize the machine for debugging purposes, such as the kernel, versioning of various components, etc.

  • 00-maas-01-lshw: this script pulls system BIOS and vendor info, and generates user-defined tags for later use.

  • 00-maas-02-virtuality: this script checks whether the machine being commissioning is a virtual machine, which may affect how MAAS interacts with it.

  • 00-maas-03-install-lldpd: this script installs the link layer discovery protocol (LLDP) daemon, which will later capture networking information about the machine. The lldpd needs to be installed early because it requires about a 60-second delay before running.

  • 00-maas-04-list-modaliases: this script figures out what hardware modules are loaded, providing a way to autorun certain scripts based on which modules are loaded.

  • 00-maas-05-dhcp-unconfigured-ifaces: MAAS will want to know all the ways the machine is connected to the network. Only PXE comes online during boot; this script brings all the other networks online so they can be recognized.

  • 00-maas-06-get-fruid-api-data: this script gathers information for the Facebook wedge power type.

  • 00-maas-08-serial-ports: this script lists what serial ports are available on the machine.

  • 40-maas-01-network-interfaces: this script is just used to get the IP address, which can then be associated with a VLAN/subnet.

  • 50-maas-01-commissioning: this script is the main MAAS tool, gathering information on machine resources, such as storage, network devices, CPU, RAM, etc. We currently pull this data using lxd: We use a Go binary built from lxd source that just contains the minimum source to gather the resource information we need.

  • 99-maas-01-capture-lldp: this script gathers LLDP network information to be presented on the logs page; this data is not used by MAAS at all.

  • 99-maas-05-kernel-cmdline: this script is used to update the boot devices; it double-checks that the right boot interface is selected.

Commissioning runs the same dozen or so scripts as enlistment, gathering all the same information, but with some additional caveats:

  • Commissioning also runs user-supplied commissioning scripts, if present. Be aware that these scripts run as root, so they can execute any system command.

  • Commissioning runs test scripts which are not run during enlistment.

In both enlistment and commissioning, MAAS uses either the MAC address or the UUID to identify machines. Currently, because some machine types encountered by MAAS do not use unique MAC addresses, we are trending toward using the UUID.

1 Like

One of the key features of MAAS is its ability to discover network-connected hardware and, if that hardware is able to netboot, to gather all sorts of useful information that can be used to configure and control that hardware.

MAAS’s primary purpose is managing a machines operating system. Enlistment is a feature to make it easier to start managing a machine’s operating system. For MAAS use a machine must be configured to network boot first. Enlistment enables users to simply connect a machine, configure the firmware, and power it on to be added to MAAS.

Network discovery is an add on feature that allows users to see what devices are connected to their network. I think leaving it out of this of this post may make things a bit more straight forward.

When MAAS finds a device that is configured to netboot (e.g., via PXE), MAAS will scan it via a set of scripts to gather information from the device.

MAAS doesn’t scan the machine, when network booting happens MAAS tells the machine to boot into Ubuntu and sends cloud-init user data which runs commissioning data. The machine actually adds itself over the API then requests permission to send commissioning data.

Since MAAS doesn’t know whether you might intend to actually include these discovered devices in your cloud configuration,

I would use the word “machine” here. In MAAS a machine is something MAAS can configure and install an operating system to. A device is something that MAAS only provides DHCP and DNS for.

00-maas-01-lshw: this script pulls system BIOS and vendor info, and automatically creates tags used for various purposes later.

  • The tags generated from lshw are user defined, MAAS doesn’t add any by default - https://maas.io/docs/cli-tag-management
  • Not sure if it matters but I’m trying to get BIOS and vendor info from LXD this cycle.

@ltrager, I’ve incorporated your comments in the latest post. Thanks for this.

I would use deploying rather than managing here. We already have enough people getting suprised that once the O/S is deployed, that MAAS won’t reconfigure it for them. MAAS’ job is in essence to get the bare-metal into a state where the user’s management tool of choice (Puppet, Ansible, …) is able to function.


1 Like