← Back to branch summary

~lutostag/ubuntu/trusty/maas/1.5.4

« back to all changes in this revision

Viewing changes to docs/maascli.rst

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez
  • Date: 2014-02-15 12:08:23 UTC
  • mto: This revision was merged to the branch mainline in revision 48.
  • Revision ID: package-import@ubuntu.com-20140215120823-u7dkitfy0h8tbruh
Tags: upstream-1.5+bzr1948
Import upstream version 1.5+bzr1948

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/maascli.rst
3
3
----------------------
4
4
 
5
5
As well as the web interface, many tasks can be performed by accessing
6
 
the MAAS API directly through the `maas-cli` command. This section
 
6
the MAAS API directly through the `maas` command. This section
7
7
details how to login with this tool and perform some common
8
8
operations.
9
9
 
13
13
Logging in
14
14
----------
15
15
 
16
 
Before the API will accept any commands from maas-cli, you must first
 
16
Before the API will accept any commands from maas, you must first
17
17
login. To do this, you need the API key which can be found in the user
18
18
interface.
19
19
 
31
31
and copy the key (it's quite long!) and then paste it into the
32
32
commandline. The format of the login command is::
33
33
 
34
 
 $ maas-cli login <profile-name> <hostname> <key>
 
34
 $ maas login <profile-name> <hostname> <key>
35
35
 
36
36
The profile created is an easy way of associating your credentials
37
37
with any subsequent call to the API. So an example login might look
38
38
like this::
39
39
 
40
 
 $ maas-cli login maas http://10.98.0.13/MAAS/api/1.0
 
40
 $ maas login maas http://10.98.0.13/MAAS/api/1.0
41
41
 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
42
42
 
43
43
which creates the profile 'maas' and registers it with the given key
51
51
consequently some of the API calls will not be available)
52
52
 
53
53
 
54
 
maas-cli commands
 
54
maas commands
55
55
-----------------
56
56
 
57
 
The ``maas-cli`` command exposes the whole API, so you can do anything
 
57
The ``maas`` command exposes the whole API, so you can do anything
58
58
you actually *can* do with MAAS using this command. Unsurprisingly,
59
59
this leaves us with a vast number of options, but before we delve into
60
60
detail on the specifics, here is a sort of 'cheat-sheet' for common
61
 
tasks you might want to do using ``maas-cli``.
 
61
tasks you might want to do using ``maas``.
62
62
 
63
63
  *  :ref:`Configure DHCP and DNS services <cli-dhcp>`
64
64
 
66
66
 
67
67
  *  :ref:`Setting IPMI power parameters for a node <cli-power>`
68
68
 
69
 
The main maas-cli commands are:
 
69
The main maas commands are:
70
70
 
71
 
.. program:: maas-cli
 
71
.. program:: maas
72
72
 
73
73
:samp:`list`
74
74
 
92
92
 
93
93
:samp:`<profile> [command] [options] ...`
94
94
 
95
 
  Using the given profile name instructs ``maas-cli`` to direct the
 
95
  Using the given profile name instructs ``maas`` to direct the
96
96
  subsequent commands and options to the relevant MAAS, which for the
97
97
  current API are detailed below...
98
98
 
102
102
This command is used for creating and destroying the
103
103
MAAS authorisation tokens associated with a profile.
104
104
 
105
 
Usage: maas-cli *<profile>* account [-d --debug] [-h --help]
 
105
Usage: maas *<profile>* account [-d --debug] [-h --help]
106
106
create-authorisation-token | delete-authorisation-token [token_key=\
107
107
*<value>*]
108
108
 
109
 
.. program:: maas-cli account
 
109
.. program:: maas account
110
110
 
111
111
:samp:`-d, --debug`
112
112
 
144
144
API calls which operate on individual nodes. With these commands, the
145
145
node is always identified by its "system_id" property - a unique tag
146
146
allocated at the time of enlistment. To discover the value of the
147
 
system_id, you can use the ``maas-cli <profile> nodes list`` command.
 
147
system_id, you can use the ``maas <profile> nodes list`` command.
148
148
 
149
 
USAGE: maas-cli <profile> node [-h] release | start | stop | delete |
 
149
USAGE: maas <profile> node [-h] release | start | stop | delete |
150
150
read | update <system_id>
151
151
 
152
 
.. program:: maas-cli node
 
152
.. program:: maas node
153
153
 
154
154
:samp:`-h, --help`
155
155
 
211
211
 
212
212
Example: Setting the power parameters for an ipmi enabled node::
213
213
 
214
 
  maas-cli maas node update <system_id> \
 
214
  maas maas node update <system_id> \
215
215
    power_type="ipmi" \
216
216
    power_parameters_power_address=192.168.22.33 \
217
217
    power_parameters_power_user=root \
