How to commission a machine
To commission a machine that’s in the “Ready” state, via the CLI, use the following command:
maas $PROFILE machine commission $SYSTEM_ID
Typical JSON output (long listing)
Success.
Machine-readable output follows:
{
"storage_test_status_name": "Pending",
"bcaches": [],
"cpu_count": 1,
"interface_set": [
{
"params": "",
"numa_node": 0,
"tags": [],
"id": 10,
"mac_address": "52:54:00:15:36:f2",
"vendor": "Red Hat, Inc.",
"children": [],
"effective_mtu": 1500,
"discovered": [],
"links": [],
"link_speed": 0,
"link_connected": true,
"system_id": "bhxws3",
"enabled": true,
"interface_speed": 0,
"firmware_version": null,
"name": "ens3",
"sriov_max_vf": 0,
"product": null,
"vlan": {
"vid": 0,
"mtu": 1500,
"dhcp_on": true,
"external_dhcp": null,
"relay_vlan": null,
"fabric": "fabric-2",
"primary_rack": "8dwnne",
"name": "untagged",
"id": 5003,
"space": "undefined",
"secondary_rack": null,
"fabric_id": 2,
"resource_uri": "/MAAS/api/2.0/vlans/5003/"
},
"parents": [],
"type": "physical",
"resource_uri": "/MAAS/api/2.0/nodes/bhxws3/interfaces/10/"
}
],
"network_test_status_name": "Unknown",
"numanode_set": [
{
"index": 0,
"memory": 985,
"cores": [
0
]
}
],
"locked": false,
"hardware_uuid": "F677A842-571C-4E65-ADC9-11E2CF92D363",
"default_gateways": {
"ipv4": {
"gateway_ip": null,
"link_id": null
},
"ipv6": {
"gateway_ip": null,
"link_id": null
}
},
"status_action": "",
"status_message": "Commissioning",
"cpu_test_status_name": "Unknown",
"memory_test_status": -1,
"virtualblockdevice_set": [],
"pool": {
"name": "default",
"description": "Default pool",
"id": 0,
"resource_uri": "/MAAS/api/2.0/resourcepool/0/"
},
"current_testing_result_id": 9,
"current_installation_result_id": null,
"netboot": true,
"description": "",
"special_filesystems": [],
"testing_status": 0,
"memory": 1024,
"current_commissioning_result_id": 8,
"storage": 5368.70912,
"commissioning_status": 0,
"cpu_test_status": -1,
"tag_names": [
"virtual"
],
"memory_test_status_name": "Unknown",
"swap_size": null,
"status_name": "Commissioning",
"other_test_status": -1,
"pod": null,
"storage_test_status": 0,
"blockdevice_set": [
{
"id_path": "/dev/disk/by-id/ata-QEMU_HARDDISK_QM00001",
"size": 5368709120,
"block_size": 512,
"tags": [
"ssd"
],
"serial": "QM00001",
"uuid": null,
"numa_node": 0,
"available_size": 5368709120,
"id": 3,
"partition_table_type": null,
"model": "QEMU HARDDISK",
"path": "/dev/disk/by-dname/sda",
"storage_pool": null,
"used_for": "Unused",
"filesystem": null,
"system_id": "bhxws3",
"used_size": 0,
"partitions": [],
"name": "sda",
"type": "physical",
"resource_uri": "/MAAS/api/2.0/nodes/bhxws3/blockdevices/3/"
}
],
"other_test_status_name": "Unknown",
"distro_series": "",
"testing_status_name": "Pending",
"ip_addresses": [],
"address_ttl": null,
"system_id": "bhxws3",
"physicalblockdevice_set": [
{
"firmware_version": "2.5+",
"serial": "QM00001",
"uuid": null,
"numa_node": 0,
"available_size": 5368709120,
"size": 5368709120,
"tags": [
"ssd"
],
"id": 3,
"partition_table_type": null,
"id_path": "/dev/disk/by-id/ata-QEMU_HARDDISK_QM00001",
"model": "QEMU HARDDISK",
"path": "/dev/disk/by-dname/sda",
"storage_pool": null,
"used_for": "Unused",
"filesystem": null,
"system_id": "bhxws3",
"used_size": 0,
"partitions": [],
"name": "sda",
"block_size": 512,
"type": "physical",
"resource_uri": "/MAAS/api/2.0/nodes/bhxws3/blockdevices/3/"
}
],
"fqdn": "ace-swan.maas",
"osystem": "",
"domain": {
"authoritative": true,
"ttl": null,
"resource_record_count": 0,
"name": "maas",
"id": 0,
"is_default": true,
"resource_uri": "/MAAS/api/2.0/domains/0/"
},
"boot_interface": {
"params": "",
"numa_node": 0,
"tags": [],
"id": 10,
"mac_address": "52:54:00:15:36:f2",
"vendor": "Red Hat, Inc.",
"children": [],
"effective_mtu": 1500,
"discovered": [],
"links": [],
"link_speed": 0,
"link_connected": true,
"system_id": "bhxws3",
"enabled": true,
"interface_speed": 0,
"firmware_version": null,
"name": "ens3",
"sriov_max_vf": 0,
"product": null,
"vlan": {
"vid": 0,
"mtu": 1500,
"dhcp_on": true,
"external_dhcp": null,
"relay_vlan": null,
"fabric": "fabric-2",
"primary_rack": "8dwnne",
"name": "untagged",
"id": 5003,
"space": "undefined",
"secondary_rack": null,
"fabric_id": 2,
"resource_uri": "/MAAS/api/2.0/vlans/5003/"
},
"parents": [],
"type": "physical",
"resource_uri": "/MAAS/api/2.0/nodes/bhxws3/interfaces/10/"
},
"hostname": "ace-swan",
"network_test_status": -1,
"min_hwe_kernel": "",
"power_state": "off",
"interface_test_status_name": "Unknown",
"owner_data": {},
"volume_groups": [],
"power_type": "virsh",
"node_type": 0,
"owner": "admin",
"cache_sets": [],
"architecture": "amd64/generic",
"hwe_kernel": null,
"zone": {
"name": "default",
"description": "",
"id": 1,
"resource_uri": "/MAAS/api/2.0/zones/default/"
},
"disable_ipv4": false,
"boot_disk": {
"firmware_version": "2.5+",
"serial": "QM00001",
"uuid": null,
"numa_node": 0,
"available_size": 5368709120,
"size": 5368709120,
"tags": [
"ssd"
],
"id": 3,
"partition_table_type": null,
"id_path": "/dev/disk/by-id/ata-QEMU_HARDDISK_QM00001",
"model": "QEMU HARDDISK",
"path": "/dev/disk/by-dname/sda",
"storage_pool": null,
"used_for": "Unused",
"filesystem": null,
"system_id": "bhxws3",
"used_size": 0,
"partitions": [],
"name": "sda",
"block_size": 512,
"type": "physical",
"resource_uri": "/MAAS/api/2.0/nodes/bhxws3/blockdevices/3/"
},
"status": 1,
"iscsiblockdevice_set": [],
"raids": [],
"node_type_name": "Machine",
"hardware_info": {
"system_vendor": "QEMU",
"system_product": "Standard PC (i440FX + PIIX, 1996)",
"system_family": "Unknown",
"system_version": "pc-i440fx-focal",
"system_sku": "Unknown",
"system_serial": "Unknown",
"cpu_model": "Intel Core Processor (Skylake, IBRS)",
"mainboard_vendor": "Unknown",
"mainboard_product": "Unknown",
"mainboard_serial": "Unknown",
"mainboard_version": "Unknown",
"mainboard_firmware_vendor": "SeaBIOS",
"mainboard_firmware_date": "04/01/2014",
"mainboard_firmware_version": "1.13.0-1ubuntu1",
"chassis_vendor": "QEMU",
"chassis_type": "Other",
"chassis_serial": "Unknown",
"chassis_version": "pc-i440fx-focal"
},
"commissioning_status_name": "Pending",
"bios_boot_method": "pxe",
"interface_test_status": -1,
"cpu_speed": 0,
"resource_uri": "/MAAS/api/2.0/machines/bhxws3/"
}
If you need to find the machine’s $SYSTEM_ID, you can use a command like this one:
maas $PROFILE machines read | jq '.[] | .hostname, .system_id'
"ace-swan"
"bhxws3"
Once commissioned, you may consider creating or applying a tag to this machine. The next step is deployment.
How to manage commissioning and testing scripts
This section explains:
- How to download built-in scripts
- How to upload hardware testing scripts
- How to list all uploaded hardware testing scripts
- How to update hardware testing scripts
- How to revert hardware testing scripts
- How to download a script
- How to view script results
- How to filter script results
- How to suppress failed results
- How to locate script files
- How to locate log files
- How to run all scripts manually
You can also refer to technical details and examples for commissioning scripts and testing scripts as needed.
How to download built-in scripts
You can download the source for all commissioning and test scripts via the API with the following command:
maas $PROFILE node-script download $SCRIPT_NAME
The source code to all built-in scripts is available on launchpad.
How to upload hardware testing scripts
To upload a hardware testing script to MAAS, enter the following:
maas $PROFILE node-scripts create name=$SCRIPT_NAME name> \
script=$PATH_TO_SCRIPT type=testing
Changing the type to commissioning adds the test script to the commissioning process.
How to list all uploaded hardware testing scripts
You can list all uploaded scripts with the following command:
maas $PROFILE node-scripts read type=testing filters=$TAG
The optional filters argument lets you search for tags assigned to a script, such as using TAG=cpu with the above example.
How to update hardware testing scripts
A script’s metadata, and even the script itself, can be updated from the command line:
maas $PROFILE node-script update \
$SCRIPT_NAME script=$PATH_TO_SCRIPT comment=$COMMENT
The JSON formatted output to the above command will include ‘history’ dictionary entries, detailing script modification times and associated comments:
"history": [
{
"id": 40,
"created": "Tue, 12 Sep 2017 12:12:08 -0000",
"comment": "Updated version"
},
{
"id": 34,
"created": "Fri, 08 Sep 2017 17:07:46 -0000",
"comment": null
}
]
How to revert hardware testing scripts
MAAS keeps a history of all uploaded script versions, allowing you to easily revert to a previous version, using the id of the desired version:
maas $PROFILE node-script revert $SCRIPT_NAME to=$VERSION_ID
Warning: The history for later modifications will be lost when reverting to an earlier version of the script.
How to download a script
To download a script, enter the following:
maas $PROFILE node-script download $SCRIPT_NAME > $LOCAL_FILENAME
How to delete a script
To delete a script, use delete:
maas $PROFILE node-script delete $SCRIPT_NAME
How to view script results
The command line allows you to not only view the current script’s progress but also retrieve the verbatim output from any previous runs too.
If you only want to see the latest or currently-running result, you can use current-commissioning, current-testing, or current-installation instead of an id:
maas $PROFILE node-script-result read $SYSTEM_ID $RESULTS
How to filter script results
You can also limit which results are returned by type (commissioning, testing, or installation), script name, or script run:
maas $PROFILE node-script-results read \
$SYSTEM_ID type=$SCRIPT_TYPE filters=$SCRIPT_NAME,$TAGS
How to suppress failed results
You can also suppress failed results, which is useful if you want to ignore a known failure:
maas $PROFILE node-script-results update \
$SYSTEM_ID type=$SCRIPT_TYPE filters=$SCRIPT_NAME,$TAGS suppressed=$SUPPRESSED
where $SUPPRESSED is either True or False. The JSON formatted output to the above command will include ‘results’ dictionary with an entry for suppressed:
"results": [
{
"id": 21,
"created": "Tue, 02 Apr 2019 17:00:36 -0000",
"updated": "Tue, 02 Apr 2019 20:56:41 -0000",
"name": "smartctl-validate",
"status": 5,
"status_name": "Aborted",
"exit_status": null,
"started": "Tue, 02 Apr 2019 20:56:41 -0000",
"ended": "Tue, 02 Apr 2019 20:56:41 -0000",
"runtime": "0:00:00",
"starttime": 1554238601.765214,
"endtime": 1554238601.765214,
"estimated_runtime": "0:00:00",
"parameters": {
"storage": {
"argument_format": "{path}",
"type": "storage",
"value": {
"id_path": "/dev/vda",
"model": "",
"name": "sda",
"physical_blockdevice_id": 1,
"serial": ""
}
}
},
"script_id": 1,
"script_revision_id": null,
"suppressed": true
}
]
Finally, results can be downloaded, either to stdout, stderr, as combined output or as a tar.xz:
maas $PROFILE node-script-result download $SYSTEM_ID $RUN_ID output=all \
filetype=tar.xz > $LOCAL_FILENAME
$RUN_ID is labelled id in the verbose result output.
As long as you’ve added your SSH key to MAAS, you can connect with SSH to the machine’s IP with a username of ubuntu. Type sudo -i to get root access.
How to locate script files
Commissioning and testing script files may be found in the following directories:
-
/tmp/user_data.sh.*/scripts/commissioning/: Commissioning scripts -
/tmp/user_data.sh.*/scripts/testing/: Hardware testing scripts
How to locate log files
Commissioning and testing log files may be found in the following directories:
/tmp/user_data.sh*/out//var/log/cloud-init-output.log/var/log/cloud-init.log
How to run all scripts manually
You can also run all commissioning and hardware-testing scripts on a machine for debugging.
/tmp/user_data.sh.*/bin/maas-run-remote-scripts \
[--no-download] \
[--no-send] \
/tmp/user_data.sh.*
Where:
-
--no-download: Optional. Do not download the scripts from MAAS again. -
--no-send: Optional. Do not send the results to MAAS.
For example, to run all the scripts again without downloading again from MAAS:
/tmp/user_data.sh.*/bin/maas-run-remote-scripts --no-download /tmp/user_data.sh.*
Here, all the scripts are run again after downloading from MAAS, but no output data is sent to MAAS:
/tmp/user_data.sh.*/bin/maas-run-remote-scripts --no-send /tmp/user_data.sh.*