Hardware Testing Script Metadata

Hardware testing scripts are used to evaluate system hardware, and you can run your own from
both the web UI and from the command line.

This page explains the various metadata fields used within these scripts, along with how
parameters are passed to scripts and how any results are returned.

Metadata fields
Metadata fields tell MAAS when the script should be used, how it should be run, and what
information a script is gathering. A script can have the following fields:

 name: Corresponds to the script's filename.

 title: Human-friendly descriptive version of name, used within the web UI.
 description: Brief outline of what the script does.
 tags: List of tags associated with the script.
 type: Either commissioning or testing.
 timeout: Length of time before MAAS automatically fails and kills execution of the script.
 destructive: True or False, depending on whether the script will overwrite system data.
 comment: Describes changes made in this revision of the script.
 hardware_type: Defines the type of hardware the script configures or tests. If the script
returns results, hardware type dictates what hardware the results are associated with. The
following types are valid:
o node: Not associated with any hardware type. This is the default.
o cpu: Configures or tests the CPUs on the node.
o memory: Configures or tests memory on the node.
o storage: Configures or test storage on the node. Each storage result may be associated
with a block device on the system.
 parallel: Enables scripts to be run in parallel and can be one of the following:
o disabled: The script will run serially on its own.
o instance: Runs in parallel only with other instances of the same script.
o any: Runs in parallel alongside any other scripts with parallel set to any.
 packages: List of packages to be installed or extracted before running the script.
Packages may be specified as a JSON string, a list of strings, or as a dictionary. For
example, packages: {apt: stress-ng}, would ask apt to install stress-ng. Package
sources can be any of the following:
o apt: Used by default if the source is omitted.
o snap: Installs packages using snap. May also be a list of dictionaries. The dictionary must
define the name of the package to be installed, and optionally, the channel, mode and
revision.
o url: The archive will be downloaded and, if possible, extracted. URL_DIR will be exported
to the script as an environment variable.

Environment variables
The following environment variables are available when a script is run within the MAAS
environment:

 OUTPUT_STDOUT_PATH: The path to the log of STDOUT from the script.

 OUTPUT_STDERR_PATH: The path to the log of STDERR from the script.
 OUTPUT_COMBINED_PATH: The path to the log of the combined STDOUT and STDERR from the
script.
 RESULT_PATH: Path for the script to write a result YAML to.

Parameters
Scripts can accept values defined within the parameters field. Parameter values can then be set
by users before commissioning or before testing. The default values are used if they are run as a
group action, or automatically by MAAS.

Parameters may only be defined within the embedded YAML of the script, and they take the
form of a dictionary of dictionaries.

The key of the dictionary must be a string and it's this string that's used by the UI and API when
users are setting parameter values during commissioning or testing.

The value is a dictionary with the following fields:

 type: Every parameter must contain a type field. This describes what the parameter may
accept and its default values. It may be one of the following:
o storage: Allows the selection of a strong device on the node being run.
o runtime: The amount of time the script should run for. This will be passed to the script in
seconds.
 min: The minimum numeric value an input is allowed to have. Only applicable to runtime
and defaults to 0.
 max: The maximum numeric value an input is allowed to have. Only applicable to
runtime. The default is unlimited.
 title: The title of the parameter field when displayed in the UI. The following types
have the following default values:
o storage: Storage device.
o runtime: Runtime.
 argument-format: Specifies how the argument should be passed to the script. Input is
described as {input}.

The storage type may also use {name}, {path}, {model} or {serial}. MAAS will lookup the
values of path, model, and serial based on user selection. For storage, {input} is synonymous
with {path}.

The following types have the following default values: - storage: --storage={path} - runtime:
--runtime={input}
  default: The default value of the parameter. The following types have the following default
values. Setting these to '' or None will override these values:
 storage: all.
 runtime: If set, the runtime value of the script.
 required: Whether or not user input is required. If set to false, no default is set and no
user input will mean the parameter is not passed to the script. Defaults to true.
 results: What results the script will return on completion. This may only be defined
within the embedded YAML of the script. Results may be a list of strings or a dictionary
of dictionaries.

