Merge lp:~allenap/maas/docs-and-man-tidy into lp:maas

Proposed by Gavin Panella
Status: Merged
Approved by: Gavin Panella
Approved revision: 1361
Merged at revision: 1357
Proposed branch: lp:~allenap/maas/docs-and-man-tidy
Merge into: lp:maas
Prerequisite: lp:~evilnick/maas/rm-import-pxe-references
Diff against target: 1491 lines (+382/-265)
14 files modified
.bzrignore (+1/-2)
INSTALL.txt (+120/-50)
Makefile (+3/-5)
docs/about.rst (+24/-8)
docs/configure.rst (+9/-3)
docs/index.rst (+9/-5)
docs/juju-quick-start.rst (+0/-2)
docs/maascli.rst (+84/-88)
docs/man/maas-cli.8.rst (+6/-5)
docs/man/maas.8.rst (+13/-9)
docs/nodes.rst (+22/-13)
docs/orientation.rst (+33/-16)
docs/tags.rst (+37/-42)
docs/troubleshooting.rst (+21/-17)
To merge this branch: bzr merge lp:~allenap/maas/docs-and-man-tidy
Reviewer Review Type Date Requested Status
Nick Veitch (community) Approve
Julian Edwards (community) Approve
Review via email: mp+135248@code.launchpad.net

Commit message

Wrap and tidy documentation, and address many doc generation errors.

To post a comment you must log in.
Revision history for this message
Julian Edwards (julian-edwards) wrote :

Looks pretty mechanical, so approving on that basis.

review: Approve
Revision history for this message
Nick Veitch (evilnick) wrote :

I think this looks okay. The only thing that worries me slightly is that references and some of the directives don't work if you break the lines, but I guess you have checked the output

review: Approve
Revision history for this message
Gavin Panella (allenap) wrote :

On 21 November 2012 09:08, Nick Veitch <email address hidden> wrote:
> Review: Approve
>
> I think this looks okay. The only thing that worries me slightly is
> that references and some of the directives don't work if you break
> the lines, ...

Gah, really? I half remember that now you mention it.

> but I guess you have checked the output

Oh... yeeees, yes, of course.

/me scuttles to check output some more

Revision history for this message
Gavin Panella (allenap) wrote :

