Getting Help

The two channels you can use to get help debugging a MAAS issue are:

 Ask Ubuntu web site

 Freenode #maas IRC channel

Gathering debugging information

If your question is related to a problem related to a specific MAAS installation, we encourage
you to gather debugging information and make it available while asking for help. This will make
it much easier for people to assist.

A big step on the way to doing this is by using sosreport, an automated information-gathering
utility. It is available in the Ubuntu archives:

sudo apt install -y sosreport

sudo sosreport -o maas

This will create a tarball containing MAAS log files, MAAS configuration files and a dump of
the MAAS database. By default, the tarball will end up in /tmp but you can change the location.
See the sosreport man page for details. If there are things you do not wish to share publicly, feel
free to edit the tarball.

The last step is to make this file available by any means at your disposal (openly accessible FTP
server, Dropbox, etc.) in order for helpers to be able to get their hands on it.
MAAS API
Restful MAAS API.

This is the documentation for the API that lets you control and query MAAS. The API is
"Restful", which means that you access it through normal HTTP requests.

API versions
At any given time, MAAS may support multiple versions of its API. The version number is
included in the API's URL, e.g. /api/2.0/

For now, 2.0 is the only supported version.

The current API version number can be retrieved by issuing a GET to "/api/version/". Accessing
an old or unknown API version URL will result in a "410 GONE" being returned, along with a
descriptive error message. Both the error message and the api version are returned as plaintext.

HTTP methods and parameter-passing

The following HTTP methods are available for accessing the API: - GET (for information
retrieval and queries), - POST (for asking the system to do things), - PUT (for updating objects),
and - DELETE (for deleting objects).

All methods except DELETE may take parameters, but they are not all passed in the same way.
GET parameters are passed in the URL, as is normal with a GET: "/item/?foo=bar" passes
parameter "foo" with value "bar".

POST and PUT are different. Your request should have MIME type "multipart/form-data"; each
part represents one parameter (for POST) or attribute (for PUT). Each part is named after the
parameter or attribute it contains, and its contents are the conveyed value.

All parameters are in text form. If you need to submit binary data to the API, don't send it as any
MIME binary format; instead, send it as a plain text part containing base64-encoded data.

Most resources offer a choice of GET or POST operations. In those cases these methods will take
one special parameter, called op, to indicate what it is you want to do.

For example, to list all machines, you might GET "/api/2.0/machines".

Operations
Logged-in user

Manage the current logged-in user.

GET /api/2.0/account/ op=list_authorisation_tokens

List authorisation tokens available to the currently logged-in user.

 return list of dictionaries representing each key's name and token.

POST /api/2.0/account/ op=create_authorisation_token

Create an authorisation OAuth token and OAuth consumer.

 param name Optional name of the token that will be generated.

 type name unicode
 return a json dict with four keys: 'token_key', 'token_secret', 'consumer_key'
and
'name'(e.g. {token_key: 's65244576fgqs', token_secret: 'qsdfdhv34', consumer_key:
'68543fhj854fg', name: 'MAAS consumer'}).
 rtype string (json)

POST /api/2.0/account/ op=delete_authorisation_token

Delete an authorisation OAuth token and the related OAuth consumer.

 param token_key The key of the token to be deleted.

 type token_key unicode

POST /api/2.0/account/ op=update_token_name

Modify the consumer name of an authorisation OAuth token.

 param token Can be the whole token or only the token key.
 type token unicode
 param name New name of the token.
 type name unicode

Bcache Cache Set

Manage bcache cache set on a machine.

DELETE /api/2.0/nodes/{system_id}/bcache-cache-set/{id}/

Delete cache set on a machine.

Returns 400 if the cache set is in use. Returns 404 if the machine or cache set is not found.
Returns 409 if the machine is not Ready.

GET /api/2.0/nodes/{system_id}/bcache-cache-set/{id}/

Read bcache cache set on a machine.

Returns 404 if the machine or cache set is not found.

PUT /api/2.0/nodes/{system_id}/bcache-cache-set/{id}/

Delete bcache on a machine.

 param cache_device Cache block device to replace current one.

 param cache_partition Cache partition to replace current one.

Specifying both a cache_device and a cache_partition is not allowed.

Returns 404 if the machine or the cache set is not found. Returns 409 if the machine is not Ready.

Bcache Cache Sets

Manage bcache cache sets on a machine.

GET /api/2.0/nodes/{system_id}/bcache-cache-sets/

List all bcache cache sets belonging to a machine.

Returns 404 if the machine is not found.

POST /api/2.0/nodes/{system_id}/bcache-cache-sets/

Creates a Bcache Cache Set.

 param cache_device Cache block device.

 param cache_partition Cache partition.

Specifying both a cache_device and a cache_partition is not allowed.

Returns 404 if the machine is not found. Returns 409 if the machine is not Ready.

Bcache Device

Manage bcache device on a machine.

DELETE /api/2.0/nodes/{system_id}/bcache/{id}/

Delete bcache on a machine.

Returns 404 if the machine or bcache is not found. Returns 409 if the machine is not Ready.

GET /api/2.0/nodes/{system_id}/bcache/{id}/

Read bcache device on a machine.

Returns 404 if the machine or bcache is not found.

PUT /api/2.0/nodes/{system_id}/bcache/{id}/

Delete bcache on a machine.

 param name Name of the Bcache.

 param uuid UUID of the Bcache.
 param cache_set Cache set to replace current one.
 param backing_device Backing block device to replace current one.
 param backing_partition Backing partition to replace current one.
 param cache_mode Cache mode (writeback, writethrough, writearound).

Specifying both a device and a partition for a given role (cache or backing) is not allowed.

Returns 404 if the machine or the bcache is not found. Returns 409 if the machine is not Ready.

Bcache Devices

Manage bcache devices on a machine.

GET /api/2.0/nodes/{system_id}/bcaches/

List all bcache devices belonging to a machine.

Returns 404 if the machine is not found.

POST /api/2.0/nodes/{system_id}/bcaches/

Creates a Bcache.

 param name Name of the Bcache.

 param uuid UUID of the Bcache.
 param cache_set Cache set.
 param backing_device Backing block device.
 param backing_partition Backing partition.
  param cache_mode Cache mode (WRITEBACK, WRITETHROUGH,
WRITEAROUND).

Specifying both a device and a partition for a given role (cache or backing) is not allowed.

Returns 404 if the machine is not found. Returns 409 if the machine is not Ready.

Block device

Manage a block device on a machine.

DELETE /api/2.0/nodes/{system_id}/blockdevices/{id}/

Delete block device on a machine.

Returns 404 if the machine or block device is not found. Returns 403 if the user is not allowed to
delete the block device. Returns 409 if the machine is not Ready.

GET /api/2.0/nodes/{system_id}/blockdevices/{id}/

Read block device on node.

Returns 404 if the machine or block device is not found.

POST /api/2.0/nodes/{system_id}/blockdevices/{id}/ op=add_tag

Add a tag to block device on a machine.

 param tag The tag being added.

Returns 404 if the machine or block device is not found. Returns 403 if the user is not allowed to
update the block device. Returns 409 if the machine is not Ready.

POST /api/2.0/nodes/{system_id}/blockdevices/{id}/ op=format

