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

To add a machine manually,

  1. Select Machines.

  2. Select *Add hardware > Machine.

  3. Fill in the form and select Save machine to register your choice.

  4. Alternatively, you can select Save and add another to register your choice and repeat the form to add another 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 reference for details on the available power types and the relevant parameters for each type.

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 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 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, 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

You can 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. The required fields will change based on the type of chassis you choose.

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

You can 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.

You cannot add machines via chassis with the MAAS CLI.

Delete USB and PCI

You can delete USB and PCI devices via the MAAS CLI.

USB and PCI devices are not visible in MAAS 2.9.

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.

USB and PCI devices are not visible in MAAS 2.9.

Clone machines

  1. Select Machines.

  2. Checkbox the machine you want to overwrite with a cloned copy of another machine.

  3. Select Actions > Clone from.

  4. Select the source machine.

  5. Select what to clone.

  6. Select Clone to machine.

Cloning example

Assume you have two machines available, like this:

Select the machine to which you want to clone configuration, and select “Clone from…”

Under “1. Select the source machine” – choose a machine from the attached list:

Under “2. Select what to clone”, choose “Network”, “Storage”, or both (here, we’ve chosen “Storage”):

Click “Clone to machine”. MAAS will report the status of the attempt.

Machine cloning is only possible via the UI in MAAS versions 3.1 and higher.

Machine cloning is only possible via the UI.

Machine cloning is only possible via the UI in MAAS versions 3.1 and higher.

List machines

To view the machine list, simply select Machines.

To view the machine list, select “Machines” on the top menu of the MAAS web UI:

To quickly view more details, roll the cursor over status icons:

To view the machine list, enter a command similar to this one:

maas $PROFILE machines read | jq -r '(["HOSTNAME","SYSID",
"POWER","STATUS","OWNER", "TAGS", "POOL","VLAN","FABRIC",
"SUBNET"] | (., map(length*"-"))),(.[] | [.hostname, .system_id, 
.power_state, .status_name, .owner // "-",.tag_names[0] // "-", 
.pool.name,.boot_interface.vlan.name,.boot_interface.vlan.fabric,
.boot_interface.links[0].subnet.name]) | @tsv' | column -t

This will return a relatively compact machine listing:

HOSTNAME      SYSID   POWER  STATUS     OWNER  TAGS                 POOL     VLAN      FABRIC    SUBNET
 --------      -----   -----  ------     -----  ----                 ----     ----      ------    ------
 lxd-vm-1      r8d6yp  off    Deployed   admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 lxd-vm-2      tfftrx  off    Allocated  admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 lxd-vm-3      grwpwc  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 lxd-vm-4      6s8dt4  off    Deployed   admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 lxd-vm-5      pyebgm  off    Allocated  admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 lxd-vm-6      ebnww6  off    New        -      pod-console-logging  default  untagged  fabric-1  
 libvirt-vm-1  m7ffsg  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 libvirt-vm-2  kpawad  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 libvirt-vm-3  r44hr6  error  Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 libvirt-vm-4  s3sdkw  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 libvirt-vm-5  48dg8m  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
 libvirt-vm-6  bacx77  on     Deployed   admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24

You can view various details for your machines, by changing the jq command as desired:

maas admin machines read | jq -r '(["HOSTNAME","SYSID","POWER","STATUS",
"OWNER", "TAGS", "POOL", "VLAN","FABRIC","SUBNET"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id, .power_state, .status_name, .owner // "-", 
.tag_names[0] // "-", .pool.name,
.boot_interface.vlan.name, .boot_interface.vlan.fabric,
.boot_interface.links[0].subnet.name]) | @tsv' | column -t

This command, for example, will display machine power status, life-cycle status, and various networking parameters:

HOSTNAME      SYSID   POWER  STATUS     OWNER  TAGS                 POOL     VLAN      FABRIC    SUBNET
--------      -----   -----  ------     -----  ----                 ----     ----      ------    ------
lxd-vm-1      r8d6yp  off    Deployed   admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
lxd-vm-2      tfftrx  off    Allocated  admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
lxd-vm-3      grwpwc  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
lxd-vm-4      6s8dt4  off    Deployed   admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
lxd-vm-5      pyebgm  off    Allocated  admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
lxd-vm-6      ebnww6  off    New        -      pod-console-logging  default  untagged  fabric-1  
libvirt-vm-1  m7ffsg  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
libvirt-vm-2  kpawad  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
libvirt-vm-3  r44hr6  error  Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
libvirt-vm-4  s3sdkw  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
libvirt-vm-5  48dg8m  off    Ready      -      pod-console-logging  default  untagged  fabric-1  10.124.141.0/24
libvirt-vm-6  bacx77  on     Deployed   admin  pod-console-logging  default  untagged  fabric-1  10.124.141.0/24

View machine details

To open a detailed view of a machine’s status and configuration:

  1. Select Machines.

  2. Click on a machine name.

To open a detailed view of a machine’s status and configuration, click a machine’s FQDN or MAC address:

To view output similar to the MAAS UI machine details page, execute the following shell script:

#!/bin/nohighlight