To sanity check things, I've used the following to compare the docs
generated in trunk to those generated in this branch:

  for file in docs/_build/html/*.html
  do
    echo === $file
    diff -u <(hxnormalize ../trunk/$file) <(hxnormalize $file)
  done

(hxnormalize comes from the html-xml-utils package.)

lp:~allenap/maas/docs-and-man-tidy updated
1361. By Gavin Panella

Merge trunk, resolving conflicts.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file '.bzrignore'
2--- .bzrignore 2012-11-20 16:45:09 +0000
3+++ .bzrignore 2012-11-21 11:51:34 +0000
4@@ -10,7 +10,6 @@
5 ./acceptance/source
6 ./bin
7 ./build
8-./celerybeat-schedule
9 ./db
10 ./develop-eggs
11 ./dist
12@@ -22,6 +21,7 @@
13 ./lib
14 ./local
15 ./logs/*
16+./man
17 ./media/demo/*
18 ./media/development
19 ./parts
20@@ -31,4 +31,3 @@
21 ./TAGS
22 ./tags
23 dropin.cache
24-./man
25
26=== modified file 'INSTALL.txt'
27--- INSTALL.txt 2012-11-20 16:45:09 +0000
28+++ INSTALL.txt 2012-11-21 11:51:34 +0000
29@@ -1,16 +1,18 @@
30 .. -*- mode: rst -*-
31
32-
33+
34 Installing MAAS
35 ===============
36
37 There are two main ways to install MAAS
38
39- * :ref:`From Ubuntu's package archive on an existing Ubuntu install. <pkg-install>`
40- * :ref:`As a fresh install from Ubuntu Server install media. <disc-install>`
41-
42+ * :ref:`From Ubuntu's package archive on an existing Ubuntu
43+ install. <pkg-install>`
44+ * :ref:`As a fresh install from Ubuntu Server install
45+ media. <disc-install>`
46
47-If you are interested in testing the latest development version you can also check out the very latest source and build MAAS yourself.
48+If you are interested in testing the latest development version you
49+can also check out the very latest source and build MAAS yourself.
50
51
52 .. _pkg-install:
53@@ -18,17 +20,34 @@
54 Installing MAAS from the archive
55 --------------------------------
56
57-Installing MAAS from packages is thankfully straightforward. There are actually several packages that go into making up a working MAAS install, but for convenience, many of these have been gathered into a virtual package called 'maas' which will install the necessary components for a 'seed cloud', that is a single server that will directly control a group of nodes. The main packages are:
58+Installing MAAS from packages is thankfully straightforward. There are
59+actually several packages that go into making up a working MAAS
60+install, but for convenience, many of these have been gathered into a
61+virtual package called 'maas' which will install the necessary
62+components for a 'seed cloud', that is a single server that will
63+directly control a group of nodes. The main packages are:
64
65- * ``maas`` - seed cloud setup, which includes both the region controller and the cluster controller below.
66+ * ``maas`` - seed cloud setup, which includes both the region
67+ controller and the cluster controller below.
68 * ``maas-region-controller`` - includes the web UI, API and database.
69- * ``maas-cluster-controller`` - controls a group ("cluster") of nodes including DHCP management.
70+ * ``maas-cluster-controller`` - controls a group ("cluster") of nodes
71+ including DHCP management.
72 * ``maas-dhcp``/``maas-dns`` - required when managing dhcp/dns.
73
74-If you need to separate these services or want to deploy an additional cluster controller, you should install the corresponding packages individually (see :ref:`the description of a typical setup <setup>` for more background on how a typical hardware setup might be arranged).
75-
76-There are two suggested additional packages 'maas-dhcp' and 'maas-dns'. These set up MAAS-controlled DHCP and DNS services which greatly simplify deployment if you are running a typical setup where the MAAS controller can run the network (Note: These **must** be installed if you later set the options in the web interface to have MAAS manage DHCP/DNS). If you need to integrate your MAAS setup under an existing DHCP setup, see :ref:`manual-dhcp`
77-
78+If you need to separate these services or want to deploy an additional
79+cluster controller, you should install the corresponding packages
80+individually (see :ref:`the description of a typical setup <setup>`
81+for more background on how a typical hardware setup might be
82+arranged).
83+
84+There are two suggested additional packages 'maas-dhcp' and
85+'maas-dns'. These set up MAAS-controlled DHCP and DNS services which
86+greatly simplify deployment if you are running a typical setup where
87+the MAAS controller can run the network (Note: These **must** be
88+installed if you later set the options in the web interface to have
89+MAAS manage DHCP/DNS). If you need to integrate your MAAS setup under
90+an existing DHCP setup, see :ref:`manual-dhcp`
91+
92
93 Install packages
94 ^^^^^^^^^^^^^^^^
95@@ -37,83 +56,118 @@
96
97 $ sudo apt-get install maas maas-dhcp maas-dns
98
99-You will see a list of packages and a confirmation message to proceed. The exact list will obviously depend on what you already have installed on your server, but expect to add about 200MB of files.
100+You will see a list of packages and a confirmation message to
101+proceed. The exact list will obviously depend on what you already have
102+installed on your server, but expect to add about 200MB of files.
103
104-The configuration for the MAAS controller will automatically run and pop up this config screen:
105+The configuration for the MAAS controller will automatically run and
106+pop up this config screen:
107
108 .. image:: media/install_cluster-config.*
109
110-Here you will need to enter the hostname for where the region controller can be contacted. In many scenarios, you may be running the region controller (i.e. the web and API interface) from a different network address, for example where a server has several network interfaces.
111+Here you will need to enter the hostname for where the region
112+controller can be contacted. In many scenarios, you may be running the
113+region controller (i.e. the web and API interface) from a different
114+network address, for example where a server has several network
115+interfaces.
116
117-Once the configuration scripts have run you should see this message telling you that the system is ready to use:
118+Once the configuration scripts have run you should see this message
119+telling you that the system is ready to use:
120
121 .. image:: media/install_controller-config.*
122
123-The web server is started last, so you have to accept this message before the service is run and you can access the Web interface. Then there are just a few more setup steps :ref:`post_install`
124+The web server is started last, so you have to accept this message
125+before the service is run and you can access the Web interface. Then
126+there are just a few more setup steps :ref:`post_install`
127+
128
129 .. _disc-install:
130
131 Installing MAAS from Ubuntu Server boot media
132 ---------------------------------------------
133
134-If you are installing MAAS as part of a fresh install it is easiest to choose the "Multiple Server install with MAAS" option from the installer and have pretty much everything set up for you.
135-Boot from the Ubuntu Server media and you will be greeted with the usual language selection screen:
136+If you are installing MAAS as part of a fresh install it is easiest to
137+choose the "Multiple Server install with MAAS" option from the
138+installer and have pretty much everything set up for you. Boot from
139+the Ubuntu Server media and you will be greeted with the usual
140+language selection screen:
141
142 .. image:: media/install_01.*
143
144-On the next screen, you will see there is an entry in the menu called "Multiple server install with MAAS". Use the cursor keys to select this and then press Enter.
145+On the next screen, you will see there is an entry in the menu called
146+"Multiple server install with MAAS". Use the cursor keys to select
147+this and then press Enter.
148
149 .. image:: media/install_02.*
150
151-The installer then runs through the usual language and keyboard options. Make your selections using Tab/Cursor keys/Enter to proceed through the install.
152-The installer will then load various drivers, which may take a moment or two.
153+The installer then runs through the usual language and keyboard
154+options. Make your selections using Tab/Cursor keys/Enter to proceed
155+through the install. The installer will then load various drivers,
156+which may take a moment or two.
157
158 .. image:: media/install_03.*
159
160-The next screen asks for the hostname for this server. Choose something appropriate for your network.
161-
162+The next screen asks for the hostname for this server. Choose
163+something appropriate for your network.
164
165 .. image:: media/install_04.*
166
167-Finally we get to the MAAS part! Here there are just two options. We want to "Create a new MAAS on this server" so go ahead and choose that one.
168+Finally we get to the MAAS part! Here there are just two options. We
169+want to "Create a new MAAS on this server" so go ahead and choose that
170+one.
171
172 .. image:: media/install_05.*
173
174-The install now continues as usual. Next you will be prompted to enter a username. This will be the admin user for the actual server that MAAS will be running on (not the same as the MAAS admin user!)
175+The install now continues as usual. Next you will be prompted to enter
176+a username. This will be the admin user for the actual server that
177+MAAS will be running on (not the same as the MAAS admin user!)
178
179 .. image:: media/install_06.*
180
181-As usual you will have the chance to encrypt your home directory. Continue to make selections based on whatever settings suit your usage.
182+As usual you will have the chance to encrypt your home
183+directory. Continue to make selections based on whatever settings suit
184+your usage.
185
186 .. image:: media/install_07.*
187
188-After making selections and partitioning storage, the system software will start to be installed. This part should only take a few minutes.
189+After making selections and partitioning storage, the system software
190+will start to be installed. This part should only take a few minutes.
191
192 .. image:: media/install_09.*
193
194-Various packages will now be configured, including the package manager and update manager. It is important to set these up appropriately so you will receive timely updates of the MAAS server software, as well as other essential services that may run on this server.
195+Various packages will now be configured, including the package manager
196+and update manager. It is important to set these up appropriately so
197+you will receive timely updates of the MAAS server software, as well
198+as other essential services that may run on this server.
199
200 .. image:: media/install_10.*
201
202-The configuration for MAAS will ask you to configure the host address of the server. This should be the IP address you will use to connect to the server (you may have additional interfaces e.g. to run node subnets)
203+The configuration for MAAS will ask you to configure the host address
204+of the server. This should be the IP address you will use to connect
205+to the server (you may have additional interfaces e.g. to run node
206+subnets)
207
208 .. image:: media/install_cluster-config.*
209
210-The next screen will confirm the web address that will be used to the web interface.
211+The next screen will confirm the web address that will be used to the
212+web interface.
213
214 .. image:: media/install_controller-config.*
215
216-After configuring any other packages the installer will finally come to and end. At this point you should eject the boot media.
217+After configuring any other packages the installer will finally come
218+to and end. At this point you should eject the boot media.
219
220 .. image:: media/install_14.*
221
222-After restarting, you should be able to login to the new server with the information you supplied during the install. The MAAS software will run automatically.
223-
224+After restarting, you should be able to login to the new server with
225+the information you supplied during the install. The MAAS software
226+will run automatically.
227
228 .. image:: media/install_15.*
229
230-
231-**NOTE:** The maas-dhcp and maas-dns packages are not installed by default. If you want to have MAAS run DHCP and DNS services, you should install these packages::
232+**NOTE:** The maas-dhcp and maas-dns packages are not installed by
233+default. If you want to have MAAS run DHCP and DNS services, you
234+should install these packages::
235
236 $ sudo apt-get install maas-dhcp maas-dns
237
238@@ -121,13 +175,19 @@
239
240 .. _post_install:
241
242+
243 Post-Install tasks
244 ==================
245-If you now use a web browser to connect to the region controller, you should see that MAAS is running, but there will also be some errors on the screen:
246+
247+If you now use a web browser to connect to the region controller, you
248+should see that MAAS is running, but there will also be some errors on
249+the screen:
250
251 .. image:: media/install_web-init.*
252
253-The on screen messages will tell you that there are no boot images present, and that you can't login because there is no admin user.
254+The on screen messages will tell you that there are no boot images
255+present, and that you can't login because there is no admin user.
256+
257
258 Create a superuser account
259 --------------------------
260@@ -137,29 +197,37 @@
261
262 $ sudo maas createsuperuser
263
264-Follow the prompts to create the account which you will need to login to the web interface. Unless you have a special need, it is best to accept the default login name of `root`, as it is rather annoying if you forget the username (although you can simply run this command again to create a new superuser).
265+Follow the prompts to create the account which you will need to login
266+to the web interface. Unless you have a special need, it is best to
267+accept the default login name of `root`, as it is rather annoying if
268+you forget the username (although you can simply run this command
269+again to create a new superuser).
270
271
272 Import the boot images
273 ----------------------
274
275 MAAS will check for and download new Ubuntu images once a week.
276-However, you'll need to download them manually the first time. To do this you will need to
277-connect to the MAAS API using the maas-cli tool. (see :ref:`api_key` for details of logging
278-in).
279-Then you need to run the command::
280+However, you'll need to download them manually the first time. To do
281+this you will need to connect to the MAAS API using the maas-cli
282+tool. (see :ref:`Logging in <api-key>` for details). Then you need to
283+run the command::
284
285 $ maas-cli maas node-groups import-boot-images
286
287-(substitute in a different profile name for 'maas' if you have called yours something else)
288-This will initiate downloading the required image files. Note that this may take some time
289-depending on your network connection.
290+(substitute in a different profile name for 'maas' if you have called
291+yours something else) This will initiate downloading the required
292+image files. Note that this may take some time depending on your
293+network connection.
294
295
296 Login to the server
297 -------------------
298
299-To check that everything is working properly, you should try and login to the server now. Both the error messages should have gone (it can take a few minutes for the boot image files to register) and you can see that there are currently 0 nodes attached to this controller.
300+To check that everything is working properly, you should try and login
301+to the server now. Both the error messages should have gone (it can
302+take a few minutes for the boot image files to register) and you can
303+see that there are currently 0 nodes attached to this controller.
304
305 .. image:: media/install-login.*
306
307@@ -167,7 +235,9 @@
308 Configure DHCP
309 --------------
310
311-If you are using MAAS to control DHCP, you need to set this via the web interface.
312-However, if you are manually configuring a DHCP server, you should take a look at :ref:`manual-dhcp`
313+If you are using MAAS to control DHCP, you need to set this via the
314+web interface. However, if you are manually configuring a DHCP
315+server, you should take a look at :ref:`manual-dhcp`
316
317-Once everything is set up and running, you are ready to :doc:`start enlisting nodes <nodes>`
318+Once everything is set up and running, you are ready to :doc:`start
319+enlisting nodes <nodes>`
320
321=== modified file 'Makefile'
322--- Makefile 2012-11-21 10:26:41 +0000
323+++ Makefile 2012-11-21 11:51:34 +0000
324@@ -153,13 +153,13 @@
325 $(MAKE) -C acceptance $@
326 find . -type f -name '*.py[co]' -print0 | xargs -r0 $(RM)
327 find . -type f -name '*~' -print0 | xargs -r0 $(RM)
328+ find . -type f -name dropin.cache -print0 | xargs -r0 $(RM)
329 $(RM) -r media/demo/* media/development
330 $(RM) $(js_enums)
331 $(RM) *.log
332- $(RM) celerybeat-schedule
333 $(RM) docs/api.rst
334- $(RM) -r docs/_autosummary
335- $(RM) -r man/
336+ $(RM) -r docs/_autosummary docs/_build
337+ $(RM) -r man
338
339 distclean: clean stop
340 $(RM) -r bin include lib local
341@@ -167,9 +167,7 @@
342 $(RM) -r build dist logs/* parts
343 $(RM) tags TAGS .installed.cfg
344 $(RM) -r *.egg *.egg-info src/*.egg-info
345- $(RM) -r docs/_build
346 $(RM) -r run/* services/*/supervise
347- $(RM) twisted/plugins/dropin.cache
348
349 harness: bin/maas bin/database
350 $(dbrun) bin/maas shell --settings=maas.demo
351
352=== modified file 'docs/about.rst'
353--- docs/about.rst 2012-10-03 20:16:24 +0000
354+++ docs/about.rst 2012-11-21 11:51:34 +0000
355@@ -1,19 +1,35 @@
356 About this documentation
357 ========================
358
359-This is the documentation for Canonical's MAAS software. If you aren't sure what that is, you should probably skip everything else and head straight to the :ref:`orientation` section where it is explained.
360-Like any software though, it can be frustrating if you don't know how bits of it work, how to achieve certain goals or what to do when things go wrong. Amongst its various sections, this manual aims to answer all those questions and plenty more you haven't even thought of yet.
361+This is the documentation for Canonical's MAAS software. If you aren't
362+sure what that is, you should probably skip everything else and head
363+straight to the :ref:`orientation` section where it is explained.
364+Like any software though, it can be frustrating if you don't know how
365+bits of it work, how to achieve certain goals or what to do when
366+things go wrong. Amongst its various sections, this manual aims to
367+answer all those questions and plenty more you haven't even thought of
368+yet.
369+
370
371 Getting it
372 ----------
373
374-In a cunning move, the current documentation always lives, and is built from, the main MAAS source code. That means that whatever MAAS package you have installed, or even if you are really living life on the edge and have checked out a development version from Launchpad, this documentation should be the latest and most appropriate version for the software you are running.
375-However, it is also possible that there have been further sections or more helpful, or clearer bits added since the package you are using was made. For this reason you can always find the latest documentation online here: http://maas.ubuntu.com
376+In a cunning move, the current documentation always lives, and is
377+built from, the main MAAS source code. That means that whatever MAAS
378+package you have installed, or even if you are really living life on
379+the edge and have checked out a development version from Launchpad,
380+this documentation should be the latest and most appropriate version
381+for the software you are running. However, it is also possible that
382+there have been further sections or more helpful, or clearer bits
383+added since the package you are using was made. For this reason you
384+can always find the latest documentation online here:
385+http://maas.ubuntu.com
386+
387
388 Contributing
389 ------------
390
391-If you have some extra information to add, or think you have spotted an error or something out of date, we really want to hear about it. File a bug report or contact us via the MAAS homepage at http://maas.ubuntu.com
392-
393-
394-
395+If you have some extra information to add, or think you have spotted
396+an error or something out of date, we really want to hear about
397+it. File a bug report or contact us via the MAAS homepage at
398+http://maas.ubuntu.com
399
400=== modified file 'docs/configure.rst'
401--- docs/configure.rst 2012-10-03 20:16:24 +0000
402+++ docs/configure.rst 2012-11-21 11:51:34 +0000
403@@ -1,14 +1,19 @@
404 Additional Configuration
405 ========================
406
407+
408 .. _manual-dhcp:
409
410 Manual DHCP configuration
411 -------------------------
412
413-There are some circumstances under which you may not wish the master MAAS worker to handle DHCP for the network. In these instances, the existing DHCP server for the network will need its configuration altered to allow MAAS to enlist and control nodes automatically.
414+There are some circumstances under which you may not wish the master
415+MAAS worker to handle DHCP for the network. In these instances, the
416+existing DHCP server for the network will need its configuration
417+altered to allow MAAS to enlist and control nodes automatically.
418
419-At the very least the next-server should point to the MAAS controller host address and the filename should be set to pxelinux.0
420+At the very least the next-server should point to the MAAS controller
421+host address and the filename should be set to pxelinux.0
422
423 The configuration entry may look something like this::
424
425@@ -21,7 +26,9 @@
426 range dynamic-bootp 192.168.122.5 192.168.122.135;
427 }
428
429+
430 .. _ssl:
431+
432 SSL Support
433 -----------
434
435@@ -43,4 +50,3 @@
436 the default SSL certificate is insecure. Please generate your own and then
437 edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the
438 certificate.
439-
440
441=== modified file 'docs/index.rst'
442--- docs/index.rst 2012-10-16 14:54:36 +0000
443+++ docs/index.rst 2012-11-21 11:51:34 +0000
444@@ -4,12 +4,12 @@
445 Metal As A Service: MAAS
446 ########################
447
448-
449 This is the documentation for the MAAS project http://maas.ubuntu.com
450
451+
452 ************
453 Introduction
454-************
455+************
456
457 .. toctree::
458 :maxdepth: 2
459@@ -17,6 +17,7 @@
460 about
461 orientation
462
463+
464 ***************
465 Getting started
466 ***************
467@@ -27,7 +28,7 @@
468 install
469 configure
470 nodes
471-
472+
473
474 ******************
475 Deploying services
476@@ -38,7 +39,8 @@
477
478 juju-quick-start
479 tags
480-
481+
482+
483 ******************************
484 Using the maas-cli commandline
485 ******************************
486@@ -48,6 +50,7 @@
487
488 maascli
489
490+
491 **********
492 Appendices
493 **********
494@@ -56,11 +59,12 @@
495 :maxdepth: 2
496
497 troubleshooting
498- hacking
499+ hacking
500 api
501 models
502 enum
503
504+
505 Indices and tables
506 ==================
507
508
509=== modified file 'docs/juju-quick-start.rst'
510--- docs/juju-quick-start.rst 2012-08-16 11:56:16 +0000
511+++ docs/juju-quick-start.rst 2012-11-21 11:51:34 +0000
512@@ -156,5 +156,3 @@
513 Note that each charm runs on its own host, so each deployment will
514 actually take as long as it took to bootstrap. Have a beer, drown your
515 sorrows in liquor, or, my preference, have another cup of tea.
516-
517-----
518
519=== modified file 'docs/maascli.rst'
520--- docs/maascli.rst 2012-11-13 11:30:52 +0000
521+++ docs/maascli.rst 2012-11-21 11:51:34 +0000
522@@ -1,9 +1,9 @@
523-
524 As well as the web interface, many tasks can be performed by accessing
525 the MAAS API directly through the maas-cli command. This section
526 details how to login with this tool and perform some common
527 operations.
528
529+
530 .. _api-key:
531
532 Logging in
533@@ -19,8 +19,9 @@
534 .. only:: html
535 .. image:: media/maascli-prefs.*
536
537-A new page will load...
538+A new page will load...
539
540+.. only:: html
541 .. image:: media/maascli-key.*
542
543 The very first item is a list of MAAS keys. One will have already been
544@@ -30,21 +31,21 @@
545
546 $ maas-cli login <profile-name> <hostname> <key>
547
548-The profile created is an easy way of associating your credentials with any
549-subsequent call to the API. So an example login might look like this::
550+The profile created is an easy way of associating your credentials
551+with any subsequent call to the API. So an example login might look
552+like this::
553
554 $ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
555
556-which creates the profile 'maas' and registers it with the given key at the
557-specified API endpoint.
558-If you omit the credentials, they will be prompted for in the console. It is
559-also possible to use a hyphen, '-' in place of the credentials. In this case a
560-single line will be read from stdin, stripped of any whitespace and used as the
561-credentials, which can be useful if you are devolping scripts for specific
562-tasks.
563-If an empty string is passed instead of the credentials, the profile will be
564-logged in anonymously (and consequently some of the API calls will not be
565-available)
566+which creates the profile 'maas' and registers it with the given key
567+at the specified API endpoint. If you omit the credentials, they will
568+be prompted for in the console. It is also possible to use a hyphen,
569+'-' in place of the credentials. In this case a single line will be
570+read from stdin, stripped of any whitespace and used as the
571+credentials, which can be useful if you are devolping scripts for
572+specific tasks. If an empty string is passed instead of the
573+credentials, the profile will be logged in anonymously (and
574+consequently some of the API calls will not be available)
575
576
577 maas-cli commands
578@@ -76,7 +77,7 @@
579 Logs in to the MAAS controller API at the given URL, using the key
580 provided and associates this connection with the given profile name.
581
582-:samp:`logout <profile>`
583+:samp:`logout <profile>`
584
585 Logs out from the given profile, flushing the stored credentials.
586
587@@ -107,12 +108,12 @@
588 :samp:`-d, --debug`
589
590 Displays debug information listing the API responses.
591-
592+
593 :samp:`-h, --help`
594
595 Display usage information.
596
597-:samp:`-k, --insecure`
598+:samp:`-k, --insecure`
599
600 Disables the SSL certificate check.
601
602@@ -126,8 +127,6 @@
603 Removes the given key from the list of authorisation tokens.
604
605
606-
607-
608 .. boot-images - not useful in user context
609 .. ^^^^^^^^^^^
610
611@@ -158,51 +157,50 @@
612 Releases the node given by *<system_id>*
613
614 :samp:`start <system_id>`
615-
616+
617 Powers up the node identified by *<system_id>* (where MAAS has
618 information for power management for this node).
619
620 :samp:`stop <system_id>`
621-
622+
623 Powers off the node identified by *<system_id>* (where MAAS has
624 information for power management for this node).
625
626 :samp:`delete <system_id>`
627-
628+
629 Removes the given node from the MAAS database.
630
631 :samp:`read <system_id>`
632-
633+
634 Returns all the current known information about the node specified
635 by *<system_id>*
636
637 :samp:`update <system_id> [parameters...]`
638-
639+
640 Used to change or set specific values for the node. The valid
641 parameters are listed below::
642
643 hostname=<value>
644 The new hostname for this node.
645
646- architecture=<value>
647+ architecture=<value>
648 Sets the architecture type, where <value>
649 is a string containing a valid architecture type,
650 e.g. "i386/generic"
651
652- power_type=<value>
653- Apply the given dotted decimal value as the broadcast IP address
654+ power_type=<value>
655+ Apply the given dotted decimal value as the broadcast IP address
656 for this subnet.
657
658- power_parameters_{param1}... =<value>
659- Set the given power parameters. Note that the valid options for these
660+ power_parameters_{param1}... =<value>
661+ Set the given power parameters. Note that the valid options for these
662 depend on the power type chosen.
663
664- power_parameters_skip_check 'true' | 'false'
665- Whether to sanity check the supplied parameters against this node's
666+ power_parameters_skip_check 'true' | 'false'
667+ Whether to sanity check the supplied parameters against this node's
668 declared power type. The default is 'false'.
669
670
671-
672 .. _cli-power:
673
674 Example: Setting the power parameters for an ipmi enabled node::
675@@ -214,8 +212,6 @@
676 power_parameters_power_pass=ubuntu;
677
678
679-
680-
681 nodes
682 ^^^^^
683
684@@ -295,7 +291,6 @@
685 $ maas-cli maas nodes list architecture="i386/generic"
686
687
688-
689 node-groups
690 ^^^^^^^^^^^
691 Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
692@@ -306,7 +301,7 @@
693 :samp:`-d, --debug`
694
695 Displays debug information listing the API responses.
696-
697+
698 :samp:`-h, --help`
699
700 Display usage information.
701@@ -316,7 +311,7 @@
702 Disables the SSL certificate check.
703
704 :samp:`register uuid=<value> name=<value> interfaces=<json_string>`
705-
706+
707 Registers a new node group with the given name and uuid. The
708 interfaces parameter must be supplied in the form of a JSON string
709 comprising the key/value data for the interface to be used, for
710@@ -327,7 +322,7 @@
711
712 :samp:`list`
713
714- Returns a JSON list of all currently defined node groups.
715+ Returns a JSON list of all currently defined node groups.
716
717 :samp:`refresh_workers`
718
719@@ -338,7 +333,7 @@
720 nodes.
721
722 :samp:`accept <uuid>`
723-
724+
725 Accepts a node-group or number of nodegroups indicated by the
726 supplied UUID
727
728@@ -348,10 +343,9 @@
729 supplied UUID
730
731
732-
733 node-group-interface
734 ^^^^^^^^^^^^^^^^^^^^
735-For managing the interfaces. See also :ref:`node_group_interfaces`
736+For managing the interfaces. See also :ref:`node-group-interfaces`
737
738 Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
739 --help] [-k --insecure] read | update | delete [parameters...]
740@@ -359,50 +353,50 @@
741 ..program:: maas-cli node-group-interface
742
743 :samp:`read <uuid> <interface>`
744-
745+
746 Returns the current settings for the given UUID and interface
747
748 :samp:`update [parameters]`
749-
750+
751 Changes the settings for the interface according to the given
752 parameters::
753
754 management= 0 | 1 | 2
755- The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
756+ The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
757 and DNS).
758
759 subnet_mask=<value>
760 Apply the given dotted decimal value as the subnet mask.
761
762 broadcast_ip=<value>
763- Apply the given dotted decimal value as the broadcast IP address for
764+ Apply the given dotted decimal value as the broadcast IP address for
765 this subnet.
766
767 router_ip=<value>
768- Apply the given dotted decimal value as the default router address
769+ Apply the given dotted decimal value as the default router address
770 for this subnet.
771
772 ip_range_low=<value>
773 The lowest value of IP address to allocate via DHCP
774
775 ip_range_high=<value>
776- The highest value of IP address to allocate via DHCP
777+ The highest value of IP address to allocate via DHCP
778
779 :samp:`delete <uuid> <interface>`
780
781 Removes the entry for the given UUID and interface.
782-
783+
784 .. _cli-dhcp:
785
786 Example:
787 Configuring DHCP and DNS.
788
789-To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
790+To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
791 interface information. To do this we need to first determine the UUID of the
792 node group affected::
793
794 $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)
795-
796+
797 Once we have the UUID we can use this to update the node-group-interface for
798 that nodegroup, and pass it the relevant interface details::
799
800@@ -413,12 +407,13 @@
801 broadcast_ip=192.168.123.255 \
802 router_ip=192.168.123.1 \
803
804-Replacing the example values with those required for this network. The only
805-non-obvious parameter is 'management' which takes the values 0 (no management), 1
806-(manage DHCP) and 2 (manage DHCP and DNS).
807-
808-
809-.. _node-group-interfaces
810+Replacing the example values with those required for this network. The
811+only non-obvious parameter is 'management' which takes the values 0
812+(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
813+
814+
815+.. _node-group-interfaces:
816+
817 node-group-interfaces
818 ^^^^^^^^^^^^^^^^^^^^^
819
820@@ -433,7 +428,7 @@
821 :samp:`-d, --debug`
822
823 Displays debug information listing the API responses.
824-
825+
826 :samp:`-h, --help`
827
828 Display usage information.
829@@ -447,25 +442,24 @@
830 Lists the current stored configurations for the given identifier
831 <label> in a key:value format which should be easy to decipher.
832
833-
834 :samp:`new <label> ip=<value> interface=<if_device> [parameters...]`
835-
836+
837 Creates a new interface group. The required parameters are the IP
838 address and the network interface this appies to (e.g. eth0). In
839 order to do anything useful, further parameters are required::
840
841- management= 0 | 1 | 2
842+ management= 0 | 1 | 2
843 The service to be managed on the interface
844 ( 0= none, 1=DHCP, 2=DHCP and DNS).
845
846 subnet_mask=<value>
847 Apply the given dotted decimal value as the subnet mask.
848
849- broadcast_ip=<value>
850+ broadcast_ip=<value>
851 Apply the given dotted decimal value as the
852 broadcast IP address for this subnet.
853
854- router_ip=<value>
855+ router_ip=<value>
856 Apply the given dotted decimal value as the
857 default router address for this subnet.
858
859@@ -476,18 +470,16 @@
860 The highest value of IP address to allocate via DHCP
861
862
863-
864-
865-tag
866+tag
867 ^^^
868
869 Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
870- nodes | delete
871+ nodes | delete
872
873 .. program:: maas-cli tag
874
875 :samp:`read <tag_name>`
876-
877+
878 Returns information on the tag specified by <name>
879
880 :samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]`
881@@ -500,10 +492,10 @@
882
883 :samp:`rebuild`
884
885- Triggers a rebuild of the tag to node mapping.
886+ Triggers a rebuild of the tag to node mapping.
887
888 :samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`
889-
890+
891 Updates the tag identified by tag_name. Any or all of name,comment
892 and definition may be supplied as parameters. If no parameters are
893 supplied, this command returns the current values.
894@@ -516,12 +508,17 @@
895
896 Deletes the given tag.
897
898-tags
899-^^^^
900-Tags are a really useful way of identifying nodes with particular
901-characteristics.
902-
903-.. only:: html For more information on how to use them effectively, please see :ref:`deploy-tags`
904+
905+tags
906+^^^^
907+
908+Tags are a really useful way of identifying nodes with particular
909+characteristics.
910+
911+.. only:: html
912+
913+ For more information on how to use them effectively, please see
914+ :ref:`deploy-tags`
915
916 Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
917 --insecure] list | new
918@@ -531,39 +528,38 @@
919 :samp:`-d, --debug`
920
921 Displays debug information listing the API responses.
922-
923+
924 :samp:`-h, --help`
925
926 Display usage information.
927
928-:samp:`-k, --insecure`
929+:samp:`-k, --insecure`
930
931 Disables the SSL certificate check.
932
933 :samp:`list`
934-
935+
936 Returns a JSON object listing all the current tags known by the MAAS server
937
938 :samp:`create name=<value> definition=<value> [comment=<value>]`
939
940 Creates a new tag with the given name and definition. A comment is
941 optional. Names must be unique, obviously - an error will be
942- returned if the given name already exists. The definition is in the form of
943- an XPath expression which parses the XML returned by running ``lshw`` on the
944- node.
945-
946+ returned if the given name already exists. The definition is in the
947+ form of an XPath expression which parses the XML returned by
948+ running ``lshw`` on the node.
949+
950 Example:
951 Adding a tag to all nodes which have an Intel GPU::
952
953 $ maas-cli maas tags new name='intel-gpu' \
954 comment='Machines which have an Intel display driver' \
955 definition='contains(//node[@id="display"]/vendor, "Intel")
956-
957-
958-unused commands
959-^^^^^^^^^^^^^^^
960+
961+
962+unused commands
963+^^^^^^^^^^^^^^^
964+
965 Because the ``maas-cli`` command exposes all of the API, it also lists
966 some command options which are not really intended for end users, such
967 as the "file" and "boot-images" options.
968-
969-
970
971=== modified file 'docs/man/maas-cli.8.rst'
972--- docs/man/maas-cli.8.rst 2012-11-20 16:45:09 +0000
973+++ docs/man/maas-cli.8.rst 2012-11-21 11:51:34 +0000
974@@ -1,4 +1,3 @@
975-
976 maas-cli
977 --------
978
979@@ -7,9 +6,9 @@
980 ^^^^^
981
982 $ maas-cli <profile> <command> [parameters]
983-
984+
985 The available commands are dependent on the API you are connecting to and the
986-profile you use. The currently available options are explained below.
987+profile you use. The currently available options are explained below.
988
989
990 Description
991@@ -17,12 +16,14 @@
992
993 .. include:: ../maascli.rst
994
995+
996 Further Documentation
997 ^^^^^^^^^^^^^^^^^^^^^
998+
999 For more documentation of MAAS, please see https://maas.ubuntu.com/docs
1000
1001+
1002 See Also
1003 ^^^^^^^^
1004+
1005 `maas`
1006-
1007-
1008
1009=== modified file 'docs/man/maas.8.rst'
1010--- docs/man/maas.8.rst 2012-11-20 16:45:09 +0000
1011+++ docs/man/maas.8.rst 2012-11-21 11:51:34 +0000
1012@@ -1,23 +1,25 @@
1013 maas
1014 ----
1015
1016-USAGE
1017+
1018+Usage
1019 ^^^^^
1020
1021 maas [-h, --help] createsuperuser | changepassword | shell
1022
1023-DESCRIPTION
1024+
1025+Description
1026 ^^^^^^^^^^^
1027
1028-The `maas` command is part of Canonical's Metal As A Service software. It is
1029-derived from and can be used similarly to the `django-admin` command, and must
1030-be run with root privileges.
1031+The `maas` command is part of Canonical's Metal As A Service software. It is
1032+derived from and can be used similarly to the `django-admin` command, and must
1033+be run with root privileges.
1034
1035 For the end user, there are only three subcommands of interest.
1036
1037 **createsuperuser**
1038 This subcommand is used to create a superuser for the
1039- MAAS install. The suggested username is "root". This command usually only
1040+ MAAS install. The suggested username is "root". This command usually only
1041 needs to be run when installing MAAS for the first time.
1042
1043 **changepassword**
1044@@ -26,16 +28,18 @@
1045 enter it once again to verify.
1046
1047 **shell**
1048- This subcommand may be useful for debugging installed systems. It
1049+ This subcommand may be useful for debugging installed systems. It
1050 will open a new python shell environment with the correct django environment
1051 for working with the installed MAAS software.
1052
1053-
1054+
1055 Further Documentation
1056 ^^^^^^^^^^^^^^^^^^^^^
1057+
1058 For more documentation of MAAS, please see https://maas.ubuntu.com/docs
1059
1060+
1061 See Also
1062 ^^^^^^^^
1063+
1064 `maas-cli`
1065-
1066
1067=== modified file 'docs/nodes.rst'
1068--- docs/nodes.rst 2012-10-11 13:23:54 +0000
1069+++ docs/nodes.rst 2012-11-21 11:51:34 +0000
1070@@ -1,10 +1,10 @@
1071-
1072-
1073 Adding nodes to the system
1074 ==========================
1075
1076-Now that the MAAS controller is running, we need to make the nodes aware of MAAS and vice-versa. If you have set up DHCP correctly, and your nodes can boot via PXE then things really couldn't be much easier and you can use :ref:`the automatic discovery procedure <auto-enlist>`
1077-
1078+Now that the MAAS controller is running, we need to make the nodes
1079+aware of MAAS and vice-versa. If you have set up DHCP correctly, and
1080+your nodes can boot via PXE then things really couldn't be much easier
1081+and you can use :ref:`the automatic discovery procedure <auto-enlist>`
1082
1083
1084 .. _auto-enlist:
1085@@ -12,21 +12,29 @@
1086 Automatic Discovery
1087 -------------------
1088
1089-With nodes set to boot from a PXE image, they will start, look for a DHCP server, receive the PXE boot details, boot the image, contact the MAAS server and shut down.
1090-
1091-During this process, the MAAS server will be passed information about the node, including the architecture, MAC address and other details which will be stored in the database of nodes. You can accept and comission the nodes via the web interface.
1092-When the nodes have been accepted the selected series of Ubuntu will be installed.
1093-
1094-To save time, you can also accept and commission all nodes from the commandline. This requires that you first login with the API key, which :ref:`you can retrieve from the web interface <api-key>`::
1095+With nodes set to boot from a PXE image, they will start, look for a
1096+DHCP server, receive the PXE boot details, boot the image, contact the
1097+MAAS server and shut down.
1098+
1099+During this process, the MAAS server will be passed information about
1100+the node, including the architecture, MAC address and other details
1101+which will be stored in the database of nodes. You can accept and
1102+comission the nodes via the web interface. When the nodes have been
1103+accepted the selected series of Ubuntu will be installed.
1104+
1105+To save time, you can also accept and commission all nodes from the
1106+commandline. This requires that you first login with the API key,
1107+which :ref:`you can retrieve from the web interface <api-key>`::
1108
1109 $ maas-cli maas nodes accept-all
1110
1111
1112-
1113 Enlist nodes via boot media
1114 ---------------------------
1115
1116-Using Boot media such as an AVAHI boot image or the Ubuntu Server install disk, it is possible to perform the discovery and enlistment process without using DHCP/PXE.
1117+Using Boot media such as an AVAHI boot image or the Ubuntu Server
1118+install disk, it is possible to perform the discovery and enlistment
1119+process without using DHCP/PXE.
1120
1121 Boot from the media and follow the instructions.
1122
1123@@ -34,4 +42,5 @@
1124 Manually add nodes
1125 ------------------
1126
1127-If you know the MAC address of a node, you can manually enter details about the node through the web interface.
1128+If you know the MAC address of a node, you can manually enter details
1129+about the node through the web interface.
1130
1131=== modified file 'docs/orientation.rst'
1132--- docs/orientation.rst 2012-10-04 15:14:12 +0000
1133+++ docs/orientation.rst 2012-11-21 11:51:34 +0000
1134@@ -1,30 +1,46 @@
1135 .. _orientation:
1136-
1137+
1138 Orientation
1139 ===========
1140
1141+
1142 MAAS in Brief
1143 -------------
1144
1145-Canonical’s MAAS brings the dynamism of cloud computing to the world of physical provisioning and Ubuntu. Connect, commission and deploy physical servers in record time, re-allocate nodes between services dynamically, and keep them up to date and in due course, retire them from use.
1146-
1147-MAAS is a new way of thinking about physical infrastructure. Compute, storage and network are commodities in the virtual world, and for large-scale deployments the same is true of the metal. “Metal as a service” lets you treat farms of servers as a malleable resource for allocation to specific problems, and re-allocation on a dynamic basis.
1148-
1149-In conjunction with the Juju service orchestration software (see https://juju.ubuntu.com/docs/), MAAS will enable you to get the most out of your physical hardware and dynamically deploy complex services with ease and confidence.
1150+Canonical’s MAAS brings the dynamism of cloud computing to the world
1151+of physical provisioning and Ubuntu. Connect, commission and deploy
1152+physical servers in record time, re-allocate nodes between services
1153+dynamically, and keep them up to date and in due course, retire them
1154+from use.
1155+
1156+MAAS is a new way of thinking about physical infrastructure. Compute,
1157+storage and network are commodities in the virtual world, and for
1158+large-scale deployments the same is true of the metal. “Metal as a
1159+service” lets you treat farms of servers as a malleable resource for
1160+allocation to specific problems, and re-allocation on a dynamic basis.
1161+
1162+In conjunction with the Juju service orchestration software (see
1163+https://juju.ubuntu.com/docs/), MAAS will enable you to get the most
1164+out of your physical hardware and dynamically deploy complex services
1165+with ease and confidence.
1166+
1167
1168 Do I Need MAAS?
1169 ---------------
1170
1171-MAAS certainly isn't for everyone, but why not ask yourself these questions?
1172+MAAS certainly isn't for everyone, but why not ask yourself these
1173+questions?
1174
1175-You probably *SHOULD* use MAAS if any or all of the following statements are true:
1176+You probably *SHOULD* use MAAS if any or all of the following
1177+statements are true:
1178
1179 * You are trying to manage many physical servers.
1180 * You want to deploy services with the minimum fuss.
1181 * You need to get the most from your resources.
1182 * You want things to work, repeatably and reliably.
1183
1184-You probably don't need MAAS if any or all of these statements are true:
1185+You probably don't need MAAS if any or all of these statements are
1186+true:
1187
1188 * You don't need to manage physical hardware
1189 * You relish time spent in the server room
1190@@ -36,17 +52,18 @@
1191 A Typical MAAS setup
1192 --------------------
1193
1194-MAAS is designed to work with your physical hardware, whether your setup includes thousands of server boxes or only a few. The key components of the MAAS software are:
1195+MAAS is designed to work with your physical hardware, whether your
1196+setup includes thousands of server boxes or only a few. The key
1197+components of the MAAS software are:
1198
1199 * Region controller
1200 * Cluster controller(s)
1201 * Nodes
1202
1203-For small (in terms of number of nodes) setups, you will probably just install the Region controller and a cluster controller on the same server - it is only worth having multiple region controllers if you need to organise your nodes into different subnets (e.g. if you have a lot of nodes).
1204+For small (in terms of number of nodes) setups, you will probably just
1205+install the Region controller and a cluster controller on the same
1206+server - it is only worth having multiple region controllers if you
1207+need to organise your nodes into different subnets (e.g. if you have a
1208+lot of nodes).
1209
1210 .. image:: media/orientation_architecture-diagram.*
1211-
1212-
1213-
1214-
1215-
1216
1217=== modified file 'docs/tags.rst'
1218--- docs/tags.rst 2012-10-25 13:09:16 +0000
1219+++ docs/tags.rst 2012-11-21 11:51:34 +0000
1220@@ -1,65 +1,69 @@
1221-
1222 .. _deploy-tags:
1223+
1224 Making use of Tags
1225 ==================
1226
1227-MAAS implements a system of tags based on the physical properties of the nodes.
1228-The idea behind this is that you can use the tags to identify nodes with
1229-particular abilities which may be useful when it comes to deploying services.
1230-
1231-A real world example of this might be to identify nodes which have fast GPUs
1232-installed, if you were planning on deploying software which used CUDA or
1233-OpenCL which would make use of this hardware.
1234+MAAS implements a system of tags based on the physical properties of
1235+the nodes. The idea behind this is that you can use the tags to
1236+identify nodes with particular abilities which may be useful when it
1237+comes to deploying services.
1238+
1239+A real world example of this might be to identify nodes which have
1240+fast GPUs installed, if you were planning on deploying software which
1241+used CUDA or OpenCL which would make use of this hardware.
1242+
1243
1244 Tag definitions
1245 ---------------
1246
1247-
1248 Before we can create a tag we need to know how we will select which nodes it
1249-gets applied to. MAAS collects hardware information from the nodes using the
1250-`"lshw" utility <http://ezix.org/project/wiki/HardwareLiSter>`_ to return
1251-detailed information in XML format. The definitions used in creating a tag are
1252+gets applied to. MAAS collects hardware information from the nodes using the
1253+`"lshw" utility <http://ezix.org/project/wiki/HardwareLiSter>`_ to return
1254+detailed information in XML format. The definitions used in creating a tag are
1255 then constructed using XPath expressions.
1256-If you are unfamiliar with XPath expressions, it is well worth checking out the
1257+If you are unfamiliar with XPath expressions, it is well worth checking out the
1258 `w3schools documentation <http://www.w3schools.com/xpath/xpath_syntax.asp>`_.
1259 For the lshw XML, we will just check all the available nodes for some properties.
1260-In our example case, we might want to find GPUs with a clock speed of over 1GHz.
1261+In our example case, we might want to find GPUs with a clock speed of over 1GHz.
1262 In this case, the relevant XML node from the output will be labelled "display"
1263 and does have a property called clock, so it will look like this::
1264-
1265+
1266 //node[@id="display"]/clock > 1000000000
1267
1268 Now we have a definition, we can go ahead and create a tag.
1269
1270+
1271 Creating a tag
1272 --------------
1273
1274-Once we have sorted out what definition we will be using, creating the tag is
1275-easy using the ``maas-cli`` command. You will need to :ref:`be logged in to the API first <api-key>`::
1276+Once we have sorted out what definition we will be using, creating the
1277+tag is easy using the ``maas-cli`` command. You will need to :ref:`be
1278+logged in to the API first <api-key>`::
1279
1280 $ maas-cli maas tags new name='gpu' \
1281 comment='GPU with clock speed >1GHz for running CUDA type operations.' \
1282 definition='//node[@id="display"]/clock > 1000000000'
1283
1284-The comment is really for your benefit. It pays to keep the actual tag name
1285-short and to the point as you will be using it frequently in commands, but it
1286+The comment is really for your benefit. It pays to keep the actual tag name
1287+short and to the point as you will be using it frequently in commands, but it
1288 may subsequently be hard to work out what exactly was the difference between
1289-tags like "gpu" and "fastgpu" unless you have a good comment. Something which
1290+tags like "gpu" and "fastgpu" unless you have a good comment. Something which
1291 explains the definition in plain language is always a good idea!
1292
1293 To check which nodes this tag applies to we can use the tag command::
1294
1295- $ maas-cli maas tag nodes gpu
1296+ $ maas-cli maas tag nodes gpu
1297
1298-The process of updating the tags does take some time - not a lot of time, but
1299-if nothing shows up straight away, try running the command again after a minute
1300+The process of updating the tags does take some time - not a lot of time, but
1301+if nothing shows up straight away, try running the command again after a minute
1302 or so.
1303
1304+
1305 Using the tag
1306 -------------
1307
1308-You can use the tag in the web interface to discover applicable nodes, but the
1309-real significance of it is when using juju to deploy services. Tags can be used
1310+You can use the tag in the web interface to discover applicable nodes, but the
1311+real significance of it is when using juju to deploy services. Tags can be used
1312 with juju constraints to make sure that a particular service only gets deployed
1313 on hardware with the tag you have created.
1314
1315@@ -68,12 +72,11 @@
1316
1317 $ juju deploy --constraints maas-tags=gpu cuda
1318
1319-You could list several tags if required, and mix in other juju constraints if
1320+You could list several tags if required, and mix in other juju constraints if
1321 needed::
1322
1323 $ juju deploy --constraints "mem=1024 maas-tags=gpu,intel" cuda
1324-
1325-
1326+
1327
1328 Manually assigning tags
1329 -----------------------
1330@@ -81,7 +84,7 @@
1331 MAAS supports the creation of arbitrary tags which don't depend on XPath
1332 definitions ("nodes which make a lot of noise" perhaps). If a tag is created
1333 without specifying the definition parameter then it will simply be ignored by
1334-tag refresh mechanism, but the MAAS administrator will be able to manually add
1335+tag refresh mechanism, but the MAAS administrator will be able to manually add
1336 and remove the tag from specific nodes.
1337
1338 In this example we are assuming you are using the 'maas' profile and you want
1339@@ -90,10 +93,10 @@
1340 $ maas-cli maas tags new name='my_tag' comment='nodes which go ping'
1341 $ maas-cli maas tag update-nodes my_tag add="<system_id>"
1342
1343-The first line creates a new tag but omits the definition, so no nodes are
1344-automatically added to it. The second line applies that tag to a specific node
1345+The first line creates a new tag but omits the definition, so no nodes are
1346+automatically added to it. The second line applies that tag to a specific node
1347 referenced by its system id property.
1348-
1349+
1350 You can easily remove a tag from a particular node, or indeed add
1351 and remove them at the same time::
1352
1353@@ -105,7 +108,7 @@
1354 subsequently edit it to remove the definition. From this point the tag behaves
1355 as if you had manually created it, but it still retains all the existing
1356 associations it has with nodes. This is particularly useful if you have some
1357-hardware which is conceptually similar but doesn't easily fit within a single
1358+hardware which is conceptually similar but doesn't easily fit within a single
1359 tag definition::
1360
1361 $ maas-cli maas tag new name='my_tag' comment='nodes I like ' \
1362@@ -113,15 +116,7 @@
1363 $ maas-cli maas tag update my_tag definition=''
1364 $ maas-cli mass tag update-nodes my_tag add=<system_id>
1365
1366-
1367 .. tip::
1368+
1369 If you add and remove the same node in one operation, it ends up having
1370 the tag removed (even if the tag was in place before the operation).
1371-
1372-
1373-
1374-
1375-
1376-
1377-
1378-
1379
1380=== modified file 'docs/troubleshooting.rst'
1381--- docs/troubleshooting.rst 2012-10-12 12:51:17 +0000
1382+++ docs/troubleshooting.rst 2012-11-21 11:51:34 +0000
1383@@ -1,6 +1,7 @@
1384 ********************
1385 MAAS Troubleshooting
1386 ********************
1387+
1388 Some parts of MAAS may still be a little confusing, and sometimes you might be
1389 trying to do things that are just plain impossible. This section covers some of
1390 the most commonly encountered problems and tries its best to make them gone.
1391@@ -13,8 +14,10 @@
1392 **Nodes hang on "Commissioning"**
1393 =================================
1394
1395+
1396 Possible Cause: Timing issues
1397 -----------------------------
1398+
1399 Various parts of MAAS rely on OAuth to negotiate a connection to nodes. If the
1400 current time reported by the hardware clock on your node differs significantly
1401 from that on the MAAS server, the connection will not be made.
1402@@ -23,6 +26,7 @@
1403 adjust them. This can usually be done from within the system BIOS, without
1404 needing to install an OS
1405
1406+
1407 Possible Cause: Network drivers
1408 -------------------------------
1409
1410@@ -34,17 +38,21 @@
1411 network adaptor. It *is* theoretically possible to modify the boot image to
1412 include proprietary drivers, but it is not a straightforward task.
1413
1414+
1415 **Nodes fail to PXE boot**
1416 ==========================
1417
1418+
1419 Possible Cause: Using an incorrectly configured VM
1420 --------------------------------------------------
1421+
1422 Some Virtual Machine setups include emulation of network hardware that does not
1423 support PXE booting, and in most setups, you will need to explicitly set up the
1424-VM to boot via PXE.
1425+VM to boot via PXE.
1426
1427 **SOLUTION**: Consult the VM docs for details of PXE booting.
1428
1429+
1430 Possible Cause: DHCP conflict
1431 -----------------------------
1432 If you are using MAAS in a setup with an existing DHCP, *DO NOT SET UP THE MAAS
1433@@ -53,7 +61,6 @@
1434
1435 **SOLUTION**: You will need to either:
1436
1437-
1438 * Configure your existing DHCP server to point to the MAAS server.
1439
1440 or
1441@@ -62,30 +69,31 @@
1442 this, please see https://wiki.ubuntu.com/ServerTeam/MAAS/AvahiBoot
1443
1444
1445-
1446 **Can't log in to node**
1447 ========================
1448
1449-Sometimes you may wish to login directly to a node on your system. If you have
1450-set up Juju and MAAS, the attached nodes will automatically receive existing ssh
1451-keys and sets up ssh on the node to authenticate via key, so you can just login
1452-with no password from the server.
1453-There is also an option in the MAAS web interface to add new ssh keys to the
1454-nodes (via Preferences in the drop down menu which appears when clicking your
1455-username in the top-right of the page).
1456+Sometimes you may wish to login directly to a node on your system. If
1457+you have set up Juju and MAAS, the attached nodes will automatically
1458+receive existing ssh keys and sets up ssh on the node to authenticate
1459+via key, so you can just login with no password from the server.
1460+There is also an option in the MAAS web interface to add new ssh keys
1461+to the nodes (via Preferences in the drop down menu which appears when
1462+clicking your username in the top-right of the page).
1463+
1464
1465 **Forgot MAAS superuser password**
1466 ==================================
1467
1468-As long as you have sudo privileges, this is not a disaster. You can use the
1469-``maas`` command to change the password for the MAAS superuser on the MAAS
1470-server:
1471+As long as you have sudo privileges, this is not a disaster. You can
1472+use the ``maas`` command to change the password for the MAAS superuser
1473+on the MAAS server:
1474
1475 ``sudo maas changepassword root``
1476
1477
1478 **Need to reconfigure server IP address**
1479 =========================================
1480+
1481 If you made a mistake during setup or you just need to reconfigure your MAAS
1482 server, you can simply run the setup again:
1483
1484@@ -109,7 +117,3 @@
1485 #. If you are still getting "404 - Page not found" errors, check that the MAAS
1486 web interface has been installed in the right place. There should be a file
1487 present called /usr/share/maas/maas/urls.py
1488-
1489-
1490-
1491-