Returns 404 if the subnet is not found.

GET /api/2.0/subnets/{id}/ op=unreserved_ip_ranges

Lists IP ranges currently unreserved in the subnet.

Returns 404 if the subnet is not found.

PUT /api/2.0/subnets/{id}/

Update the specified subnet.

Please see the documentation for the 'create' operation for detailed descriptions of each
parameter.
Optional parameters

name Name of the subnet.

description Description of the subnet.

vlan VLAN this subnet belongs to.

space Space this subnet is in.

cidr The network CIDR for this subnet.

gateway_ip The gateway IP address for this subnet.

rdns_mode How reverse DNS is handled for this subnet.

allow_proxy Configure maas-proxy to allow requests from this subnet.

dns_servers Comma-seperated list of DNS servers for this subnet.

managed If False, MAAS should not manage this subnet. (Default: True)

Returns 404 if the subnet is not found.

Subnets

Manage subnets.

GET /api/2.0/subnets/

List all subnets.

POST /api/2.0/subnets/

Create a subnet.
Required parameters

cidr The network CIDR for this subnet.

Optional parameters

name Name of the subnet.

description Description of the subnet.

vlan VLAN this subnet belongs to. Defaults to the default VLAN for the provided fabric or
defaults to the default VLAN in the default fabric (if unspecified).

fabric Fabric for the subnet. Defaults to the fabric the provided VLAN belongs to, or defaults to
the default fabric.

vid VID of the VLAN this subnet belongs to. Only used when vlan is not provided. Picks the
VLAN with this VID in the provided fabric or the default fabric if one is not given.

space Space this subnet is in. Defaults to the default space.

gateway_ip The gateway IP address for this subnet.

rdns_mode How reverse DNS is handled for this subnet. One of: 0 (Disabled), 1 (Enabled), or 2
(RFC2317). Disabled means no reverse zone is created; Enabled means generate the reverse
zone; RFC2317 extends Enabled to create the necessary parent zone with the appropriate
CNAME resource records for the network, if the network is small enough to require the support
described in RFC2317.

allow_proxy Configure maas-proxy to allow requests from this subnet.

dns_servers Comma-seperated list of DNS servers for this subnet.

managed In MAAS 2.0+, all subnets are assumed to be managed by default.

Only managed subnets allow DHCP to be enabled on their related dynamic ranges. (Thus,
dynamic ranges become "informational only"; an indication that another DHCP server is
currently handling them, or that MAAS will handle them when the subnet is enabled for
management.)

