Commissioning scripts reference

This document provides technical details about commissioning scripts. For the corresponding details about test scripts, see Hardware test scripts reference.

Metadata field reference

Metadata fields tell MAAS when to use the script, how it should run, and what information it’s gathering. A script can employ some combination of the following seventeen fields:

Parameter reference

Scripts can accept exactly three types of parameters, and only three types:

1. storage.
2. interface.
3. URL.

The values of these parameters are strictly checked against existing disks (storage), working interfaces (interface), and valid URLs (URL) No other types of information can be passed as parameters; they are not configured to pass user-specified data.

Parameters are automatically switched by MAAS to match the device being tested, to allow one test to be run against multiple devices at the same time while keeping separate logs. For this reason, you may only specify parameters within the embedded YAML of the script, and they must 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 five fields:

Example script using default values:

#!/usr/bin/env python3

# --- Start MAAS 1.0 script metadata ---
# name: example
# parallel: instance
# parameters:
#   storage: {type: storage}
# --- End MAAS 1.0 script metadata ---

import argparse

parser = argparse.ArgumentParser(description='')
parser.add_argument(
    '--storage', dest='storage', required=True,
    help='path to storage device you want to test. e.g. /dev/sda')
args = parser.parse_args()

print("Testing: %s" % args.storage)

Example script using customised parameters:

#!/bin/bash

# --- Start MAAS 1.0 script metadata ---
# name: example
# parallel: instance
# parameters:
#   storage:
#     type: storage
#     argument-format: '{model}' '{serial}'
# --- End MAAS 1.0 script metadata ---

echo "Model: $1"
echo "Serial: $2"

Environment variable reference

The following seven environment variables are available when a script runs within the MAAS environment:

1. OUTPUT_STDOUT_PATH: The path to the log of STDOUT from the script.
2. OUTPUT_STDERR_PATH: The path to the log of STDERR from the script.
3. OUTPUT_COMBINED_PATH: The path to the log of the combined STDOUT and STDERR from the script.
4. RESULT_PATH: Path for the script to write a result YAML.
5. DOWNLOAD_PATH: The path where MAAS will download all files.
6. RUNTIME: The amount of time the script has to run in seconds.
7. HAS_STARTED: When ‘True’, MAAS has run the script once before but not to completion. Indicates the machine has rebooted.

Commissioning script example: Configure HPA

Below is a sample script to configure an Intel C610/X99 HPA controller on an HP system. The script will only run on systems with an Intel C610/X99 controller identified by the PCI ID 8086:8d06.

Before the script runs, MAAS will download and install the HP RESTful Interface Tool↗ package from HP. After the script completes, the built-in commissioning scripts will be re-run to capture the new configuration.

#!/bin/bash -ex
# --- Start MAAS 1.0 script metadata ---
# name: hp_c610_x99_ahci
# title: Configure Intel C610/X99 controller on HP systems
# description: Configure Intel C610/X99 controller on HP systems to AHCI
# script_type: commissioning
# tags: configure_hpa
# packages:
#  url: http://downloads.linux.hpe.com/SDR/repo/hprest/pool/non-free/hprest-1.5-26_amd64.deb
# for_hardware: pci:8086:8d06
# recommission: True
# --- End MAAS 1.0 script metadata ---
output=$(sudo hprest get EmbeddedSata --selector HpBios.)
echo $output
if [ $(echo $output | grep -c 'EmbeddedSata=Raid') ]; then
    echo "Server is in Dynamic Smart Array RAID mode. Changing to SATA AHCI support mode."
    sudo hprest set EmbeddedSata=Ahci --selector HpBios. --commit
else:
    echo "No changes made to the system, Server is Already in AHCI Mode"
fi

Commissioning script example: Update firmware

Below is a sample script to update the mainboard firmware on an ASUS P8P67 Pro using a vendor-provided tool. The tool is automatically downloaded and extracted by MAAS. The script reboots the system to complete the update. The system will boot back into the MAAS ephemeral environment to finish commissioning and (optionally) testing.

NOTE: Currently, MAAS does not support vendor tools which use UEFI boot capsules or need to store resource files on disk while rebooting.

#!/bin/bash -ex
# --- Start MAAS 1.0 script metadata ---
# name: update_asus_p8p67_firmware
# title: Firmware update for the ASUS P8P67 mainboard
# description: Firmware update for the ASUS P8P67 mainboard
# script_type: commissioning
# tags: update_firmware
# packages:
#  url: http://example.com/firmware.tar.gz
# for_hardware: mainboard_product:P8P67 PRO
# may_reboot: True
# --- End MAAS 1.0 script metadata ---
$DOWNLOAD_PATH/update_firmware
reboot