← Back to branch summary

~ubuntu-branches/ubuntu/precise/maas/precise-updates

« back to all changes in this revision

Viewing changes to docs/man/maas-cli.8.rst

Tags: 1.2+bzr1373+dfsg-0ubuntu1~12.04.4
https://launchpad.net/bugs/1039513
https://launchpad.net/bugs/1158425
* SECURITY UPDATE: failure to authenticate downloaded content (LP: #1039513)
  - debian/patches/CVE-2013-1058.patch: Authenticate downloaded files with
    GnuPG and MD5SUM files. Thanks to Julian Edwards.
  - CVE-2013-1058
* SECURITY UPDATE: configuration options may be loaded from current working
  directory (LP: #1158425)
  - debian/patches/CVE-2013-1057-1-2.patch: Do not load configuration
    options from the current working directory. Thanks to Julian Edwards.
  - CVE-2013-1057

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/man/maas-cli.8.rst
 
1
 
 
2
maas-cli
 
3
--------
 
4
 
 
5
Usage
 
6
^^^^^
 
7
 
 
8
 $ maas-cli <profile> <command> [parameters]
 
9
 
 
10
The available commands are dependent on the API you are connecting to and the
 
11
profile you use. The currently available options are explained below. 
 
12
 
 
13
 
 
14
Description
 
15
^^^^^^^^^^^
 
16
 
 
17
As well as the web interface, many tasks can be performed by accessing
 
18
the MAAS API directly through the maas-cli command. This section
 
19
details how to login with this tool and perform some common
 
20
operations.
 
21
 
 
22
 
 
23
Logging in
 
24
----------
 
25
 
 
26
Before the API will accept any commands from maas-cli, you must first
 
27
login. To do this, you need the API key which can be found in the user
 
28
interface.
 
29
 
 
30
Login to the web interface on your MAAS. Click on the username in the
 
31
top right corner and select 'Preferences' from the menu which appears.
 
32
 
 
33
The very first item is a list of MAAS keys. One will have already been
 
34
generated when the system was installed. It's easiest to just select
 
35
and copy the key (it's quite long!) and then paste it into the
 
36
commandline. The format of the login command is::
 
37
 
 
38
 $ maas-cli login <profile-name> <hostname> <key>
 
39
 
 
40
The profile created is an easy way of associating your credentials with any 
 
41
subsequent call to the API. So an example login might look like this::
 
42
 
 
43
$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
 
44
 
 
45
which creates the profile 'maas' and registers it with the given key at the 
 
46
specified API endpoint.
 
47
If you omit the credentials, they will be prompted for in the console. It is 
 
48
also possible to use  a hyphen, '-' in place of the credentials. In this case a 
 
49
single line will be read from stdin, stripped of any whitespace and used as the 
 
50
credentials, which can be useful if you are devolping scripts for specific 
 
51
tasks.
 
52
If an empty string is passed instead of the credentials, the profile will be 
 
53
logged in anonymously (and consequently some of the API calls will not be 
 
54
available)
 
55
 
 
56
 
 
57
maas-cli commands
 
58
-----------------
 
59
 
 
60
The ``maas-cli`` command exposes the whole API, so you can do anything
 
61
you actually *can* do with MAAS using this command. Unsurprisingly,
 
62
this leaves us with a vast number of options.
 
63
 
 
64
The main maas-cli commands are:
 
65
 
 
66
.. program:: maas-cli
 
67
 
 
68
:samp:`list`
 
69
 
 
70
  lists the details [name url auth-key] of all the currently logged-in
 
71
  profiles.
 
72
 
 
73
:samp:`login <profile> <url> <key>`
 
74
 
 
75
  Logs in to the MAAS controller API at the given URL, using the key
 
76
  provided and associates this connection with the given profile name.
 
77
 
 
78
:samp:`logout <profile>` 
 
79
 
 
80
  Logs out from the given profile, flushing the stored credentials.
 
81
 
 
82
:samp:`refresh`
 
83
 
 
84
  Refreshes the API descriptions of all the current logged in
 
85
  profiles. This may become necessary for example when upgrading the
 
86
  maas packages to ensure the command-line options match with the API.
 
87
 
 
88
:samp:`<profile> [command] [options] ...`
 
89
 
 
90
  Using the given profile name instructs ``maas-cli`` to direct the
 
91
  subsequent commands and options to the relevant MAAS, which for the
 
92
  current API are detailed below...
 
93
 
 
94
 
 
95
account
 
96
^^^^^^^
 
97
This command is used for creating and destroying the
 
98
MAAS authorisation tokens associated with a profile.
 
99
 
 
100
Usage: maas-cli *<profile>* account [-d --debug] [-h --help]
 
101
create-authorisation-token | delete-authorisation-token [token_key=\
 
102
*<value>*]
 
103
 
 
104
.. program:: maas-cli account
 
105
 
 
106
:samp:`-d, --debug`
 
107
 
 
108
   Displays debug information listing the API responses.
 
109
        
 
110
:samp:`-h, --help`
 
111
 
 
112
   Display usage information.
 
113
 
 
114
:samp:`-k, --insecure` 
 
115
 
 
116
   Disables the SSL certificate check.
 
117
 
 
118
:samp:`create-authorisation-token`
 
119
 
 
120
    Creates a new MAAS authorisation token for the current profile
 
121
    which can be used to authenticate connections to the API.
 
122
 
 
123
:samp:`delete-authorisation-token token_key=<value>`
 
124
 
 
125
    Removes the given key from the list of authorisation tokens.
 
126
 
 
127
 
 
128
node
 
129
^^^^
 
130
 
 
131
API calls which operate on individual nodes. With these commands, the
 
132
node is always identified by its "system_id" property - a unique tag
 
133
allocated at the time of enlistment. To discover the value of the
 
134
system_id, you can use the ``maas-cli <profile> nodes list`` command.
 
135
 
 
136
USAGE: maas-cli <profile> node [-h] release | start | stop | delete |
 
137
read | update <system_id>
 
138
 
 
139
.. program:: maas-cli node
 
140
 
 
141
:samp:`-h, --help`
 
142
 
 
143
   Display usage information.
 
144
 
 
145
:samp:`release <system_id>`
 
146
 
 
147
   Releases the node given by *<system_id>*
 
148
 
 
149
:samp:`start <system_id>`
 
150
 
 
151
   Powers up the node identified by *<system_id>* (where MAAS has
 
152
   information for power management for this node).
 
153
 
 
154
:samp:`stop <system_id>`
 
155
 
 
156
   Powers off the node identified by *<system_id>* (where MAAS has
 
157
   information for power management for this node).
 
158
 
 
159
:samp:`delete <system_id>`
 
160
 
 
161
   Removes the given node from the MAAS database.
 
162
 
 
163
:samp:`read <system_id>`
 
164
 
 
165
   Returns all the current known information about the node specified
 
166
   by *<system_id>*
 
167
 
 
168
:samp:`update <system_id> [parameters...]`
 
169
 
 
170
   Used to change or set specific values for the node. The valid
 
171
   parameters are listed below::
 
172
 
 
173
      hostname=<value>
 
174
           The new hostname for this node.
 
175
 
 
176
      architecture=<value> 
 
177
           Sets the architecture type, where <value>
 
178
           is a string containing a valid architecture type,
 
179
           e.g. "i386/generic"
 
180
 
 
181
      distro_series=<value>
 
182
           Sets the series of Ubuntu to use.
 
183
 
 
184
      power_type=<value> 
 
185
           Sets the type of power management used on the node, e.g. "ipmi" or
 
186
           "virsh".
 
187
 
 
188
      power_parameters_{param1}... =<value> 
 
189
           Set the given power parameters. Note that the valid options for these 
 
190
           depend on the power type chosen.
 
191
 
 
192
      power_parameters_skip_check 'true' | 'false' 
 
193
           Whether to sanity check the supplied parameters against this node's 
 
194
           declared power type. The default is 'false'.
 
195
 
 
196
 
 
197
 
 
198
.. _cli-power:
 
199
 
 
200
Example: Setting the power parameters for an ipmi enabled node::
 
201
 
 
202
  maas-cli maas node update <system_id> \
 
203
    power_type="ipmi" \
 
204
    power_parameters_power_address=192.168.22.33 \
 
205
    power_parameters_power_user=root \
 
206
    power_parameters_power_pass=ubuntu;
 
207
 
 
208
 
 
209
 
 
210
 
 
211
nodes
 
212
^^^^^
 
213
 
 
214
Usage: maas-cli <profile> nodes [-h] is-registered | list-allocated |
 
215
acquire | list | accept | accept-all | new | check-commissioning
 
216
 
 
217
.. program:: maas-cli nodes
 
218
 
 
219
:samp:`-h, --help`
 
220
 
 
221
   Display usage information.
 
222
 
 
223
 
 
224
:samp:`accept <system_id>`
 
225
 
 
226
   Accepts the node referenced by <system_id>.
 
227
 
 
228
:samp:`accept-all`
 
229
 
 
230
   Accepts all currently discovered but not previously accepted nodes.
 
231
 
 
232
:samp:`acquire`
 
233
 
 
234
   Allocates a node to the profile used to issue the command. Any
 
235
   ready node may be allocated.
 
236
 
 
237
:samp:`is-registered mac_address=<address>`
 
238
 
 
239
   Checks to see whether the specified MAC address is registered to a
 
240
   node.
 
241
 
 
242
:samp:`list`
 
243
 
 
244
   Returns a JSON formatted object listing all the currently known
 
245
   nodes, their system_id, status and other details.
 
246
 
 
247
:samp:`list-allocated`
 
248
 
 
249
   Returns a JSON formatted object listing all the currently allocated
 
250
   nodes, their system_id, status and other details.
 
251
 
 
252
:samp:`new architecture=<value> mac_addresses=<value> [parameters]`
 
253
 
 
254
   Creates a new node entry given the provided key=value information
 
255
   for the node. A minimum of the MAC address and architecture must be
 
256
   provided. Other parameters may also be supplied::
 
257
 
 
258
     architecture="<value>" - The architecture of the node, must be
 
259
     one of the recognised architecture strings (e.g. "i386/generic")
 
260
     hostname="<value>" - a name for this node. If not supplied a name
 
261
     will be generated.
 
262
     mac_addresses="<value>" - The mac address(es)
 
263
     allocated to this node.
 
264
     powertype="<value>" - the power type of
 
265
     the node (e.g. virsh, ipmi)
 
266
 
 
267
 
 
268
:samp:`check-commissioning`
 
269
 
 
270
   Displays current status of nodes in the commissioning phase. Any
 
271
   that have not returned before the system timeout value are listed
 
272
   as "failed".
 
273
 
 
274
Examples:
 
275
Accept and commission all discovered nodes::
 
276
 
 
277
 $ maas-cli maas nodes accept-all
 
278
 
 
279
List all known nodes::
 
280
 
 
281
 $ maas-cli maas nodes list
 
282
 
 
283
Filter the list using specific key/value pairs::
 
284
 
 
285
 $ maas-cli maas nodes list architecture="i386/generic"
 
286
 
 
287
 
 
288
 
 
289
node-groups
 
290
^^^^^^^^^^^
 
291
Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
 
292
--insecure] register | list | refresh-workers | accept | reject
 
293
 
 
294
.. program:: maas-cli node-groups
 
295
 
 
296
:samp:`-d, --debug`
 
297
 
 
298
   Displays debug information listing the API responses.
 
299
        
 
300
:samp:`-h, --help`
 
301
 
 
302
   Display usage information.
 
303
 
 
304
:samp:`-k, --insecure`
 
305
 
 
306
   Disables the SSL certificate check.
 
307
 
 
308
:samp:`register uuid=<value> name=<value> interfaces=<json_string>`
 
309
   
 
310
   Registers a new node group with the given name and uuid. The
 
311
   interfaces parameter must be supplied in the form of a JSON string
 
312
   comprising the key/value data for the interface to be used, for
 
313
   example: interface='["ip":"192.168.21.5","interface":"eth1", \
 
314
   "subnet_mask":"255.255.255.0","broadcast_ip":"192.168.21.255", \
 
315
   "router_ip":"192.168.21.1", "ip_range_low":"192.168.21.10", \
 
316
   "ip_range_high":"192.168.21.50"}]'
 
