← Back to branch summary

~ubuntu-branches/ubuntu/raring/maas/raring-updates

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez, Raphaël Badin, Julian Edwards, Jeroen Vermeulen, Gavin Panella, Andres Rodriguez
  • Date: 2013-03-04 11:49:44 UTC
  • mfrom: (1.2.5)
  • Revision ID: package-import@ubuntu.com-20130304114944-81my0hho8arxa3ix
Tags: 1.3+bzr1452+dfsg-0ubuntu1
https://launchpad.net/bugs/1103195
https://launchpad.net/bugs/1085865
https://launchpad.net/bugs/1083542
https://launchpad.net/bugs/1066935
https://launchpad.net/bugs/1072744
https://launchpad.net/bugs/1069734
https://launchpad.net/bugs/1081212
https://launchpad.net/bugs/1076028
https://launchpad.net/bugs/1103194
* New upstream release.
  - MAAS file storage mechanism is shifting from a single shared
    namespace to a per-user namespace. Operators of the majority
    of MAAS systems will not notice any change. However, operators
    of the most complex installations may find that a new
    "shared-environment" user is created, and that some resources
    are reassigned to it, such as API credentials and SSH public
    keys. This provides a transitional environment that mimics the
    behaviour of a shared namespace.

[ Raphaël Badin ]
* debian/control: maas-region-controller depends on bind9utils.
  (LP: #1103195)
* debian/maas-dns.postinst: Call write_dns_config.
  (LP: #1085865).
* debian/maas-cluster-controller.postinst: Fix the name of the config
  file (/etc/maas/pserv.yaml and not /etc/maas/pserv.conf)
  (LP: #1083542).
* debian/extras/99-maas-sudoers: Add 'SETENV:' to sudo rule
  to allow preserving the environment when running
  /usr/sbin/maas-import-pxe-files via sudo.
* debian/maas-dns.postinst: fix permissions and group ownership of
  file /etc/bind/maas/named.conf.rndc.maas. (LP: #1066935)
* debian/control: Remove the dependency of maas-cluster-controller
  on rabbitmq-server. (LP: #1072744)
* debian/extras/99-maas-sudoers: Add sudo rule for script
  /usr/sbin/maas-import-pxe-files.
* debian/maas-cluster-controller.install: Removed commissioning-user-data
  script.

[ Julian Edwards ]
* debian/maas-region-controller.install: Remove installation of maas-gc; it
  is no longer required as upstream no longer stores files in the filesystem.
  (LP: #1069734)
* debian/maas-cluster-controller.postinst: Ensure that /etc/maas/pserv.yaml
  is updated when reconfiguring. (LP: #1081212)

[ Jeroen Vermeulen ]
* debian/maas-cluster-controller.install: Install import scripts.
* debian/maas-cluster-controller.postinst: Configure tgt (the iSCSI server)
  so the import script can install files to it.
* debian/maas-cluster-controller.postrm: Clean up tgt config.
* debian/maas-region-controller.install: Move import scripts out to the
  cluster controller, and drop the maas-import-isos compatibility script.
* debian/maas-region-controller.postinst: Remove tgt config.
* debian/maas-region-controller.postrm: Remove tgt config cleanup.
* Bump code revision to include latest user_data.template fixes.

[ Gavin Panella ]
* debian/extras/99-maas: squashfs image download is no longer needed.
* debian/maas-cluster-controller.install: maas-import-squashfs and its
  configuration file are no longer part of upstream.
* debian/maas-cluster-controller.install: The maas-import-pxe-files cron
  task is no longer used.
* debian/maas-cluster-controller.postinst: Remove leading comment
  markers from the 'generator' line in pserv.yaml.

[ Andres Rodriguez ]
* debian/control:
  - maas-cluster-controller Conflicts with tftpd-hpa (LP: #1076028)
  - maas-dns: Conflicts with dnsmasq
  - maas-cluster-controller Conflicts/Replaces maas-region-controller as
    import scripts are no longer shipped in the region.
  - debian/control: Depends on distro-info for maas-cluster-controller
    instead of maas-region-controller (LP: #1103194)
* debian/maas-cluster-controller.config: If URL has been detected,
  add /MAAS if it doesn't contain it. This helps upgrades from versions
  where DEFAULT_MAAS_URL didn't use /MAAS.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/man/maas-cli.8.rst
1
 
 
2
1
maas-cli
3
2
--------
4
3
 
 
4
 
5
5
Usage
6
6
^^^^^
7
7
 
8
8
 $ maas-cli <profile> <command> [parameters]
9
 
 
 
9
 
10
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. 
 
11
profile you use. The currently available options are explained below.
12
12
 
13
13
 
14
14
Description
15
15
^^^^^^^^^^^
16
 
 
17
16
As well as the web interface, many tasks can be performed by accessing
18
17
the MAAS API directly through the maas-cli command. This section
19
18
details how to login with this tool and perform some common
30
29
Login to the web interface on your MAAS. Click on the username in the
31
30
top right corner and select 'Preferences' from the menu which appears.
32
31
 
 
32
A new page will load...
 
33
 
33
34
The very first item is a list of MAAS keys. One will have already been
34
35
generated when the system was installed. It's easiest to just select
35
36
and copy the key (it's quite long!) and then paste it into the
37
38
 
38
39
 $ maas-cli login <profile-name> <hostname> <key>
39
40
 
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)
 
41
The profile created is an easy way of associating your credentials
 
42
with any subsequent call to the API. So an example login might look
 
43
like this::
 
44
 
 
45
$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0
 
46
AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
 
47
 
 
48
which creates the profile 'maas' and registers it with the given key
 
49
at the specified API endpoint.  If you omit the credentials, they will
 
50
be prompted for in the console. It is also possible to use a hyphen,
 
51
'-' in place of the credentials. In this case a single line will be
 
52
read from stdin, stripped of any whitespace and used as the
 
53
credentials, which can be useful if you are devolping scripts for
 
54
specific tasks.  If an empty string is passed instead of the
 
55
credentials, the profile will be logged in anonymously (and
 
56
consequently some of the API calls will not be available)
55
57
 
56
58
 
57
59
maas-cli commands
59
61
 
60
62
The ``maas-cli`` command exposes the whole API, so you can do anything
61
63
you actually *can* do with MAAS using this command. Unsurprisingly,
62
 
this leaves us with a vast number of options.
 
64
this leaves us with a vast number of options, but before we delve into
 
65
detail on the specifics, here is a sort of 'cheat-sheet' for common
 
66
tasks you might want to do using ``maas-cli``.
 
67
 
 
68
  *  :ref:`Configure DHCP and DNS services <cli-dhcp>`
 
69
 
 
70
  *  :ref:`Commission all enlisted nodes <cli-commission>`
 
71
 
 
72
  *  :ref:`Setting IPMI power parameters for a node <cli-power>`
63
73
 
64
74
The main maas-cli commands are:
65
75
 
75
85
  Logs in to the MAAS controller API at the given URL, using the key
76
86
  provided and associates this connection with the given profile name.
77
87
 
78
 
:samp:`logout <profile>` 
 
88
:samp:`logout <profile>`
79
89
 
80
90
  Logs out from the given profile, flushing the stored credentials.
81
91
 
106
116
:samp:`-d, --debug`
107
117
 
108
118
   Displays debug information listing the API responses.
109
 
        
 
119
 
110
120
:samp:`-h, --help`
111
121
 
112
122
   Display usage information.
113
123
 
114
 
:samp:`-k, --insecure` 
 
124
:samp:`-k, --insecure`
115
125
 
116
126
   Disables the SSL certificate check.
117
127
 
125
135
    Removes the given key from the list of authorisation tokens.
126
136
 
127
137
 
 
138
.. boot-images - not useful in user context
 
139
.. ^^^^^^^^^^^
 
140
 
 
141
 
 
142
.. files - not useful in user context
 
143
.. ^^^^^
 
144
 
 
145
 
128
146
node
129
147
^^^^
130
148
 
147
165
   Releases the node given by *<system_id>*
148
166
 
149
167
:samp:`start <system_id>`
150
 
 
 
168
 
151
169
   Powers up the node identified by *<system_id>* (where MAAS has
152
170
   information for power management for this node).
153
171
 
154
172
:samp:`stop <system_id>`
155
 
 
 
173
 
156
174
   Powers off the node identified by *<system_id>* (where MAAS has
157
175
   information for power management for this node).
158
176
 
159
177
:samp:`delete <system_id>`
160
 
 
 
178
 
161
179
   Removes the given node from the MAAS database.
162
180
 
163
181
:samp:`read <system_id>`
164
 
 
 
182
 
165
183
   Returns all the current known information about the node specified
166
184
   by *<system_id>*
167
185
 
168
186
:samp:`update <system_id> [parameters...]`
169
 
 
 
187
 
170
188
   Used to change or set specific values for the node. The valid
171
189
   parameters are listed below::
172
190
 
173
191
      hostname=<value>
174
192
           The new hostname for this node.
175
193
 
176
 
      architecture=<value> 
 
194
      architecture=<value>
177
195
           Sets the architecture type, where <value>
178
196
           is a string containing a valid architecture type,
179
197
           e.g. "i386/generic"
180
198
 
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 
 
199
      power_type=<value>
 
200
           Apply the given dotted decimal value as the broadcast IP address
 
201
           for this subnet.
 
202
 
 
203
      power_parameters_{param1}... =<value>
 
204
           Set the given power parameters. Note that the valid options for these
190
205
           depend on the power type chosen.
191
206
 
192
 
      power_parameters_skip_check 'true' | 'false' 
193
 
           Whether to sanity check the supplied parameters against this node's 
 
207
      power_parameters_skip_check 'true' | 'false'
 
208
           Whether to sanity check the supplied parameters against this node's
194
209
           declared power type. The default is 'false'.
195
210
 
196
211
 
197
 
 
198
212
.. _cli-power:
199
213
 
200
214
Example: Setting the power parameters for an ipmi enabled node::
206
220
    power_parameters_power_pass=ubuntu;
207
221
 
208
222
 
209
 
 
210
 
 
211
223
nodes
212
224
^^^^^
213
225
 
271
283
   that have not returned before the system timeout value are listed
272
284
   as "failed".
273
285
 
 
286
 
274
287
Examples:
275
288
Accept and commission all discovered nodes::
276
289
 
285
298
 $ maas-cli maas nodes list architecture="i386/generic"
286
299
 
287
300
 
288
 
 
289
301
node-groups
290
302
^^^^^^^^^^^
291
303
Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
296
308
:samp:`-d, --debug`
297
309
 
298
310
   Displays debug information listing the API responses.
299
 
        
 
311
 
300
312
:samp:`-h, --help`
301
313
 
302
314
   Display usage information.
306
318
   Disables the SSL certificate check.
307
319
 
308
320
:samp:`register uuid=<value> name=<value> interfaces=<json_string>`
309
 
   
 
321
 
310
322
   Registers a new node group with the given name and uuid. The
311
323
   interfaces parameter must be supplied in the form of a JSON string
312
324
   comprising the key/value data for the interface to be used, for
317
329
 
318
330
:samp:`list`
319
331
 
320
 
   Returns a JSON list of all currently defined node groups.   
 
332
   Returns a JSON list of all currently defined node groups.
321
333
 
322
334
:samp:`refresh_workers`
323
335
 
328
340
   nodes.
329
341
 
330
342
:samp:`accept <uuid>`
331
 
   
 
343
 
332
344
   Accepts a node-group or number of nodegroups indicated by the
333
345
   supplied UUID
334
346
 
338
350
   supplied UUID
339
351
 
340
352
 
341
 
 
342
353
node-group-interface
343
354
^^^^^^^^^^^^^^^^^^^^
344
 
For managing the interfaces. See also 
345
 
"node_group_interfaces"
 
355
For managing the interfaces. See also :ref:`node-group-interfaces`
346
356
 
347
 
Usage: maas-cli *<profile>* node-group-interface [-d --debug] [-h
 
357
Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
348
358
--help] [-k --insecure] read | update | delete [parameters...]
349
359
 
350
360
..program:: maas-cli node-group-interface
351
361
 
352
362
:samp:`read <uuid> <interface>`
353
 
   
 
363
 
354
364
   Returns the current settings for the given UUID and interface
355
365
 
356
366
:samp:`update [parameters]`
357
 
   
 
367
 
358
368
   Changes the settings for the interface according to the given
359
369
   parameters::
360
370
 
361
371
      management=  0 | 1 | 2
362
 
           The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP 
 
372
           The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
363
373
           and DNS).
364
374
 
365
375
      subnet_mask=<value>
366
376
           Apply the given dotted decimal value as the subnet mask.
367
377
 
368
378
      broadcast_ip=<value>
369
 
           Apply the given dotted decimal value as the broadcast IP address for 
 
379
           Apply the given dotted decimal value as the broadcast IP address for
370
380
           this subnet.
371
381
 
372
382
      router_ip=<value>
373
 
           Apply the given dotted decimal value as the default router address 
 
383
           Apply the given dotted decimal value as the default router address
374
384
           for this subnet.
375
385
 
376
386
      ip_range_low=<value>
377
387
           The lowest value of IP address to allocate via DHCP
378
388
 
379
389
      ip_range_high=<value>
380
 
           The highest value of IP address to allocate via DHCP 
 
390
           The highest value of IP address to allocate via DHCP
381
391
 
382
392
:samp:`delete <uuid> <interface>`
383
393
 
384
394
   Removes the entry for the given UUID and interface.
385
 
   
386
395
 
387
396
Example:
388
397
Configuring DHCP and DNS.
389
398
 
390
 
To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant 
 
399
To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
391
400
interface information. To do this we need to first determine the UUID of the
392
401
node group affected::
393
402
 
394
403
 $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)
395
 
 
 
404
 
396
405
Once we have the UUID we can use this to update the node-group-interface for
397
406
that nodegroup, and pass it the relevant interface details::
398
407
 
403
412
         broadcast_ip=192.168.123.255     \
404
413
         router_ip=192.168.123.1          \
405
414
 
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).
 
415
Replacing the example values with those required for this network. The
 
416
only non-obvious parameter is 'management' which takes the values 0
 
417
(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
409
418
 
410
419
 
411
420
node-group-interfaces
422
431
:samp:`-d, --debug`
423
432
 
424
433
   Displays debug information listing the API responses.
425
 
        
 
434
 
426
435
:samp:`-h, --help`
427
436
 
428
437
   Display usage information.
436
445
   Lists the current stored configurations for the given identifier
437
446
   <label> in a key:value format which should be easy to decipher.
438
447
 
439
 
        
440
448
:samp:`new <label> ip=<value> interface=<if_device> [parameters...]`
441
 
              
 
449
 
442
450
   Creates a new interface group. The required parameters are the IP
443
451
   address and the network interface this appies to (e.g. eth0). In
444
452
   order to do anything useful, further parameters are required::
445
453
 
446
 
      management= 0 | 1 | 2 
 
454
      management= 0 | 1 | 2
447
455
           The service to be managed on the interface
448
456
           ( 0= none, 1=DHCP, 2=DHCP and DNS).
449
457
 
450
458
      subnet_mask=<value>
451
459
           Apply the given dotted decimal value as the subnet mask.
452
460
 
453
 
      broadcast_ip=<value> 
 
461
      broadcast_ip=<value>
454
462
           Apply the given dotted decimal value as the
455
463
           broadcast IP address for this subnet.
456
464
 
457
 
      router_ip=<value> 
 
465
      router_ip=<value>
458
466
           Apply the given dotted decimal value as the
459
467
           default router address for this subnet.
460
468
 
465
473
           The highest value of IP address to allocate via DHCP
466
474
 
467
475
 
468
 
 
469
 
 
470
 
tag 
 
476
tag
471
477
^^^
472
478
 
473
479
Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
474
 
  nodes | delete 
 
480
  nodes | delete
475
481
 
476
482
.. program:: maas-cli tag
477
483
 
478
484
:samp:`read <tag_name>`
479
 
   
 
485
 
480
486
   Returns information on the tag specified by <name>
481
487
 
482
 
:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]`
 
488
:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>]
 
489
[nodegroup=<system_id>]`
483
490
 
484
491
   Applies or removes the given tag from a list of nodes specified by
485
492
   either or both of add="<system_id>" and remove="<system_id>". The
489
496
 
490
497
:samp:`rebuild`
491
498
 
492
 
   Triggers a rebuild of the tag to node mapping. 
493
 
 
494
 
:samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`
495
 
   
 
499
   Triggers a rebuild of the tag to node mapping.
 
500
 
 
501
:samp:`update <tag_name> [name=<value>] | [comment=<value>]|
 
502
[definition=<value>]`
 
503
 
496
504
   Updates the tag identified by tag_name. Any or all of name,comment
497
505
   and definition may be supplied as parameters. If no parameters are
498
506
   supplied, this command returns the current values.
505
513
 
506
514
   Deletes the given tag.
507
515
 
508
 
tags 
509
 
^^^^ 
510
 
Tags are a really useful way of identifying nodes with particular 
511
 
characteristics. 
 
516
 
 
517
tags
 
518
^^^^
 
519
 
 
520
Tags are a really useful way of identifying nodes with particular
 
521
characteristics.
 
522
 
 
523
.. only:: html
 
524
 
 
525
  For more information on how to use them effectively, please see
 
526
  :ref:`deploy-tags`
512
527
 
513
528
Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
514
529
--insecure] list | new
518
533
:samp:`-d, --debug`
519
534
 
520
535
   Displays debug information listing the API responses.
521
 
        
 
536
 
522
537
:samp:`-h, --help`
523
538
 
524
539
   Display usage information.
525
540
 
526
 
:samp:`-k, --insecure` 
 
541
:samp:`-k, --insecure`
527
542
 
528
543
   Disables the SSL certificate check.
529
544
 
530
545
:samp:`list`
531
 
  
 
546
 
532
547
   Returns a JSON object listing all the current tags known by the MAAS server
533
548
 
534
549
:samp:`create name=<value> definition=<value> [comment=<value>]`
535
550
 
536
551
   Creates a new tag with the given name and definition. A comment is
537
552
   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
 
   
 
553
   returned if the given name already exists. The definition is in the
 
554
   form of an XPath expression which parses the XML returned by
 
555
   running ``lshw`` on the node.
 
556
 
542
557
Example:
543
558
Adding a tag to all nodes which have an Intel GPU::
544
559
 
545
560
   $ maas-cli maas tags new name='intel-gpu' \
546
561
       comment='Machines which have an Intel display driver' \
547
562
       definition='contains(//node[@id="display"]/vendor, "Intel")
548
 
 
549
 
 
550
 
unused commands 
551
 
^^^^^^^^^^^^^^^ 
 
563
 
 
564
 
 
565
unused commands
 
566
^^^^^^^^^^^^^^^
 
567
 
552
568
Because the ``maas-cli`` command exposes all of the API, it also lists
553
569
some command options which are not really intended for end users, such
554
570
as the "file" and "boot-images" options.
555
571
 
556
572
Further Documentation
557
573
^^^^^^^^^^^^^^^^^^^^^
 
574
 
558
575
For more documentation of MAAS, please see https://maas.ubuntu.com/docs
559
576
 
 
577
 
560
578
See Also
561
579
^^^^^^^^
 
580
 
562
581
`maas`
563
 
 
564