There are two ways to add a machine to MAAS:
- If you place the machine on a connected network, and the machine is configured to netboot, MAAS will automatically enlist it.
- If you add a machine manually, MAAS will automatically commission it.
This article will explain more about both methods.
About adding machines
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 method of adding machines is called enlistment.
Configuring a computer to boot over PXE is done via its BIOS, 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, you’ll probably want to understand statuses and actions. See Node statuses and Machine actions respectively.
About enlistment
When MAAS enlists a machine, it first contacts the DHCP server, so that the machine can be assigned an IP address. An IP address is necessary to download a kernel and initrd via TFTP, since these functions can’t accept domain names. 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 information about the machine to the region API server, 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 or network discovery.
After the enlistment process, MAAS places the machine in the ‘Ready’ state. ‘Ready’ is a holding state for machines that are enlisted (or commissioned), waiting to be deployed when needed.
Typically, the next step will be to commission the machine. 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. Note that when you manually add a machine, MAAS automatically commissions the machine as soon as you’ve added it.
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.
How to add a machine manually
Enlistment can be done manually if the hardware specifications of the underlying machine are known.
At the command line, enter the following information:
stormrider@wintermute:~$ maas admin machines create \
> architecture=$ARCH \
> max_addresses=$MAC_ADDRESS \
> power_type=$POWER_TYPE \
> power_parameters_power_id=$POWER_ID \
> power_parameters_power_address=$POWER_ADDRESS \
> power_parameters_power_pass=$POWER_PASSWORD
When you enter the command (substituting the $... parameters for your own particulars), the screen will pause for a moment, and then return a stream of JSON relating to the added machine.
Here’s an example with a local laptop MAAS install, using KVMs as virtual machines:
stormrider@wintermute:~$ maas admin machines create \
> architecture=amd64 \
> max_addresses=52:54:00:6f:b4:af \
> power_type=virsh \
> power_parameters_power_id=50f6cca2-5d89-43b9-941c-90c9fcd7c156 \
> power_parameters_power_address=qemu+ssh://stormrider@192.168.123.1/system \
> power_parameters_power_pass=xxxxxxx
The variable fields in the machines create command (the $... items) are as follows, in this example:
> architecture=$ARCH \
> mac_addresses=$MAC_ADDRESS \
> power_type=$POWER_TYPE \
> power_parameters_power_id=$POWER_ID \
> power_parameters_power_address=$POWER_ADDRESS \
> power_parameters_power_pass=$POWER_PASSWORD
-
$ARCH: This field refers to the architecture of the machine being added,amd64in the local laptop example. -
$MAC_ADDRESS: This is the MAC address of the boot-enabled NIC for the machine being added. Note that the MAC address entered here must use a colon (":") separator, although some MAC addresses are written with dash ("-") separators. -
$POWER_TYPE: You must select the power type supported by the machine you are adding, and fill in additional required fields that appear. See Power management for details on the available power types and the relevant parameters for each type. In this example, we’ve used a “virsh” power type (a libvirt KVM), but your choice will depend on your hardware. -
$POWER_ID: This is generally the UUID of the machine being added. -
$POWER_ADDRESS/$POWER_PASSWORD: In the case of a KVM, these are the only parameters that need to be entered. See Power types in the API reference for details on the available power types and the relevant parameters for each type.
Normally, when you add a machine manually, MAAS will immediately attempt to commission the machine. Note that you will need to configure the underlying machine to boot over the network, or commissioning will fail. MAAS cannot handle this configuration for you. While the correct method for configuring network boot depends heavily on your server, there are two common elements:
-
The network card on your server must be able to support PXE, i.e., your NIC – whether independent or integrated on a motherboard – must have a boot PROM that supports network booting. You’ll need to consult the documentation for the machine in question to determine this.
-
You usually have to interrupt the boot process and enter the BIOS/UEFI menu to configure the network card’s PXE stack. Again, you may need to consult your machine’s documentation to pin down this step.
Additional steps will vary widely by machine type and architecture.
About 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.
For IPMI machines, you only need to provide IPMI credentials. MAAS automatically discovers the machine and runs enlistment configuration by matching the BMC address.
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.
How to add machines via a chassis
Use the chassis feature to add multiple machines at once. This feature can only be done via the MAAS UI.
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.