Commission machines (deb/3.0/UI)

2.9 3.0

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.

About enlisting machines

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.

Commissioning requires 60 seconds.

About commissioning machines

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:

  • Allow SSH access and prevent machine powering off: Machines are normally powered off after commissioning. This option keeps the machine on and enables SSH so you can access the machine.

  • Retain network configuration: When enabled, preserves any custom network settings previously configured for the machine. See Networking for more information.

  • Retain storage configuration: When enabled, preserves any storage settings previously configured for the machine. See Storage for more details.

  • Update firmware: Runs scripts tagged with update_firmware. See Testing scripts for more details.

  • Configure HBA: Runs scripts tagged with configure_hba. As above, see Testing scripts for further details.

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.

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.

About commissioning NUMA and SR-IOV nodes

If you are using the NUMA architecture, MAAS versions 2.7 and higher guarantee that machines are assigned to a single NUMA node that contains all the machine’s resources. Node boundaries are critical, especially in vNUMA situations. Splitting nodes can create unnecessary latency. You want the NUMA node boundaries to match VM boundaries if at all possible.

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.

About 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:

  • maas-support-info: MAAS gathers information that helps to identify and characterise the machine for debugging purposes, such as the kernel, versioning of various components, etc. Runs in parallel with other scripts.

  • maas-lshw: this script pulls system BIOS and vendor info, and generates user-defined tags for later use. Runs in parallel with other scripts.

  • 20-maas-01-install-lldpd: this script installs the link layer discovery protocol (LLDP) daemon, which will later capture networking information about the machine. This script provides some extensive logging.

  • maas-list-modaliases: this script figures out what hardware modules are loaded, providing a way to autorun certain scripts based on which modules are loaded. Runs in parallel with other scripts.

  • 20-maas-02-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 recognised. This script provides extensive logging.

  • maas-get-fruid-api-data: this script gathers information for the Facebook wedge power type. Runs in parallel with other scripts.

  • maas-serial-ports: this script lists what serial ports are available on the machine. Runs in parallel with other scripts.

  • 50-maas-01-commissioning: this script is the main MAAS tool, gathering information on machine resources, such as storage, network devices, CPU, RAM, details about attached USB and PCI devices, 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. This script also checks whether the machine being commissioning is a virtual machine, which may affect how MAAS interacts with it.

  • maas-capture-lldp: this script gathers LLDP network information to be presented on the logs page; this data is not used by MAAS at all. Runs in parallel with other scripts.

  • maas-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 these seven caveats:

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

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

  3. Commissioning scripts can send BMC configuration data, and can be used to configure BMC data.

  4. The environment variable BMC_CONFIG_PATH is passed to serially run commissioning scripts; these scripts may write BMC power credentials to BMC_CONFIG_PATH in YAML format, where each key is a power parameter. The first script to write BMC_CONFIG_PATH is the only script allowed to configure the BMC, allowing you to override MAAS’ built-in BMC detection. If the script returns 0, that value will be send to MAAS.

  5. All built-in commissioning scripts have been migrated into the database.

  6. maas-run-remote-scripts is capable of enlisting machines, so enlistment user-data scripts have been removed.

  7. The metadata endpoints http://<MAAS>:5240/<latest or 2012-03-01>/ and http://<MAAS>:5240/<latest or 2012-03-01>/meta-data/ are now available anonymously for use 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.

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

About bond and bridge interfaces

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.

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.

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.

  • Auto assign: MAAS will assign a random static address (iface eth0 inet static). The pool of available addresses depends on whether the subnet is managed or unmanaged (see Subnet management).

  • Static assign: The administrator will specify a static address using a secondary field.

  • DHCP: The machine leases a dynamic IP address, via either MAAS-managed DHCP or an external DHCP server.

  • Unconfigured: The interface is not configured.

Press the “Save” button to apply the changes.

See Concepts and terms for the definitions of reserved range types.

How to create a bond interface

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:

  • balance-rr: Transmit packets in sequential order from the first available slave through to the last. This mode provides load balancing and fault tolerance.

  • active-backup: Only one slave in the bond is active. A different slave becomes active if, and only if, the active slave fails. The bond’s MAC address is externally visible on only one port (network adaptor) to avoid confusing the switch.

  • balance-xor: Transmit based on the selected transmit hash policy. The default policy is simple, which means that an XOR operation selects packages. This XOR compares the source MAC address and the resultant XOR between the destination MAC address, the packet type identifier, and the modulo slave count.

  • broadcast: Transmit everything on all slave interfaces. This mode provides fault tolerance.

  • 802.3ad: Creates aggregation groups that share the same speed and duplex settings. This mode utilises all slaves in the active aggregation, following the IEEE 802.3ad specification.

  • balance-tlb: Adaptive transmit load balancing, channel bonding that does not require any special switch support.

  • balance-alb: Adaptive load balancing, includes balance-tlb plus receive load balancing (rlb) for IPV4 traffic. This mode does not require any special switch support. ARP negotiation achieves load balancing in this case.

Press the “Save” button when you’re done.

The MAC address defaults to the MAC address of the primary interface.

