← Back to branch summary

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

« back to all changes in this revision

Viewing changes to docs/maascli.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/maascli.rst
1
 
 
2
1
As well as the web interface, many tasks can be performed by accessing
3
2
the MAAS API directly through the maas-cli command. This section
4
3
details how to login with this tool and perform some common
5
4
operations.
6
5
 
 
6
 
7
7
.. _api-key:
8
8
 
9
9
Logging in
16
16
Login to the web interface on your MAAS. Click on the username in the
17
17
top right corner and select 'Preferences' from the menu which appears.
18
18
 
19
 
.. only:: html
20
19
.. image:: media/maascli-prefs.*
21
20
 
22
 
A new page will load... 
 
21
A new page will load...
23
22
 
24
 
.. only:: html
25
23
.. image:: media/maascli-key.*
26
24
 
27
25
The very first item is a list of MAAS keys. One will have already been
31
29
 
32
30
 $ maas-cli login <profile-name> <hostname> <key>
33
31
 
34
 
The profile created is an easy way of associating your credentials with any 
35
 
subsequent call to the API. So an example login might look like this::
36
 
 
37
 
$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
38
 
 
39
 
which creates the profile 'maas' and registers it with the given key at the 
40
 
specified API endpoint.
41
 
If you omit the credentials, they will be prompted for in the console. It is 
42
 
also possible to use  a hyphen, '-' in place of the credentials. In this case a 
43
 
single line will be read from stdin, stripped of any whitespace and used as the 
44
 
credentials, which can be useful if you are devolping scripts for specific 
45
 
tasks.
46
 
If an empty string is passed instead of the credentials, the profile will be 
47
 
logged in anonymously (and consequently some of the API calls will not be 
48
 
available)
 
32
The profile created is an easy way of associating your credentials
 
33
with any subsequent call to the API. So an example login might look
 
34
like this::
 
35
 
 
36
$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0
 
37
AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
 
38
 
 
39
which creates the profile 'maas' and registers it with the given key
 
40
at the specified API endpoint.  If you omit the credentials, they will
 
41
be prompted for in the console. It is also possible to use a hyphen,
 
42
'-' in place of the credentials. In this case a single line will be
 
43
read from stdin, stripped of any whitespace and used as the
 
44
credentials, which can be useful if you are devolping scripts for
 
45
specific tasks.  If an empty string is passed instead of the
 
46
credentials, the profile will be logged in anonymously (and
 
47
consequently some of the API calls will not be available)
49
48
 
50
49
 
51
50
maas-cli commands
77
76
  Logs in to the MAAS controller API at the given URL, using the key
78
77
  provided and associates this connection with the given profile name.
79
78
 
80
 
:samp:`logout <profile>` 
 
79
:samp:`logout <profile>`
81
80
 
82
81
  Logs out from the given profile, flushing the stored credentials.
83
82
 
108
107
:samp:`-d, --debug`
109
108
 
110
109
   Displays debug information listing the API responses.
111
 
        
 
110
 
112
111
:samp:`-h, --help`
113
112
 
114
113
   Display usage information.
115
114
 
116
 
:samp:`-k, --insecure` 
 
115
:samp:`-k, --insecure`
117
116
 
118
117
   Disables the SSL certificate check.
119
118
 
127
126
    Removes the given key from the list of authorisation tokens.
128
127
 
129
128
 
130
 
 
131
 
 
132
129
.. boot-images - not useful in user context
133
130
.. ^^^^^^^^^^^
134
131
 
159
156
   Releases the node given by *<system_id>*
160
157
 
161
158
:samp:`start <system_id>`
162
 
 
 
159
 
163
160
   Powers up the node identified by *<system_id>* (where MAAS has
164
161
   information for power management for this node).
165
162
 
166
163
:samp:`stop <system_id>`
167
 
 
 
164
 
168
165
   Powers off the node identified by *<system_id>* (where MAAS has
169
166
   information for power management for this node).
170
167
 
171
168
:samp:`delete <system_id>`
172
 
 
 
169
 
173
170
   Removes the given node from the MAAS database.
174
171
 
175
172
:samp:`read <system_id>`
176
 
 
 
