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.
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:
The fields on the “Add machine” screen include the following items:
-
Machine name: This field is used to identify the machine to the user. It can be set to anything, though it is often set to the MAC address of the machine in question. This field is optional, in that MAAS will assign a unique, nonsense name if you leave it blank. You can change this nonsense name later, if desired.
-
Domain: This field sets the domain name of the domain managed by MAAS. It can be set to anything; MAAS assigns the domain name “maas” by default.
-
Architecture: This field refers to the architecture of the machine being added.
-
Minimum Kernel: This field supplies a drop-down of possible kernels available for deployment on this machine.
-
Zone: This field allows you to set the availability zone, selected from AZs that you have already created (if any).
-
Resource pool: This field allows you to set the resource pool for this machine, selected from pools you have already created (if any).
-
MAC Address: You should fill in this field with the MAC address of the machine you are adding. 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.
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.
About disabling individual boot methods
In MAAS 3.0, it is possible to diable individual boot methods. This must be done via the CLI. When a boot method is disabled MAAS will configure MAAS controlled isc-dhcpd to not respond to the associated boot architecture code. External DHCP servers must be configured manually.
To allow different boot methods to be in different states on separate physical networks using the same VLAN ID configuration is done on the subnet in the UI or API. When using the API boot methods to be disabled may be specified using the MAAS internal name or boot architecture code in octet or hex form. For example the following disabled i386/AMD64 PXE, AMD64 UEFI TFTP, and AMD64 UEFI HTTP
maas $PROFILE subnet \
update $SUBNET \
disabled_boot_architectures="0x00 uefi_amd64_tftp 00:10"
Specifically, for MAAS 3.0, the following changes have been implemented:
- UEFI AMD64 HTTP(00:10) has been reenabled.
- UEFI ARM64 HTTP(00:13) has been enabled.
- UEFI ARM64 TFTP(00:0B) and UEFI ARM64 HTTP(00:13) will now provide a shim and GRUB signed with the Microsoft boot loader keys.
- grub.cfg for all UEFI platforms has been updated to replace the deprecated
linuxefiandinitrdeficommands with the standardlinuxandinitrdcommands. - GRUB debug may now be enabled by enabling rackd debug logging.