Add machines

Enlistment KVM host nodes
Adding virtual machines Add a machine manually
Add machines via a chassis  

MAAS typically adds a machine via a combination of DHCP, TFTP, and PXE. By now, you should have enabled MAAS to automatically add devices and machines to your environment. This unattended manner of adding a machine is called enlistment.

Configuring a computer to boot over PXE is done via its BIOS and is often referred to as “netboot” or “network boot”.

Regardless of how MAAS adds a machine, there are no special requirements for the underlying machine. In particular, there is no need to install an operating system on it.

Once MAAS is working to the point of adding machines, it is important to understand statuses and actions. See Node statuses and Machine actions respectively.


When MAAS enlists a machine, the first step is to contact the DHCP server, so that the machine can be assigned an IP address, which is necessary to download a kernel and initrd via TFTP. Once the machine has a bootable kernel, MAAS boots it:

Next, initrd mounts a Squashfs image, ephemerally, via HTTP, so that cloud-init can execute:

Finally, cloud-init runs enlistment and setup scripts:

The enlistment scripts send the region API server information about the machine, including the architecture, MAC address and other details. The API server, in turn, stores these details in the database. This information-gathering process is known as automatic discovery.

After the enlistment process, the MAAS places the machine in the ‘Ready’ state.

Typically, the next step will be to commission the machine. See Commission machines.

MAAS runs built-in commissioning scripts during the enlistment phase. When you commission a machine, any customised commissioning scripts you add will have access to data collected during enlistment. Follow the link above for more information about commissioning and commission scripts.

As an alternative to enlistment, an administrator can add a machine manually (see below). Typically this is done when enlistment doesn’t work for some reason.

KVM host nodes

For more information about adding nodes to use as KVM hosts, please see Add KVM pods.

Adding virtual machines

After you have deployed a machine to use as a KVM host, you can “compose” VMs to add to MAAS. Please see the Compose a virtual machine section for more information.

Add a machine manually

Enlistment can be done manually if the hardware specifications of the underlying machine are known. On the ‘Machines’ page of the web UI, click the ‘Add hardware’ button and then select ‘Machine’.

Fill in the form and hit ‘Save machine’. In this example, you are adding an IPMI machine:

You will need to configure the underlying machine to boot over the network, or commissioning will not happen. MAAS will not do this for you.

BMC enlistment

2.4: Note that in MAAS versions before 2.5, you are required to provide the MAC address of the PXE interface when adding a new machine manually.

IPMI machines

For IPMI machines, you only need to provide IPMI credentials. MAAS automatically discovers the machine and runs enlistment configuration by matching the BMC address.

Non-IPMI machines

For non-IPMI machines, you must specify a non-PXE MAC address. MAAS automatically discovers the machine and runs enlistment configuration by matching the non-PXE MAC address.

Add machines via a chassis

Use the chassis feature to add multiple machines at once. To do this, instead of selecting ‘Machine’ as above, choose ‘Chassis’ from the drop-down menu. In the following example, MAAS will add all available VMs from the given virsh address:

The required fields will change based on the type of chassis you choose.

As with the manual method, the underlying machines will require netbooting.