Format block device with filesystem.

 param fstype Type of filesystem.

 param uuid UUID of the filesystem.

Returns 403 when the user doesn't have the ability to format the block device. Returns 404 if the
machine or block device is not found. Returns 409 if the machine is not Ready or Allocated.

POST /api/2.0/nodes/{system_id}/blockdevices/{id}/ op=mount

Mount the filesystem on block device.

  param mount_point Path on the filesystem to mount.
 param mount_options Options to pass to mount(8).

Returns 403 when the user doesn't have the ability to mount the block device. Returns 404 if the
machine or block device is not found. Returns 409 if the machine is not Ready or Allocated.

POST /api/2.0/nodes/{system_id}/blockdevices/{id}/ op=remove_tag

Remove a tag from block device on a machine.

 param tag The tag being removed.

Returns 404 if the machine or block device is not found. Returns 403 if the user is not allowed to
update the block device. Returns 409 if the machine is not Ready.

POST /api/2.0/nodes/{system_id}/blockdevices/{id}/ op=set_boot_disk

Set this block device as the boot disk for the machine.

Returns 400 if the block device is a virtual block device. Returns 404 if the machine or block
device is not found. Returns 403 if the user is not allowed to update the block device. Returns
409 if the machine is not Ready or Allocated.

POST /api/2.0/nodes/{system_id}/blockdevices/{id}/ op=unformat

Unformat block device with filesystem.

Returns 400 if the block device is not formatted, currently mounted, or part of a filesystem group.
Returns 403 when the user doesn't have the ability to unformat the block device. Returns 404 if
the machine or block device is not found. Returns 409 if the machine is not Ready or Allocated.

POST /api/2.0/nodes/{system_id}/blockdevices/{id}/ op=unmount

Unmount the filesystem on block device.

Returns 400 if the block device is not formatted or not currently mounted. Returns 403 when the
user doesn't have the ability to unmount the block device. Returns 404 if the machine or block
device is not found. Returns 409 if the machine is not Ready or Allocated.

PUT /api/2.0/nodes/{system_id}/blockdevices/{id}/

Update block device on a machine.

Machines must have a status of Ready to have access to all options. Machines with Deployed
status can only have the name, model, serial, and/or id_path updated for a block device. This is
intented to allow a bad block device to be replaced while the machine remains deployed.
Fields for physical block device:

 param name Name of the block device.

 param model Model of the block device.
 param serial Serial number of the block device.
 param id_path (optional) Only used if model and serial cannot be provided. This should
be a path that is fixed and doesn't change depending on the boot order or kernel version.
 param size Size of the block device.
 param block_size Block size of the block device.

Fields for virtual block device:

 param name Name of the block device.

 param uuid UUID of the block device.
 param size Size of the block device. (Only allowed for logical volumes.)

Returns 404 if the machine or block device is not found. Returns 403 if the user is not allowed to
update the block device. Returns 409 if the machine is not Ready.

Block devices

Manage block devices on a machine.

GET /api/2.0/nodes/{system_id}/blockdevices/

List all block devices belonging to a machine.

Returns 404 if the machine is not found.

POST /api/2.0/nodes/{system_id}/blockdevices/

Create a physical block device.

 param name Name of the block device.

 param model Model of the block device.
 param serial Serial number of the block device.
 param id_path (optional) Only used if model and serial cannot be provided. This should
be a path that is fixed and doesn't change depending on the boot order or kernel version.
 param size Size of the block device.
 param block_size Block size of the block device.

Returns 404 if the node is not found.

Boot resource

Manage a boot resource.

DELETE /api/2.0/boot-resources/{id}/

Delete boot resource.

GET /api/2.0/boot-resources/{id}/

Read a boot resource.

Boot resources

Manage the boot resources.

GET /api/2.0/boot-resources/

List all boot resources.

 param type Type of boot resources to list. Default: all

GET /api/2.0/boot-resources/ op=is_importing

Return import status.

POST /api/2.0/boot-resources/