How to create a bridge interface

Press the “Save” button when you’re done.

How to delete an interface

The “delete” command can be used to delete a bridge interface, a bond interface or a physical interface:

maas $PROFILE interface delete $SYSTEM_ID $IFACE_ID

For example:

maas admin interface delete 4efwb4 15

The following is output after the successful deletion of an interface:

Machine-readable output follows:

Note that while the label is presented, there is no machine-readable output expected after the successful execution of the delete command.

How to assign a network interface to a fabric

This task is made easier with the aid of the jq utility. It filters the maas command (JSON formatted) output and prints it in the desired way, which allows you to view and compare data quickly. Go ahead and install it:

sudo apt install jq

In summary, MAAS assigns an interface to a fabric by assigning it to a VLAN. First, we need to gather various bits of data.

List some information on all machines:

maas $PROFILE machines read | jq ".[] | \
    {hostname:.hostname, system_id: .system_id, status:.status}" --compact-output

Example output:


You can only edit an interface when the corresponding machine has a status of ‘Ready’. This state is numerically denoted by the integer ‘4’.

List some information for all interfaces on the machine in question (identified by its system id ‘dfgnnd’):

maas $PROFILE interfaces read dfgnnd | jq ".[] | \
    {,, mac:.mac_address, vid:.vlan.vid, fabric:.vlan.fabric}" --compact-output

Example output:


List some information for all fabrics:

maas $PROFILE fabrics read | jq ".[] | \
    {, vlans:.vlans[] | {, vid:.vid}}" --compact-output

Example output:


This example will show how to move interface ‘8’ (on machine ‘dfgnnd’) from ‘fabric-1’ to ‘fabric-0’. Based on the gathered information, this will consist of changing the interface’s VLAN from ‘5002’ to ‘5001’:

maas $PROFILE interface update dfgnnd 8 vlan=5001 >/dev/null

Verify the operation by relisting information for the machine’s interface:

maas $PROFILE interfaces read dfgnnd | jq ".[] | \
    {,, mac:.mac_address, vid:.vlan.vid, fabric:.vlan.fabric}" --compact-output

The output shows that the interface is now on fabric-0:


How to discover interface identifiers

The MAAS CLI uses a numeric interface identifier for many interface operations. Use the following command to retrieve the identifier(s):

maas $PROFILE interfaces read $SYSTEM_ID

Look for either id or the number at the end of an interface’s resource URI, such as 15 in the following example output:

"id": 15,
"mac_address": "52:54:00:55:06:40",
"name": "ens9",
"resource_uri": "/MAAS/api/2.0/nodes/4efwb4/interfaces/15/"

How to create a VLAN interface

To create a VLAN interface, use the following syntax:

maas $PROFILE vlans create $FABRIC_ID name=$NAME vid=$VLAN_ID

For example, the following command creates a VLAN called 'Storage network:

maas admin vlans create 0 name="Storage network" vid=100

The above command generates the following output:

Machine-readable output follows:
    "vid": 100,
    "mtu": 1500,
    "dhcp_on": false,
    "external_dhcp": null,
    "relay_vlan": null,
    "name": "Storage network",
    "space": "undefined",
    "fabric": "fabric-0",
    "id": 5004,
    "primary_rack": null,
    "fabric_id": 0,
    "secondary_rack": null,
    "resource_uri": "/MAAS/api/2.0/vlans/5004/"

Be aware that the $VLAN_ID parameter does not indicate a VLAN ID that corresponds to the VLAN tag. You must first create the VLAN and then associate it with the interface:

maas $PROFILE interfaces create-vlan $SYSTEM_ID vlan=$OUTPUT_VLAN_ID \

OUTPUT_VLAN_ID corresponds to the id value output when MAAS created the VLAN.

The following example contains values that correspond to the output above:

maas admin interfaces create-vlan 4efwb4 vlan=5004 parent=4

The above command generates the following output:

Machine-readable output follows:
    "tags": [],
    "type": "vlan",
    "enabled": true,
    "system_id": "4efwb4",
    "id": 21,
    "children": [],
    "mac_address": "52:54:00:eb:f2:29",
    "params": {},
    "vlan": {
        "vid": 100,
        "mtu": 1500,
        "dhcp_on": false,
        "external_dhcp": null,
        "relay_vlan": null,
        "id": 5004,
        "secondary_rack": null,
        "fabric_id": 0,
        "space": "undefined",
        "fabric": "fabric-0",
        "name": "Storage network",
        "primary_rack": null,
        "resource_uri": "/MAAS/api/2.0/vlans/5004/"
    "parents": [
    "effective_mtu": 1500,
    "links": [
            "id": 55,
            "mode": "link_up"
    "discovered": null,
    "name": "ens3.100",
    "resource_uri": "/MAAS/api/2.0/nodes/4efwb4/interfaces/21/"

How to delete a VLAN interface

The following command outlines the syntax required to delete a VLAN interface from the command line:

maas $PROFILE vlan delete $FABRIC__ID $VLAN_ID

Using the values from previous examples, you executed this step as follows:

maas admin vlan delete 0 100

Last updated 15 days ago.