173
 
177
174
   Returns all the current known information about the node specified
178
175
   by *<system_id>*
179
176
 
180
177
:samp:`update <system_id> [parameters...]`
181
 
 
 
178
 
182
179
   Used to change or set specific values for the node. The valid
183
180
   parameters are listed below::
184
181
 
185
182
      hostname=<value>
186
183
           The new hostname for this node.
187
184
 
188
 
      architecture=<value> 
 
185
      architecture=<value>
189
186
           Sets the architecture type, where <value>
190
187
           is a string containing a valid architecture type,
191
188
           e.g. "i386/generic"
192
189
 
193
190
      distro_series=<value>
194
 
           Sets the series of Ubuntu to use.
195
 
 
196
 
      power_type=<value> 
197
 
           Sets the type of power management used on the node, e.g. "ipmi" or
198
 
           "virsh".
199
 
 
200
 
      power_parameters_{param1}... =<value> 
201
 
           Set the given power parameters. Note that the valid options for these 
 
191
           Sets the distro series of Ubuntu to use (e.g. "precise").
 
192
 
 
193
      power_type=<value>
 
194
           Apply the given dotted decimal value as the broadcast IP address
 
195
           for this subnet.
 
196
 
 
197
      power_parameters_{param1}... =<value>
 
198
           Set the given power parameters. Note that the valid options for these
202
199
           depend on the power type chosen.
203
200
 
204
 
      power_parameters_skip_check 'true' | 'false' 
205
 
           Whether to sanity check the supplied parameters against this node's 
 
201
      power_parameters_skip_check 'true' | 'false'
 
202
           Whether to sanity check the supplied parameters against this node's
206
203
           declared power type. The default is 'false'.
207
204
 
208
205
 
209
 
 
210
206
.. _cli-power:
211
207
 
212
208
Example: Setting the power parameters for an ipmi enabled node::
218
214
    power_parameters_power_pass=ubuntu;
219
215
 
220
216
 
221
 
 
222
 
 
223
217
nodes
224
218
^^^^^
225
219
 
299
293
 $ maas-cli maas nodes list architecture="i386/generic"
300
294
 
301
295
 
302
 
 
303
296
node-groups
304
297
^^^^^^^^^^^
305
298
Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
310
303
:samp:`-d, --debug`
311
304
 
312
305
   Displays debug information listing the API responses.
313
 
        
 
306
 
314
307
:samp:`-h, --help`
315
308
 
316
309
   Display usage information.
320
313
   Disables the SSL certificate check.
321
314
 
322
315
:samp:`register uuid=<value> name=<value> interfaces=<json_string>`
323
 
   
 
316
 
324
317
   Registers a new node group with the given name and uuid. The
325
318
   interfaces parameter must be supplied in the form of a JSON string
326
319
   comprising the key/value data for the interface to be used, for
331
324
 
332
325
:samp:`list`
333
326
 
334
 
   Returns a JSON list of all currently defined node groups.   
 
327
   Returns a JSON list of all currently defined node groups.
335
328
 
336
329
:samp:`refresh_workers`
337
330
 
342
335
   nodes.
343
336
 
344
337
:samp:`accept <uuid>`
345
 
   
 
338
 
346
339
   Accepts a node-group or number of nodegroups indicated by the
347
340
   supplied UUID
348
341
 
352
345
   supplied UUID
353
346
 
354
347
 
355
 
 
356
348
node-group-interface
357
349
^^^^^^^^^^^^^^^^^^^^
358
 
For managing the interfaces. See also 
359
 
:ref:`node_group_interfaces <node_group_interfaces>`
 
350
For managing the interfaces. See also :ref:`node-group-interfaces`
360
351
 
361
 
Usage: maas-cli *<profile>* node-group-interface [-d --debug] [-h
 
352
Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
362
353
--help] [-k --insecure] read | update | delete [parameters...]
363
354
 
364
355
..program:: maas-cli node-group-interface
365
356
 
366
357
:samp:`read <uuid> <interface>`
367
 
   
 
358
 
368
359
   Returns the current settings for the given UUID and interface
369
360
 
