~maas-maintainers/maas/1.3

.TH "MAAS-CLI" "8" "November 22, 2012" "12.10" "MAAS"
.SH NAME
maas-cli \- MAAS API commandline utility
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.SH USAGE
.INDENT 0.0
.INDENT 3.5
$ maas\-cli <profile> <command> [parameters]
.UNINDENT
.UNINDENT
.sp
The available commands are dependent on the API you are connecting to and the
profile you use. The currently available options are explained below.
.SH DESCRIPTION
.sp
As well as the web interface, many tasks can be performed by accessing
the MAAS API directly through the maas\-cli command. This section
details how to login with this tool and perform some common
operations.
.sp
Before the API will accept any commands from maas\-cli, you must first
login. To do this, you need the API key which can be found in the user
interface.
.sp
Login to the web interface on your MAAS. Click on the username in the
top right corner and select \(aqPreferences\(aq from the menu which appears.
[image]
.sp
A new page will load...
[image]
.sp
The very first item is a list of MAAS keys. One will have already been
generated when the system was installed. It\(aqs easiest to just select
and copy the key (it\(aqs quite long!) and then paste it into the
commandline. The format of the login command is:
.sp
.nf
.ft C
$ maas\-cli login <profile\-name> <hostname> <key>
.ft P
.fi
.sp
The profile created is an easy way of associating your credentials
with any subsequent call to the API. So an example login might look
like this:
.sp
.nf
.ft C
$ maas\-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
.ft P
.fi
.sp
which creates the profile \(aqmaas\(aq and registers it with the given key
at the specified API endpoint.  If you omit the credentials, they will
be prompted for in the console. It is also possible to use a hyphen,
\(aq\-\(aq in place of the credentials. In this case a single line will be
read from stdin, stripped of any whitespace and used as the
credentials, which can be useful if you are devolping scripts for
specific tasks.  If an empty string is passed instead of the
credentials, the profile will be logged in anonymously (and
consequently some of the API calls will not be available)
.sp
The \fBmaas\-cli\fP command exposes the whole API, so you can do anything
you actually \fIcan\fP do with MAAS using this command. Unsurprisingly,
this leaves us with a vast number of options, but before we delve into
detail on the specifics, here is a sort of \(aqcheat\-sheet\(aq for common
tasks you might want to do using \fBmaas\-cli\fP.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%Configure DHCP and DNS services\fP
.IP \(bu 2
\fI\%Commission all enlisted nodes\fP
.IP \(bu 2
\fI\%Setting IPMI power parameters for a node\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The main maas\-cli commands are:
.sp
\fBlist\fP
.INDENT 0.0
.INDENT 3.5
lists the details [name url auth\-key] of all the currently logged\-in
profiles.
.UNINDENT
.UNINDENT
.sp
\fBlogin <profile> <url> <key>\fP
.INDENT 0.0
.INDENT 3.5
Logs in to the MAAS controller API at the given URL, using the key
provided and associates this connection with the given profile name.
.UNINDENT
.UNINDENT
.sp
\fBlogout <profile>\fP
.INDENT 0.0
.INDENT 3.5
Logs out from the given profile, flushing the stored credentials.
.UNINDENT
.UNINDENT
.sp
\fBrefresh\fP
.INDENT 0.0
.INDENT 3.5
Refreshes the API descriptions of all the current logged in
profiles. This may become necessary for example when upgrading the
maas packages to ensure the command\-line options match with the API.
.UNINDENT
.UNINDENT
.sp
\fB<profile> [command] [options] ...\fP
.INDENT 0.0
.INDENT 3.5
Using the given profile name instructs \fBmaas\-cli\fP to direct the
subsequent commands and options to the relevant MAAS, which for the
current API are detailed below...
.UNINDENT
.UNINDENT
.SH ACCOUNT
.sp
This command is used for creating and destroying the
MAAS authorisation tokens associated with a profile.
.sp
Usage: maas\-cli \fI<profile>\fP account [\-d \-\-debug] [\-h \-\-help]
create\-authorisation\-token | delete\-authorisation\-token [token_key=\fI<value>\fP]
.sp
\fB\-d, \-\-debug\fP
.INDENT 0.0
.INDENT 3.5
Displays debug information listing the API responses.
.UNINDENT
.UNINDENT
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Display usage information.
.UNINDENT
.UNINDENT
.sp
\fB\-k, \-\-insecure\fP
.INDENT 0.0
.INDENT 3.5
Disables the SSL certificate check.
.UNINDENT
.UNINDENT
.sp
\fBcreate\-authorisation\-token\fP
.INDENT 0.0
.INDENT 3.5
Creates a new MAAS authorisation token for the current profile
which can be used to authenticate connections to the API.
.UNINDENT
.UNINDENT
.sp
\fBdelete\-authorisation\-token token_key=<value>\fP
.INDENT 0.0
.INDENT 3.5
Removes the given key from the list of authorisation tokens.
.UNINDENT
.UNINDENT
.SH NODE
.sp
API calls which operate on individual nodes. With these commands, the
node is always identified by its "system_id" property \- a unique tag
allocated at the time of enlistment. To discover the value of the
system_id, you can use the \fBmaas\-cli <profile> nodes list\fP command.
.sp
USAGE: maas\-cli <profile> node [\-h] release | start | stop | delete |
read | update <system_id>
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Display usage information.
.UNINDENT
.UNINDENT
.sp
\fBrelease <system_id>\fP
.INDENT 0.0
.INDENT 3.5
Releases the node given by \fI<system_id>\fP
.UNINDENT
.UNINDENT
.sp
\fBstart <system_id>\fP
.INDENT 0.0
.INDENT 3.5
Powers up the node identified by \fI<system_id>\fP (where MAAS has
information for power management for this node).
.UNINDENT
.UNINDENT
.sp
\fBstop <system_id>\fP
.INDENT 0.0
.INDENT 3.5
Powers off the node identified by \fI<system_id>\fP (where MAAS has
information for power management for this node).
.UNINDENT
.UNINDENT
.sp
\fBdelete <system_id>\fP
.INDENT 0.0
.INDENT 3.5
Removes the given node from the MAAS database.
.UNINDENT
.UNINDENT
.sp
\fBread <system_id>\fP
.INDENT 0.0
.INDENT 3.5
Returns all the current known information about the node specified
by \fI<system_id>\fP
.UNINDENT
.UNINDENT
.sp
\fBupdate <system_id> [parameters...]\fP
.INDENT 0.0
.INDENT 3.5
Used to change or set specific values for the node. The valid
parameters are listed below:
.sp
.nf
.ft C
hostname=<value>
     The new hostname for this node.

architecture=<value>
     Sets the architecture type, where <value>
     is a string containing a valid architecture type,
     e.g. "i386/generic"

power_type=<value>
     Apply the given dotted decimal value as the broadcast IP address
     for this subnet.

power_parameters_{param1}... =<value>
     Set the given power parameters. Note that the valid options for these
     depend on the power type chosen.

power_parameters_skip_check \(aqtrue\(aq | \(aqfalse\(aq
     Whether to sanity check the supplied parameters against this node\(aqs
     declared power type. The default is \(aqfalse\(aq.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example: Setting the power parameters for an ipmi enabled node:
.sp
.nf
.ft C
maas\-cli maas node update <system_id> \e
  power_type="ipmi" \e
  power_parameters_power_address=192.168.22.33 \e
  power_parameters_power_user=root \e
  power_parameters_power_pass=ubuntu;
.ft P
.fi
.SH NODES
.sp
Usage: maas\-cli <profile> nodes [\-h] is\-registered | list\-allocated |
acquire | list | accept | accept\-all | new | check\-commissioning
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Display usage information.
.UNINDENT
.UNINDENT
.sp
\fBaccept <system_id>\fP
.INDENT 0.0
.INDENT 3.5
Accepts the node referenced by <system_id>.
.UNINDENT
.UNINDENT
.sp
\fBaccept\-all\fP
.INDENT 0.0
.INDENT 3.5
Accepts all currently discovered but not previously accepted nodes.
.UNINDENT
.UNINDENT
.sp
\fBacquire\fP
.INDENT 0.0
.INDENT 3.5
Allocates a node to the profile used to issue the command. Any
ready node may be allocated.
.UNINDENT
.UNINDENT
.sp
\fBis\-registered mac_address=<address>\fP
.INDENT 0.0
.INDENT 3.5
Checks to see whether the specified MAC address is registered to a
node.
.UNINDENT
.UNINDENT
.sp
\fBlist\fP
.INDENT 0.0
.INDENT 3.5
Returns a JSON formatted object listing all the currently known
nodes, their system_id, status and other details.
.UNINDENT
.UNINDENT
.sp
\fBlist\-allocated\fP
.INDENT 0.0
.INDENT 3.5
Returns a JSON formatted object listing all the currently allocated
nodes, their system_id, status and other details.
.UNINDENT
.UNINDENT
.sp
\fBnew architecture=<value> mac_addresses=<value> [parameters]\fP
.INDENT 0.0
.INDENT 3.5
Creates a new node entry given the provided key=value information
for the node. A minimum of the MAC address and architecture must be
provided. Other parameters may also be supplied:
.sp
.nf
.ft C
architecture="<value>" \- The architecture of the node, must be
one of the recognised architecture strings (e.g. "i386/generic")
hostname="<value>" \- a name for this node. If not supplied a name
will be generated.
mac_addresses="<value>" \- The mac address(es)
allocated to this node.
powertype="<value>" \- the power type of
the node (e.g. virsh, ipmi)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBcheck\-commissioning\fP
.INDENT 0.0
.INDENT 3.5
Displays current status of nodes in the commissioning phase. Any
that have not returned before the system timeout value are listed
as "failed".
.UNINDENT
.UNINDENT
.sp
Examples:
Accept and commission all discovered nodes:
.sp
.nf
.ft C
$ maas\-cli maas nodes accept\-all
.ft P
.fi
.sp
List all known nodes:
.sp
.nf
.ft C
$ maas\-cli maas nodes list
.ft P
.fi
.sp
Filter the list using specific key/value pairs:
.sp
.nf
.ft C
$ maas\-cli maas nodes list architecture="i386/generic"
.ft P
.fi
.SH NODE-GROUPS
.sp
Usage: maas\-cli <profile> node\-groups [\-d \-\-debug] [\-h \-\-help] [\-k
\-\-insecure] register | list | refresh\-workers | accept | reject
.sp
\fB\-d, \-\-debug\fP
.INDENT 0.0
.INDENT 3.5
Displays debug information listing the API responses.
.UNINDENT
.UNINDENT
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Display usage information.
.UNINDENT
.UNINDENT
.sp
\fB\-k, \-\-insecure\fP
.INDENT 0.0
.INDENT 3.5
Disables the SSL certificate check.
.UNINDENT
.UNINDENT
.sp
\fBregister uuid=<value> name=<value> interfaces=<json_string>\fP
.INDENT 0.0
.INDENT 3.5
Registers a new node group with the given name and uuid. The
interfaces parameter must be supplied in the form of a JSON string
comprising the key/value data for the interface to be used, for
example: interface=\(aq["ip":"192.168.21.5","interface":"eth1", "subnet_mask":"255.255.255.0","broadcast_ip":"192.168.21.255", "router_ip":"192.168.21.1", "ip_range_low":"192.168.21.10", "ip_range_high":"192.168.21.50"}]\(aq
.UNINDENT
.UNINDENT
.sp
\fBlist\fP
.INDENT 0.0
.INDENT 3.5
Returns a JSON list of all currently defined node groups.
.UNINDENT
.UNINDENT
.sp
\fBrefresh_workers\fP
.INDENT 0.0
.INDENT 3.5
It sounds a bit like they will get a cup of tea and a
biscuit. Actually this just sends each node\-group worker an update
of its credentials (API key, node\-group name). This command is
usually not needed at a user level, but is often used by worker
nodes.
.UNINDENT
.UNINDENT
.sp
\fBaccept <uuid>\fP
.INDENT 0.0
.INDENT 3.5
Accepts a node\-group or number of nodegroups indicated by the
supplied UUID
.UNINDENT
.UNINDENT
.sp
\fBreject <uuid>\fP
.INDENT 0.0
.INDENT 3.5
Rejects a node\-group or number of nodegroups indicated by the
supplied UUID
.UNINDENT
.UNINDENT
.SH NODE-GROUP-INTERFACE
.sp
For managing the interfaces. See also \fI\%node-group-interfaces\fP
.sp
Usage: maas\-cli \fI<profile>\fP node\-group\-interfaces [\-d \-\-debug] [\-h
\-\-help] [\-k \-\-insecure] read | update | delete [parameters...]
.sp
..program:: maas\-cli node\-group\-interface
.sp
\fBread <uuid> <interface>\fP
.INDENT 0.0
.INDENT 3.5
Returns the current settings for the given UUID and interface
.UNINDENT
.UNINDENT
.sp
\fBupdate [parameters]\fP
.INDENT 0.0
.INDENT 3.5
Changes the settings for the interface according to the given
parameters:
.sp
.nf
.ft C
management=  0 | 1 | 2
     The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
     and DNS).

subnet_mask=<value>
     Apply the given dotted decimal value as the subnet mask.

broadcast_ip=<value>
     Apply the given dotted decimal value as the broadcast IP address for
     this subnet.

router_ip=<value>
     Apply the given dotted decimal value as the default router address
     for this subnet.

ip_range_low=<value>
     The lowest value of IP address to allocate via DHCP

ip_range_high=<value>
     The highest value of IP address to allocate via DHCP
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBdelete <uuid> <interface>\fP
.INDENT 0.0
.INDENT 3.5
Removes the entry for the given UUID and interface.
.UNINDENT
.UNINDENT
.sp
Example:
Configuring DHCP and DNS.
.sp
To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
interface information. To do this we need to first determine the UUID of the
node group affected:
.sp
.nf
.ft C
$ uuid=$(maas\-cli <profile> node\-groups list | grep uuid | cut \-d\e" \-f4)
.ft P
.fi
.sp
Once we have the UUID we can use this to update the node\-group\-interface for
that nodegroup, and pass it the relevant interface details:
.sp
.nf
.ft C
$ maas\-cli <profile> node\-group\-interface update $uuid eth0 \e
        ip_range_high=192.168.123.200    \e
        ip_range_low=192.168.123.100     \e
        management=2                     \e
        broadcast_ip=192.168.123.255     \e
        router_ip=192.168.123.1          \e
.ft P
.fi
.sp
Replacing the example values with those required for this network. The
only non\-obvious parameter is \(aqmanagement\(aq which takes the values 0
(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
.SH NODE-GROUP-INTERFACES
.sp
The node\-group\-interfaces commands are used for configuring the
management of DHCP and DNS services where these are managed by MAAS.
.sp
Usage: maas\-cli \fI<profile>\fP node\-group\-interfaces [\-d \-\-debug] [\-h
\-\-help] [\-k \-\-insecure] list | new [parameters...]
.sp
\fB\-d, \-\-debug\fP
.INDENT 0.0
.INDENT 3.5
Displays debug information listing the API responses.
.UNINDENT
.UNINDENT
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Display usage information.
.UNINDENT
.UNINDENT
.sp
\fB\-k, \-\-insecure\fP
.INDENT 0.0
.INDENT 3.5
Disables the SSL certificate check.
.UNINDENT
.UNINDENT
.sp
\fBlist <label>\fP
.INDENT 0.0
.INDENT 3.5
Lists the current stored configurations for the given identifier
<label> in a key:value format which should be easy to decipher.
.UNINDENT
.UNINDENT
.sp
\fBnew <label> ip=<value> interface=<if_device> [parameters...]\fP
.INDENT 0.0
.INDENT 3.5
Creates a new interface group. The required parameters are the IP
address and the network interface this appies to (e.g. eth0). In
order to do anything useful, further parameters are required:
.sp
.nf
.ft C
management= 0 | 1 | 2
     The service to be managed on the interface
     ( 0= none, 1=DHCP, 2=DHCP and DNS).

subnet_mask=<value>
     Apply the given dotted decimal value as the subnet mask.

broadcast_ip=<value>
     Apply the given dotted decimal value as the
     broadcast IP address for this subnet.

router_ip=<value>
     Apply the given dotted decimal value as the
     default router address for this subnet.

ip_range_low=<value>
     The lowest value of IP address to allocate via DHCP

ip_range_high=<value>
     The highest value of IP address to allocate via DHCP
.ft P
.fi
.UNINDENT
.UNINDENT
.SH TAG
.INDENT 0.0
.TP
.B Usage: maas\-cli <profile> tag read | update\-nodes | rebuild | update |
nodes | delete
.UNINDENT
.sp
\fBread <tag_name>\fP
.INDENT 0.0
.INDENT 3.5
Returns information on the tag specified by <name>
.UNINDENT
.UNINDENT
.sp
\fBupdate\-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]\fP
.INDENT 0.0
.INDENT 3.5
Applies or removes the given tag from a list of nodes specified by
either or both of add="<system_id>" and remove="<system_id>". The
nodegroup parameter, which restricts the operations to a particular
nodegroup, is optional, but only the superuser can execute this
command without it.
.UNINDENT
.UNINDENT
.sp
\fBrebuild\fP
.INDENT 0.0
.INDENT 3.5
Triggers a rebuild of the tag to node mapping.
.UNINDENT
.UNINDENT
.sp
\fBupdate <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]\fP
.INDENT 0.0
.INDENT 3.5
Updates the tag identified by tag_name. Any or all of name,comment
and definition may be supplied as parameters. If no parameters are
supplied, this command returns the current values.
.UNINDENT
.UNINDENT
.sp
\fBnodes <tag_name>\fP
.INDENT 0.0
.INDENT 3.5
Returns a list of nodes which are associated with the given tag.
.UNINDENT
.UNINDENT
.sp
\fBdelete <tag_name>\fP
.INDENT 0.0
.INDENT 3.5
Deletes the given tag.
.UNINDENT
.UNINDENT
.SH TAGS
.sp
Tags are a really useful way of identifying nodes with particular
characteristics.
.sp
Usage: maas\-cli <profile> tag [\-d \-\-debug] [\-h \-\-help] [\-k
\-\-insecure] list | new
.sp
\fB\-d, \-\-debug\fP
.INDENT 0.0
.INDENT 3.5
Displays debug information listing the API responses.
.UNINDENT
.UNINDENT
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Display usage information.
.UNINDENT
.UNINDENT
.sp
\fB\-k, \-\-insecure\fP
.INDENT 0.0
.INDENT 3.5
Disables the SSL certificate check.
.UNINDENT
.UNINDENT
.sp
\fBlist\fP
.INDENT 0.0
.INDENT 3.5
Returns a JSON object listing all the current tags known by the MAAS server
.UNINDENT
.UNINDENT
.sp
\fBcreate name=<value> definition=<value> [comment=<value>]\fP
.INDENT 0.0
.INDENT 3.5
Creates a new tag with the given name and definition. A comment is
optional. Names must be unique, obviously \- an error will be
returned if the given name already exists. The definition is in the
form of an XPath expression which parses the XML returned by
running \fBlshw\fP on the node.
.UNINDENT
.UNINDENT
.sp
Example:
Adding a tag to all nodes which have an Intel GPU:
.sp
.nf
.ft C
$ maas\-cli maas tags new name=\(aqintel\-gpu\(aq \e
    comment=\(aqMachines which have an Intel display driver\(aq \e
    definition=\(aqcontains(//node[@id="display"]/vendor, "Intel")
.ft P
.fi
.SH UNUSED COMMANDS
.sp
Because the \fBmaas\-cli\fP command exposes all of the API, it also lists
some command options which are not really intended for end users, such
as the "file" and "boot\-images" options.
.SH FURTHER DOCUMENTATION
.sp
For more documentation of MAAS, please see \fI\%https://maas.ubuntu.com/docs\fP
.SH SEE ALSO
.sp
\fImaas\fP
.SH AUTHOR
Canonical 2012
.SH COPYRIGHT
2012, MAAS Developers
.\" Generated by docutils manpage writer.
.\" 
.