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 idenfied 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 identifing 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’s 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.

Addtional 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 integar. 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.

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

lock

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

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

Keyword arguments

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

mark-broken

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

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

Requirements

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

Keyword arguments

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

mark-fixed

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

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

Keyword arguments

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

mount-special

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

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

override-failed-testing

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

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

Keyword arguments

  • comment Optional string. Comment for the event log.

power-off

Powers off the machine identified by system_id.

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.

power-on

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

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.

power-parameters

Gets power parameters for a given system_id, if any.

Note: For some types of power control this will include private information such as passwords and secret keys.

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

Effects

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

query-power-state

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

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

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

Reads information from a machine identified by system_id.

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

Effects

Returns comprehensive information about the machine in JSON format.

release

Releases a machine with the given system_id.

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

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

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.

rescue-mode

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

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

Requirements

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

restore-default-configuration

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

Restore default configuration

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

restore-networking-configuration

  ```bash

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

Restore networking options


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

## restore-storage-configuration

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

Restore storage configuration

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

set-owner-data

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

Deprecated, use set-workload-annotations.

Deprecated, use set-workload-annotations instead.

set-storage-layout

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

Change storage layout

Changes the storage layout on machine with the given
system_id.

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

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

:param storage_layout** Required. Storage layout for the
machine** flat, lvm, bcache, vmfs6, vmfs7,
custom or blank.
:type storage_layout** String

  • boot_size Optional. Size of the boot partition
    (e.g. 512M, 1G).
    :type boot_size** String

  • root_size Optional. Size of the root partition
    (e.g. 24G).
    :type root_size** String

  • root_device Optional. Physical block device to
    place the root partition (e.g. /dev/sda).
    :type root_device** String

  • vg_name Optional. LVM only. Name of created
    volume group.
    :type vg_name** String

  • lv_name Optional. LVM only. Name of created
    logical volume.
    :type lv_name** String

  • lv_size Optional. LVM only. Size of created
    logical volume.
    :type lv_size** String

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

  • cache_mode Optional. Bcache only. Cache mode
    for bcache device** writeback, writethrough, writearound.
    :type cache_mode** String

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

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

set-workload-annotations

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

Set key=value data

Set key=value data for the current owner.

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.

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.

:param key** Required. key can be any string value.
:type key** String

test

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

Begin testing process for a machine

Begins the testing process for a given machine.

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.

:param enable_ssh** Optional. Whether to enable SSH for
the testing environment using the user’s SSH key(s). 0 == false. 1 ==
true.
:type enable_ssh** Int

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

  • parameters Optional. 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.
    :type parameters** String

unlock

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

Unlock a machine

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

:param comment** Optional. Optional comment for the
event log.
:type comment** String

unmount-special

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

Unmount a special-purpose filesystem

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

:param mount_point** Required. Path on the filesystem to
unmount.
:type mount_point** String

update

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

Update a machine

Updates a machine with the given system_id.

:param hostname** Optional. The new hostname for this
machine.
:type hostname** String

  • description Optional. The new description for
    this machine.
    :type description** String

  • domain Optional. The domain for this machine.
    If not given the default domain is used.
    :type domain** String

  • architecture Optional. The new architecture
    for this machine.
    :type architecture** String

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

  • power_type Optional. The new power type for
    this machine. If you use the default value, power_parameters will be
    set to the empty string. Available to admin users. See the Power types_ section for a list of the available power types.
    :type power_type** String

  • power_parameters_skip_check Optional.
    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’.
    :type power_parameters_skip_check** Boolean

  • pool Optional. 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.
    :type pool** String

  • zone Optional. Name of a valid physical zone
    in which to place this machine.
    :type zone** String

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

  • disable_ipv4 Optional. Deprecated. If
    specified, must be false.
    :type disable_ipv4** Boolean

  • cpu_count Optional. The amount of CPU cores the
    machine has.
    :type cpu_count** Int

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

accept-all

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

Accept all declared machines

Accept all declared machines into MAAS.

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.

add-chassis

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

Add special hardware

Add special hardware types.

:param chassis_type** Required. The type
of hardware:

  • 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.
    :type chassis_type** String

  • hostname Required. The URL, hostname, or IP
    address to access the chassis.
    :type hostname** String

  • username Optional. The username used to access
    the chassis. This field is required for the recs_box, seamicro15k,
    vmware, mscm, msftocs, ucsm, and hmcz chassis types.
    :type username** String

  • password Optional. The password used to access
    the chassis. This field is required for the recs_box,
    seamicro15k, vmware, mscm, msftocs, ucsm, and
    hmcz chassis types.
    :type password** String

  • accept_all Optional. If true, all enlisted
    machines will be commissioned.
    :type accept_all** String

  • rack_controller Optional. The system_id of the
    rack controller to send the add chassis command through. If none is
    specifed MAAS will automatically determine the rack controller to use.
    :type rack_controller** String

  • domain Optional. The domain that each new
    machine added should use.
    :type domain** String

  • prefix_filter Optional. (virsh,
    vmware, powerkvm, proxmox, hmcz only.) Filter machines
    with supplied prefix.
    :type prefix_filter** String

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

The following are optional if you are adding a proxmox chassis.
:type power_control** String

  • token_name Optional. The name the
    authentication token to be used instead of a password.
    :type token_name** String

  • token_secret Optional. The token secret
    to be used in combination with the power_token_name used in place of
    a password.
    :type token_secret** String

  • verify_ssl Optional. Whether SSL
    connections should be verified.

The following are optional if you are adding a recs_box, vmware or
msftocs chassis.
:type verify_ssl** Boolean

  • port Optional. (recs_box, vmware,
    msftocs only) The port to use when accessing the chassis.

The following are optional if you are adding a vmware chassis:
:type port** Int

  • protocol Optional. (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.
:type protocol** String

allocate

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

Allocate a machine

Allocates an available machine for deployment.

Constraints parameters can be used to allocate a machine that possesses
certain characteristics. All the constraints are optional and when
multiple constraints are provided, they are combined using ‘AND’
semantics.

:param name** Optional. Hostname or FQDN of the desired
machine. If a FQDN is specified, both the domain and the hostname
portions must match.
:type name** String

  • system_id Optional. system_id of the desired
    machine.
    :type system_id** String

  • arch Optional. 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.
:type arch** String

  • cpu_count Optional. Minimum
    number of CPUs a returned machine must have.

A machine with additional CPUs may be allocated if there is no exact
match, or if the ‘mem’ constraint is not also specified.
:type cpu_count** Int

  • mem Optional. 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.
    :type mem** Int

  • tags Optional. 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.
:type tags** String

  • not_tags Optional. 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.
    :type not_tags** String

  • zone Optional. Physical zone name the machine
    must be located in.
    :type zone** String

  • not_in_zone Optional. 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.
    :type not_in_zone** String

  • pool Optional. Resource pool name the machine
    must belong to.
    :type pool** String

  • not_in_pool Optional. 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.
    :type not_in_pool** String

  • pod Optional. Pod the machine must be located
    in.
    :type pod** String

  • not_pod Optional. Pod the machine must not be
    located in.
    :type not_pod** String

  • pod_type Optional. Pod type the machine must
    be located in.
    :type pod_type** String

  • not_pod_type Optional. Pod type the machine
    must not be located in.
    :type not_pod_type** String

  • subnets Optional. 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
    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 (as of this writing), 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.

Note that this replaces the legacy ‘networks’ constraint in MAAS 1.x.
:type subnets** String

  • not_subnets Optional. 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).

Note that this replaces the legacy ‘not_networks’ constraint in MAAS
1.x.
:type not_subnets** String

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

  • interfaces Optional. 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.
    :type interfaces** String

  • fabrics Optional. 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.
    :type fabrics** String

  • not_fabrics Optional. 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.
    :type not_fabrics** String

  • fabric_classes Optional. 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.
    :type fabric_classes** String

  • not_fabric_classes Optional. 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.
    :type not_fabric_classes** String

  • agent_name Optional. An optional agent name to
    attach to the acquired machine.
    :type agent_name** String

  • comment Optional. Comment for the event log.
    :type comment** String

  • 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)
    :type bridge_all** Boolean

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

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

  • 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 sensative

  • product_name** The device product name, not case sensative

  • commissioning_driver** The device uses this driver during
    commissioning.
    :type devices** String

  • dry_run Optional. Optional boolean 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.
    :type dry_run** Boolean

  • verbose Optional. Optional boolean 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).
    :type verbose** Boolean

clone

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

Clone storage and/or interface configurations

Clone storage and/or interface configurations

A machine storage and/or interface configuration can be cloned to a
set of destination machines.

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.

:param source** Required. The system_id of the machine
that is the source of the configuration.
:type source** String

  • destinations Required. A list of system_ids to
    clone the configuration to.
    :type destinations** String

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

  • storage Required. Whether to clone storage
    configuration. Defaults to False.
    :type storage** Boolean

create

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

Create a new machine

Create a new machine.

Adding a server to MAAS will (by default) cause the machine to
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.

The minimum data required is:

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

:param architecture** Required. A string containing the
architecture type of the machine. (For example, “i386”, or “amd64”.) To
:type architecture** unicode
:type architecture** String

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

  • subarchitecture Optional. A string containing
    the subarchitecture type of the machine. (For example, “generic” or
    “hwe-t”.) To determine the supported subarchitectures, use the
    boot-resources endpoint.
    :type subarchitecture** String

  • mac_addresses Required. 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”)
    :type mac_addresses** String

  • hostname Optional. A hostname. If not given,
    one will be generated.
    :type hostname** String

  • description Optional. A optional description.
    :type description** String

  • domain Optional. The domain of the machine. If
    not given the default domain is used.
    :type domain** String

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

  • commission Optional. 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.
    :type commission** Boolean

  • deployed Optional. 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.
    :type deployed** Boolean

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

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

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

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

  • commissioning_scripts Optional. A comma
    seperated 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 HBA’s on
    matching machines.
    :type commissioning_scripts** String

  • testing_scripts Optional. A comma seperated
    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.
    :type testing_scripts** String

is-registered

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

MAC address registered

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

:param mac_address** Required. The MAC address to be
checked.
:type mac_address** URL String

list-allocated

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

List allocated

List machines that were allocated to the User.

power-parameters

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

Get power parameters

Get power parameters for multiple machines. To request
power parameters for a specific machine or more than one machine:
op=power_parameters&id=abc123&id=def456.

:param 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.
:type id** URL String

read

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

List Machines visible to the user

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

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

:param hostname** Optional. Only machines relating to the
machine with the matching hostname will be returned. This can be specified
multiple times to see multiple machines.
:type hostname** String

  • cpu_count Optional. Only machines with the specified
    minimum number of CPUs will be included.
    :type cpu_count** Int

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

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

  • id Optional. Only machines relating to the machines
    with matching system ids will be returned.
    :type id** String

  • domain Optional. Only machines relating to the
    machines in the domain will be returned.
    :type domain** String

  • zone Optional. Only machines relating to the
    machines in the zone will be returned.
    :type zone** String

  • pool Optional. Only machines belonging to the
    pool will be returned.
    :type pool** String

  • agent_name Optional. Only machines relating to
    the machines with matching agent names will be returned.
    :type agent_name** String

  • fabrics Optional. Only machines with interfaces
    in specified fabrics will be returned.
    :type fabrics** String

  • not_fabrics Optional. Only machines with
    interfaces not in specified fabrics will be returned.
    :type not_fabrics** String

  • vlans Optional. Only machines with interfaces in
    specified VLANs will be returned.
    :type vlans** String

  • not_vlans Optional. Only machines with interfaces
    not in specified VLANs will be returned.
    :type not_vlans** String

  • subnets Optional. Only machines with interfaces
    in specified subnets will be returned.
    :type subnets** String

  • not_subnets Optional. Only machines with
    interfaces not in specified subnets will be returned.
    :type not_subnets** String

  • link_speed Optional. Only machines with
    interfaces with link speeds greater than or equal to link_speed will
    be returned.
    :type link_speed** String

  • status Optional. Only machines with specified
    status will be returned.
    :type status** String

  • pod Optional. Only machines that belong to a
    specified pod will be returned.
    :type pod** String

  • not_pod Optional. Only machines that don’t
    belong to a specified pod will be returned.
    :type not_pod** String

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

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

  • devices Optional. 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 sensative
  • product_name** The device product name, not case sensative
  • commissioning_driver** The device uses this driver during
    commissioning.
    :type devices** String

release

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

Release machines

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

:param machines** Required. A list of system_ids of the
machines which are to be released. (An empty list is acceptable).
:type machines** String

  • comment Optional. Optional comment for the
    event log.
    :type comment** String

set-zone

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

Assign machines to a zone

Assigns a given machine to a given zone.

:param zone** Required. The zone name.
:type zone** String

  • machines Required. The machine to add.
    :type machines** String