370
361
:samp:`update [parameters]`
371
 
   
 
362
 
372
363
   Changes the settings for the interface according to the given
373
364
   parameters::
374
365
 
375
366
      management=  0 | 1 | 2
376
 
           The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP 
 
367
           The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
377
368
           and DNS).
378
369
 
379
370
      subnet_mask=<value>
380
371
           Apply the given dotted decimal value as the subnet mask.
381
372
 
382
373
      broadcast_ip=<value>
383
 
           Apply the given dotted decimal value as the broadcast IP address for 
 
374
           Apply the given dotted decimal value as the broadcast IP address for
384
375
           this subnet.
385
376
 
386
377
      router_ip=<value>
387
 
           Apply the given dotted decimal value as the default router address 
 
378
           Apply the given dotted decimal value as the default router address
388
379
           for this subnet.
389
380
 
390
381
      ip_range_low=<value>
391
382
           The lowest value of IP address to allocate via DHCP
392
383
 
393
384
      ip_range_high=<value>
394
 
           The highest value of IP address to allocate via DHCP 
 
385
           The highest value of IP address to allocate via DHCP
395
386
 
396
387
:samp:`delete <uuid> <interface>`
397
388
 
398
389
   Removes the entry for the given UUID and interface.
399
 
   
 
390
 
400
391
.. _cli-dhcp:
401
392
 
402
393
Example:
403
394
Configuring DHCP and DNS.
404
395
 
405
 
To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant 
 
396
To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
406
397
interface information. To do this we need to first determine the UUID of the
407
398
node group affected::
408
399
 
409
400
 $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)
410
 
 
 
401
 
411
402
Once we have the UUID we can use this to update the node-group-interface for
412
403
that nodegroup, and pass it the relevant interface details::
413
404
 
418
409
         broadcast_ip=192.168.123.255     \
419
410
         router_ip=192.168.123.1          \
420
411
 
421
 
Replacing the example values with those required for this network. The only 
422
 
non-obvious parameter is 'management' which takes the values 0 (no management), 1
423
 
(manage DHCP) and 2 (manage DHCP and DNS).
 
412
Replacing the example values with those required for this network. The
 
413
only non-obvious parameter is 'management' which takes the values 0
 
414
(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
424
415
 
425
416
 
426
417
.. _node-group-interfaces:
 
418
 
427
419
node-group-interfaces
428
420
^^^^^^^^^^^^^^^^^^^^^
429
421
 
438
430
:samp:`-d, --debug`
439
431
 
440
432
   Displays debug information listing the API responses.
441
 
        
 
433
 
442
434
:samp:`-h, --help`
443
435
 
444
436
   Display usage information.
452
444
   Lists the current stored configurations for the given identifier
453
445
   <label> in a key:value format which should be easy to decipher.
454
446
 
455
 
        
456
447
:samp:`new <label> ip=<value> interface=<if_device> [parameters...]`
457
 
              
 
448
 
458
449
   Creates a new interface group. The required parameters are the IP
459
450
   address and the network interface this appies to (e.g. eth0). In
460
451
   order to do anything useful, further parameters are required::
461
452
 
462
 
      management= 0 | 1 | 2 
 
453
      management= 0 | 1 | 2
463
454
           The service to be managed on the interface
464
455
           ( 0= none, 1=DHCP, 2=DHCP and DNS).
465
456
 
466
457
      subnet_mask=<value>
467
458
           Apply the given dotted decimal value as the subnet mask.
468
459
 
469
 
      broadcast_ip=<value> 
 
460
      broadcast_ip=<value>
470
461
           Apply the given dotted decimal value as the
471
462
           broadcast IP address for this subnet.
472
463
 
473
 
      router_ip=<value> 
 
464
      router_ip=<value>
474
465
           Apply the given dotted decimal value as the
475
466
           default router address for this subnet.
476
467
 
481
472
           The highest value of IP address to allocate via DHCP
482
473
 
483
474
 
484
 
 
485
 
 
486
 
tag 
 
475
tag
487
476
^^^
488
 
 
489
 
Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
490
 
  nodes | delete 
 
477
The tag command is used  to manually alter tags, tagged nodes or 
 
478
rebuild the automatic tags. 
 
479
 
 
480
  For more information on how to use them effectively, please see
 
481
  :ref:`deploy-tags`
 
482
 
 
483
Usage: maas-cli <profile> tag read | update-nodes | rebuild 
 
484
| update | nodes | delete
 
485
 
491
486
 
492
487
.. program:: maas-cli tag
493
488
 
494
489
:samp:`read <tag_name>`
495
 
   
 
490
 
496
491
   Returns information on the tag specified by <name>
497
492
 
498
 
:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]`
 
493
:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>]
 
494
[nodegroup=<system_id>]`
499
495
 
