Offline docs (switch to live docs)                          Full          UI-only         CLI-only

Commission machines

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 you configure a machine to netboot – and turn it on while connected to the network – MAAS will enlist it, giving it a status of “New.” You can also add a machine manually). In either case, the next step is commissioning, which boots the machine into an ephemeral Ubuntu kernel so that resource information can be gathered. You can also run custom commissioning scripts to meet your specific needs.

Questions you may have:

How machines are commissioned

When MAAS commissions a machine, the following sequence of events takes place:

  1. DHCP server is contacted
  2. kernel and initrd are received over TFTP
  3. machine boots
  4. initrd mounts a Squashfs image ephemerally over HTTP
  5. cloud-init runs built-in and custom commissioning scripts
  6. machine shuts down

The commissioning scripts will talk to the region API server to ensure that everything is in order and that eventual deployment will succeed.

MAAS chooses the latest Ubuntu LTS release as the default image for commissioning. If desired, you can select a different image in the ‘Settings’ page of the web UI, by selecting the ‘General’ tab and then scrolling down to the Commissioning section.

To commission, on the ‘Machines’ page, select a machine and choose ‘Commission’ under the ‘Take action’ drop-down menu.


You have the option of selecting some extra parameters (checkboxes) and performing hardware tests.

These options include:


Click the Hardware tests field to reveal a drop-down list of tests to add and run during commissioning. See Hardware testing) for more information on hardware testing scripts.

Finalise the directive by hitting ‘Commission machine’.

While commissioning, the machine status will change to reflect this state (Commissioning). MAAS discovers the machine’s network topology. MAAS then prompts a machine network interface to connect to the fabric, VLAN, and subnet combination for configuration. Usually, MAAS assigns a static IP address out of the reserved IP range for the subnet (‘Auto assign’ mode). The next section details several assignment modes.

See MAAS CLI for how to commission a machine with the CLI.

Once commissioned, a machine’s status will change to Ready, and an extra tab for the machine called ‘Commissioning’ will become available. This tab contains the results of the scripts executed during the commissioning process.

Once commissioned, you may consider creating or applying a tag to this machine. The next step is deployment.

Commission NUMA and SR-IOV nodes

If you are using the NUMA architecture, MAAS version 2.7 guarantees that machines are assigned to a single NUMA node that contains all the machine’s resoures. Note that you must recommission NUMA/SR-IOV machines that were previously commissioned under version 2.6 or earlier.


When using these nodes, you can specify a node index for interfaces and physical block devices. MAAS will display the NUMA node index and details, depending upon your configuration, to include the count of NUMA nodes, number of CPU cores, memory, NICs, and node spaces for bonds and block devices. You can also filter machines by CPU cores, memory, subnet, VLAN, fabric, space, storage, and RAID, among others.

MAAS commissioning scripts

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:

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

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.

Post-commission configuration

Once commissioned, you can configure the machine’s network interface(s). Specifically, when a machine’s status is either ‘Ready’ or ‘Broken’, interfaces can be added/removed, attached to a fabric and linked to a subnet, and provided an IP assignment mode. Tags can also be assigned to specific network interfaces (see Tags for network interfaces).

From a machine’s ‘Interfaces’ page, click the menu icon for the interface to be edited and select ‘Edit Physical’ from the resulting menu:


The following window will appear:


Four modes determine how a subnet address is assigned when MAAS deploys the machine. You can select one of these modes by clicking on the ‘IP mode’ drop-down menu.

Press the ‘Save’ button to apply the changes.

See Concepts and terms for the definitions of reserved range types and MAAS CLI - advanced tasks to learn how to change the IP-assignment mode of a network interface using the CLI.

Bond interfaces and how to create one

A bond interface is used to aggregate two or more physical interfaces into a single logical interface. Combining multiple network connections in parallel can increase network throughput beyond what a single NIC will allow. It also provides some redundancy in case one of the NICs should fail. More information about the theory behind bonded NICs is found in the relevant IEEE standard.

In the case of our MAAS hospital example, bond interfaces would probably be used in machines dealing with “Prescriber controls” and “Nursing meds.” Medication administration and reconciliation can involve a significant amount of data that must be communicated in a near real-time way: prescriptions must be verified and corrected, dosages must be monitored and frequently changed or paused, and complications and side-effects checked constantly.

A bond is created by selecting more than one interface and clicking the now-active ‘Create bond’ button:


After clicking the ‘Create bond’ button, the bond configuration pane will appear.

From the bond configuration pane, you can rename the bond, select a bond mode (see below), assign a MAC address to the aggregate device and attach one or more tags.

The interfaces aggregated into the bond interface are listed below the ‘Tags’ field. Use the ‘Primary’ column to select the interface to act as the primary device.


You can select from the following bonding modes on the ‘Bond mode’ drop-down menu:

Press the ‘Save’ button when you’re done.

[note] The MAC address defaults to the MAC address of the primary interface. [/note]

Bridge interfaces and how to create one

A network bridge may be useful if you intend to put virtual machines or containers on the machine. You can create a bridge by selecting an interface and clicking the now-active ‘Create bridge’ button. A form will appear that allows you to configure a MAC address, STP, and an appropriate tag.


Press the ‘Save’ button when you’re done.

See CLI Interface Management for details on how you can configure interfaces from the command line.