Uploads a new boot resource.

 param name Name of the boot resource.

 param title Title for the boot resource.
 param architecture Architecture the boot resource supports.
 param filetype Filetype for uploaded content. (Default: tgz, Supported:
tgz, ddtgz,
ddtbz, ddtxz, ddtar, ddbz2, ddgz, ddxz, ddraw
 param content Image content. Note: this is not a normal parameter, but a file upload.

POST /api/2.0/boot-resources/ op=import

Import the boot resources.

POST /api/2.0/boot-resources/ op=stop_import

Stop import of boot resources.

Boot source

Manage a boot source.

DELETE /api/2.0/boot-sources/{id}/

Delete a specific boot source.

GET /api/2.0/boot-sources/{id}/

Read a boot source.

PUT /api/2.0/boot-sources/{id}/

Update a specific boot source.

 param url The URL of the BootSource.

 param keyring_filename The path to the keyring file for this BootSource.
 param keyring_data The GPG keyring for this BootSource, base64-encoded data.

Boot source selection

Manage a boot source selection.

DELETE /api/2.0/boot-sources/{boot_source_id}/selections/{id}/

Delete a specific boot source.

GET /api/2.0/boot-sources/{boot_source_id}/selections/{id}/

Read a boot source selection.

PUT /api/2.0/boot-sources/{boot_source_id}/selections/{id}/

Update a specific boot source selection.

 param os The OS (e.g. ubuntu, centos) for which to import resources.

 param release The release for which to import resources.
 param arches The list of architectures for which to import resources.
 param subarches The list of subarchitectures for which to import resources.
 param labels The list of labels for which to import resources.

Boot source selections

Manage the collection of boot source selections.

GET /api/2.0/boot-sources/{boot_source_id}/selections/

List boot source selections.

Get a listing of a boot source's selections.

POST /api/2.0/boot-sources/{boot_source_id}/selections/

Create a new boot source selection.

 param os The OS (e.g. ubuntu, centos) for which to import resources.

 param release The release for which to import resources.
 param arches The architecture list for which to import resources.
 param subarches The subarchitecture list for which to import resources.
 param labels The label lists for which to import resources.

Boot sources

Manage the collection of boot sources.

GET /api/2.0/boot-sources/

List boot sources.

Get a listing of boot sources.

POST /api/2.0/boot-sources/

Create a new boot source.

 param url The URL of the BootSource.

 param keyring_filename The path to the keyring file for this BootSource.
 param keyring_data The GPG keyring for this BootSource, base64-encoded.

Commissioning script

Manage a custom commissioning script.

This functionality is only available to administrators.

This endpoint has been deprecated in favor of the node-script endpoint.

DELETE /api/2.0/commissioning-scripts/{name}

Delete a commissioning script.

GET /api/2.0/commissioning-scripts/{name}

Read a commissioning script.

PUT /api/2.0/commissioning-scripts/{name}

Update a commissioning script.

Commissioning scripts

Manage custom commissioning scripts.

This functionality is only available to administrators.

This endpoint has been deprecated in favor of the node-scripts endpoint.

GET /api/2.0/commissioning-scripts/

List commissioning scripts.

POST /api/2.0/commissioning-scripts/

Create a new commissioning script.

Each commissioning script is identified by a unique name.

By convention the name should consist of a two-digit number, a dash, and a brief descriptive
identifier consisting only of ASCII characters. You don't need to follow this convention, but not
doing so opens you up to risks w.r.t. encoding and ordering. The name must not contain any
whitespace, quotes, or apostrophes.

A commissioning machine will run each of the scripts in lexicographical order. There are no
promises about how non-ASCII characters are sorted, or even how upper-case letters are sorted
relative to lower-case letters. So where ordering matters, use unique numbers.

Scripts built into MAAS will have names starting with "00-maas" or "99-maas" to ensure that
they run first or last, respectively.

Usually a commissioning script will be just that, a script. Ideally a script should be ASCII text to
avoid any confusion over encoding. But in some cases a commissioning script might consist of a
binary tool provided by a hardware vendor. Either way, the script gets passed to the
commissioning machine in the exact form in which it was uploaded.

 param name Unique identifying name for the script. Names should follow the pattern of
"25-burn-in-hard-disk" (all ASCII, and with numbers greater than zero, and generally no
"weird" characters).
 param content A script file, to be uploaded in binary form. Note: this is not a normal
parameter, but a file upload. Its filename is ignored; MAAS will know it by the name you
pass to the request.
DHCP Snippet

Manage an individual DHCP snippet.

The DHCP snippet is identified by its id.

DELETE /api/2.0/dhcp-snippets/{id}/

Delete a DHCP snippet.

Returns 404 if the DHCP snippet is not found.

GET /api/2.0/dhcp-snippets/{id}/

Read DHCP snippet.

Returns 404 if the snippet is not found.

POST /api/2.0/dhcp-snippets/{id}/ op=revert

Revert the value of a DHCP snippet to an earlier revision.

 param to What revision in the DHCP snippet's history to revert to. This can either be an
ID or a negative number representing how far back to go.
 type to integer

Returns 404 if the DHCP snippet is not found.

PUT /api/2.0/dhcp-snippets/{id}/

Update a DHCP snippet.

 param name The name of the DHCP snippet.

 type name unicode
 param value The new value of the DHCP snippet to be used in dhcpd.conf. Previous
values are stored and can be reverted.
 type value unicode
 param description A description of what the DHCP snippet does.
 type description unicode
 param enabled Whether or not the DHCP snippet is currently enabled.
 type enabled boolean
 param node The node the DHCP snippet is to be used for. Can not be set if subnet is set.
 type node unicode
 param subnet The subnet the DHCP snippet is to be used for. Can not be set if node is
set.
 type subnet unicode
  param global_snippet Set the DHCP snippet to be a global option. This removes any
node or subnet links.
 type global_snippet boolean

Returns 404 if the DHCP snippet is not found.

DHCP Snippets

Manage the collection of all DHCP snippets in MAAS.

GET /api/2.0/dhcp-snippets/

List all DHCP snippets.

POST /api/2.0/dhcp-snippets/

Create a DHCP snippet.

 param name The name of the DHCP snippet. This is required to create a new DHCP
snippet.
 type name unicode
 param value The snippet of config inserted into dhcpd.conf. This is required to create a
new DHCP snippet.
 type value unicode
 param description A description of what the snippet does.
 type description unicode
 param enabled Whether or not the snippet is currently enabled.
 type enabled boolean
 param node The node this snippet applies to. Cannot be used withsubnet or
global_snippet.
 type node unicode
 param subnet The subnet this snippet applies to. Cannot be used with node or
global_snippet.
 type subnet unicode
 param global_snippet Whether or not this snippet is to be applied globally. Cannot be
used with node or subnet.
 type global_snippet boolean

Returns 404 if the DHCP snippet is not found.

DNSResource

Manage dnsresource.
DELETE /api/2.0/dnsresources/{id}/

Delete dnsresource.

Returns 403 if the user does not have permission to delete the dnsresource. Returns 404 if the
dnsresource is not found.

GET /api/2.0/dnsresources/{id}/

Read dnsresource.

Returns 404 if the dnsresource is not found.

PUT /api/2.0/dnsresources/{id}/

Update dnsresource.

 param fqdn Hostname (with domain) for the dnsresource.

 param ip_address Address to assign to the dnsresource.

Returns 403 if the user does not have permission to update the dnsresource. Returns 404 if the
dnsresource is not found.

DNSResourceRecord

Manage dnsresourcerecord.

DELETE /api/2.0/dnsresourcerecords/{id}/

Delete dnsresourcerecord.

Returns 403 if the user does not have permission to delete the dnsresourcerecord. Returns 404 if
the dnsresourcerecord is not found.

GET /api/2.0/dnsresourcerecords/{id}/

Read dnsresourcerecord.

Returns 404 if the dnsresourcerecord is not found.

PUT /api/2.0/dnsresourcerecords/{id}/

Update dnsresourcerecord.

 param rrtype Resource Type

 param rrdata Resource Data (everything to the right of Type.)
Returns 403 if the user does not have permission to update the dnsresourcerecord. Returns 404 if
the dnsresourcerecord is not found.

DNSResourceRecords

Manage dnsresourcerecords.

GET /api/2.0/dnsresourcerecords/

List all dnsresourcerecords.

 param domain restrict the listing to entries for the domain.

 param name restrict the listing to entries of the given name.
 param rrtype restrict the listing to entries which have records of the given rrtype.

POST /api/2.0/dnsresourcerecords/

Create a dnsresourcerecord.

 param fqdn Hostname (with domain) for the dnsresource. Either fqdn or (name, domain)
must be specified. Fqdn is ignored if either name or domain is given.
 param name Hostname (without domain)
 param domain Domain (name or id)
 param rrtype resource type to create
 param rrdata resource data (everything to the right of resource type.)

DNSResources

Manage dnsresources.

GET /api/2.0/dnsresources/

List all resources for the specified criteria.

 param domain restrict the listing to entries for the domain.

 param name restrict the listing to entries of the given name.
 param rrtype restrict the listing to entries which have records of the given rrtype.

POST /api/2.0/dnsresources/

Create a dnsresource.

 param fqdn Hostname (with domain) for the dnsresource. Either fqdn or (name, domain)
must be specified. Fqdn is ignored if either name or domain is given.
 param name Hostname (without domain)
 param domain Domain (name or id)
  param address_ttl Default ttl for entries in this zone.
 param ip_addresses (optional) Address (ip or id) to assign to the dnsresource.

Device

Manage an individual device.

The device is identified by its system_id.

DELETE /api/2.0/devices/{system_id}/

Delete a specific Device.

Returns 404 if the device is not found. Returns 403 if the user does not have permission to delete
the device. Returns 204 if the device is successfully deleted.

GET /api/2.0/devices/{system_id}/

Read a specific Node.

Returns 404 if the node is not found.

GET /api/2.0/devices/{system_id}/ op=details

Obtain various system details.

For example, LLDP and lshw XML dumps.

Returns a {detail_type: xml, ...} map, where detail_type is something like "lldp" or
"lshw".

Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because
JSON can't do binary content without applying additional encoding like base-64.

Returns 404 if the node is not found.

GET /api/2.0/devices/{system_id}/ op=power_parameters

Obtain power parameters.

This method is reserved for admin users and returns a 403 if the user is not one.

This returns the power parameters, if any, configured for a node. For some types of power control
this will include private information such as passwords and secret keys.

Returns 404 if the node is not found.

POST /api/2.0/devices/{system_id}/ op=restore_default_configuration

Reset a device's configuration to its initial state.

Returns 404 if the device is not found. Returns 403 if the user does not have permission to reset
the device.

POST /api/2.0/devices/{system_id}/ op=restore_networking_configuration

Reset a device's network options.

Returns 404 if the device is not found Returns 403 if the user does not have permission to reset
the device.

POST /api/2.0/devices/{system_id}/ op=set_owner_data

Set key/value data for the current owner.

Pass any key/value data to this method to add, modify, or remove. A key is removed when the
value for that key is set to an empty string.

This operation will not remove any previous keys unless explicitly passed with an empty string.
All owner data is removed when the machine is no longer allocated to a user.

Returns 404 if the machine is not found. Returns 403 if the user does not have permission.

PUT /api/2.0/devices/{system_id}/

Update a specific device.

 param hostname The new hostname for this device.

 type hostname unicode
 param domain The domain for this device.
 type domain unicode
 param parent Optional system_id to indicate this device's parent. If the parent is already
set and this parameter is omitted, the parent will be unchanged.
 type parent unicode
 param zone Name of a valid physical zone in which to place this node.
 type zone unicode

Returns 404 if the device is not found. Returns 403 if the user does not have permission to update
the device.

Devices

Manage the collection of all the devices in the MAAS.

GET /api/2.0/devices/

List Nodes visible to the user, optionally filtered by criteria.

Nodes are sorted by id (i.e. most recent last) and grouped by type.

 param hostname An optional hostname. Only nodes relating to the node with the
matching hostname will be returned. This can be specified multiple times to see multiple
nodes.
 type hostname unicode
 param mac_address An optional MAC address. Only nodes relating to the node owning
the specified MAC address will be returned. This can be specified multiple times to see
multiple nodes.
 type mac_address unicode
 param id An optional list of system ids. Only nodes relating to the nodes with matching
system ids will be returned.
 type id unicode
 param domain An optional name for a dns domain. Only nodes relating to the nodes in
the domain will be returned.
 type domain unicode
 param zone An optional name for a physical zone. Only nodes relating to the nodes in
the zone will be returned.
 type zone unicode
 param agent_name An optional agent name. Only nodes relating to the nodes with
matching agent names will be returned.
 type agent_name unicode

GET /api/2.0/devices/ op=is_registered

Returns whether or not the given MAC address is registered within this MAAS (and attached to a
non-retired node).

 param mac_address The mac address to be checked.

 type mac_address unicode
 return 'true' or 'false'.
 rtype unicode

Returns 400 if any mandatory parameters are missing.

POST /api/2.0/devices/

Create a new device.

 param hostname A hostname. If not given, one will be generated.

 type hostname unicode
 param domain The domain of the device. If not given the default domain is used.
  type domain unicode
 param mac_addresses One or more MAC addresses for the device.
 type mac_addresses unicode
 param parent The system id of the parent. Optional.
 type parent unicode

POST /api/2.0/devices/ op=set_zone

Assign multiple nodes to a physical zone at once.

 param zone Zone name. If omitted, the zone is "none" and the nodes will be taken out of
their physical zones.
 param nodes system_ids of the nodes whose zones are to be set. (An empty list is
acceptable).

Raises 403 if the user is not an admin.

Discoveries

Query observed discoveries.

GET /api/2.0/discovery/

Lists all the devices MAAS has discovered.

Discoveries are listed in the order they were last observed on the network (most recent first).

GET /api/2.0/discovery/ op=by_unknown_ip

Lists all discovered devices which have an unknown IP address.

Filters the list of discovered devices by excluding any discoveries where a known MAAS node is
configured with the IP address of the discovery, or has been observed using it after it was
assigned by a MAAS-managed DHCP server.

Discoveries are listed in the order they were last observed on the network (most recent first).

GET /api/2.0/discovery/ op=by_unknown_ip_and_mac

Lists all discovered devices which are completely unknown to MAAS.

Filters the list of discovered devices by excluding any discoveries where a known MAAS node is
configured with either the MAC address or the IP address of the discovery.

Discoveries are listed in the order they were last observed on the network (most recent first).
GET /api/2.0/discovery/ op=by_unknown_mac

Lists all discovered devices which have an unknown IP address.

Filters the list of discovered devices by excluding any discoveries where an interface known to
MAAS is configured with MAC address of the discovery.

Discoveries are listed in the order they were last observed on the network (most recent first).

POST /api/2.0/discovery/ op=clear

Deletes all discovered neighbours and/or mDNS entries.

 param mdns if True, deletes all mDNS entries.

 param neighbours if True, deletes all neighbour entries.
 param all if True, deletes all discovery data.

POST /api/2.0/discovery/ op=scan

Immediately run a neighbour discovery scan on all rack networks.

This command causes each connected rack controller to execute the 'maas-rack scan-network'
command, which will scan all CIDRs configured on the rack controller using 'nmap' (if it is
installed) or 'ping'.

Network discovery must not be set to 'disabled' for this command to be useful.

Scanning will be started in the background, and could take a long time on rack controllers that do
not have 'nmap' installed and are connected to large networks.

If the call is a success, this method will return a dictionary of results as follows:

result: A human-readable string summarizing the results. scan_attempted_on: A list of rack

'system_id' values where a scan was attempted. (That is, an RPC connection was successful and a
subsequent call was intended.)

failed_to_connect_to: A list of rack 'system_id' values where the RPC connection failed.

scan_started_on: A list of rack 'system_id' values where a scan was successfully started.

scan_failed_on: A list of rack 'system_id' values where a scan was attempted, but failed because a
scan was already in progress.

rpc_call_timed_out_on: A list of rack 'system_id' values where the RPC connection was made,
but the call timed out before a ten second timeout elapsed.
  param cidr The subnet CIDR(s) to scan (can be specified multiple times). If not
specified, defaults to all networks.
 param force If True, will force the scan, even if all networks are specified. (This may
not be the best idea, depending on acceptable use agreements, and the politics of the
organization that owns the network.) Default: False.
 param always_use_ping If True, will force the scan to use 'ping' even if 'nmap' is
installed. Default: False.
 param slow If True, and 'nmap' is being used, will limit the scan to nine packets per
second. If the scanner is 'ping', this option has no effect. Default: False.
 param threads The number of threads to use during scanning. If 'nmap' is the scanner,
the default is one thread per 'nmap' process. If 'ping' is the scanner, the default is four
threads per CPU.

Discovery

Read or delete an observed discovery.

GET /api/2.0/discovery/{discovery_id}/
Domain

Manage domain.

DELETE /api/2.0/domains/{id}/

Delete domain.

Returns 403 if the user does not have permission to update the dnsresource. Returns 404 if the
domain is not found.

GET /api/2.0/domains/{id}/

Read domain.

Returns 404 if the domain is not found.

PUT /api/2.0/domains/{id}/

Update domain.

 param name Name of the domain.

 param authoritative True if we are authoritative for this domain.
 param ttl The default TTL for this domain.

Returns 403 if the user does not have permission to update the dnsresource. Returns 404 if the
domain is not found.
Domains

Manage domains.

GET /api/2.0/domains/

List all domains.

POST /api/2.0/domains/

Create a domain.

 param name Name of the domain.

 param authoritative Class type of the domain.

POST /api/2.0/domains/ op=set_serial

Set the SOA serial number (for all DNS zones.)

 param serial serial number to use next.

Events

Retrieve filtered node events.

A specific Node's events is identified by specifying one or more ids, hostnames, or mac addresses
as a list.

GET /api/2.0/events/ op=query

List Node events, optionally filtered by various criteria via URL query parameters.

 param hostname An optional hostname. Only events relating to the node with the
matching hostname will be returned. This can be specified multiple times to get events
relating to more than one node.
 param mac_address An optional list of MAC addresses. Only nodes with matching
MAC addresses will be returned.
 param id An optional list of system ids. Only nodes with matching system ids will be
returned.
 param zone An optional name for a physical zone. Only nodes in the zone will be
returned.
 param agent_name An optional agent name. Only nodes with matching agent names will
be returned.
 param level Desired minimum log level of returned events. Returns this level of events
and greater. Choose from: CRITICAL, DEBUG, ERROR, INFO, WARNING. The
default is INFO.
  param limit Optional number of events to return. Default 100. Maximum: 1000.
 param before Optional event id. Defines where to start returning older events.
 param after Optional event id. Defines where to start returning newer events.

Fabric

Manage fabric.

DELETE /api/2.0/fabrics/{id}/

Delete fabric.

Returns 404 if the fabric is not found.

GET /api/2.0/fabrics/{id}/

Read fabric.

Returns 404 if the fabric is not found.

PUT /api/2.0/fabrics/{id}/

Update fabric.

 param name Name of the fabric.

 param description Description of the fabric.
 param class_type Class type of the fabric.

Returns 404 if the fabric is not found.

Fabrics

Manage fabrics.

GET /api/2.0/fabrics/

List all fabrics.

POST /api/2.0/fabrics/

Create a fabric.

 param name Name of the fabric.

 param description Description of the fabric.
 param class_type Class type of the fabric.
Fan Network

Manage Fan Network.

DELETE /api/2.0/fannetworks/{id}/

Delete fannetwork.

Returns 404 if the fannetwork is not found.

GET /api/2.0/fannetworks/{id}/

Read fannetwork.

Returns 404 if the fannetwork is not found.

PUT /api/2.0/fannetworks/{id}/

Update fannetwork.

 param name Name of the fannetwork.

 param overlay Overlay network
 param underlay Underlay network
 param dhcp confiugre dhcp server for overlay net
 param host_reserve number of IP addresses to reserve for host
 param bridge override bridge name
 param off put this int he config, but disable it.

Returns 404 if the fannetwork is not found.

Fan Networks

Manage Fan Networks.

GET /api/2.0/fannetworks/

List all fannetworks.

POST /api/2.0/fannetworks/

Create a fannetwork.

 param name Name of the fannetwork.

 param overlay Overlay network
 param underlay Underlay network
 param dhcp confiugre dhcp server for overlay net
  param host_reserve number of IP addresses to reserve for host
 param bridge override bridge name
 param off put this int he config, but disable it.

File

Manage a FileStorage object.

The file is identified by its filename and owner.

DELETE /api/2.0/files/{filename}/

Delete a FileStorage object.

GET /api/2.0/files/{filename}/

GET a FileStorage object as a json object.

The 'content' of the file is base64-encoded.

Files

Manage the collection of all the files in this MAAS.

DELETE /api/2.0/files/

Delete a FileStorage object.

 param filename The filename of the object to be deleted.

 type filename unicode

GET /api/2.0/files/

List the files from the file storage.

The returned files are ordered by file name and the content is excluded.

 param prefix Optional prefix used to filter out the returned files.
 type prefix string

GET /api/2.0/files/ op=get

Get a named file from the file storage.

 param filename The exact name of the file you want to get.
 type filename string
  return The file is returned in the response content.

GET /api/2.0/files/ op=get_by_key

Get a file from the file storage using its key.

 param key The exact key of the file you want to get.
 type key string
 return The file is returned in the response content.

POST /api/2.0/files/

Add a new file to the file storage.

 param filename The file name to use in the storage.

 type filename string
 param file Actual file data with content type application/octet-stream

Returns 400 if any of these conditions apply: - The filename is missing from the parameters - The
file data is missing - More than one file is supplied

IP Addresses

Manage IP addresses allocated by MAAS.

GET /api/2.0/ipaddresses/

List IP addresses known to MAAS.

By default, gets a listing of all IP addresses allocated to the requesting user.

 param ip If specified, will only display information for the specified IP address.
 type ip unicode (must be an IPv4 or IPv6 address)

If the requesting user is a MAAS administrator, the following options may also be supplied:

 param all If True, all reserved IP addresses will be shown. (By default, only addresses
of type 'User reserved' that are assigned to the requesting user are shown.)
 type all bool
 param owner If specified, filters the list to show only IP addresses owned by the specified
username.
 type user unicode

POST /api/2.0/ipaddresses/ op=release

Release an IP address that was previously reserved by the user.

  param ip The IP address to release.
 type ip unicode
 param force If True, allows a MAAS administrator to force an IP address to be released,
even if it is not a user-reserved IP address or does not belong to the requesting user. Use
with caution.
 type force bool
 param discovered If True, allows a MAAS administrator to release a discovered
address. Only valid if 'force' is specified. If not specified, MAAS will attempt to release
any type of address except for discovered addresses.

Returns 404 if the provided IP address is not found.

POST /api/2.0/ipaddresses/ op=reserve

Reserve an IP address for use outside of MAAS.

Returns an IP adddress, which MAAS will not allow any of its known nodes to use; it is free for
use by the requesting user until released by the user.

The user may supply either a subnet or a specific IP address within a subnet.

 param subnet CIDR representation of the subnet on which the IP reservation is required.
e.g. 10.1.2.0/24
 param ip The IP address, which must be within a known subnet.
 param ip_address (Deprecated.) Alias for 'ip' parameter. Provided for backward
compatibility.
 param hostname The hostname to use for the specified IP address. If no domain
component is given, the default domain will be used.
 param mac The MAC address that should be linked to this reservation.

Returns 400 if there is no subnet in MAAS matching the provided one, or a ip_address is
supplied, but a corresponding subnet could not be found. Returns 503 if there are no more IP
addresses available.

IP Range

Manage IP range.

DELETE /api/2.0/ipranges/{id}/

Delete IP range.

Returns 403 if not owner of IP range. Returns 404 if the IP range is not found.
GET /api/2.0/ipranges/{id}/

Read IP range.

Returns 404 if the IP range is not found.

PUT /api/2.0/ipranges/{id}/

Update IP range.

 param start_ip Start IP address of this range (inclusive).

 param end_ip End IP address of this range (inclusive).
 param comment A description of this range. (optional)

Returns 403 if not owner of IP range. Returns 404 if the IP Range is not found.

IP Ranges

Manage IP ranges.

GET /api/2.0/ipranges/

List all IP ranges.

POST /api/2.0/ipranges/

Create an IP range.

 param type Type of this range. (dynamic or reserved)

 param start_ip Start IP address of this range (inclusive).
 param end_ip End IP address of this range (inclusive).
 param subnet Subnet this range is associated with. (optional)
 param comment A description of this range. (optional)

Returns 403 if standard users tries to create a dynamic IP range.

Interface

Manage a node's or device's interface.

DELETE /api/2.0/nodes/{system_id}/interfaces/{id}/

Delete interface on node.

Returns 404 if the node or interface is not found.

GET /api/2.0/nodes/{system_id}/interfaces/{id}/

Read interface on node.

Returns 404 if the node or interface is not found.

POST /api/2.0/nodes/{system_id}/interfaces/{id}/ op=add_tag

Add a tag to interface on a node.

 param tag The tag being added.

Returns 404 if the node or interface is not found. Returns 403 if the user is not allowed to update
the interface.

POST /api/2.0/nodes/{system_id}/interfaces/{id}/ op=disconnect

Disconnect an interface.

Deletes any linked subnets and IP addresses, and disconnects the interface from any associated
VLAN.

Returns 404 if the node or interface is not found.

POST /api/2.0/nodes/{system_id}/interfaces/{id}/ op=link_subnet

Link interface to a subnet.

 param mode AUTO, DHCP, STATIC or LINK_UP connection to subnet.

 param subnet Subnet linked to interface.
 param ip_address IP address for the interface in subnet. Only used when mode is
STATIC. If not provided an IP address from subnet will be auto selected.
 param force If True, allows LINK_UP to be set on the interface even if other links
already exist. Also allows the selection of any VLAN, even a VLAN MAAS does not
believe the interface to currently be on. Using this option will cause all other links on the
interface to be deleted. (Defaults to False.)
 param default_gateway True sets the gateway IP address for the subnet as the default
gateway for the node this interface belongs to. Option can only be used with the AUTO
and STATIC modes.

Mode definitions: AUTO - Assign this interface a static IP address from the provided subnet. The
subnet must be a managed subnet. The IP address will not be assigned until the node goes to be
deployed.

DHCP - Bring this interface up with DHCP on the given subnet. Only one subnet can be set to
DHCP. If the subnet is managed this interface will pull from the dynamic IP range.
STATIC - Bring this interface up with a STATIC IP address on the given subnet. Any number of
STATIC links can exist on an interface.

LINK_UP - Bring this interface up only on the given subnet. No IP address will be assigned to
this interface. The interface cannot have any current AUTO, DHCP or STATIC links.

Returns 404 if the node or interface is not found.

POST /api/2.0/nodes/{system_id}/interfaces/{id}/ op=remove_tag

Remove a tag from interface on a node.

 param tag The tag being removed.

Returns 404 if the node or interface is not found. Returns 403 if the user is not allowed to update
the interface.

POST /api/2.0/nodes/{system_id}/interfaces/{id}/ op=set_default_gateway

Set the node to use this interface as the default gateway.

If this interface has more than one subnet with a gateway IP in the same IP address family then
specifying the ID of the link on this interface is required.

 param link_id ID of the link on this interface to select the default gateway IP address from.

Returns 400 if the interface has not AUTO or STATIC links. Returns 404 if the node or interface
is not found.

POST /api/2.0/nodes/{system_id}/interfaces/{id}/ op=unlink_subnet

Unlink interface to a subnet.

 param id ID of the link on the interface to remove.

Returns 404 if the node or interface is not found.

PUT /api/2.0/nodes/{system_id}/interfaces/{id}/

Update interface on node.

Machines must have a status of Ready or Broken to have access to all options. Machines with
Deployed status can only have the name and/or mac_address updated for an interface. This is
intented to allow a bad interface to be replaced while the machine remains deployed.

Fields for physical interface:

  param name Name of the interface.
 param mac_address MAC address of the interface.
 param tags Tags for the interface.
 param vlan Untagged VLAN the interface is connected to. If not set then the interface is
considered disconnected.

Fields for bond interface:

 param name Name of the interface.

 param mac_address MAC address of the interface.
 param tags Tags for the interface.
 param vlan Untagged VLAN the interface is connected to. If not set then the interface is
considered disconnected.
 param parents Parent interfaces that make this bond.

Fields for VLAN interface:

 param tags Tags for the interface.

 param vlan Tagged VLAN the interface is connected to.
 param parent Parent interface for this VLAN interface.

Fields for bridge interface:

 param name Name of the interface.

 param mac_address MAC address of the interface.
 param tags Tags for the interface.
 param vlan VLAN the interface is connected to.
 param parent Parent interface for this bridge interface.

Following are extra parameters that can be set on all interface types:

 param mtu Maximum transmission unit.

 param accept_ra Accept router advertisements. (IPv6 only)
 param autoconf Perform stateless autoconfiguration. (IPv6 only)

Following are parameters specific to bonds:

 param bond_mode The operating mode of the bond. (Default: active-backup).

 param bond_miimon The link monitoring freqeuncy in milliseconds. (Default: 100).
 param bond_downdelay Specifies the time, in milliseconds, to wait before disabling a
slave after a link failure has been detected.
 param bond_updelay Specifies the time, in milliseconds, to wait before enabling a slave
after a link recovery has been detected.
 param bond_lacp_rate Option specifying the rate in which we'll ask our link partner to
transmit LACPDU packets in 802.3ad mode. Available options are fast or slow. (Default:
slow).
  param bond_xmit_hash_policy The transmit hash policy to use for slave selection in
balance-xor, 802.3ad, and tlb modes.

Supported bonding modes (bond-mode):

balance-rr - Transmit packets in sequential order from the first available slave through the last.
This mode provides load balancing and fault tolerance.

active-backup - Only one slave in the bond is active. A different slave becomes active if, and only
if, the active slave fails. The bond's MAC address is externally visible on only one port (network
adapter) to avoid confusing the switch.