Managed subnets do not allow IP allocation by default. The meaning of a "reserved" IP range is
reversed for an unmanaged subnet. (That is, for managed subnets, "reserved" means "MAAS
cannot allocate any IP address within this reserved block". For unmanaged subnets, "reserved"
means "MAAS must allocate IP addresses only from reserved IP ranges".

Tag

Manage a Tag.

Tags are properties that can be associated with a Node and serve as criteria for selecting and
allocating nodes.

A Tag is identified by its name.

DELETE /api/2.0/tags/{name}/

Delete a specific Tag.

Returns 404 if the tag is not found. Returns 204 if the tag is successfully deleted.

GET /api/2.0/tags/{name}/

Read a specific Tag.

Returns 404 if the tag is not found.

GET /api/2.0/tags/{name}/ op=devices

Get the list of devices that have this tag.

Returns 404 if the tag is not found.

GET /api/2.0/tags/{name}/ op=machines

Get the list of machines that have this tag.

Returns 404 if the tag is not found.

GET /api/2.0/tags/{name}/ op=nodes

Get the list of nodes that have this tag.

Returns 404 if the tag is not found.

GET /api/2.0/tags/{name}/ op=rack_controllers

Get the list of rack controllers that have this tag.

Returns 404 if the tag is not found.

GET /api/2.0/tags/{name}/ op=region_controllers

Get the list of region controllers that have this tag.

Returns 404 if the tag is not found.

POST /api/2.0/tags/{name}/ op=rebuild

Manually trigger a rebuild the tag <=> node mapping.

This is considered a maintenance operation, which should normally not be necessary. Adding
nodes or updating a tag's definition should automatically trigger the appropriate changes.

Returns 404 if the tag is not found.

POST /api/2.0/tags/{name}/ op=update_nodes

Add or remove nodes being associated with this tag.

 param add system_ids of nodes to add to this tag.

 param remove system_ids of nodes to remove from this tag.
 param definition (optional) If supplied, the definition will be validated against the
current definition of the tag. If the value does not match, then the update will be dropped
(assuming this was just a case of a worker being out-of-date)
 param rack_controller A system ID of a rack controller that did the processing. This
value is optional. If not supplied, the requester must be a superuser. If supplied, then the
requester must be the rack controller.

Returns 404 if the tag is not found. Returns 401 if the user does not have permission to update the
nodes. Returns 409 if 'definition' doesn't match the current definition.

PUT /api/2.0/tags/{name}/

Update a specific Tag.

 param name The name of the Tag to be created. This should be a short name, and will be
used in the URL of the tag.
 param comment A long form description of what the tag is meant for. It is meant as a
human readable description of the tag.
 param definition An XPATH query that will be evaluated against the hardware_details
stored for all nodes (output of lshw -xml).

Returns 404 if the tag is not found.

Tags

Manage the collection of all the Tags in this MAAS.

GET /api/2.0/tags/

List Tags.

Get a listing of all tags that are currently defined.

POST /api/2.0/tags/

Create a new Tag.

 param name The name of the Tag to be created. This should be a short name, and will be
used in the URL of the tag.
 param comment A long form description of what the tag is meant for. It is meant as a
human readable description of the tag.
 param definition An XPATH query that will be evaluated against the hardware_details
stored for all nodes (output of lshw -xml).
 param kernel_opts Can be None. If set, nodes associated with this tag will add this
string to their kernel options when booting. The value overrides the global 'kernel_opts'
setting. If more than one tag is associated with a node, the one with the lowest
alphabetical name will be picked (eg 01-my-tag will be taken over 99-tag-name).

Returns 401 if the user is not an admin.

User

Manage a user account.

DELETE /api/2.0/users/{username}/

Deletes a user

GET /api/2.0/users/{username}/
Users

Manage the user accounts of this MAAS.

GET /api/2.0/users/

List users.
GET /api/2.0/users/ op=whoami

Returns the currently logged in user.

POST /api/2.0/users/

Create a MAAS user account.

This is not safe: the password is sent in plaintext. Avoid it for production, unless you are
confident that you can prevent eavesdroppers from observing the request.

 param username Identifier-style username for the new user.

 type username unicode
 param email Email address for the new user.
 type email unicode
 param password Password for the new user.
 type password unicode
 param is_superuser Whether the new user is to be an administrator.
 type is_superuser bool ('0' for False, '1' for True)

Returns 400 if any mandatory parameters are missing.

MAAS version

Information about this MAAS instance.

This returns a JSON dictionary with information about this MAAS instance:

{
'version': '1.8.0',
'subversion': 'alpha10+bzr3750',
'capabilities': ['capability1', 'capability2', ...]
}
GET /api/2.0/version/

Version and capabilities of this MAAS instance.

VLAN

Manage VLAN on a fabric.

DELETE /api/2.0/fabrics/{fabric_id}/vlans/{vid}/

Delete VLAN on fabric.

Returns 404 if the fabric or VLAN is not found.

GET /api/2.0/fabrics/{fabric_id}/vlans/{vid}/

Read VLAN on fabric.

Returns 404 if the fabric or VLAN is not found.

PUT /api/2.0/fabrics/{fabric_id}/vlans/{vid}/

Update VLAN.

 param name Name of the VLAN.

 type name unicode
 param description Description of the VLAN.
 type description unicode
 param vid VLAN ID of the VLAN.
 type vid integer
 param mtu The MTU to use on the VLAN.
 type mtu integer
 param dhcp_on Whether or not DHCP should be managed on the VLAN.
 type dhcp_on boolean
 param primary_rack The primary rack controller managing the VLAN.
 type primary_rack system_id
 param secondary_rack The secondary rack controller manging the VLAN.
 type secondary_rack system_id
 param relay_vlan Only set when this VLAN will be using a DHCP relay to forward
DHCP requests to another VLAN that MAAS is or will run the DHCP server. MAAS will
not run the DHCP relay itself, it must be configured to proxy reqests to the primary and/or
secondary rack controller interfaces for the VLAN specified in this field.
 type relay_vlan ID of VLAN
 param space The space this VLAN should be placed in. Passing in an empty string (or
the string 'undefined') will cause the VLAN to be placed in the 'undefined' space.
 type space unicode

Returns 404 if the fabric or VLAN is not found.

VLANs

Manage VLANs on a fabric.

GET /api/2.0/fabrics/{fabric_id}/vlans/

List all VLANs belonging to fabric.

Returns 404 if the fabric is not found.

POST /api/2.0/fabrics/{fabric_id}/vlans/

Create a VLAN.

 param name Name of the VLAN.

 param description Description of the VLAN.
 param vid VLAN ID of the VLAN.

Volume group

Manage volume group on a machine.

DELETE /api/2.0/nodes/{system_id}/volume-group/{id}/

Delete volume group on a machine.

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

GET /api/2.0/nodes/{system_id}/volume-group/{id}/

Read volume group on a machine.

Returns 404 if the machine or volume group is not found.

POST /api/2.0/nodes/{system_id}/volume-group/{id}/ op=create_logical_volume

Create a logical volume in the volume group.

 param name Name of the logical volume.

 param uuid (optional) UUID of the logical volume.
 param size Size of the logical volume.

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

POST /api/2.0/nodes/{system_id}/volume-group/{id}/ op=delete_logical_volume

Delete a logical volume in the volume group.

 param id ID of the logical volume.

Returns 403 if no logical volume with id. Returns 404 if the machine or volume group is not
found. Returns 409 if the machine is not Ready.
PUT /api/2.0/nodes/{system_id}/volume-group/{id}/

Read volume group on a machine.

 param name Name of the volume group.

 param uuid UUID of the volume group.
 param add_block_devices Block devices to add to the volume group.
 param remove_block_devices Block devices to remove from the volume group.
 param add_partitions Partitions to add to the volume group.
 param remove_partitions Partitions to remove from the volume group.

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

Volume groups

Manage volume groups on a machine.

GET /api/2.0/nodes/{system_id}/volume-groups/

List all volume groups belonging to a machine.

Returns 404 if the machine is not found.

POST /api/2.0/nodes/{system_id}/volume-groups/

Create a volume group belonging to machine.

 param name Name of the volume group.

 param uuid (optional) UUID of the volume group.
 param block_devices Block devices to add to the volume group.
 param partitions Partitions to add to the volume group.

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

Zone

Manage a physical zone.

Any node is in a physical zone, or "zone" for short. The meaning of a physical zone is up to you:
it could identify e.g. a server rack, a network, or a data centre. Users can then allocate nodes from
specific physical zones, to suit their redundancy or performance requirements.

This functionality is only available to administrators. Other users can view physical zones, but
not modify them.
DELETE /api/2.0/zones/{name}/

DELETE request. Delete zone.

Returns 404 if the zone is not found. Returns 204 if the zone is successfully deleted.

GET /api/2.0/zones/{name}/

GET request. Return zone.

Returns 404 if the zone is not found.

PUT /api/2.0/zones/{name}/

PUT request. Update zone.

Returns 404 if the zone is not found.

Zones

Manage physical zones.

GET /api/2.0/zones/

List zones.

Get a listing of all the physical zones.

POST /api/2.0/zones/

Create a new physical zone.

 param name Identifier-style name for the new zone.

 type name unicode
 param description Free-form description of the new zone.
 type description unicode

Power types
This is the list of the supported power types and their associated power parameters. Note that the
list of usable power types for a particular rack controller might be a subset of this list if the rack
controller in question is from an older version of MAAS.

ipmi (IPMI)

Power parameters:
  power_driver (Power driver). Choices: 'LAN' (LAN [IPMI 1.5]), 'LAN_2_0' (LAN_2_0 [IPMI 2.0])
Default: 'LAN_2_0'.
 power_address (IP address).
 power_user (Power user).
 power_pass (Power password).
 mac_address (Power MAC).

amt (Intel AMT)

Power parameters:

 power_pass (Power password).

 power_address (Power address).

sm15k (SeaMicro 15000)

Power parameters:

 system_id (System ID).

 power_address (Power address).
 power_user (Power user).
 power_pass (Power password).
 power_control (Power control type). Choices: 'ipmi' (IPMI), 'restapi' (REST API v0.9), 'restapi2'
(REST API v2.0) Default: 'ipmi'.

vmware (VMware)

Power parameters:

 power_vm_name (VM Name (if UUID unknown)).

 power_uuid (VM UUID (if known)).
 power_address (VMware hostname).
 power_user (VMware username).
 power_pass (VMware password).
 power_port (VMware API port (optional)).
 power_protocol (VMware API protocol (optional)).

rsd (Rack Scale Design)

Power parameters:

 power_address (Pod address).

 power_user (Pod user).
 power_pass (Pod password).
 node_id (Node ID).
virsh (Virsh (virtual systems))

Power parameters:

 power_address (Virsh address).

 power_pass (Virsh password (optional)).
 power_id (Virsh VM ID).

apc (American Power Conversion (APC) PDU)

Power parameters:

 power_address (IP for APC PDU).

 node_outlet (APC PDU node outlet number (1-16)).
 power_on_delay (Power ON outlet delay (seconds)). Default: '5'.

wedge (Facebook's Wedge)

Power parameters:

 power_address (IP address).

 power_user (Power user).
 power_pass (Power password).

nova (OpenStack Nova)

Power parameters:

 nova_id (Host UUID).

 os_tenantname (Tenant name).
 os_username (Username).
 os_password (Password).
 os_authurl (Auth URL).

mscm (HP Moonshot - iLO Chassis Manager)

Power parameters:

 power_address (IP for MSCM CLI API).

 power_user (MSCM CLI API user).
 power_pass (MSCM CLI API password).
 node_id (Node ID - Must adhere to cXnY format (X=cartridge number, Y=node number).).

dli (Digital Loggers, Inc. PDU)

Power parameters:
  outlet_id (Outlet ID).
 power_address (Power address).
 power_user (Power user).
 power_pass (Power password).

ucsm (Cisco UCS Manager)

Power parameters:

 uuid (Server UUID).

 power_address (URL for XML API).
 power_user (API user).
 power_pass (API password).

hmc (IBM Hardware Management Console (HMC))

Power parameters:

 power_address (IP for HMC).

 power_user (HMC username).
 power_pass (HMC password).
 server_name (HMC Managed System server name).
 lpar (HMC logical partition).

msftocs (Microsoft OCS - Chassis Manager)

Power parameters:

 power_address (Power address).

 power_port (Power port).
 power_user (Power user).
 power_pass (Power password).
 blade_id (Blade ID (Typically 1-24)).

fence_cdu (Sentry Switch CDU)

Power parameters:

 power_address (Power address).

 power_id (Power ID).
 power_user (Power user).
 power_pass (Power password).

manual (Manual)

Power parameters:
moonshot (HP Moonshot - iLO4 (IPMI))

Power parameters:

 power_address (Power address).

 power_user (Power user).
 power_pass (Power password).
 power_hwaddress (Power hardware address).

Pod types
This is the list of the supported pod types and their associated parameters. Note that the list of
usable pod types for a particular rack controller might be a subset of this list if the rack controller
in question is from an older version of MAAS.

rsd (Rack Scale Design)

Parameters:

 power_address (Pod address).

 power_user (Pod user).
 power_pass (Pod password).
 node_id (Node ID).

virsh (Virsh (virtual systems))

Parameters:

 power_address (Virsh address).

 power_pass (Virsh password (optional)).
 power_id (Virsh VM ID).
API authentication
MAAS's API uses OAuth as its authentication mechanism. There isn't a third party involved (as
in 3-legged OAuth) and so the process used is what's commonly referred to as 0-legged OAuth:
the consumer accesses protected resources by submitting OAuth signed requests.

Note that some API endpoints support unauthenticated requests (i.e. anonymous access). See the
API documentation <api> for details.

Examples
Here are two examples on how to perform an authenticated GET request to retrieve the list of
nodes. The <key>, <secret>, <consumer_key> tokens are the three elements that compose the
API key (API key = '<consumer_key>:<key>:<secret>').

Python
import oauth.oauth as oauth
import httplib2
import uuid

def perform_API_request(site, uri, method, key, secret, consumer_key):

resource_tok_string = "oauth_token_secret=%s&oauth_token=%s" % (
secret, key)
resource_token = oauth.OAuthToken.from_string(resource_tok_string)
consumer_token = oauth.OAuthConsumer(consumer_key, "")

oauth_request = oauth.OAuthRequest.from_consumer_and_token(
consumer_token, token=resource_token, http_url=site,
parameters={'oauth_nonce': uuid.uuid4().get_hex()})
oauth_request.sign_request(
oauth.OAuthSignatureMethod_PLAINTEXT(), consumer_token,
resource_token)
headers = oauth_request.to_header()
url = "%s%s" % (site, uri)
http = httplib2.Http()
return http.request(url, method, body=None, headers=headers)

# API key = '<consumer_key>:<key>:<secret>'

response = perform_API_request(
'http://server/MAAS/api/1.0', '/nodes/?op=list', 'GET', '<key>',
'<secret>',
'<consumer_key>')

Ruby
require 'oauth'
require 'oauth/signature/plaintext'

def perform_API_request(site, uri, key, secret, consumer_key)

 consumer = OAuth::Consumer.new(
consumer_key, "",
{ :site => "http://localhost/MAAS/api/1.0",
:scheme => :header, :signature_method => "PLAINTEXT"})
access_token = OAuth::AccessToken.new(consumer, key, secret)
return access_token.request(:get, "/nodes/?op=list")
end

# API key = "<consumer_key>:<key>:<secret>"

response = perform_API_request(
"http://server/MAAS/api/1.0", "/nodes/?op=list", "<key>", "<secret>",
"consumer_key>")