317
 
 
318
:samp:`list`
 
319
 
 
320
   Returns a JSON list of all currently defined node groups.   
 
321
 
 
322
:samp:`refresh_workers`
 
323
 
 
324
   It sounds a bit like they will get a cup of tea and a
 
325
   biscuit. Actually this just sends each node-group worker an update
 
326
   of its credentials (API key, node-group name). This command is
 
327
   usually not needed at a user level, but is often used by worker
 
328
   nodes.
 
329
 
 
330
:samp:`accept <uuid>`
 
331
   
 
332
   Accepts a node-group or number of nodegroups indicated by the
 
333
   supplied UUID
 
334
 
 
335
:samp:`reject <uuid>`
 
336
 
 
337
   Rejects a node-group or number of nodegroups indicated by the
 
338
   supplied UUID
 
339
 
 
340
 
 
341
 
 
342
node-group-interface
 
343
^^^^^^^^^^^^^^^^^^^^
 
344
For managing the interfaces. See also 
 
345
"node_group_interfaces"
 
346
 
 
347
Usage: maas-cli *<profile>* node-group-interface [-d --debug] [-h
 
348
--help] [-k --insecure] read | update | delete [parameters...]
 
349
 
 
350
..program:: maas-cli node-group-interface
 
351
 
 
352
:samp:`read <uuid> <interface>`
 