Results
A script can output its results to a YAML file and those results will be associated with the
hardware type defined within the script.

If the hardware type is storage, for example, and the script accepts a storage type parameter, the
result will be associated with a specific storage device.

The YAML file must represent a dictionary with the following fields:

 result: The completion status of the script. This can be either passed, failed or
degraded. If no status is defined, an exit code of 0 indicates a pass while a non-zero value
indicates a failure.
 results: A dictionary of results. The key may map to a results key defined as embedded
YAML within the script. The value of each result must be a string or a list of strings.
Advanced CLI Tasks
This is a list of advanced tasks to perform with the MAAS CLI. See MAAS CLI on how to get
started.

Update node hostname and power parameters

To update the hostname and power parameters of a node:

maas $PROFILE machine update $SYSTEM_ID \

hostname=$HOSTNAME \
power_type=$POWER_TYPE \
power_parameters_power_address=$POWER_ADDRESS \
power_parameters_power_id=$HOSTNAME

For example, to configure a KVM-based node:

maas $PROFILE machine update $SYSTEM_ID \

hostname=$HOSTNAME \
power_type=virsh \
power_parameters_power_address=qemu+ssh://ubuntu@$KVM_HOST/system \
power_parameters_power_id=$HOSTNAME

See Common CLI tasks for how to find a node's system id and BMC Power Types for details on
different power types.

Relay DHCP
To relay DHCP traffic for a VLAN (source) through another VLAN (target):

maas $PROFILE vlan update $FABRIC_ID $VLAN_VID_SRC relay_vlan=$VLAN_ID_TARGET

For example, to relay VLAN with vid 0 (on fabric-2) through VLAN with id 5002 :

maas $PROFILE vlan update 2 0 relay_van=5002

See DHCP relay for more information.

Assign a network interface to a fabric

This task is made easier with the aid of the jq utility. It filters the maas command (JSON
formatted) output and prints it in a desired way. This allows one to quickly view and compare
data. Go ahead and install it:

sudo apt install jq

In summary, an interface is indirectly assigned to a fabric by assigning it to a VLAN. First we
need to gather various bits of data.

List some information on all machines:

maas $PROFILE machines read | jq ".[] | \

{hostname:.hostname, system_id: .system_id, status:.status}" --compact-
output

Example output:

{"hostname":"node1","system_id":"dfgnnd","status":4}
{"hostname":"node2","system_id":"bkaf6e","status":6}
{"hostname":"node4","system_id":"63wqky","status":6}
{"hostname":"node3","system_id":"qwkmar","status":4}

Note: An interface can only be edited when the corresponding machine has a status of 'Ready'.
This is numberically denoted by the integer '4'.

List some information for all interfaces on the machine in question (identified by its system id
'dfgnnd'):

maas $PROFILE interfaces read dfgnnd | jq ".[] | \

{id:.id, name:.name, mac:.mac_address, vid:.vlan.vid,
fabric:.vlan.fabric}" --compact-output

Example output:

{"id":8,"name":"eth0","mac":"52:54:00:01:01:01","vid":0,"fabric":"fabric-1"}
{"id":9,"name":"eth1","mac":"52:54:00:01:01:02","vid":null,"fabric":null}

List some information for all fabrics:

maas $PROFILE fabrics read | jq ".[] | \

{name:.name, vlans:.vlans[] | {id:.id, vid:.vid}}" --compact-output

Example output:

{"name":"fabric-0","vlans":{"id":5001,"vid":0}}
{"name":"fabric-1","vlans":{"id":5002,"vid":0}}
{"name":"fabric-2","vlans":{"id":5003,"vid":0}}

This example will show how to move interface '8' (on machine 'dfgnnd') from 'fabric-1' to 'fabric-
0'. Based on the gathered information, this will consist of changing the interface's VLAN from
'5002' to '5001':

maas $PROFILE interface update dfgnnd 8 vlan=5001 >/dev/null

Verify the operation by relisting information for the machine's interface:

maas $PROFILE interfaces read dfgnnd | jq ".[] | \
{id:.id, name:.name, mac:.mac_address, vid:.vlan.vid,
fabric:.vlan.fabric}" --compact-output

The output shows that the interface is now on fabric-0:

