58
58
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
62
maas [\-h, \-\-help] createadmin | changepassword | shell
66
$ maas <profile> <command> [parameters]
72
The available commands are dependent on the API you are connecting to and the
73
profile you use. The currently available options are explained below.
65
The \fImaas\fP command is part of Canonical\(aqs Metal As A Service software. It is
66
derived from and can be used similarly to the \fIdjango\-admin\fP command, and must
67
be run with root privileges.
69
For the end user, there are only three subcommands of interest.
73
This subcommand is used to create a superuser for the
74
MAAS install. The suggested username is "root". This command usually only
75
needs to be run when installing MAAS for the first time.
77
.B \fBchangepassword\fP
78
This subcommand is used to change the superuser password
79
for the MAAS install. You will be prompted to enter a new password, and then
80
enter it once again to verify.
83
This subcommand may be useful for debugging installed systems. It
84
will open a new python shell environment with the correct django environment
85
for working with the installed MAAS software.
76
As well as the web interface, many tasks can be performed by accessing
77
the MAAS API directly through the maas command. This section
78
details how to login with this tool and perform some common
82
Before the API will accept any commands from maas, you must first
83
login. To do this, you need the API key which can be found in the user
86
Log in to the web interface on your MAAS. Click on the username in the
87
top right corner and select \(aqPreferences\(aq from the menu which appears.
89
A new page will load...
91
The very first item is a list of MAAS keys. One will have already been
92
generated when the system was installed. It\(aqs easiest to just select
93
and copy the key (it\(aqs quite long!) and then paste it into the
94
commandline. The format of the login command is:
100
$ maas login <profile\-name> <hostname> <key>
106
The profile created is an easy way of associating your credentials
107
with any subsequent call to the API. So an example login might look
114
$ maas login maas http://10.98.0.13/MAAS/api/1.0
115
AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
121
which creates the profile \(aqmaas\(aq and registers it with the given key
122
at the specified API endpoint. If you omit the credentials, they will
123
be prompted for in the console. It is also possible to use a hyphen,
124
\(aq\-\(aq in place of the credentials. In this case a single line will be
125
read from stdin, stripped of any whitespace and used as the
126
credentials, which can be useful if you are devolping scripts for
127
specific tasks. If an empty string is passed instead of the
128
credentials, the profile will be logged in anonymously (and
129
consequently some of the API calls will not be available)
132
The \fBmaas\fP command exposes the whole API, so you can do anything
133
you actually \fIcan\fP do with MAAS using this command. Unsurprisingly,
134
this leaves us with a vast number of options, but before we delve into
135
detail on the specifics, here is a sort of \(aqcheat\-sheet\(aq for common
136
tasks you might want to do using \fBmaas\fP\&.
141
\fIConfigure DHCP and DNS services\fP
143
\fICommission all enlisted nodes\fP
145
\fI\%Setting IPMI power parameters for a node\fP
150
The main maas commands are:
155
lists the details [name url auth\-key] of all the currently logged\-in
160
\fBlogin <profile> <url> <key>\fP
163
Logs in to the MAAS controller API at the given URL, using the key
164
provided and associates this connection with the given profile name.
168
\fBlogout <profile>\fP
171
Logs out from the given profile, flushing the stored credentials.
178
Refreshes the API descriptions of all the current logged in
179
profiles. This may become necessary for example when upgrading the
180
maas packages to ensure the command\-line options match with the API.
184
\fB<profile> [command] [options] ...\fP
187
Using the given profile name instructs \fBmaas\fP to direct the
188
subsequent commands and options to the relevant MAAS, which for the
189
current API are detailed below...
194
This command is used for creating and destroying the
195
MAAS authorisation tokens associated with a profile.
197
Usage: maas \fI<profile>\fP account [\-d \-\-debug] [\-h \-\-help]
198
create\-authorisation\-token | delete\-authorisation\-token [token_key=\fI<value>\fP]
203
Displays debug information listing the API responses.
210
Display usage information.
214
\fB\-k, \-\-insecure\fP
217
Disables the SSL certificate check.
221
\fBcreate\-authorisation\-token\fP
224
Creates a new MAAS authorisation token for the current profile
225
which can be used to authenticate connections to the API.
229
\fBdelete\-authorisation\-token token_key=<value>\fP
232
Removes the given key from the list of authorisation tokens.
237
API calls which operate on individual nodes. With these commands, the
238
node is always identified by its "system_id" property \- a unique tag
239
allocated at the time of enlistment. To discover the value of the
240
system_id, you can use the \fBmaas <profile> nodes list\fP command.
242
USAGE: maas <profile> node [\-h] release | start | stop | delete |
243
read | update <system_id>
249
Display usage information.
252
\fBrelease <system_id>\fP
255
Releases the node given by \fI<system_id>\fP
259
\fBstart <system_id>\fP
262
Powers up the node identified by \fI<system_id>\fP (where MAAS has
263
information for power management for this node).
267
\fBstop <system_id>\fP
270
Powers off the node identified by \fI<system_id>\fP (where MAAS has
271
information for power management for this node).
275
\fBdelete <system_id>\fP
278
Removes the given node from the MAAS database.
282
\fBread <system_id>\fP
285
Returns all the current known information about the node specified
290
\fBupdate <system_id> [parameters...]\fP
293
Used to change or set specific values for the node. The valid
294
parameters are listed below:
301
The new hostname for this node.
304
Sets the architecture type, where <value>
305
is a string containing a valid architecture type,
309
Apply the given dotted decimal value as the broadcast IP address
312
power_parameters_{param1}... =<value>
313
Set the given power parameters. Note that the valid options for these
314
depend on the power type chosen.
316
power_parameters_skip_check \(aqtrue\(aq | \(aqfalse\(aq
317
Whether to sanity check the supplied parameters against this node\(aqs
318
declared power type. The default is \(aqfalse\(aq.
326
Example: Setting the power parameters for an ipmi enabled node:
332
maas update <system_id> \e
334
power_parameters_power_address=192.168.22.33 \e
335
power_parameters_power_user=root \e
336
power_parameters_power_pass=ubuntu;
343
Usage: maas <profile> nodes [\-h] is\-registered | list\-allocated |
344
acquire | list | accept | accept\-all | new | check\-commissioning
349
Display usage information.
353
\fBaccept <system_id>\fP
356
Accepts the node referenced by <system_id>.
363
Accepts all currently discovered but not previously accepted nodes.
370
Allocates a node to the profile used to issue the command. Any
371
ready node may be allocated.
375
\fBis\-registered mac_address=<address>\fP
378
Checks to see whether the specified MAC address is registered to a
386
Returns a JSON formatted object listing all the currently known
387
nodes, their system_id, status and other details.
391
\fBlist\-allocated\fP
394
Returns a JSON formatted object listing all the currently allocated
395
nodes, their system_id, status and other details.
399
\fBnew architecture=<value> mac_addresses=<value> [parameters]\fP
402
Creates a new node entry given the provided key=value information
403
for the node. A minimum of the MAC address and architecture must be
404
provided. Other parameters may also be supplied:
410
architecture="<value>" \- The architecture of the node, must be
411
one of the recognised architecture strings (e.g. "i386/generic")
412
hostname="<value>" \- a name for this node. If not supplied a name
414
mac_addresses="<value>" \- The mac address(es)
415
allocated to this node.
416
power_type="<value>" \- the power type of
417
the node (e.g. virsh, ipmi)
425
\fBcheck\-commissioning\fP
428
Displays current status of nodes in the commissioning phase. Any
429
that have not returned before the system timeout value are listed
435
Accept and commission all discovered nodes:
441
$ maas maas nodes accept\-all
447
List all known nodes:
453
$ maas maas nodes list
459
Filter the list using specific key/value pairs:
465
$ maas maas nodes list architecture="i386/generic"
472
Usage: maas <profile> node\-groups [\-d \-\-debug] [\-h \-\-help] [\-k
473
\-\-insecure] register | list | refresh\-workers | accept | reject
478
Displays debug information listing the API responses.
485
Display usage information.
489
\fB\-k, \-\-insecure\fP
492
Disables the SSL certificate check.
496
\fBregister uuid=<value> name=<value> interfaces=<json_string>\fP
499
Registers a new node group with the given name and uuid. The
500
interfaces parameter must be supplied in the form of a JSON string
501
comprising the key/value data for the interface to be used, for
502
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
509
Returns a JSON list of all currently defined node groups.
513
\fBrefresh_workers\fP
516
It sounds a bit like they will get a cup of tea and a
517
biscuit. Actually this just sends each node\-group worker an update
518
of its credentials (API key, node\-group name). This command is
519
usually not needed at a user level, but is often used by worker
527
Accepts a node\-group or number of nodegroups indicated by the
535
Rejects a node\-group or number of nodegroups indicated by the
539
.SH NODE-GROUP-INTERFACE
541
For managing the interfaces. See also \fInode\-group\-interfaces\fP
543
Usage: maas \fI<profile>\fP node\-group\-interfaces [\-d \-\-debug] [\-h
544
\-\-help] [\-k \-\-insecure] read | update | delete [parameters...]
546
\&..program:: maas node\-group\-interface
548
\fBread <uuid> <interface>\fP
551
Returns the current settings for the given UUID and interface
555
\fBupdate [parameters]\fP
558
Changes the settings for the interface according to the given
565
management= 0 | 1 | 2
566
The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
570
Apply the given dotted decimal value as the subnet mask.
573
Apply the given dotted decimal value as the broadcast IP address for
577
Apply the given dotted decimal value as the default router address
581
The lowest value of IP address to allocate via DHCP
583
ip_range_high=<value>
584
The highest value of IP address to allocate via DHCP
592
\fBdelete <uuid> <interface>\fP
595
Removes the entry for the given UUID and interface.
600
Configuring DHCP and DNS.
602
To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
603
interface information. To do this we need to first determine the UUID of the
610
$ uuid=$(maas <profile> node\-groups list | grep uuid | cut \-d\e" \-f4)
616
Once we have the UUID we can use this to update the node\-group\-interface for
617
that nodegroup, and pass it the relevant interface details:
623
$ maas <profile> node\-group\-interface update $uuid eth0 \e
624
ip_range_high=192.168.123.200 \e
625
ip_range_low=192.168.123.100 \e
627
broadcast_ip=192.168.123.255 \e
628
router_ip=192.168.123.1 \e
634
Replacing the example values with those required for this network. The
635
only non\-obvious parameter is \(aqmanagement\(aq which takes the values 0
636
(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
637
.SH NODE-GROUP-INTERFACES
639
The node\-group\-interfaces commands are used for configuring the
640
management of DHCP and DNS services where these are managed by MAAS.
642
Usage: maas \fI<profile>\fP node\-group\-interfaces [\-d \-\-debug] [\-h
643
\-\-help] [\-k \-\-insecure] list | new [parameters...]
648
Displays debug information listing the API responses.
655
Display usage information.
659
\fB\-k, \-\-insecure\fP
662
Disables the SSL certificate check.
669
Lists the current stored configurations for the given identifier
670
<label> in a key:value format which should be easy to decipher.
674
\fBnew <label> ip=<value> interface=<if_device> [parameters...]\fP
677
Creates a new interface group. The required parameters are the IP
678
address and the network interface this appies to (e.g. eth0). In
679
order to do anything useful, further parameters are required:
685
management= 0 | 1 | 2
686
The service to be managed on the interface
687
( 0= none, 1=DHCP, 2=DHCP and DNS).
690
Apply the given dotted decimal value as the subnet mask.
693
Apply the given dotted decimal value as the
694
broadcast IP address for this subnet.
697
Apply the given dotted decimal value as the
698
default router address for this subnet.
701
The lowest value of IP address to allocate via DHCP
703
ip_range_high=<value>
704
The highest value of IP address to allocate via DHCP
714
.B Usage: maas <profile> tag read | update\-nodes | rebuild | update |
718
\fBread <tag_name>\fP
721
Returns information on the tag specified by <name>
725
\fBupdate\-nodes <tag_name> [add=<system_id>] [remove=<system_id>]
726
[nodegroup=<system_id>]\fP
729
Applies or removes the given tag from a list of nodes specified by
730
either or both of add="<system_id>" and remove="<system_id>". The
731
nodegroup parameter, which restricts the operations to a particular
732
nodegroup, is optional, but only the superuser can execute this
740
Triggers a rebuild of the tag to node mapping.
744
\fBupdate <tag_name> [name=<value>] | [comment=<value>]|
745
[definition=<value>]\fP
748
Updates the tag identified by tag_name. Any or all of name,comment
749
and definition may be supplied as parameters. If no parameters are
750
supplied, this command returns the current values.
754
\fBnodes <tag_name>\fP
757
Returns a list of nodes which are associated with the given tag.
761
\fBdelete <tag_name>\fP
764
Deletes the given tag.
769
Tags are a really useful way of identifying nodes with particular
772
Usage: maas <profile> tag [\-d \-\-debug] [\-h \-\-help] [\-k
773
\-\-insecure] list | new
778
Displays debug information listing the API responses.
785
Display usage information.
789
\fB\-k, \-\-insecure\fP
792
Disables the SSL certificate check.
799
Returns a JSON object listing all the current tags known by the MAAS server
803
\fBcreate name=<value> definition=<value> [comment=<value>]\fP
806
Creates a new tag with the given name and definition. A comment is
807
optional. Names must be unique, obviously \- an error will be
808
returned if the given name already exists. The definition is in the
809
form of an XPath expression which parses the XML returned by
810
running \fBlshw\fP on the node.
815
Adding a tag to all nodes which have an Intel GPU:
821
$ maas maas tags new name=\(aqintel\-gpu\(aq \e
822
comment=\(aqMachines which have an Intel display driver\(aq \e
823
definition=\(aqcontains(//node[@id="display"]/vendor, "Intel")
830
Because the \fBmaas\fP command exposes all of the API, it also lists
831
some command options which are not really intended for end users, such
832
as the "file" and "boot\-images" options.
87
833
.SH FURTHER DOCUMENTATION
89
835
For more documentation of MAAS, please see \fI\%https://maas.ubuntu.com/docs\fP
96
842
2013, MAAS Developers
97
843
.\" Generated by docutils manpage writer.
added
removed
man/maas.8
