How to manage machines

*Errors or typos? Topics missing? Hard to read? Let us know.

Most of the day-to-day work of managing machines is covered here. Utilising machines to do work – for example, commissioning, testing, and deploying them – is discussed in How to deploy machines.

Add machines

In the MAAS UI, select Machines > Add hardware > Machine > fill in the form > Save machine (or Save and add another). The fields in this form are as follows:

  • 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 reference for details on the available power types and the relevant parameters for each type.

To create a new machine at the command line, enter the following command:

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, amd64 in 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 reference 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.

Add machines via chassis (UI)

You can use the chassis feature to add multiple machines at once. To do this, select Machines > Add hardware > Chassis > fill in the form > *Save…" The required fields will change based on the type of chassis you choose.

Delete USB and PCI (CLI)

Note that USB and PCI devices are not visible in MAAS 2.9 and below.

To delete PCI/USB devices from the machine in any machine state, use the following command:

maas $PROFILE node-device delete $SYSTEM_ID $DEVICE_ID

where:

  • $PROFILE = your user profile (e.g., “admin”)
  • $SYSTEM_ID = the ID of the machine in question (e.g., “ngx7ry”)
  • $DEVICE_ID = the ID of the device you want to delete

If the device is still present in the system, it will be recognised again (and thus “recreated”) when the machine is commissioned again.

Clone machines (MAAS 3.1 and above, UI only)

To clone machines, select Machines > choose machine > Actions > Clone from > > > Clone to machine.

Soft power off (MAAS 3.5 and above, UI only)

To power-off machines “softly” – that is, by asking the deployed OS to shut down gracefully – choose Machines >