{"id":8,"name":"eth0","mac":"52:54:00:01:01:01","vid":0,"fabric":"fabric-0"}
{"id":9,"name":"eth1","mac":"52:54:00:01:01:02","vid":null,"fabric":null}

Change the IP assignment mode of a network interface

To edit the IP assignment mode of a network interface the existing subnet link first needs to be
removed.

Begin by finding the interface ID as well as the interface's subnet link ID with the command:

maas $PROFILE node read $SYSTEM_ID

Once that's done, proceed to unlink and link:

maas $PROFILE interface unlink-subnet $SYSTEM_ID $INTERFACE_ID

id=$SUBNET_LINK_ID
maas $PROFILE interface link-subnet $SYSTEM_ID $INTERFACE_ID mode=$IP_MODE
subnet=$SUBNET_CIDR [$OPTIONS]

For instance, to have interface '58', with subnet link '146', on node 'exqn37' use DHCP on subnet
'192.168.1.0/24':

maas $PROFILE interface unlink-subnet exqn37 58 id=146

maas $PROFILE interface link-subnet exqn37 58 mode=dhcp subnet=192.168.1.0/24

If, instead of DHCP, a static address was desired, then the second command would have looked
like:

maas $PROFILE interface link-subnet exqn37 58 mode=static

subnet=192.168.1.0/24 ip_address=192.168.1.113

For a summary of IP assignment modes see Post-commission configuration.

Install a rack controller

To install and register a rack controller with the MAAS:

sudo apt install maas-rack-controller

sudo maas-rack register

Note: The register command is not required when the rack controller is being added to a system
that already houses an API server.
You will be asked for the URL of the region API server. If you provide a hostname ensure it is
resolvable. Next, you will be prompted for the secret key that is stored in file
/var/lib/maas/secret on the API server.

You can get the above information from the web UI by visiting the 'Nodes' page, then the
Controller tab, and clicking the button 'Add rack controller'. Here is an example of what you may
see:

Based on the above, then, we could have also entered:

sudo maas-rack register --url http://10.5.1.5:5240/MAAS \

--secret fa847000e7cb681101d26e3477e6e39e

See Rack controller for an overview.

List rack controllers

To list all rack controllers registered with the region:

maas $PROFILE rack-controllers read | grep hostname | cut -d '"' -f 4

Set the default storage layout
To set the default storage layout for all nodes:

maas $PROFILE maas set-config name=default_storage_layout value=$LAYOUT_TYPE

For example, to set the default layout to Flat:

maas $PROFILE maas set-config name=default_storage_layout value=flat

Important: The new default will only apply to newly-commissioned nodes.

See Storage for more details on MAAS storage features.

Set a storage layout

An administrator can set a storage layout for a node with a status of 'Ready' like this:

maas $PROFILE machine set-storage-layout $SYSTEM_ID

storage_layout=$LAYOUT_TYPE [$OPTIONS]

For example, to set an LVM layout where the logical volume has a size of 5 GB:

maas $PROFILE machine set-storage-layout $SYSTEM_ID storage_layout=lvm

lv_size=5368709120

All storage sizes are currently required to be specified in bytes.

Warning: This will remove the configuration that may exist on any block device.

Create an alias (CNAME) record in DNS

An administrator can set a DNS Alias (CNAME record) to an already existing DNS entry of a
node.

mass $PROFILE dnsresource-records create fqdn=$HOSTNAME.$DOMAIN rrtype=cname

rrdata=$ALIAS

For example, to set webserver.maas.io to alias to www.maas.io:

maas $PROFILE dnsresource-records create fqdn=webserver.maas.io rrtype=cname

rrdata=www

Create a Mail Exchange pointer record in DNS

An administrator can set a DNS Mail Exchange pointer record (MX and value) to a domain.
maas $PROFILE dnsresource-records create fqdn=$DOMAIN rrtype=mx rrdata='10
$MAIL_SERVER.$DOMAIN'

For example, to set domain.name managed by MAAS to have an MX record and that you own
the domain:

maas $PROFILE dnsresource-records create fqdn=maas.io rrtype=mx rrdata='10

smtp.maas.io'