353
   
 
354
   Returns the current settings for the given UUID and interface
 
355
 
 
356
:samp:`update [parameters]`
 
357
   
 
358
   Changes the settings for the interface according to the given
 
359
   parameters::
 
360
 
 
361
      management=  0 | 1 | 2
 
362
           The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP 
 
363
           and DNS).
 
364
 
 
365
      subnet_mask=<value>
 
366
           Apply the given dotted decimal value as the subnet mask.
 
367
 
 
368
      broadcast_ip=<value>
 
369
           Apply the given dotted decimal value as the broadcast IP address for 
 
370
           this subnet.
 
371
 
 
372
      router_ip=<value>
 
373
           Apply the given dotted decimal value as the default router address 
 
374
           for this subnet.
 
375
 
 
376
      ip_range_low=<value>
 
377
           The lowest value of IP address to allocate via DHCP
 
378
 
 
379
      ip_range_high=<value>
 
380
           The highest value of IP address to allocate via DHCP 
 
381
 
 
382
:samp:`delete <uuid> <interface>`
 
383
 
 
384
   Removes the entry for the given UUID and interface.
 
385
   
 
386
 
 
387
Example:
 
388
Configuring DHCP and DNS.
 
389
 
 
390
To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant 
 
391
interface information. To do this we need to first determine the UUID of the
 