maas admin machine read r3rd6h | jq '.' > /tmp/machine-json
cat /tmp/machine-json | jq -r '([.hostname,.status_name,"| Power:",.power_state,"| Kernel:",.hwe_kernel,"| Owner:",.owner]) | @tsv' | column -t -o " " > /tmp/machine-details
cat /tmp/machine-json | jq -r '(["CPU:",.architecture,"/",.cpu_count,"core(s) /",.cpu_speed,"Mhz","| Type:",.hardware_info.cpu_model]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["Memory:",.memory,"MB | Storage:",.storage,"MB | Power type:",.power_type]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["Zone:",.zone.name,"| Resource pool:",.pool.name,"| Domain:",.domain.name]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["Tags:",.tag_names[]]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["SYSTEM Vendor:",.hardware_info.system_vendor,"| Product:",.hardware_info.system_product]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '([".......Vsn:",.hardware_info.system_version,"| Serial:",.hardware_info.system_serial]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["MAINBOARD Vendor:",.hardware_info.mainboard_vendor,"| Product:",.hardware_info.mainboard_product]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["..........Firmware:",.hardware_info.mainboard_firmware_vendor]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["..........Firmware Vsn:",.hardware_info.mainboard_firmware_version,"| Date:",.hardware_info.mainboard_firmware_date]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '(["NETWORK: Vendor:",.boot_interface.vendor]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '([".........Name:",.boot_interface.name,"| MAC:",.boot_interface.mac_address,"| Link speed:",.boot_interface.link_speed,"Mbps"]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-json | jq -r '([".........Fabric:",.boot_interface.vlan.fabric,"| MAAS DHCP:",.boot_interface.vlan.dhcp_on,"| SR-IOV:",.boot_interface.sriov_max_vf]) | @tsv' | column -t -o " " >> /tmp/machine-details
cat /tmp/machine-details

This shell script should produce output similar to the following:

merry-cobra Deployed | Power: on | Kernel: ga-20.04 | Owner: admin
CPU: amd64/generic / 1 core(s) / 1600 Mhz | Type: Intel(R) Core(TM) i5-8265U CPU
Memory: 2048 MB | Storage: 8000.004096 MB | Power type: lxd
Zone: default | Resource pool: default | Domain: maas
Tags: pod-console-logging virtual
SYSTEM Vendor: QEMU | Product: Standard PC (Q35 + ICH9, 2009)
.......Vsn: pc-q35-5.2 | Serial: Unknown
MAINBOARD Vendor: Canonical Ltd. | Product: LXD
..........Firmware: EFI Development Kit II / OVMF
..........Firmware Vsn: 0.0.0 | Date: 02/06/2015
NETWORK: Vendor: Red Hat, Inc.
.........Name: enp5s0 | MAC: 00:16:3e:cc:17:58 | Link speed: 0 Mbps
.........Fabric: fabric-5 | MAAS DHCP: true | SR-IOV: 0

Find network info

To find network info for a specific machine:

  1. Select Machines.

  2. Click on a machine name.

  3. Select Network.

To find network info for a specific machine, open that machine’s “Network” tab in the machine summary:

Options on this tab are described in the introduction to Networking article in this documentation set.

To find network info, use the MAAS UI.

Find storage info

To view/edit machine storage info:

  1. Select Machines.

  2. Click on a machine name.

  3. Select Storage.

To view/edit machine storage info, click on the “Storage” tab in the machine summary:

See the section about storage for more information.

To find network info, use the MAAS UI.

View PCI devices

To view the list of PCI devices associated with a given machine:

  1. Select Machines.

  2. Click on a machine name.

  3. Select *PCI devices

To view PCI devices, use the MAAS 3.4 UI.

To view PCI devices, use the MAAS 3.4 UI.

View USB devices

To view the list of USB devices associated with a given machine:

  1. Select Machines.

  2. Click on a machine name.

  3. Select USB.

To view USB devices, use the MAAS 3.4 UI.

To view USB devices, use the MAAS 3.4 UI.

Find commissioning logs

To view commissioning logs for a given machine:

  1. Select Machines.

  2. Click on a machine name.

  3. Select Commissioning.

  4. To examine an individual log, select View details at the end of the row for that log.

  5. To review the commissioning history, select View previous tests at the end of the row for that log.

The “Commissioning” tab brings up a summary log of commissioning events:

Click on the drop-down at the end of the row you’re interested in, and click on “View details”:

This will bring up a detailed log view for that row:

These logs present an extremely detailed, timestamped record of completion and status items from the commissioning process. See the article on logging for more details on how to read and interpret these logs.

To find commissioning logs, use the MAAS UI.

Find test logs

To view commissioning logs for a given machine:

  1. Select Machines.

  2. Click on a machine name.

  3. Select Test.

  4. To examine an individual log, select View details at the end of the row for that log.

  5. To review the commissioning history, select View previous tests at the end of the row for that log.

This tab presents a summary of tests run against this particular machine. You can view the summary report, or choose the “View details” drop-down to get details on any particular tests:

The format of these screens is very similar to the Configuration logs shown above.

To find test logs, use the MAAS UI.

Find raw log output

  1. Select Machines.

  2. Click on the machine name.

  3. Select Logs.

  4. Select Installation output.

By choosing “Installation output” on the “Logs” tab, you can see the “raw” log output:

Help interpreting these logs can be found under the logging section of this documentation.

To find raw log output, use the MAAS UI.

Find event logs

  1. Select Machines.

  2. Click on the machine name.

  3. Select Logs.

  4. Using the Download drop-down, you can download logs in various formats.

To view the Event log for a machine, choose the “Event” tab under “Logs.” This displays a list of timestamped status updates for events and actions performed on the machine:

There is a drop-down on the upper right which allows you to choose how many events per page you wish to view. Detailed discussion of this event log can be found under the logging section of this documentation.

To find event logs, use the MAAS UI.

Find config info

  1. Select Machines.

  2. Click on the machine name.

  3. Select Configuration.

The final tab from the Machine menu allows you to update machine and power configuration options:

There are two sections to this tab. The “Machine configuration” section, shown above, offers some general parameters, mostly related to how this machine is grouped and categorised. More information on these options are found in the relevant sections of the documentation (e.g., tags, resource pools, and so forth).

The “Power configuration” supplies the parameters necessary for MAAS to access the machine to PXE-boot it:

More information on Power configuration will be found in the Power management section of this documentation.

To find config info, use the MAAS UI.


Last updated 20 days ago.