Machines (snap/3.0/UI)

2.9 3.0

Machines are the heart of MAAS. They are the backbone of your data centre application(s), providing the functions that are relevant to your customers. MAAS manages their transit through a life-cycle, from adding and enlistment, through commissioning, allocation, and deployment, finally being released back to the pool, or retired altogether. You can move them around, create redundant versions (even in other geographies you can access), and basically rearrange them to the extent that your network allows.

Twelve questions you may have:

  1. How are the machine states and actions related?
  2. How can I view the machine list?
  3. How can I view machine details?
  4. How can I view a machine summary?
  5. How does MAAS handle attached USB/PCI devices?
  6. Where can I find network info for a machine?
  7. Where can I find storage info for a machine?
  8. Where can I find the commissioning log for a machine?
  9. Where can I find machine hardware & test logs?
  10. Where can I find raw log output for a machine?
  11. Where can I find a machine’s event log?
  12. Where can I find machine configuration info?

For example, in the illustration below, you see a typical small hospital data centre, including servers ready and allocated for functions like Pharmacy, Orders, Charts, and so on:

These example machines would typically be duplicated in several different geographies, with a quick way to switch to a redundant node, should anything go wrong (e.g., high availability). We used the word node there because, In the network language of MAAS, machines are one of several different types of nodes. A node is simply a network-connected object or, more specifically, an object that can independently communicate on a network. MAAS nodes include controllers, network devices, and of course, machines.

Looking back at the example above, you can see that there are several columns in the machine list:

The columns list eight details for each machine:

  1. FQDN | MAC: The fully qualified domain name or the MAC address of the machine.
  2. Power: ‘On’, ‘Off’ or ‘Error’ to highlight an error state.
  3. Status: The current status of the machine, such as ‘Ready’, ‘Commissioning’ or ‘Failed testing’.
  4. Owner: The MAAS account responsible for the machine.
  5. Cores: The number of CPU cores detected on the machine.
  6. RAM: The amount of RAM, in GiB, discovered on the machine.
  7. Disks: The number of drives detected on the machine.
  8. Storage: The amount of storage, in GB, identified on the machine.

Machine life-cycle

One of the most important things to understand about machines is their life-cycle. Machines can be discovered or added, commissioned by MAAS, acquired, deployed, released, marked broken, tested, put into rescue mode, and deleted. In addition, pools, zones, and tags can be set for machines.

All of these states and actions represent the possible life-cycle of a machine. This life-cycle isn’t strict or linear – it depends on how you use a machine – but it’s useful to give a general overview of how machines tend to change states. In the discussion that follows, states and actions are shown in bold type.

  1. Machines start as servers in your environment, attached to a network or subnet MAAS can manage.

  2. If machines are configured to netboot, MAAS can discover them and present them to you for possible commissioning, changing their state to New.

  3. When you select a machine that is marked New, you can choose to commission it. If you add a machine manually, it is automatically commissioned.

  4. Machines that have successfully commissioned can be acquired and deployed. Machines that don’t successfully commission can be marked broken (and later recovered when the issues are resolved).

  5. Resolving problems with machines usually involve testing the machine.

  6. Once you’ve deployed a machine, and you’re done with it, you can release it.

  7. You can place a machine in rescue mode, which allows you to SSH to a machine to make configuration changes or do other maintenance. Once you’re done, you can exit rescue mode*.

  8. Any time a machine is on, you have the option to select it and power off that machine.

  9. You can abort any operation that’s in progress.

  10. You also have the option to set tags, availability zone, or resource pool at various stages along the way.

Since these actions are not necessarily sequential, and the available actions change as the machine state changes, it’s not very useful to make a state diagram or flowchart. Instead, consider the following table:

Action/State New Ready Acquired Deployed Locked Rescue Broken
Commission X X X
Acquire X
Deploy X X
Release X X
Power on X X
Power off
Test X X X X X
Rescue mode X X X X X
Exit rescue X
Mark broken X X
Mark fixed X
Lock X
Unlock X
Tag X X X X X X
Set zone X X X X X X
Set…pool X X X X X X
Delete X X X X X X

When a machine is in the state listed in a column, it is possible to take the row actions marked with an “X.” You access these actions from the “Take action” menu in the upper right corner of the machine listing. Note that some actions, such as “Mark broken” or “Lock,” may be hidden when they are not available.

View the machine list

You can view the list of machines from the choice “Machines” on the top menu of the MAAS web UI. This action will display a table like the one above, listing all the machines that are currently visible to your MAAS installation. During commissioning and deployment, MAAS updates the table to reflect the changing state of each machine. These values are augmented with green, amber and red icons to represent successful, in-progress and failed transitions, respectively. The MAAS web UI employs similar icons and colours throughout the interface to reflect a machine’s status.

Rolling the cursor over status icons often reveals more details. For example, a failed hardware test script will place a warning icon alongside the hardware type tested by the script. Rolling the cursor over this will reveal which test failed. Likewise, you can find some immediate options by rolling over the column data items in the machines table.