392
node group affected::
 
393
 
 
394
 $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)
 
395
 
 
396
Once we have the UUID we can use this to update the node-group-interface for
 
397
that nodegroup, and pass it the relevant interface details::
 
398
 
 
399
 $ maas-cli <profile> node-group-interface update $uuid eth0 \
 
400
         ip_range_high=192.168.123.200    \
 
401
         ip_range_low=192.168.123.100     \
 
402
         management=2                     \
 
403
         broadcast_ip=192.168.123.255     \
 
404
         router_ip=192.168.123.1          \
 
405
 
 
406
Replacing the example values with those required for this network. The only 
 
407
non-obvious parameter is 'management' which takes the values 0 (no management), 1
 
408
(manage DHCP) and 2 (manage DHCP and DNS).
 
409
 
 
410
 
 
411
node-group-interfaces
 
412
^^^^^^^^^^^^^^^^^^^^^
 
413
 
 
414
The node-group-interfaces commands are used for configuring the
 
415
management of DHCP and DNS services where these are managed by MAAS.
 
416
 
 
417
Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
 
418
--help] [-k --insecure] list | new [parameters...]
 
419
 
 
420
.. program:: maas-cli node-group-interfaces
 
421
 
 
422
:samp:`-d, --debug`
 
423
 
 
424
   Displays debug information listing the API responses.
 
425
        
 
426
:samp:`-h, --help`
 
427
 
 
428
   Display usage information.
 
429
 
 
430
:samp:`-k, --insecure`
 
431
 
 
432
   Disables the SSL certificate check.
 
433
 
 
434
:samp:`list <label>`
 
435
 
 
436
   Lists the current stored configurations for the given identifier
 
437
   <label> in a key:value format which should be easy to decipher.
 
438
 
 
439
        
 
440
:samp:`new <label> ip=<value> interface=<if_device> [parameters...]`
 
441
              
 
442
   Creates a new interface group. The required parameters are the IP
 
443
   address and the network interface this appies to (e.g. eth0). In
 