balance-xor - Transmit based on the selected transmit hash policy. The default policy is a simple
[(source MAC address XOR'd with destination MAC address XOR packet type ID) modulo slave
count].

broadcast - Transmits everything on all slave interfaces. This mode provides fault tolerance.

802.3ad - IEEE 802.3ad Dynamic link aggregation. Creates aggregation groups that share the
same speed and duplex settings. Utilizes all slaves in the active aggregator according to the
802.3ad specification.

balance-tlb - Adaptive transmit load balancing: channel bonding that does not require any special
switch support.

balance-alb - Adaptive load balancing: includes balance-tlb plus receive load balancing (rlb) for
IPV4 traffic, and does not require any special switch support. The receive load balancing is
achieved by ARP negotiation.

Following are parameters specific to bridges:

 param bridge_stp Turn spanning tree protocol on or off. (Default: False).

 param bridge_fd Set bridge forward delay to time seconds. (Default: 15).

Returns 404 if the node or interface is not found.

Interfaces

Manage interfaces on a node.

GET /api/2.0/nodes/{system_id}/interfaces/

List all interfaces belonging to a machine, device, or rack controller.

Returns 404 if the node is not found.

POST /api/2.0/nodes/{system_id}/interfaces/ op=create_bond

Create a bond interface on a machine.

 param name Name of the interface.

 param mac_address MAC address of the interface.
 param tags Tags for the interface.
 param vlan VLAN the interface is connected to. If not provided then the interface is
considered disconnected.
 param parents Parent interfaces that make this bond.

Following are parameters specific to bonds:

 param bond_mode The operating mode of the bond. (Default: active-backup).

 param bond_miimon The link monitoring freqeuncy in milliseconds. (Default: 100).
 param bond_downdelay Specifies the time, in milliseconds, to wait before disabling a
slave after a link failure has been detected.
 param bond_updelay Specifies the time, in milliseconds, to wait before enabling a slave
after a link recovery has been detected.
 param bond_lacp_rate Option specifying the rate in which we'll ask our link partner to
transmit LACPDU packets in 802.3ad mode. Available options are fast or slow. (Default:
slow).
 param bond_xmit_hash_policy The transmit hash policy to use for slave selection in
balance-xor, 802.3ad, and tlb modes. (Default: layer2)

Supported bonding modes (bond-mode): balance-rr - Transmit packets in sequential order from
the first available slave through the last. This mode provides load balancing and fault tolerance.

active-backup - Only one slave in the bond is active. A different slave becomes active if, and only
if, the active slave fails. The bond's MAC address is externally visible on only one port (network
adapter) to avoid confusing the switch.

