machine

Docs
1

Manage an individual machine.

maas $PROFILE machine [-h] COMMAND ...

Common command-line options include:

  • HELP (--help, -h): shows an explanatory message and exits.
  • DEBUG (--debug, -d): be verbose about API responses.
  • INSECURE (--insecure, -k): disable SSL certificate checks.

These options will not be repeated in the instructions below. Note that values for COMMAND and associated syntax are given below. Also note that some operations use the singular (“machine”) and others use the plural (“machines”).

Some commands accept keyword arguments. Pass each argument as a key-value pair with an equals sign between the key and the value:

key1=value1 key2=value key3=value3

Keyword arguments must come after any positional arguments.

abort

Aborts any active operations on the machine identified by system_id.

Canonical form

maas $PROFILE machine abort [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • comment Optional string. A message to be added to the event log, alongside the logging of the abort operation.

Requirements

No special requirements.

Additional effects

None.

clear-default-gateways

Clear any set default gateways on a machine with the given system_id.

Canonical form

maas $PROFILE machine clear-default-gateways [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

This will clear both IPv4 and IPv6 gateways on the machine. This will transition the logic of identifying the best gateway to MAAS, based the following criteria:

  1. Managed subnets over unmanaged subnets.
  2. Bond interfaces over physical interfaces.
  3. Machine’s boot interface over all other interfaces except bonds.
  4. Physical interfaces over VLAN interfaces.
  5. Sticky IP links over user reserved IP links.
  6. User reserved IP links over auto IP links.

If the default gateways need to be specific for this machine you can set which interface and subnet gateway to use when this machine is deployed with the interfaces set-default-gateway API.

commission

Begin the commissioning process for the machine identified by system_id.

Canonical form

maas $PROFILE machine commission [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • enable_ssh Optional integer. Whether to enable SSH for the commissioning environment using the user’s SSH key(s). ‘1’ == True, ‘0’ == False.

  • skip_bmc_config Optional integer. Whether to skip re-configuration of the BMC for IPMI based machines. ‘1’ == True, ‘0’ == False.

  • skip_networking Optional integer. Whether to skip re-configuring the networking on the machine after the commissioning has completed. ‘1’ == True, ‘0’ == False.

  • skip_storage Optional integer. Whether to skip re-configuring the storage on the machine after the commissioning has completed. ‘1’ == True, ‘0’ == False.

  • commissioning_scripts Optional string. A comma separated list of commissioning script names and tags to be run. By default all custom commissioning scripts are run. Built-in commissioning scripts always run. Selecting ‘update_firmware’ or ‘configure_hba’ will run firmware updates or configure HBAs on matching machines.

  • testing_scripts Optional string. A comma separated list of testing script names and tags to be run. By default all tests tagged ‘commissioning’ will be run. Set to ‘none’ to disable running tests.

  • parameters Optional string. Scripts selected to run may define their own parameters. These parameters may be passed using the parameter name. Optionally a parameter may have the script name prepended to have that parameter only apply to that specific script.

Requirements

A machine in the ‘ready’, ‘declared’ or ‘failed test’ state may initiate a commissioning cycle where it is checked out and tested in preparation for transitioning to the ‘ready’ state. If it is already in the ‘ready’ state this is considered a re-commissioning process
which is useful if commissioning tests were changed after it previously commissioned.

Additional effects

None.

delete

Deletes a machine with the given system_id.

Canonical form

maas $PROFILE machine delete [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

A machine that is acting as a VM host (or pod) cannot be deleted if it currently hosts virtual machines.

deploy

Deploys an operating system on a machine with the given system_id.

Canonical form

maas $PROFILE machine deploy [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • user_data Optional string. If present, this blob of base64-encoded user-data to be made available to the machines through the metadata service.

  • distro_series Optional string. If present, this parameter specifies the OS release the machine will use.

  • hwe_kernel Optional string. If present, this parameter specified the kernel to be used on the machine.

  • agent_name Optional string. An optional agent name to attach to the acquired machine.

  • bridge_all Optional Boolean. Optionally create a bridge interface for every configured interface on the machine. The created bridges will be removed once the machine is released.

  • bridge_type Optional string. Optionally create the bridges with this type. Possible values are standard and ovs.

  • bridge_stp Optional Boolean. Optionally turn spanning tree protocol on or off for the bridges created on every configured interface.

  • bridge_fd Optional integer. Optionally adjust the forward delay to time seconds (defaults to 15s).

  • comment Optional string. Optional comment for the event log.

  • install_rackd Optional Boolean. If true, the rack controller will be installed on this machine.

  • install_kvm Optional Boolean. If true, KVM will be installed on this machine and added to MAAS.

  • register_vmhost Optional Boolean. If true, the machine will be registered as a LXD VM host in MAAS.

  • ephemeral_deploy Optional Boolean. If true, machine will be deployed ephemerally even if it has disks.

  • vcenter_registration Optional Boolean. If false, do not send globally defined VMWare vCenter credentials to the machine.

  • enable_hw_sync Optional. If true, machine will be deployed with a small agent periodically pushing hardware data to detect any change in devices.

Requirements

No special requirements.

Additional effects

None.

details

Get system details for the machine with system_id.

Canonical form

maas $PROFILE machine details [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

Returns 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.

exit-rescue-mode

Exits the rescue mode process on a machine with the given system_id.

Canonical form

maas $PROFILE machine exit-rescue-mode [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

A machine in the ‘rescue mode’ state may exit the rescue mode process.

Additional effects

None.

get-curtin-config

Return the rendered curtin configuration for the machine identified by system_id.

Canonical form

maas $PROFILE machine get-curtin-config [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

None.

get-token

Get a machine token for system_id.

Canonical form

maas $PROFILE machine get-token [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

None.

lock

Mark a machine with the given system_id as ‘Locked’ to prevent changes.

Canonical form

maas $PROFILE machine lock [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • comment Optional string. Optional comment for the event log.

Requirements

No special requirements.

Additional effects

None.

mark-broken

Mark a machine with the given system_id as broken to prevent it from being put into operation.

Canonical form

maas $PROFILE machine mark-broken [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • comment Optional string. Optional comment for the event log. Will also be displayed on the machine as an error description until marked fixed.

Requirements

Allocated machines must be released before they can be marked broken.

Additional effects

None.

mark-fixed

Mark a machine with the given system_id as ‘Fixed’.

Canonical form

maas $PROFILE machine mark-fixed [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • comment Optional string. Optional comment for the event log. Will also be displayed on the machine as an error description until marked fixed.

Requirements

No special requirements.

Additional effects

None.

mount-special

Mount a special-purpose filesystem (e.g. tmpfs) on a machine with the given system_id.

Canonical form

maas $PROFILE machine mount-special [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • fstype Required string. The filesystem type. This must be a filesystem that does not require a block special device.

  • mount_point Required string… Path on the filesystem to mount.

  • mount_option Optional string. Options to pass to mount(8).

Requirements

No special requirements.

Additional effects

None.

override-failed-testing

Ignore failed tests and put machine back into a usable state.

Canonical form

maas $PROFILE machine override-failed-testing [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • comment Optional string. Comment for the event log.

Requirements

No special requirements.

Additional effects

None.

power-off

Powers off the machine identified by system_id.

Canonical form

maas $PROFILE machine power-off [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • stop_mode Optional string. Power-off mode. If ‘soft’, perform a soft power down if the machine’s power type supports it, otherwise perform a hard power off. For all values other than ‘soft’, and by default, perform a hard power off. A soft power off generally asks the OS to shutdown the system gracefully before powering off, while a hard power off occurs immediately without any warning to the OS.

  • comment Optional. Comment for the event log.

Requirements

No special requirements.

Additional effects

None.

power-on

Turn on the machine identified by system_id with optional user-data and comment.

Canonical form

maas $PROFILE machine power-on [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • user_data Optional string. Base64-encoded blob of data to be made available to the machines through the metadata service.

  • comment Optional string. Comment for the event log.

Requirements

No special requirements.

Additional effects

None.

power-parameters

Gets power parameters for a given system_id, if any.

Canonical form

maas $PROFILE machine power-parameters [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

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

Additional effects

For some types of power control, the returned parameters will include private information such as passwords and secret keys.

query-power-state

Gets the power state of a given machine identified by system_id.

Canonical form

maas $PROFILE machine query-power-state [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

MAAS sends a request to the machine’s power controller, which asks it about the machine’s state. The reply to this could be delayed by up to 30 seconds while waiting for the power controller to respond. Use this method sparingly as it ties up an appserver thread while waiting.

read

Returns comprehensive information about the machine identified by system_id in JSON format.

Canonical form

maas $PROFILE machine read [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

None.

release

Releases a machine with the given system_id.

Canonical form

maas $PROFILE machine release [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • comment Optional string. Optional comment for the event log.

  • erase Optional Boolean. Erase the disk when releasing.

  • secure_erase Optional Boolean. Use the drive’s secure erase feature if available. In some cases, this can be much faster than overwriting the drive. Some drives implement secure erasure by overwriting themselves so this could still be slow.

  • quick_erase Optional Boolean. Wipe 2MiB at the start and at the end of the drive to make data recovery inconvenient and unlikely to happen by accident. This is not secure.

  • force Optional. Will force the release of a machine. If the machine was deployed as a KVM host, this will be deleted as well as all machines inside the KVM host. USE WITH CAUTION.

Requirements

No special requirements.

Additional effects

Releasing a machine moves it from “Deployed” to “Ready,” that is, the machine is no longer actively running, and it is no longer allocated to the user who deployed it. This means a released machine could be allocated for use by another MAAS user.

Also, if you choose to erase the machine when releasing it, be aware of these options:

  • If neither secure_erase nor quick_erase are specified, MAAS will overwrite the whole disk with null bytes. This can be very slow.

  • If both secure_erase and quick_erase are specified and the drive does NOT have a secure erase feature, MAAS will behave as if only quick_erase was specified.

  • If secure_erase is specified and quick_erase is NOT specified and the drive does NOT have a secure erase feature, MAAS will behave as if secure_erase was NOT specified, i.e. MAAS will overwrite the whole disk with null bytes. This can be very slow.

rescue-mode

Begins the rescue mode process on a machine with the given system_id.

Canonical form

maas $PROFILE machine rescue-mode [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

A machine in the “Deployed” or “Broken” state may enter rescue mode.

Additional effects

None.

restore-default-configuration

Restores the default configuration options on a machine with the given system_id.

Canonical form

maas $PROFILE machine restore-default-configuration [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

None.

restore-networking-configuration

Restores networking options to their initial state on a machine with the given system_id.

Canonical form

maas $PROFILE machine restore-networking-configuration [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

None.

restore-storage-configuration

Restores storage configuration options to their initial state on a machine with the given system_id.

Canonical form

maas $PROFILE machine restore-storage-configuration [--help] [-d] [-k] system_id [data ...]

Keyword arguments

None.

Requirements

No special requirements.

set-owner-data

Deprecated, use set-workload-annotations instead.

set-storage-layout

Changes the storage layout on machine with the given system_id.

Canonical form

maas $PROFILE machine set-storage-layout [--help] [-d] [-k]
                                                system_id [data ...]

Keyword arguments

  • storage_layout Required string. Storage layout for the machine, choosing from flat, lvm, bcache, vmfs6, vmfs7, custom or blank.

  • boot_size Optional string. Size of the boot partition (e.g. 512M, 1G).

  • root_size Optional string. Size of the root partition (e.g. 24G).

  • root_device Optional string. Physical block device to place the root partition (e.g. /dev/sda).

  • vg_name Optional string. LVM only. Name of created volume group.

  • lv_name Optional string. LVM only. Name of created logical volume.

  • lv_size Optional string. LVM only. Size of created logical volume.

  • cache_device Optional string. Bcache only. Physical block device to use as the cache device (e.g. /dev/sda).

  • cache_mode Optional string. Bcache only. Cache mode for bcache device, choosing from writeback, writethrough, writearound.

  • cache_size Optional string. Bcache only. Size of the cache partition to create on the cache device (e.g. 48G).

  • cache_no_part Optional Boolean. Bcache only. Don’t create a partition on the cache device. Use the entire disk as the cache device.

Requirements

This operation can only be performed on a machine with a status of ‘Ready’.

Additional effects

This will clear the current storage layout and any extra configuration and replace it will the new layout.

set-workload-annotations

Set workload annotations for the machine identified by system_id.

Canonical form

maas $PROFILE machine set-workload-annotations [--help] [-d] [-k]
                                                      system_id [data ...]

Keyword arguments

  • key Required string. The workload annotation to be applied to the machine; can be any valid string. Pass any key=value form 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.

Requirements

Only the allocated owner can set a workload annotation.

Additional effects

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

test

Begins the testing process for a given machine.

Canonical form

maas $PROFILE machine test [--help] [-d] [-k] system_id [data ...]

Keyword annotations

  • enable_ssh Optional integer. Whether to enable SSH for the testing environment using the user’s SSH key(s). 0 == false. 1 == true.

  • testing_scripts Optional string. A comma-separated list of testing script names and tags to be run. By default all tests tagged ‘commissioning’ will be run.

  • parameters Optional string. Scripts selected to run may define their own parameters. These parameters may be passed using the parameter name. Optionally a parameter may have the script name prepended to have that parameter only apply to that specific script.

Requirements

A machine in the ‘ready’, ‘allocated’, ‘deployed’, ‘broken’, or any failed state may run tests. If testing is started and successfully passes from ‘broken’ or any failed state besides ‘failed commissioning’ the machine will be returned to a ready state. Otherwise the machine will return to the state it was when testing started.

Additional effects

None.

unlock

Mark a machine with the given system_id as ‘Unlocked’ to allow changes.

Canonical form

maas $PROFILE machine unlock [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • comment Optional string. Optional comment for the event log.

Requirements

No special requirements.

Additional effects

None.

unmount-special

Unmount a special-purpose filesystem, like tmpfs, on a machine with the given system_id.

Canonical form

maas $PROFILE machine unmount-special [--help] [-d] [-k]
                                             system_id [data ...]

Keyword arguments

  • mount_point Required string. Path on the filesystem to unmount.

Requirements

No special requirements.

Additional effects

None.

update

Updates a machine with the given system_id.

Canonical form

maas $PROFILE machine update [--help] [-d] [-k] system_id [data ...]

Keyword arguments

  • hostname Optional string. The new hostname for this machine.

  • description Optional string. The new description for this machine.

  • domain Optional string. The domain for this machine. If not given the default domain is used.

  • architecture Optional string. The new architecture for this machine.

  • min_hwe_kernel Optional string. A string containing the minimum kernel version allowed to be ran on this machine.

  • power_type Optional string. The new power type for this machine. If you use the default value, power_parameters will be set to the empty string.

  • power_parameters_skip_check Optional Boolean. Whether or not the new power parameters for this machine should be checked against the expected power parameters for the machine’s power type (‘true’ or ‘false’). The default is ‘false’.

  • pool Optional string. The resource pool to which the machine should belong. All machines belong to the ‘default’ resource pool if they do not belong to any other resource pool.

  • zone Optional string. Name of a valid physical zone in which to place this machine.

  • swap_size Optional. Specifies the size of the swap file, in bytes. Field accepts K, M, G and T suffixes for values expressed respectively in kilobytes, megabytes, gigabytes and terabytes.

  • disable_ipv4 Deprecated optional Boolean. Deprecated. If specified, must be false.

  • cpu_count Optional. The amount of CPU cores the machine has.

  • memory Optional. How much memory the machine has. Field accepts K, M, G and T suffixes for values expressed respectively in kilobytes, megabytes, gigabytes and terabytes.

Requirements

The *power_type can only be changed by an administrator.

Additional effects

Specifying incorrect or non-existent values for most of the keyword arguments will prevent MAAS from provisioning the machine, and may create a situation in which the machine musts be removed from MAAS and re-added. Take care to validate new input values before setting them.

accept-all

Accept all declared machines into MAAS.

Canonical form

maas $PROFILE machines accept-all [--help] [-d] [-k] [data ...]

Keyword arguments

None.

Requirements

Machines can be enlisted in the MAAS anonymously or by non-admin users, as opposed to by an admin. These machines are held in the ‘new’ state; a MAAS admin must first verify the authenticity of these enlistments, and accept them.

Additional effects

None.

add-chassis

Add special hardware types, possibly adding machines in bulk.

Canonical form

maas $PROFILE machines add-chassis [--help] [-d] [-k] [data ...]

Keyword arguments

  • chassis_type Required string. Acceptable values include:

– hmcz** IBM Hardware Management Console (HMC) for Z
– mscm** Moonshot Chassis Manager.
– msftocs** Microsoft OCS Chassis Manager.
– powerkvm** Virtual Machines on Power KVM, managed by Virsh.
– proxmox** Virtual Machines managed by Proxmox
– recs_box** Christmann RECS|Box servers.
– sm15k** Seamicro 1500 Chassis.
– ucsm** Cisco UCS Manager.
– virsh** virtual machines managed by Virsh.
– vmware is the type for virtual machines managed by VMware.

  • hostname Required string. The URL, hostname, or IP address to access the chassis.

  • username Mixed arity string. The username used to access the chassis. This field is required for the recs_box, seamicro15k, vmware, mscm, msftocs, ucsm, and hmcz chassis types. It is optional for all other chassis types.

  • password Mixed arity string. The password used to access the chassis. This field is required for the recs_box, seamicro15k, vmware, mscm, msftocs, ucsm, and hmcz chassis types, and optional for all other chassis types.

  • accept_all Optional string. If true, all enlisted machines will be commissioned.

  • rack_controller Optional string. The system_id of the rack controller to send the add chassis command through. If none is specified MAAS will automatically determine the rack controller to use.

  • domain Optional string. The domain that each new machine added should use.

  • prefix_filter Optional string. Usable on virsh,vmware, powerkvm, proxmox, hmcz chassis types only. Filter machines with supplied prefix.

  • power_control Optional string. Usable on seamicro15k only. The power_control to use, either ipmi (default), restapi, or restapi2.

  • token_name Optional string. The name the authentication token to be used instead of a password.

  • token_secret Optional string. The token secret to be used in combination with the power_token_name used in place of a password.

  • verify_ssl Optional Boolean. Whether SSL connections should be verified.

  • port Optional integer. Usable on recs_box, vmware and msftocs only. The port to use when accessing the chassis.

  • protocol Optional string. Usable on vmware only. The protocol to use when accessing the VMware chassis (default = “https”).

  • return A string containing the chassis powered on by which rack controller.

Requirements

Special requirements may vary by power type.

Additional effects

The keyword arguments are dense and have limited applicability; check them carefully before using them.

allocate

Allocates an available machine for deployment.

Canonical form

maas $PROFILE machines allocate [--help] [-d] [-k] [data ...]

Keyword arguments

Constraints parameters can be used to allocate a machine that possesses certain characteristics. All the constraints are optional. Combine multiple constraints are provided using ‘AND’ semantics. Note that more than one parameter has both an include version (tags) and an exclude version (not_tags).

  • name Optional string. Hostname or FQDN of the desired machine. If a FQDN is specified, both the domain and the hostname portions must match.

  • system_id Optional string. system_id of the desired machine.

  • arch Optional string. Architecture of the returned machine (e.g. ‘i386/generic’, ‘amd64’, ‘armhf/highbank’,
    etc.). If multiple architectures are specified, the machine to acquire may match any of the given architectures. To request multiple
    architectures, this parameter must be repeated in the request with each value

  • cpu_count Optional integer. Minimum number of CPUs a returned machine must have. A machine with more than the minimal number of CPUs may be allocated if there is no exact
    match, or if the ‘mem’ constraint is not also specified.

  • mem Optional integer. The minimum amount of memory (expressed in MB) the returned machine must have. A machine with additional memory may be allocated if there is no exact match, or the ‘cpu_count’ constraint is not also specified.

  • tags Optional string. Tags the machine must match in order to be acquired. If multiple tag names are specified, the machine must be tagged with
    all of them. To request multiple tags, this parameter must be repeated in the request with each value.

  • not_tags Optional string. Tags the machine must NOT match. If multiple tag names are specified, the machine must NOT be tagged with ANY of them. To request exclusion of multiple tags, this parameter must be repeated in the request with each value.

  • zone Optional string. Physical zone name the machine must be located in.

  • not_in_zone Optional string. List of physical zones from which the machine must not be acquired. If multiple zones are specified, the machine must NOT be associated with ANY of them. To request multiple zones to exclude, this parameter must be repeated in the request with each value.

  • pool Optional string. Resource pool name the machine must belong to.

  • not_in_pool Optional string. List of resource pool from which the machine must not be acquired. If multiple pools are specified, the machine must NOT be associated with ANY of them. To request multiple pools to exclude, this parameter must be repeated in the request with each value.

  • pod Optional string. Pod the machine must be located in.

  • not_pod Optional string. Pod the machine must not be located in.

  • pod_type Optional string. Pod type the machine must be located in.

  • not_pod_type Optional string. Pod type the machine must not be located in.

  • subnets Optional string. Subnets that must be linked to the machine. “Linked to” means the machine must be configured to acquire an address in the specified subnet, have a static IP address in the specified subnet, or have been observed to DHCP from the specified subnet during commissioning time (which implies that it could have an address on
    the specified subnet).

Subnets can be specified by one of the following criteria:

  • Match the subnet by its ‘id’ field
  • fabric: Match all subnets in a given fabric.
  • ip: Match the subnet containing with the longest-prefix match.
  • name: Match a subnet with the given name.
  • space: Match all subnets in a given space.
  • vid: Match a subnet on a VLAN with the specified VID.
    Valid values range from 0 through 4094 (inclusive). An untagged VLAN can be specified by using the value “0”.
  • vlan: Match all subnets on the given VLAN.

Note that the ‘fabric’, ‘space’, ‘vid’, and ‘vlan’ specifiers are only useful for the ‘not_spaces’ version of this constraint, because they will most likely force the query to match ALL the subnets in each fabric, space, or VLAN, and thus not return any machines. (This is not a particularly useful behavior, so may be changed in the future.)

If multiple subnets are specified, the machine must be associated with all of them. To request multiple subnets, this parameter must be repeated in the request with each value.

  • not_subnets Optional string. Subnets that must NOT be linked to the machine. See the ‘subnets’ constraint documentation above for more information about how each subnet can be specified. If multiple subnets are specified, the machine must NOT be associated with ANY of them. To request multiple subnets to exclude, this parameter must be repeated in the request with each value. (Or a fabric, space, or VLAN specifier may be used to match multiple subnets).

  • storage Optional string. A list of storage constraint identifiers, in the form** label:size(tag[,tag[,...])][,label:...].

  • interfaces Optional string. A labeled constraint map associating constraint labels with interface properties that should be matched. Returned machines must have one or more interface matching the specified constraints. The labeled constraint map must be in the format** label:key=value[,key2=value2[,...]].

Each key can be one of the following:

  • id Matches an interface with the specific id

  • fabric Matches an interface attached to the specified fabric.

  • fabric_class Matches an interface attached to a fabric with the specified class.

  • ip Matches an interface with the specified IP address assigned to it.

  • mode Matches an interface with the specified mode. (Currently, the only supported mode is “unconfigured”.)

  • name Matches an interface with the specified name. (For example, “eth0”.)

  • hostname Matches an interface attached to the machine with the specified hostname.

  • subnet Matches an interface attached to the specified subnet.

  • space Matches an interface attached to the specified space.

  • subnet_cidr Matches an interface attached to the specified subnet CIDR. (For example, “192.168.0.0/24”.)

  • type Matches an interface of the specified type. (Valid types: “physical”, “vlan”, “bond”, “bridge”, or “unknown”.)

  • vlan Matches an interface on the specified VLAN.

  • vid Matches an interface on a VLAN with the specified VID.

  • tag Matches an interface tagged with the specified tag.

  • link_speed Matches an interface with link_speed equal to or greater than the specified speed.

  • fabrics Optional string. Set of fabrics that the machine must be associated with in order to be acquired. If multiple fabrics names are specified, the machine can be in any of the specified fabrics. To request multiple possible fabrics to match, this parameter must be repeated in the request with each value.

  • not_fabrics Optional string. Fabrics the machine must NOT be associated with in order to be acquired. If multiple fabrics names are specified, the machine must NOT be in ANY of them. To request exclusion of multiple fabrics, this parameter must be repeated in the request with each value.

  • fabric_classes Optional string. Set of fabric class types whose fabrics the machine must be associated with in order to be acquired. If multiple fabrics class types are specified, the machine can be in any matching fabric. To request multiple possible fabrics class types to match, this parameter must be repeated in the request with each value.

  • not_fabric_classes Optional string. Fabric class types whose fabrics the machine must NOT be associated with in order to be acquired. If multiple fabrics names are specified, the machine must NOT be in ANY of them. To request exclusion of multiple fabrics, this parameter must be repeated in the request with each value.

  • agent_name Optional string. An optional agent name to attach to the acquired machine.

  • comment Optional string. Comment for the event log.

  • bridge_all Optional. Optionally create a bridge interface for every configured interface on the machine. The created bridges will be removed once the machine is released. (Default** False)

  • bridge_stp Optional. Optionally turn spanning tree protocol on or off for the bridges created on every configured interface. (Default** off)

  • bridge_fd Optional. Optionally adjust the forward delay to time seconds. (Default 15)

  • devices Optional. Only return a machine which have one or more devices containing the following constraints in the format key=value[,key2=value2[,…]]. Each key can be one of the following:

  • vendor_id The device vendor id

  • product_id The device product id

  • vendor_name The device vendor name, not case sensitive

  • product_name The device product name, not case sensitive

  • commissioning_driver The device uses this driver during commissioning.

  • dry_run Optional Boolean. Flag to indicate that the machine should not actually be acquired (this is for support/troubleshooting, or users who want to see which machine would
    match a constraint, without acquiring a machine). Defaults to False.

  • verbose Optional Boolean. Flag to indicate that the user would like additional verbosity in the constraints_by_type field (each constraint will be prefixed by
    verbose_, and contain the full data structure that indicates which machine(s) matched).

Requirements

No special requirements.

Additional effects

None.

clone

Clone storage and/or interface configurations to a set of destination machines.

Canonical form

maas $PROFILE machines clone [--help] [-d] [-k] [data ...]

Keyword arguments

  • source Required string. The system_id of the machine that is the source of the configuration.

  • destinations Required string. A list of system_ids to clone the configuration to.

  • interfaces Required Boolean Whether to clone interface configuration. Defaults to False.

  • storage Required Boolean. Whether to clone storage configuration. Defaults to False.

Requirements

For storage configuration, cloning the destination machine must have at
least the same number of physical block devices or more, along with
the physical block devices being the same size or greater.

For interface configuration, cloning the destination machine must have
at least the same number of interfaces with the same names. The
destination machine can have more interfaces than the source, as long
as the subset of interfaces on the destination have the same matching
names as the source.

Additional effects

None.

create

Create a new machine.

Canonical form

maas $PROFILE machines create [--help] [-d] [-k] [data ...]

Keyword parameters

  • architecture Required string. A string containing the architecture type of the machine. (For example, “i386”, or “amd64”.)

  • min_hwe_kernel Optional string. A string containing the minimum kernel version allowed to be ran on this machine.

  • sub-architecture Optional string. A string containing the sub-architecture type of the machine. (For example, “generic” or
    “hwe-t”.) To determine the supported sub-architectures, use the boot-resources endpoint.

  • mac_addresses Required string. One or more MAC addresses for the machine. To specify more than one MAC address, the parameter must be specified twice, such as “machines new
    mac_addresses=01:02:03:04:05:06 mac_addresses=02:03:04:05:06:07”.

  • hostname Optional string. A hostname. If not given, one will be generated.

  • description Optional string. A optional description.

  • domain Optional string. The domain of the machine. If not given the default domain is used.

  • power_type Optional string. A power management type, if applicable (e.g. “virsh”, “ipmi”).

  • commission Optional Boolean. Request the newly created machine to be created with status set to COMMISSIONING. Machines will wait for COMMISSIONING results and not
    time out. Machines created by administrators will be commissioned unless set to false.

  • deployed Optional Boolean. Request the newly created machine to be created with status set to DEPLOYED. Setting this to true implies commissioning=false, meaning that the machine won’t go through the commissioning process.

  • enable_ssh Optional integer. Whether to enable SSH for the commissioning environment using the user’s SSH key(s). ‘1’ == True,
    ‘0’ == False.

  • skip_bmc_config Optional integer. Whether to skip re-configuration of the BMC for IPMI based machines. ‘1’ == True, ‘0’ == False.

  • skip_networking Optional integer. Whether to skip re-configuring the networking on the machine after the commissioning has completed. ‘1’ == True, ‘0’ == False.

  • skip_storage Optional integer. Whether to skip re-configuring the storage on the machine after the commissioning has completed. ‘1’ == True, ‘0’ == False.

  • commissioning_scripts Optional string. A comma separated list of commissioning script names and tags to be run. By default all custom commissioning scripts are run. Built-in
    commissioning scripts always run. Selecting ‘update_firmware’ or ‘configure_hba’ will run firmware updates or configure HBAs on matching machines.

  • testing_scripts Optional string. A comma separated list of testing script names and tags to be run. By default all tests tagged ‘commissioning’ will be run. Set to ‘none’ to disable running tests.

Requirements

The minimum data required is:

  • architecture= (e.g. “i386/generic”)
  • mac_addresses= (e.g. “aa:bb:cc:dd:ee:ff”)

Additional effects

Adding a server to MAAS will (by default) cause the machine to commission, that is, network boot into an ephemeral environment to collect hardware information.

In anonymous enlistment (and when the enlistment is done by a non-admin), the machine is held in the “New” state for approval by a MAAS admin.

is-registered

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

Canonical form

maas $PROFILE machines is-registered [--help] [-d] [-k] [data ...]

Keyword arguments

  • mac_address Required string. The MAC address to be checked.

Requirements

No special requirements.

Additional effects

None.

list-allocated

List machines that were allocated to the specified $PROFILE.

Canonical form

maas $PROFILE machines list-allocated [--help] [-d] [-k] [data ...]

Keyword arguments

None.

Requirements

No special requirements.

Additional effects

None.

power-parameters

Get power parameters for multiple machines.

Canonical form

maas $PROFILE machines power-parameters [--help] [-d] [-k] [data ...]

Keyword arguments

  • id Required. A system ID. To request more than one machine, provide multiple id arguments in the request. Only machines with matching system ids will be returned.

Requirements

No special requirements.

Additional effects

None.

read

List machines visible to current user, optionally filtered by criteria.

Canonical form

maas $PROFILE machines read [--help] [-d] [-k] [data ...]

Keyword arguments

  • hostname Optional string. Only machines relating to the machine with the matching hostname will be returned. This can be specified multiple times to see multiple machines.

  • cpu_count Optional integer. Only machines with the specified minimum number of CPUs will be included.

  • mem Optional string. Only machines with the specified minimum amount of RAM (in MiB) will be included.

  • mac_address Optional string. Only machines relating to the machine owning the specified MAC address will be returned. This can be specified multiple times to see multiple machines.

  • id Optional string. Only machines relating to the machines with matching system ids will be returned.

  • domain Optional string. Only machines relating to the machines in the domain will be returned.

  • zone Optional string. Only machines relating to the machines in the zone will be returned.

  • pool Optional string. Only machines belonging to the pool will be returned.

  • agent_name Optional string. Only machines relating to the machines with matching agent names will be returned.

  • fabrics Optional string. Only machines with interfaces in specified fabrics will be returned.

  • not_fabrics Optional string. Only machines with interfaces not in specified fabrics will be returned.

  • vlans Optional string. Only machines with interfaces in specified VLANs will be returned.

  • not_vlans Optional string. Only machines with interfaces not in specified VLANs will be returned.

  • subnets Optional string. Only machines with interfaces in specified subnets will be returned.

  • not_subnets Optional string. Only machines with interfaces not in specified subnets will be returned.

  • link_speed Optional string. Only machines with interfaces with link speeds greater than or equal to link_speed will be returned.

  • status Optional string. Only machines with specified status will be returned.

  • pod Optional string. Only machines that belong to a specified pod will be returned.

  • not_pod Optional string. Only machines that don’t belong to a specified pod will be returned.

  • pod_type Optional string. Only machines that belong to a pod of the specified type will be returned.

  • not_pod_type Optional string. Only machines that don’t belong a pod of the specified type will be returned.

  • devices Optional string. Only return machines which have one or more devices containing the following constraints in the format key=value[,key2=value2[,…]]

Each key can be one of the following:

  • vendor_id The device vendor id
  • product_id The device product id
  • vendor_name The device vendor name, not case sensitive
  • product_name The device product name, not case sensitive
  • commissioning_driver The device uses this driver during commissioning.

Requirements

No special requirements.

Additional effects

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

release

Release multiple machines. Places the machines back into the pool, ready to be reallocated.

Canonical form

maas $PROFILE machines release [--help] [-d] [-k] [data ...]

Keyword arguments

  • machines Required string. A list of system_ids of the machines which are to be released. (An empty list is acceptable).

  • comment Optional string. Optional comment for the event log.

Requirements

No special requirements.

Additional effects

None.

set-zone

Assigns a given machine to a given zone.

Canonical form

maas $PROFILE machines set-zone [--help] [-d] [-k] [data ...]

Keyword parameters

  • zone Required string. The zone name.

  • machines Required string. The machine to add.