500
496
   Applies or removes the given tag from a list of nodes specified by
501
497
   either or both of add="<system_id>" and remove="<system_id>". The
505
501
 
506
502
:samp:`rebuild`
507
503
 
508
 
   Triggers a rebuild of the tag to node mapping. 
509
 
 
510
 
:samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`
511
 
   
 
504
   Triggers a rebuild of the tag to node mapping.
 
505
 
 
506
:samp:`update <tag_name> [name=<value>] | [comment=<value>]|
 
507
[definition=<value>]`
 
508
 
512
509
   Updates the tag identified by tag_name. Any or all of name,comment
513
510
   and definition may be supplied as parameters. If no parameters are
514
511
   supplied, this command returns the current values.
521
518
 
522
519
   Deletes the given tag.
523
520
 
524
 
tags 
525
 
^^^^ 
526
 
Tags are a really useful way of identifying nodes with particular 
527
 
characteristics. 
528
 
 
529
 
.. only:: html For more information on how to use them effectively, please see :ref:`deploy-tags`
 
521
 
 
522
tags
 
523
^^^^
 
524
 
 
525
Tags are a really useful way of identifying nodes with particular
 
526
characteristics.
 
527
 
 
528
.. only:: html
 
529
 
 
530
  For more information on how to use them effectively, please see
 
531
  :ref:`deploy-tags`
530
532
 
531
533
Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
532
 
--insecure] list | new
 
534
--insecure] list | create
533
535
 
534
536
.. program:: maas-cli tag
535
537
 
536
538
:samp:`-d, --debug`
537
539
 
538
540
   Displays debug information listing the API responses.
539
 
        
 
541
 
540
542
:samp:`-h, --help`
541
543
 
542
544
   Display usage information.
543
545
 
544
 
:samp:`-k, --insecure` 
 
546
:samp:`-k, --insecure`
545
547
 
546
548
   Disables the SSL certificate check.
547
549
 
548
550
:samp:`list`
549
 
  
 
551
 
550
552
   Returns a JSON object listing all the current tags known by the MAAS server
551
553
 
552
554
:samp:`create name=<value> definition=<value> [comment=<value>]`
553
555
 
554
556
   Creates a new tag with the given name and definition. A comment is
555
557
   optional. Names must be unique, obviously - an error will be
556
 
   returned if the given name already exists. The definition is in the form of 
557
 
   an XPath expression which parses the XML returned by running ``lshw`` on the 
558
 
   node.
559
 
   
 
558
   returned if the given name already exists. The definition is in the
 
559
   form of an XPath expression which parses the XML returned by
 
560
   running ``lshw`` on the node.
 
561
 
560
562
Example:
561
563
Adding a tag to all nodes which have an Intel GPU::
562
564
 
563
565
   $ maas-cli maas tags new name='intel-gpu' \
564
566
       comment='Machines which have an Intel display driver' \
565
 
       definition='contains(//node[@id="display"]/vendor, "Intel")
566
 
 
567
 
 
568
 
unused commands 
569
 
^^^^^^^^^^^^^^^ 
 
567
       definition='contains(//node[@id="display"]/vendor, "Intel")'
 
568
 
 
569
 
 
570
unused commands
 
571
^^^^^^^^^^^^^^^
 
572
 
570
573
Because the ``maas-cli`` command exposes all of the API, it also lists
571
574
some command options which are not really intended for end users, such
572
575
as the "file" and "boot-images" options.
573
 
 
574