444
   order to do anything useful, further parameters are required::
 
445
 
 
446
      management= 0 | 1 | 2 
 
447
           The service to be managed on the interface
 
448
           ( 0= none, 1=DHCP, 2=DHCP and DNS).
 
449
 
 
450
      subnet_mask=<value>
 
451
           Apply the given dotted decimal value as the subnet mask.
 
452
 
 
453
      broadcast_ip=<value> 
 
454
           Apply the given dotted decimal value as the
 
455
           broadcast IP address for this subnet.
 
456
 
 
457
      router_ip=<value> 
 
458
           Apply the given dotted decimal value as the
 
459
           default router address for this subnet.
 
460
 
 
461
      ip_range_low=<value>
 
462
           The lowest value of IP address to allocate via DHCP
 
463
 
 
464
      ip_range_high=<value>
 
465
           The highest value of IP address to allocate via DHCP
 
466
 
 
467
 
 
468
 
 
469
 
 
470
tag 
 
471
^^^
 
472
 
 
473
Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
 
474
  nodes | delete 
 
475
 
 
476
.. program:: maas-cli tag
 
477
 
 
478
:samp:`read <tag_name>`
 
479
   
 
480
   Returns information on the tag specified by <name>
 
481
 
 
482
:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]`
 
483
 
 
484
   Applies or removes the given tag from a list of nodes specified by
 
485
   either or both of add="<system_id>" and remove="<system_id>". The
 
486
   nodegroup parameter, which restricts the operations to a particular
 
487
   nodegroup, is optional, but only the superuser can execute this
 
488
   command without it.
 
489
 
 
490
:samp:`rebuild`
 
491
 
 
492
   Triggers a rebuild of the tag to node mapping. 
 
493
 
 
494
:samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`
 
495
   
 
496
   Updates the tag identified by tag_name. Any or all of name,comment
 
497
   and definition may be supplied as parameters. If no parameters are
 
498
   supplied, this command returns the current values.
 
499
 
 
500
:samp:`nodes <tag_name>`
 
501
 
 
502
   Returns a list of nodes which are associated with the given tag.
 
503
 
 
504
:samp:`delete <tag_name>`
 
505
 
 
506
   Deletes the given tag.
 
507
 
 
508
tags 
 
509
^^^^ 
 
510
Tags are a really useful way of identifying nodes with particular 
 
511
characteristics. 
 
512
 
 
513
Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
 
514
--insecure] list | new
 
515
 
 
516
.. program:: maas-cli tag
 
517
 
 
518
:samp:`-d, --debug`
 
519
 
 
520
   Displays debug information listing the API responses.
 
521
        
 
522
:samp:`-h, --help`
 
523
 
 
524
   Display usage information.
 
525
 
 
526
:samp:`-k, --insecure` 
 
527
 
 
528
   Disables the SSL certificate check.
 
529
 
 
530
:samp:`list`
 
531
  
 
532
   Returns a JSON object listing all the current tags known by the MAAS server
 
533
 
 
534
:samp:`create name=<value> definition=<value> [comment=<value>]`
 
535
 
 
536
   Creates a new tag with the given name and definition. A comment is
 
537
   optional. Names must be unique, obviously - an error will be
 
538
   returned if the given name already exists. The definition is in the form of 
 
539
   an XPath expression which parses the XML returned by running ``lshw`` on the 
 
540
   node.
 
541
   
 
542
Example:
 
543
Adding a tag to all nodes which have an Intel GPU::
 
544
 
 
545
   $ maas-cli maas tags new name='intel-gpu' \
 
546
       comment='Machines which have an Intel display driver' \
 
547
       definition='contains(//node[@id="display"]/vendor, "Intel")
 
548
 
 
549
 
 
550
unused commands 
 
551
^^^^^^^^^^^^^^^ 
 
552
Because the ``maas-cli`` command exposes all of the API, it also lists
 
553
some command options which are not really intended for end users, such
 
554
as the "file" and "boot-images" options.
 
555
 
 
556
Further Documentation
 
557
^^^^^^^^^^^^^^^^^^^^^
 
558
For more documentation of MAAS, please see https://maas.ubuntu.com/docs
 
559
 
 
560
See Also
 
561
^^^^^^^^
 
562
`maas`
 
563
 
 
564