balance-xor - Transmit based on the selected transmit hash policy. The default policy is a simple
[(source MAC address XOR'd with destination MAC address XOR packet type ID) modulo slave
count].

broadcast - Transmits everything on all slave interfaces. This mode provides fault tolerance.

802.3ad - IEEE 802.3ad Dynamic link aggregation. Creates aggregation groups that share the
same speed and duplex settings. Utilizes all slaves in the active aggregator according to the
802.3ad specification.

balance-tlb - Adaptive transmit load balancing: channel bonding that does not require any special
switch support.
balance-alb - Adaptive load balancing: includes balance-tlb plus receive load balancing (rlb) for
IPV4 traffic, and does not require any special switch support. The receive load balancing is
achieved by ARP negotiation.

Following are extra parameters that can be set on the interface:

 param mtu Maximum transmission unit.

 param accept_ra Accept router advertisements. (IPv6 only)
 param autoconf Perform stateless autoconfiguration. (IPv6 only)

Returns 404 if the node is not found.

POST /api/2.0/nodes/{system_id}/interfaces/ op=create_bridge

Create a bridge interface on a machine.

 param name Name of the interface.

 param mac_address MAC address of the interface.
 param tags Tags for the interface.
 param vlan VLAN the interface is connected to.
 param parent Parent interface for this bridge interface.

Following are parameters specific to bridges:

 param bridge_stp Turn spanning tree protocol on or off. (Default: False).

 param bridge_fd Set bridge forward delay to time seconds. (Default: 15).

Following are extra parameters that can be set on the interface:

 param mtu Maximum transmission unit.

 param accept_ra Accept router advertisements. (IPv6 only)
 param autoconf Perform stateless autoconfiguration. (IPv6 only)

Returns 404 if the node is not found.

POST /api/2.0/nodes/{system_id}/interfaces/ op=create_physical

Create a physical interface on a machine and device.

 param name Name of the interface.

 param mac_address MAC address of the interface.
 param tags Tags for the interface.
 param vlan Untagged VLAN the interface is connected to. If not provided then the
interface is considered disconnected.

Following are extra parameters that can be set on the interface:

  param mtu Maximum transmission unit.
 param accept_ra Accept router advertisements. (IPv6 only)
 param autoconf Perform stateless autoconfiguration. (IPv6 only)

Returns 404 if the node is not found.

POST /api/2.0/nodes/{system_id}/interfaces/ op=create_vlan

Create a VLAN interface on a machine.

 param tags Tags for the interface.

 param vlan Tagged VLAN the interface is connected to.
 param parent Parent interface for this VLAN interface.

Following are extra parameters that can be set on the interface:

 param mtu Maximum transmission unit.

 param accept_ra Accept router advertisements. (IPv6 only)
 param autoconf Perform stateless autoconfiguration. (IPv6 only)

Returns 404 if the node is not found.

License Key

Manage a license key.

DELETE /api/2.0/license-key/{osystem}/{distro_series}

Delete license key.

GET /api/2.0/license-key/{osystem}/{distro_series}

Read license key.

PUT /api/2.0/license-key/{osystem}/{distro_series}

Update license key.

 param osystem Operating system that the key belongs to.

 param distro_series OS release that the key belongs to.
 param license_key License key for osystem/distro_series combo.

License Keys

Manage the license keys.

GET /api/2.0/license-keys/

List license keys.

POST /api/2.0/license-keys/

Define a license key.

 param osystem Operating system that the key belongs to.

 param distro_series OS release that the key belongs to.
 param license_key License key for osystem/distro_series combo.

MAAS server

Manage the MAAS server.

GET /api/2.0/maas/ op=get_config

Get a config value.

 param name The name of the config item to be retrieved.

Available configuration items:

 active_discovery_interval Active subnet mapping interval. When enabled, each rack

will scan subnets enabled for active mapping. This helps ensure discovery information is
accurate and complete.
 boot_images_auto_import Automatically import/refresh the boot images every 60
minutes.
 commissioning_distro_series Default Ubuntu release used for commissioning.
 completed_intro Marks if the initial intro has been completed.
 curtin_verbose Run the fast-path installer with higher verbosity. This provides more
detail in the installation logs.
 default_distro_series Default OS release used for deployment.
 default_dns_ttl Default Time-To-Live for the DNS. If no TTL value is specified at a
more specific point this is how long DNS responses are valid, in seconds.
 default_min_hwe_kernel Default Minimum Kernel Version. The default minimum
kernel version used on all new and commissioned nodes.
 default_osystem Default operating system used for deployment.
 default_storage_layout Default storage layout. Storage layout that is applied to a
node when it is commissioned. Available choices are: 'bcache' (Bcache layout), 'flat' (Flat
layout), 'lvm' (LVM layout).
 disk_erase_with_quick_erase Use quick erase by default when erasing disks.. This is
not a secure erase; it wipes only the beginning and end of each disk.
 disk_erase_with_secure_erase Use secure erase by default when erasing disks. Will
only be used on devices that support secure erase. Other devices will fall back to full wipe
or quick erase depending on the selected options.
 dnssec_validation Enable DNSSEC validation of upstream zones. Only used when
MAAS is running its own DNS server. This value is used as the value of
'dnssec_validation' in the DNS server config.
 enable_analytics Enable Google Analytics in MAAS UI to shape improvements in
user experience.
 enable_disk_erasing_on_release Erase nodes' disks prior to releasing. Forces users to
always erase disks when releasing.
 enable_http_proxy Enable the use of an APT and HTTP/HTTPS proxy. Provision
nodes to use the built-in HTTP proxy (or user specified proxy) for APT. MAAS also uses
the proxy for downloading boot images.
 enable_third_party_drivers Enable the installation of proprietary drivers (i.e.
HPVSA).
 http_proxy Proxy for APT and HTTP/HTTPS. This will be passed onto provisioned
nodes to use as a proxy for APT traffic. MAAS also uses the proxy for downloading boot
images. If no URL is provided, the built-in MAAS proxy will be used.
 kernel_opts Boot parameters to pass to the kernel by default.
 maas_name MAAS name.
 max_node_commissioning_results The maximum number of commissioning results
runs which are stored.
 max_node_installation_results The maximum number of installation result runs
which are stored.
 max_node_testing_results The maximum number of testing results runs which are
stored.
 network_discovery . When enabled, MAAS will use passive techniques (such as
listening to ARP requests and mDNS advertisements) to observe networks attached to
rack controllers. Active subnet mapping will also be available to be enabled on the
configured subnets.
 ntp_external_only Use external NTP servers only. Configure all region controller
hosts, rack controller hosts, and subsequently deployed machines to refer directly to the
configured external NTP servers. Otherwise only region controller hosts will be
configured to use those external NTP servers, rack contoller hosts will in turn refer to the
regions' NTP servers, and deployed machines will refer to the racks' NTP servers.
 ntp_servers Addresses of NTP servers. NTP servers, specified as IP addresses or
hostnames delimited by commas and/or spaces, to be used as time references for MAAS
itself, the machines MAAS deploys, and devices that make use of MAAS's DHCP
services.
 subnet_ip_exhaustion_threshold_count If the number of free IP addresses on a
subnet becomes less than or equal to this threshold, an IP exhaustion warning will appear
for that subnet.
 upstream_dns Upstream DNS used to resolve domains not managed by this MAAS
(space-separated IP addresses). Only used when MAAS is running its own DNS server.
This value is used as the value of 'forwarders' in the DNS server config.
  windows_kms_host Windows KMS activation host. FQDN or IP address of the host that
provides the KMS Windows activation service. (Only needed for Windows deployments
using KMS activation.)

POST /api/2.0/maas/ op=set_config

Set a config value.

 param name The name of the config item to be set.

 param value The value of the config item to be set.

Available configuration items:

 active_discovery_interval Active subnet mapping interval. When enabled, each rack

will scan subnets enabled for active mapping. This helps ensure discovery information is
accurate and complete.
 boot_images_auto_import Automatically import/refresh the boot images every 60
minutes.
 commissioning_distro_series Default Ubuntu release used for commissioning.
 completed_intro Marks if the initial intro has been completed.
 curtin_verbose Run the fast-path installer with higher verbosity. This provides more
detail in the installation logs.
 default_distro_series Default OS release used for deployment.
 default_dns_ttl Default Time-To-Live for the DNS. If no TTL value is specified at a
more specific point this is how long DNS responses are valid, in seconds.
 default_min_hwe_kernel Default Minimum Kernel Version. The default minimum
kernel version used on all new and commissioned nodes.
 default_osystem Default operating system used for deployment.
 default_storage_layout Default storage layout. Storage layout that is applied to a
node when it is commissioned. Available choices are: 'bcache' (Bcache layout), 'flat' (Flat
layout), 'lvm' (LVM layout).
 disk_erase_with_quick_erase Use quick erase by default when erasing disks.. This is
not a secure erase; it wipes only the beginning and end of each disk.
 disk_erase_with_secure_erase Use secure erase by default when erasing disks. Will
only be used on devices that support secure erase. Other devices will fall back to full wipe
or quick erase depending on the selected options.
 dnssec_validation Enable DNSSEC validation of upstream zones. Only used when
MAAS is running its own DNS server. This value is used as the value of
'dnssec_validation' in the DNS server config.
 enable_analytics Enable Google Analytics in MAAS UI to shape improvements in
user experience.
 enable_disk_erasing_on_release Erase nodes' disks prior to releasing. Forces users to
always erase disks when releasing.
 enable_http_proxy Enable the use of an APT and HTTP/HTTPS proxy. Provision
nodes to use the built-in HTTP proxy (or user specified proxy) for APT. MAAS also uses
the proxy for downloading boot images.
  enable_third_party_drivers Enable the installation of proprietary drivers (i.e.
HPVSA).
 http_proxy Proxy for APT and HTTP/HTTPS. This will be passed onto provisioned
nodes to use as a proxy for APT traffic. MAAS also uses the proxy for downloading boot
images. If no URL is provided, the built-in MAAS proxy will be used.
 kernel_opts Boot parameters to pass to the kernel by default.
 maas_name MAAS name.
 max_node_commissioning_results The maximum number of commissioning results
runs which are stored.
 max_node_installation_results The maximum number of installation result runs
which are stored.
 max_node_testing_results The maximum number of testing results runs which are
stored.
 network_discovery . When enabled, MAAS will use passive techniques (such as
listening to ARP requests and mDNS advertisements) to observe networks attached to
rack controllers. Active subnet mapping will also be available to be enabled on the
configured subnets.
 ntp_external_only Use external NTP servers only. Configure all region controller
hosts, rack controller hosts, and subsequently deployed machines to refer directly to the
configured external NTP servers. Otherwise only region controller hosts will be
configured to use those external NTP servers, rack contoller hosts will in turn refer to the
regions' NTP servers, and deployed machines will refer to the racks' NTP servers.
 ntp_servers Addresses of NTP servers. NTP servers, specified as IP addresses or
hostnames delimited by commas and/or spaces, to be used as time references for MAAS
itself, the machines MAAS deploys, and devices that make use of MAAS's DHCP
services.
 subnet_ip_exhaustion_threshold_count If the number of free IP addresses on a
subnet becomes less than or equal to this threshold, an IP exhaustion warning will appear
for that subnet.
 upstream_dns Upstream DNS used to resolve domains not managed by this MAAS
(space-separated IP addresses). Only used when MAAS is running its own DNS server.
This value is used as the value of 'forwarders' in the DNS server config.
 windows_kms_host Windows KMS activation host. FQDN or IP address of the host that
provides the KMS Windows activation service. (Only needed for Windows deployments
using KMS activation.)

Machine

Manage an individual Machine.

The Machine is identified by its system_id.

DELETE /api/2.0/machines/{system_id}/

Delete a specific Node.

Returns 404 if the node is not found. Returns 403 if the user does not have permission to delete
the node. Returns 204 if the node is successfully deleted.

GET /api/2.0/machines/{system_id}/

Read a specific Node.

Returns 404 if the node is not found.

GET /api/2.0/machines/{system_id}/ op=details

Obtain various system details.

For example, LLDP and lshw XML dumps.

Returns a {detail_type: xml, ...} map, where detail_type is something like "lldp" or
"lshw".

Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because
JSON can't do binary content without applying additional encoding like base-64.

Returns 404 if the node is not found.

GET /api/2.0/machines/{system_id}/ op=get_curtin_config

Return the rendered curtin configuration for the machine.

Returns 404 if the machine could not be found. Returns 403 if the user does not have permission
to get the curtin configuration.

GET /api/2.0/machines/{system_id}/ op=power_parameters

Obtain power parameters.

This method is reserved for admin users and returns a 403 if the user is not one.

This returns the power parameters, if any, configured for a node. For some types of power control
this will include private information such as passwords and secret keys.

Returns 404 if the node is not found.

GET /api/2.0/machines/{system_id}/ op=query_power_state

Query the power state of a node.