221
221
nodes
222
222
^^^^^
223
223
 
224
 
Usage: maas-cli <profile> nodes [-h] is-registered | list-allocated |
 
224
Usage: maas <profile> nodes [-h] is-registered | list-allocated |
225
225
acquire | list | accept | accept-all | new | check-commissioning
226
226
 
227
 
.. program:: maas-cli nodes
 
227
.. program:: maas nodes
228
228
 
229
229
:samp:`-h, --help`
230
230
 
286
286
Examples:
287
287
Accept and commission all discovered nodes::
288
288
 
289
 
 $ maas-cli maas nodes accept-all
 
289
 $ maas maas nodes accept-all
290
290
 
291
291
List all known nodes::
292
292
 
293
 
 $ maas-cli maas nodes list
 
293
 $ maas maas nodes list
294
294
 
295
295
Filter the list using specific key/value pairs::
296
296
 
297
 
 $ maas-cli maas nodes list architecture="i386/generic"
 
297
 $ maas maas nodes list architecture="i386/generic"
298
298
 
299
299
 
300
300
node-groups
301
301
^^^^^^^^^^^
302
 
Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
 
302
Usage: maas <profile> node-groups [-d --debug] [-h --help] [-k
303
303
--insecure] register | list | refresh-workers | accept | reject
304
304
 
305
 
.. program:: maas-cli node-groups
 
305
.. program:: maas node-groups
306
306
 
307
307
:samp:`-d, --debug`
308
308
 
353
353
^^^^^^^^^^^^^^^^^^^^
354
354
For managing the interfaces. See also :ref:`node-group-interfaces`
355
355
 
356
 
Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
 
356
Usage: maas *<profile>* node-group-interfaces [-d --debug] [-h
357
357
--help] [-k --insecure] read | update | delete [parameters...]
358
358
 
359
 
..program:: maas-cli node-group-interface
 
359
..program:: maas node-group-interface
360
360
 
361
361
:samp:`read <uuid> <interface>`
362
362
 
401
401
interface information. To do this we need to first determine the UUID of the
402
402
node group affected::
403
403
 
404
 
 $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)
 
404
 $ uuid=$(maas <profile> node-groups list | grep uuid | cut -d\" -f4)
405
405
 
406
406
Once we have the UUID we can use this to update the node-group-interface for
407
407
that nodegroup, and pass it the relevant interface details::
408
408
 
409
 
 $ maas-cli <profile> node-group-interface update $uuid eth0 \
 
409
 $ maas <profile> node-group-interface update $uuid eth0 \
410
410
         ip_range_high=192.168.123.200    \
411
411
         ip_range_low=192.168.123.100     \
412
412
         management=2                     \
426
426
The node-group-interfaces commands are used for configuring the
427
427
management of DHCP and DNS services where these are managed by MAAS.
428
428
 
429
 
Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
 
429
Usage: maas *<profile>* node-group-interfaces [-d --debug] [-h
430
430
--help] [-k --insecure] list | new [parameters...]
431
431
 
432
 
.. program:: maas-cli node-group-interfaces
 
432
.. program:: maas node-group-interfaces
433
433
 
434
434
:samp:`-d, --debug`
435
435
 
484
484
  For more information on how to use them effectively, please see
485
485
  :ref:`deploy-tags`
486
486
 
487
 
Usage: maas-cli <profile> tag read | update-nodes | rebuild 
 
487
Usage: maas <profile> tag read | update-nodes | rebuild 
488
488
| update | nodes | delete
489
489
 
490
490
 
491
 
.. program:: maas-cli tag
 
491
.. program:: maas tag
492
492
 
493
493
:samp:`read <tag_name>`
494
494
 
534
534
  For more information on how to use them effectively, please see
535
535
  :ref:`deploy-tags`
536
536
 
537
 
Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
 
537
Usage: maas <profile> tag [-d --debug] [-h --help] [-k
538
538
--insecure] list | create
539
539
 
540
 
.. program:: maas-cli tag
 
540
.. program:: maas tag
541
541
 
542
542
:samp:`-d, --debug`
543
543
 
566
566
Example:
567
567
Adding a tag to all nodes which have an Intel GPU::
568
568
 
569
 
   $ maas-cli maas tags new name='intel-gpu' \
 
569
   $ maas maas tags new name='intel-gpu' \
570
570
       comment='Machines which have an Intel display driver' \
571
571
       definition='contains(//node[@id="display"]/vendor, "Intel")'
572
572
 
574
574
unused commands
575
575
^^^^^^^^^^^^^^^
576
576
 
577
 
Because the ``maas-cli`` command exposes all of the API, it also lists
 
577
Because the ``maas`` command exposes all of the API, it also lists
578
578
some command options which are not really intended for end users, such
579
579
as the "file" and "boot-images" options.