How to find machines
The Machines and Devices pages contain a powerful interactive search bar that lets you filter machines and devices. This article is designed to help you understand how to use this resource.
This article will explain:
- How to do simple searches
- How to do filtered searches
- How to create manual filters
- How to set up exact matching
- How to set up partial matching
- How to include multiple search terms
This article also includes a filter properties reference
A valid MAAS search parameter looks like this:
Each search attribute is placed in the Search box, separated by spaces (if it’s an “AND” search operation), or by parentheses and commas (if’s it’s an “OR” operation). Specific search parameters use the notation “parameter-name” followed by a colon (":"). For example, here we’re searching for “pod:”, which equates to the pod name (VM name).
You can match exactly by using the equals sign ("=") with a filter fragment, or make a partial match by excluding the “=”. You can get an idea how these parameters work by using the filter dropdowns in the UI, which generate a valid search expression in the “Search” box. There is also a “not” operator ("!") which can be applied to partial or exact matches.
To begin searching, enter your search text. As you type, MAAS will update search results in real time. You can search across virtually every parameter, including domain, name, tag, power type, IP, status, zone, and so on.
Filter your searches to major categories by selecting one from the Filters drop-down menu next to the search bar.
For example, to find all “New” machines containing the name or tag ‘quail’, select Status/New from the drop-down Filters menu, and then type the word ‘quail’ next to it:
Enter filters manually in the search bar to more precisely control your searches:
Note: Surround search terms with parentheses when they must occur together, e.g.,
If you need an exact match, preface the search value with an equal sign. For example, to find machines belonging to a pod named
Without an equal sign, MAAS returns partial matches. For example, the following will display all machines belonging to pods with names containing
MAAS uses Boolean AND logic to evaluate multiple search terms. For example, when you type
pod:able,cattle cpu:=5, MAAS displays machines that belong to pods with names containing
cattle AND having 5 CPU cores. Similarly, if you enter multiple words into the search tool, e.g.,
steady able, MAAS will display machines matching both terms (e.g.,
The following table describes the expanded filter set for the MAAS machine list:
- Items marked “Dyn” are dynamic, populated based on existing data, that is, the “Tags” filter only shows tags that currently exist.
- Items which are not dynamic present the entire range of possible values, regardless of whether that value currently exists in MAAS; for example, all machine status values are available to be filtered, even if no machines currently have that status.
- Items marked “Grp” can be used to group machines, instead of the default machine status.
- Items marked “Man” must be manually entered, i.e., they are not in the UI filter dropdown, but can be entered in the “Search” box if properly formatted (as in the examples given).
See How to search MAAS for more details on how to use these parameters.
|Parameter (bold) w/example||Shows nodes…||Dyn||Grp||Man|
|arch:(!=architecture)||NOT with “architecture”||Dyn|
|zone:(!=zone-name)||NOT in “zone-name”||Dyn|
|pool:(!=resource-pool)||NOT in “resource-pool”||Dyn|
|pod:(!=pod-name)||NOT with “pod-name”||Dyn|
|pod_type:(=pod-type)||with power type “pod-type”||Dyn||Grp||Man|
|pod_type:(!=pod-type)||NOT with power type “pod-type”||Dyn||Man|
|domain:(!=domain-name)||NOT with “domain-name”||Dyn||Man|
|status:(!=op-status)||NOT having “op-status”||Dyn|
|owner:(=user)||owned by “user”||Dyn||Grp|
|owner:(!=user)||NOT owned by “user”||Dyn|
|power_state:(!=power-state)||NOT having “power-state”||Dyn||Man|
|tags:(=tag-name)||with tag “tag-name”||Dyn|
|tags:(!=tag-name)||NOT with tag “tag-name”||Dyn|
|fabrics:(!=fabric-name)||NOT in “fabric-name”||Dyn|
|fabric_classes:(!=fabric-class)||NOT in “fabric-class”||Dyn||Man|
|fabric_name:(!=fabric-name)||NOT in “boot-interface-fabric”||Dyn||Man|
|subnets:(=subnet-name)||attached to “subnet-name”||Dyn|
|subnets:(!=subnet-name)||Not attached to “subnet-name”||Dyn|
|link_speed:(!link-speed)||NOT having “link-speed”||Dyn||Man|
|vlans:(=vlan-name)||attached to “vlan-name”||Dyn|
|vlans:(!=vlan-name)||NOT attached to “vlan-name”||Dyn|
|total_storage:(!total-stg-MB)||NOT having “total-stg-MB”||Dyn||Man|
|cpu_count:(!cpu-count)||NOT having “cpu-count”||Dyn||Man|
|mem:(!ram-in-MB)||NOT having “ram-in-MB”||Dyn||Man|
|mac_address:(=MAC)||having MAC address “MAC”||Dyn||Man|
|agent_name:(=agent-name)||Include nodes with agent-name||Dyn||Man|
|agent_name:(!=agent-name)||Exclude nodes with agent-name||Dyn||Man|
|osystem:(=os-name)||The OS of the desired node||Dyn||Man|
|osystem:(!=os-name)||OS to ignore||Dyn||Man|
|distro_series:(=distro-name)||Include nodes using distro||Dyn||Man|
|distro_series:(!=distro-name)||Exclude ndoes using distro||Dyn||Man|
|ip_addresses:(=ip-address)||Node’s IP address||Dyn||Man|
|ip_addresses:(!=ip-address)||IP address to ignore||Dyn||Man|
|workloads:(=annotation-text)||Node’s workload annotations||Dyn|
|workloads:(!=annotation-text)||Node’s workload annotations||Dyn|
|physical_disk_count:(disk-count)||Physical disk Count||Dyn||Man|
|physical_disk_count:(!disk-count)||Physical disk Count||Dyn||Man|
|pxe_mac:(=PXE-MAC)||Boot interface MAC address||Dyn||Man|
|pxe_mac:(!=PXE-MAC)||Boot interface MAC address||Dyn||Man|
|simple_status:(=status-val)||Include nodes with simple-status||Dyn||Man|
|simple_status:(!=status-val)||Exclude nodes with simple-status||Dyn||Man|