The ‘Add hardware’ drop-down menu is used to add either new machines or a new chassis. This menu changes context when one or more machines are selected from the table, using either the individual checkboxes in the first column or the column title checkbox to select all.

With one or more machines selected, the ‘Add hardware’ drop-down menu moves to the left, and is joined by the ‘Take action’ menu. This menu provides access to the various machine actions that can be applied to the selected machine(s):

The ‘Filter by’ section limits the machines listed in the table to selected keywords and machine attributes.

View machine details

Click a machine’s FQDN or MAC address to open a detailed view of a machine’s status and configuration.

The default view is ‘Machine summary’, presented as a series of cards detailing the CPU, memory, storage and tag characteristics of the machine, as well as an overview of its current status. When relevant, ‘Edit’ links take you directly to the settings pane for the configuration referenced within the card. The machine menu bar within the web UI also includes links to logs, events, and configuration options:

The menu includes links to a number of additional forms and controls, as described in the following sections.

View a machine summary

As shown above, the Machine summary presents an overview of CPU, memory, storage, tags, and general settings:

The first card presents some basics of the machine resources and configuration:

Here are some details on what this card presents, with details on in-card links described in following sections:

  • OVERVIEW the machine status (in this case “Deployed”), and lists OS version information.

  • CPU shows the specifics of the CPU(s), including a link to test the processor(s).

  • MEMORY gives the total available RAM for this machine, along with a test link.

  • STORAGE presents the total amount of storage available and the number of disks that provide that storage. There are two links here: one gives the storage layout (with the opportunity to change it for devices that are in ‘Ready’ or ‘Allocated’ states.

  • Owner identifies the owner of the machine.

  • Domain indicates the domain in which the machine exists.

  • Zone shows the AZ in which this machine resides, along with a link to edit the machine configuration (to change the AZ, if desired).

  • Resource pool shows the pool to which this machine has been assigned, and an edit link.

  • Power type gives the current power type, which links to the relevant edit form.

  • Tags presents the list of tags associated with this machine, editable via the link.

Note that clicking any of the links in this card will either present a pop-up form or take you to another item in the machine menu – so using the browser “back” button will take you completely away from this machine’s page. For example, you can choose the “Test CPU” option, which brings up this overlay:

From this screen, you can choose test scripts and run the tests (in the background) as the interface returns to the Machine summary. A linked note in the CPU block lets you know that the tests are in progress:

And you can watch the results under the “Tests” option in the Machine menu:

The rest of the cards on the Machine summary are either self-explanatory, or they’re covered in the sections below. The main point is this: You can see that nearly everything about machines takes place within the main menu’s “Machines” option. Incidentally, you can learn more about testing by visiting the Hardware testing page.

Handling attached USB and PCI devices

The machines in your MAAS may have devices attached to them via USB or PCI interface, such as keyboards, cameras, network cards, GPUs, etc. MAAS will recognize these devices and make them visible to you when a machine is commissioned.

For example, the machine details presents USB and PCI devices like this:

Note that this page now includes two new tabs: “PCI devices” and “USB.” For each USB/PCI device attached to your machine, these tabs will list:

  • device type
  • vendor ID
  • a product description
  • a product ID
  • the driver name
  • the containing NUMA node (if any)
  • the device address

A typical PCI device tab would look something like this:

The USB tab presents similar information in the same format.

If you are upgrading from a previous version of MAAS, PCI and USB devices aren’t modeled, so you will have to recommission the machine to capture these devices.

Once you’ve commissioned the machine, you have the option of deleting PCI/USB devices from the machine in any machine state, via the CLI only, using the following command:

maas $PROFILE node-device delete $SYSTEM_ID $DEVICE_ID


  • $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 recogized again (and thus “recreated”)
when the machine is commissioned again.

Find network info for a machine

The Network “tab” provides you with a way to view/edit the network and interface configuration for a machine:

In the case of this deployed machine, there are not many editing options. If the machine is in a ‘Ready’ state, though, altering the network configuration is possible, as shown in the screenshot above.

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

Find storage info for a machine

The Storage tab on the machine list brings up a form that allows you to view/edit the file system, partitioning and storage parameters for the selected machine:

This tab describes the filesystem(s) in use, as well as the available and used partitions for this machine. See the article Storage for a detailed discussion on how to use this screen, as well as many other considerations for machine storage configurations.

Find the commissioning log for you

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

Click on the dropdown 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.

Find machine hardware & test logs

This tab presents a summary of tests run against this particular machine:

You can view the summary report, or choose the “View details” dropdown to get details on any particular tests:

The format of these screens is very similar to the Configuration logs shown above. For more information, please see the article on Hardware testing.

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.

Find a machine’s event logs

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 dropdown 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.

Find machine configuration info

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.


This article has offered you a cursory glimpse into machines and how they are configured and managed in MAAS. Read on through this section of the documentation to learn more.