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

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-committers/maas/trunk
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
=== modified file '.bzrignore'
--- .bzrignore 2012-11-20 16:45:09 +0000
+++ .bzrignore 2012-11-21 11:51:34 +0000
@@ -10,7 +10,6 @@
10./acceptance/source10./acceptance/source
11./bin11./bin
12./build12./build
13./celerybeat-schedule
14./db13./db
15./develop-eggs14./develop-eggs
16./dist15./dist
@@ -22,6 +21,7 @@
22./lib21./lib
23./local22./local
24./logs/*23./logs/*
24./man
25./media/demo/*25./media/demo/*
26./media/development26./media/development
27./parts27./parts
@@ -31,4 +31,3 @@
31./TAGS31./TAGS
32./tags32./tags
33dropin.cache33dropin.cache
34./man
3534
=== modified file 'INSTALL.txt'
--- INSTALL.txt 2012-11-20 16:45:09 +0000
+++ INSTALL.txt 2012-11-21 11:51:34 +0000
@@ -1,16 +1,18 @@
1.. -*- mode: rst -*-1.. -*- mode: rst -*-
22
3 3
4Installing MAAS4Installing MAAS
5===============5===============
66
7There are two main ways to install MAAS7There are two main ways to install MAAS
88
9 * :ref:`From Ubuntu's package archive on an existing Ubuntu install. <pkg-install>`9 * :ref:`From Ubuntu's package archive on an existing Ubuntu
10 * :ref:`As a fresh install from Ubuntu Server install media. <disc-install>`10 install. <pkg-install>`
11 11 * :ref:`As a fresh install from Ubuntu Server install
12 media. <disc-install>`
1213
13If you are interested in testing the latest development version you can also check out the very latest source and build MAAS yourself. 14If you are interested in testing the latest development version you
15can also check out the very latest source and build MAAS yourself.
1416
1517
16.. _pkg-install:18.. _pkg-install:
@@ -18,17 +20,34 @@
18Installing MAAS from the archive20Installing MAAS from the archive
19--------------------------------21--------------------------------
2022
21Installing 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:23Installing MAAS from packages is thankfully straightforward. There are
24actually several packages that go into making up a working MAAS
25install, but for convenience, many of these have been gathered into a
26virtual package called 'maas' which will install the necessary
27components for a 'seed cloud', that is a single server that will
28directly control a group of nodes. The main packages are:
2229
23 * ``maas`` - seed cloud setup, which includes both the region controller and the cluster controller below.30 * ``maas`` - seed cloud setup, which includes both the region
31 controller and the cluster controller below.
24 * ``maas-region-controller`` - includes the web UI, API and database.32 * ``maas-region-controller`` - includes the web UI, API and database.
25 * ``maas-cluster-controller`` - controls a group ("cluster") of nodes including DHCP management.33 * ``maas-cluster-controller`` - controls a group ("cluster") of nodes
34 including DHCP management.
26 * ``maas-dhcp``/``maas-dns`` - required when managing dhcp/dns.35 * ``maas-dhcp``/``maas-dns`` - required when managing dhcp/dns.
2736
28If 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).37If you need to separate these services or want to deploy an additional
2938cluster controller, you should install the corresponding packages
30There 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`39individually (see :ref:`the description of a typical setup <setup>`
31 40for more background on how a typical hardware setup might be
41arranged).
42
43There are two suggested additional packages 'maas-dhcp' and
44'maas-dns'. These set up MAAS-controlled DHCP and DNS services which
45greatly simplify deployment if you are running a typical setup where
46the MAAS controller can run the network (Note: These **must** be
47installed if you later set the options in the web interface to have
48MAAS manage DHCP/DNS). If you need to integrate your MAAS setup under
49an existing DHCP setup, see :ref:`manual-dhcp`
50
3251
33Install packages52Install packages
34^^^^^^^^^^^^^^^^53^^^^^^^^^^^^^^^^
@@ -37,83 +56,118 @@
3756
38 $ sudo apt-get install maas maas-dhcp maas-dns57 $ sudo apt-get install maas maas-dhcp maas-dns
3958
40You 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.59You will see a list of packages and a confirmation message to
60proceed. The exact list will obviously depend on what you already have
61installed on your server, but expect to add about 200MB of files.
4162
42The configuration for the MAAS controller will automatically run and pop up this config screen:63The configuration for the MAAS controller will automatically run and
64pop up this config screen:
4365
44.. image:: media/install_cluster-config.*66.. image:: media/install_cluster-config.*
4567
46Here 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. 68Here you will need to enter the hostname for where the region
69controller can be contacted. In many scenarios, you may be running the
70region controller (i.e. the web and API interface) from a different
71network address, for example where a server has several network
72interfaces.
4773
48Once the configuration scripts have run you should see this message telling you that the system is ready to use:74Once the configuration scripts have run you should see this message
75telling you that the system is ready to use:
4976
50.. image:: media/install_controller-config.*77.. image:: media/install_controller-config.*
5178
52The 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`79The web server is started last, so you have to accept this message
80before the service is run and you can access the Web interface. Then
81there are just a few more setup steps :ref:`post_install`
82
5383
54.. _disc-install:84.. _disc-install:
5585
56Installing MAAS from Ubuntu Server boot media86Installing MAAS from Ubuntu Server boot media
57---------------------------------------------87---------------------------------------------
5888
59If 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.89If you are installing MAAS as part of a fresh install it is easiest to
60Boot from the Ubuntu Server media and you will be greeted with the usual language selection screen:90choose the "Multiple Server install with MAAS" option from the
91installer and have pretty much everything set up for you. Boot from
92the Ubuntu Server media and you will be greeted with the usual
93language selection screen:
6194
62.. image:: media/install_01.*95.. image:: media/install_01.*
6396
64On 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.97On the next screen, you will see there is an entry in the menu called
98"Multiple server install with MAAS". Use the cursor keys to select
99this and then press Enter.
65100
66.. image:: media/install_02.*101.. image:: media/install_02.*
67102
68The installer then runs through the usual language and keyboard options. Make your selections using Tab/Cursor keys/Enter to proceed through the install.103The installer then runs through the usual language and keyboard
69The installer will then load various drivers, which may take a moment or two.104options. Make your selections using Tab/Cursor keys/Enter to proceed
105through the install. The installer will then load various drivers,
106which may take a moment or two.
70107
71.. image:: media/install_03.*108.. image:: media/install_03.*
72109
73The next screen asks for the hostname for this server. Choose something appropriate for your network.110The next screen asks for the hostname for this server. Choose
74111something appropriate for your network.
75112
76.. image:: media/install_04.*113.. image:: media/install_04.*
77114
78Finally 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.115Finally we get to the MAAS part! Here there are just two options. We
116want to "Create a new MAAS on this server" so go ahead and choose that
117one.
79118
80.. image:: media/install_05.*119.. image:: media/install_05.*
81120
82The 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!)121The install now continues as usual. Next you will be prompted to enter
122a username. This will be the admin user for the actual server that
123MAAS will be running on (not the same as the MAAS admin user!)
83124
84.. image:: media/install_06.*125.. image:: media/install_06.*
85126
86As usual you will have the chance to encrypt your home directory. Continue to make selections based on whatever settings suit your usage.127As usual you will have the chance to encrypt your home
128directory. Continue to make selections based on whatever settings suit
129your usage.
87130
88.. image:: media/install_07.*131.. image:: media/install_07.*
89132
90After making selections and partitioning storage, the system software will start to be installed. This part should only take a few minutes.133After making selections and partitioning storage, the system software
134will start to be installed. This part should only take a few minutes.
91135
92.. image:: media/install_09.*136.. image:: media/install_09.*
93137
94Various 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.138Various packages will now be configured, including the package manager
139and update manager. It is important to set these up appropriately so
140you will receive timely updates of the MAAS server software, as well
141as other essential services that may run on this server.
95142
96.. image:: media/install_10.*143.. image:: media/install_10.*
97144
98The 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)145The configuration for MAAS will ask you to configure the host address
146of the server. This should be the IP address you will use to connect
147to the server (you may have additional interfaces e.g. to run node
148subnets)
99149
100.. image:: media/install_cluster-config.*150.. image:: media/install_cluster-config.*
101151
102The next screen will confirm the web address that will be used to the web interface.152The next screen will confirm the web address that will be used to the
153web interface.
103154
104.. image:: media/install_controller-config.*155.. image:: media/install_controller-config.*
105156
106After configuring any other packages the installer will finally come to and end. At this point you should eject the boot media.157After configuring any other packages the installer will finally come
158to and end. At this point you should eject the boot media.
107159
108.. image:: media/install_14.*160.. image:: media/install_14.*
109161
110After 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.162After restarting, you should be able to login to the new server with
111163the information you supplied during the install. The MAAS software
164will run automatically.
112165
113.. image:: media/install_15.*166.. image:: media/install_15.*
114167
115168**NOTE:** The maas-dhcp and maas-dns packages are not installed by
116**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::169default. If you want to have MAAS run DHCP and DNS services, you
170should install these packages::
117171
118 $ sudo apt-get install maas-dhcp maas-dns172 $ sudo apt-get install maas-dhcp maas-dns
119173
@@ -121,13 +175,19 @@
121175
122.. _post_install:176.. _post_install:
123177
178
124Post-Install tasks179Post-Install tasks
125==================180==================
126If 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:181
182If you now use a web browser to connect to the region controller, you
183should see that MAAS is running, but there will also be some errors on
184the screen:
127185
128.. image:: media/install_web-init.*186.. image:: media/install_web-init.*
129187
130The 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. 188The on screen messages will tell you that there are no boot images
189present, and that you can't login because there is no admin user.
190
131191
132Create a superuser account192Create a superuser account
133--------------------------193--------------------------
@@ -137,29 +197,37 @@
137197
138 $ sudo maas createsuperuser198 $ sudo maas createsuperuser
139199
140Follow 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).200Follow the prompts to create the account which you will need to login
201to the web interface. Unless you have a special need, it is best to
202accept the default login name of `root`, as it is rather annoying if
203you forget the username (although you can simply run this command
204again to create a new superuser).
141205
142206
143Import the boot images207Import the boot images
144----------------------208----------------------
145209
146MAAS will check for and download new Ubuntu images once a week.210MAAS will check for and download new Ubuntu images once a week.
147However, you'll need to download them manually the first time. To do this you will need to211However, you'll need to download them manually the first time. To do
148connect to the MAAS API using the maas-cli tool. (see :ref:`api_key` for details of logging 212this you will need to connect to the MAAS API using the maas-cli
149in).213tool. (see :ref:`Logging in <api-key>` for details). Then you need to
150Then you need to run the command::214run the command::
151215
152 $ maas-cli maas node-groups import-boot-images216 $ maas-cli maas node-groups import-boot-images
153217
154(substitute in a different profile name for 'maas' if you have called yours something else)218(substitute in a different profile name for 'maas' if you have called
155This will initiate downloading the required image files. Note that this may take some time 219yours something else) This will initiate downloading the required
156depending on your network connection.220image files. Note that this may take some time depending on your
221network connection.
157222
158223
159Login to the server224Login to the server
160-------------------225-------------------
161226
162To 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.227To check that everything is working properly, you should try and login
228to the server now. Both the error messages should have gone (it can
229take a few minutes for the boot image files to register) and you can
230see that there are currently 0 nodes attached to this controller.
163231
164.. image:: media/install-login.*232.. image:: media/install-login.*
165233
@@ -167,7 +235,9 @@
167Configure DHCP235Configure DHCP
168--------------236--------------
169237
170If you are using MAAS to control DHCP, you need to set this via the web interface.238If you are using MAAS to control DHCP, you need to set this via the
171However, if you are manually configuring a DHCP server, you should take a look at :ref:`manual-dhcp`239web interface. However, if you are manually configuring a DHCP
240server, you should take a look at :ref:`manual-dhcp`
172241
173Once everything is set up and running, you are ready to :doc:`start enlisting nodes <nodes>`242Once everything is set up and running, you are ready to :doc:`start
243enlisting nodes <nodes>`
174244
=== modified file 'Makefile'
--- Makefile 2012-11-21 10:26:41 +0000
+++ Makefile 2012-11-21 11:51:34 +0000
@@ -153,13 +153,13 @@
153 $(MAKE) -C acceptance $@153 $(MAKE) -C acceptance $@
154 find . -type f -name '*.py[co]' -print0 | xargs -r0 $(RM)154 find . -type f -name '*.py[co]' -print0 | xargs -r0 $(RM)
155 find . -type f -name '*~' -print0 | xargs -r0 $(RM)155 find . -type f -name '*~' -print0 | xargs -r0 $(RM)
156 find . -type f -name dropin.cache -print0 | xargs -r0 $(RM)
156 $(RM) -r media/demo/* media/development157 $(RM) -r media/demo/* media/development
157 $(RM) $(js_enums)158 $(RM) $(js_enums)
158 $(RM) *.log159 $(RM) *.log
159 $(RM) celerybeat-schedule
160 $(RM) docs/api.rst160 $(RM) docs/api.rst
161 $(RM) -r docs/_autosummary161 $(RM) -r docs/_autosummary docs/_build
162 $(RM) -r man/162 $(RM) -r man
163163
164distclean: clean stop164distclean: clean stop
165 $(RM) -r bin include lib local165 $(RM) -r bin include lib local
@@ -167,9 +167,7 @@
167 $(RM) -r build dist logs/* parts167 $(RM) -r build dist logs/* parts
168 $(RM) tags TAGS .installed.cfg168 $(RM) tags TAGS .installed.cfg
169 $(RM) -r *.egg *.egg-info src/*.egg-info169 $(RM) -r *.egg *.egg-info src/*.egg-info
170 $(RM) -r docs/_build
171 $(RM) -r run/* services/*/supervise170 $(RM) -r run/* services/*/supervise
172 $(RM) twisted/plugins/dropin.cache
173171
174harness: bin/maas bin/database172harness: bin/maas bin/database
175 $(dbrun) bin/maas shell --settings=maas.demo173 $(dbrun) bin/maas shell --settings=maas.demo
176174
=== modified file 'docs/about.rst'
--- docs/about.rst 2012-10-03 20:16:24 +0000
+++ docs/about.rst 2012-11-21 11:51:34 +0000
@@ -1,19 +1,35 @@
1About this documentation1About this documentation
2========================2========================
33
4This 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.4This is the documentation for Canonical's MAAS software. If you aren't
5Like 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. 5sure what that is, you should probably skip everything else and head
6straight to the :ref:`orientation` section where it is explained.
7Like any software though, it can be frustrating if you don't know how
8bits of it work, how to achieve certain goals or what to do when
9things go wrong. Amongst its various sections, this manual aims to
10answer all those questions and plenty more you haven't even thought of
11yet.
12
613
7Getting it14Getting it
8----------15----------
916
10In 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.17In a cunning move, the current documentation always lives, and is
11However, 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.com18built from, the main MAAS source code. That means that whatever MAAS
19package you have installed, or even if you are really living life on
20the edge and have checked out a development version from Launchpad,
21this documentation should be the latest and most appropriate version
22for the software you are running. However, it is also possible that
23there have been further sections or more helpful, or clearer bits
24added since the package you are using was made. For this reason you
25can always find the latest documentation online here:
26http://maas.ubuntu.com
27
1228
13Contributing29Contributing
14------------30------------
1531
16If 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.com32If you have some extra information to add, or think you have spotted
1733an error or something out of date, we really want to hear about
1834it. File a bug report or contact us via the MAAS homepage at
1935http://maas.ubuntu.com
2036
=== modified file 'docs/configure.rst'
--- docs/configure.rst 2012-10-03 20:16:24 +0000
+++ docs/configure.rst 2012-11-21 11:51:34 +0000
@@ -1,14 +1,19 @@
1Additional Configuration1Additional Configuration
2========================2========================
33
4
4.. _manual-dhcp:5.. _manual-dhcp:
56
6Manual DHCP configuration7Manual DHCP configuration
7-------------------------8-------------------------
89
9There 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.10There are some circumstances under which you may not wish the master
11MAAS worker to handle DHCP for the network. In these instances, the
12existing DHCP server for the network will need its configuration
13altered to allow MAAS to enlist and control nodes automatically.
1014
11At the very least the next-server should point to the MAAS controller host address and the filename should be set to pxelinux.015At the very least the next-server should point to the MAAS controller
16host address and the filename should be set to pxelinux.0
1217
13The configuration entry may look something like this::18The configuration entry may look something like this::
1419
@@ -21,7 +26,9 @@
21 range dynamic-bootp 192.168.122.5 192.168.122.135;26 range dynamic-bootp 192.168.122.5 192.168.122.135;
22 }27 }
2328
29
24.. _ssl:30.. _ssl:
31
25SSL Support32SSL Support
26-----------33-----------
2734
@@ -43,4 +50,3 @@
43the default SSL certificate is insecure. Please generate your own and then50the default SSL certificate is insecure. Please generate your own and then
44edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the51edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the
45certificate.52certificate.
46
4753
=== modified file 'docs/index.rst'
--- docs/index.rst 2012-10-16 14:54:36 +0000
+++ docs/index.rst 2012-11-21 11:51:34 +0000
@@ -4,12 +4,12 @@
4Metal As A Service: MAAS4Metal As A Service: MAAS
5########################5########################
66
7
8This is the documentation for the MAAS project http://maas.ubuntu.com7This is the documentation for the MAAS project http://maas.ubuntu.com
98
9
10************10************
11Introduction11Introduction
12************ 12************
1313
14.. toctree::14.. toctree::
15 :maxdepth: 215 :maxdepth: 2
@@ -17,6 +17,7 @@
17 about17 about
18 orientation18 orientation
1919
20
20***************21***************
21Getting started22Getting started
22***************23***************
@@ -27,7 +28,7 @@
27 install28 install
28 configure29 configure
29 nodes30 nodes
30 31
3132
32******************33******************
33Deploying services34Deploying services
@@ -38,7 +39,8 @@
3839
39 juju-quick-start40 juju-quick-start
40 tags41 tags
41 42
43
42******************************44******************************
43Using the maas-cli commandline45Using the maas-cli commandline
44******************************46******************************
@@ -48,6 +50,7 @@
4850
49 maascli51 maascli
5052
53
51**********54**********
52Appendices55Appendices
53**********56**********
@@ -56,11 +59,12 @@
56 :maxdepth: 259 :maxdepth: 2
5760
58 troubleshooting61 troubleshooting
59 hacking 62 hacking
60 api63 api
61 models64 models
62 enum65 enum
6366
67
64Indices and tables68Indices and tables
65==================69==================
6670
6771
=== modified file 'docs/juju-quick-start.rst'
--- docs/juju-quick-start.rst 2012-08-16 11:56:16 +0000
+++ docs/juju-quick-start.rst 2012-11-21 11:51:34 +0000
@@ -156,5 +156,3 @@
156Note that each charm runs on its own host, so each deployment will156Note that each charm runs on its own host, so each deployment will
157actually take as long as it took to bootstrap. Have a beer, drown your157actually take as long as it took to bootstrap. Have a beer, drown your
158sorrows in liquor, or, my preference, have another cup of tea.158sorrows in liquor, or, my preference, have another cup of tea.
159
160----
161159
=== modified file 'docs/maascli.rst'
--- docs/maascli.rst 2012-11-13 11:30:52 +0000
+++ docs/maascli.rst 2012-11-21 11:51:34 +0000
@@ -1,9 +1,9 @@
1
2As well as the web interface, many tasks can be performed by accessing1As well as the web interface, many tasks can be performed by accessing
3the MAAS API directly through the maas-cli command. This section2the MAAS API directly through the maas-cli command. This section
4details how to login with this tool and perform some common3details how to login with this tool and perform some common
5operations.4operations.
65
6
7.. _api-key:7.. _api-key:
88
9Logging in9Logging in
@@ -19,8 +19,9 @@
19.. only:: html19.. only:: html
20.. image:: media/maascli-prefs.*20.. image:: media/maascli-prefs.*
2121
22A new page will load... 22A new page will load...
2323
24.. only:: html
24.. image:: media/maascli-key.*25.. image:: media/maascli-key.*
2526
26The very first item is a list of MAAS keys. One will have already been27The very first item is a list of MAAS keys. One will have already been
@@ -30,21 +31,21 @@
3031
31 $ maas-cli login <profile-name> <hostname> <key>32 $ maas-cli login <profile-name> <hostname> <key>
3233
33The profile created is an easy way of associating your credentials with any 34The profile created is an easy way of associating your credentials
34subsequent call to the API. So an example login might look like this::35with any subsequent call to the API. So an example login might look
36like this::
3537
36$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te238$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
3739
38which creates the profile 'maas' and registers it with the given key at the 40which creates the profile 'maas' and registers it with the given key
39specified API endpoint.41at the specified API endpoint. If you omit the credentials, they will
40If you omit the credentials, they will be prompted for in the console. It is 42be prompted for in the console. It is also possible to use a hyphen,
41also possible to use a hyphen, '-' in place of the credentials. In this case a 43'-' in place of the credentials. In this case a single line will be
42single line will be read from stdin, stripped of any whitespace and used as the 44read from stdin, stripped of any whitespace and used as the
43credentials, which can be useful if you are devolping scripts for specific 45credentials, which can be useful if you are devolping scripts for
44tasks.46specific tasks. If an empty string is passed instead of the
45If an empty string is passed instead of the credentials, the profile will be 47credentials, the profile will be logged in anonymously (and
46logged in anonymously (and consequently some of the API calls will not be 48consequently some of the API calls will not be available)
47available)
4849
4950
50maas-cli commands51maas-cli commands
@@ -76,7 +77,7 @@
76 Logs in to the MAAS controller API at the given URL, using the key77 Logs in to the MAAS controller API at the given URL, using the key
77 provided and associates this connection with the given profile name.78 provided and associates this connection with the given profile name.
7879
79:samp:`logout <profile>` 80:samp:`logout <profile>`
8081
81 Logs out from the given profile, flushing the stored credentials.82 Logs out from the given profile, flushing the stored credentials.
8283
@@ -107,12 +108,12 @@
107:samp:`-d, --debug`108:samp:`-d, --debug`
108109
109 Displays debug information listing the API responses.110 Displays debug information listing the API responses.
110 111
111:samp:`-h, --help`112:samp:`-h, --help`
112113
113 Display usage information.114 Display usage information.
114115
115:samp:`-k, --insecure` 116:samp:`-k, --insecure`
116117
117 Disables the SSL certificate check.118 Disables the SSL certificate check.
118119
@@ -126,8 +127,6 @@
126 Removes the given key from the list of authorisation tokens.127 Removes the given key from the list of authorisation tokens.
127128
128129
129
130
131.. boot-images - not useful in user context130.. boot-images - not useful in user context
132.. ^^^^^^^^^^^131.. ^^^^^^^^^^^
133132
@@ -158,51 +157,50 @@
158 Releases the node given by *<system_id>*157 Releases the node given by *<system_id>*
159158
160:samp:`start <system_id>`159:samp:`start <system_id>`
161 160
162 Powers up the node identified by *<system_id>* (where MAAS has161 Powers up the node identified by *<system_id>* (where MAAS has
163 information for power management for this node).162 information for power management for this node).
164163
165:samp:`stop <system_id>`164:samp:`stop <system_id>`
166 165
167 Powers off the node identified by *<system_id>* (where MAAS has166 Powers off the node identified by *<system_id>* (where MAAS has
168 information for power management for this node).167 information for power management for this node).
169168
170:samp:`delete <system_id>`169:samp:`delete <system_id>`
171 170
172 Removes the given node from the MAAS database.171 Removes the given node from the MAAS database.
173172
174:samp:`read <system_id>`173:samp:`read <system_id>`
175 174
176 Returns all the current known information about the node specified175 Returns all the current known information about the node specified
177 by *<system_id>*176 by *<system_id>*
178177
179:samp:`update <system_id> [parameters...]`178:samp:`update <system_id> [parameters...]`
180 179
181 Used to change or set specific values for the node. The valid180 Used to change or set specific values for the node. The valid
182 parameters are listed below::181 parameters are listed below::
183182
184 hostname=<value>183 hostname=<value>
185 The new hostname for this node.184 The new hostname for this node.
186185
187 architecture=<value> 186 architecture=<value>
188 Sets the architecture type, where <value>187 Sets the architecture type, where <value>
189 is a string containing a valid architecture type,188 is a string containing a valid architecture type,
190 e.g. "i386/generic"189 e.g. "i386/generic"
191190
192 power_type=<value> 191 power_type=<value>
193 Apply the given dotted decimal value as the broadcast IP address 192 Apply the given dotted decimal value as the broadcast IP address
194 for this subnet.193 for this subnet.
195194
196 power_parameters_{param1}... =<value> 195 power_parameters_{param1}... =<value>
197 Set the given power parameters. Note that the valid options for these 196 Set the given power parameters. Note that the valid options for these
198 depend on the power type chosen.197 depend on the power type chosen.
199198
200 power_parameters_skip_check 'true' | 'false' 199 power_parameters_skip_check 'true' | 'false'
201 Whether to sanity check the supplied parameters against this node's 200 Whether to sanity check the supplied parameters against this node's
202 declared power type. The default is 'false'.201 declared power type. The default is 'false'.
203202
204203
205
206.. _cli-power:204.. _cli-power:
207205
208Example: Setting the power parameters for an ipmi enabled node::206Example: Setting the power parameters for an ipmi enabled node::
@@ -214,8 +212,6 @@
214 power_parameters_power_pass=ubuntu;212 power_parameters_power_pass=ubuntu;
215213
216214
217
218
219nodes215nodes
220^^^^^216^^^^^
221217
@@ -295,7 +291,6 @@
295 $ maas-cli maas nodes list architecture="i386/generic"291 $ maas-cli maas nodes list architecture="i386/generic"
296292
297293
298
299node-groups294node-groups
300^^^^^^^^^^^295^^^^^^^^^^^
301Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k296Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
@@ -306,7 +301,7 @@
306:samp:`-d, --debug`301:samp:`-d, --debug`
307302
308 Displays debug information listing the API responses.303 Displays debug information listing the API responses.
309 304
310:samp:`-h, --help`305:samp:`-h, --help`
311306
312 Display usage information.307 Display usage information.
@@ -316,7 +311,7 @@
316 Disables the SSL certificate check.311 Disables the SSL certificate check.
317312
318:samp:`register uuid=<value> name=<value> interfaces=<json_string>`313:samp:`register uuid=<value> name=<value> interfaces=<json_string>`
319 314
320 Registers a new node group with the given name and uuid. The315 Registers a new node group with the given name and uuid. The
321 interfaces parameter must be supplied in the form of a JSON string316 interfaces parameter must be supplied in the form of a JSON string
322 comprising the key/value data for the interface to be used, for317 comprising the key/value data for the interface to be used, for
@@ -327,7 +322,7 @@
327322
328:samp:`list`323:samp:`list`
329324
330 Returns a JSON list of all currently defined node groups. 325 Returns a JSON list of all currently defined node groups.
331326
332:samp:`refresh_workers`327:samp:`refresh_workers`
333328
@@ -338,7 +333,7 @@
338 nodes.333 nodes.
339334
340:samp:`accept <uuid>`335:samp:`accept <uuid>`
341 336
342 Accepts a node-group or number of nodegroups indicated by the337 Accepts a node-group or number of nodegroups indicated by the
343 supplied UUID338 supplied UUID
344339
@@ -348,10 +343,9 @@
348 supplied UUID343 supplied UUID
349344
350345
351
352node-group-interface346node-group-interface
353^^^^^^^^^^^^^^^^^^^^347^^^^^^^^^^^^^^^^^^^^
354For managing the interfaces. See also :ref:`node_group_interfaces`348For managing the interfaces. See also :ref:`node-group-interfaces`
355349
356Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h350Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
357--help] [-k --insecure] read | update | delete [parameters...]351--help] [-k --insecure] read | update | delete [parameters...]
@@ -359,50 +353,50 @@
359..program:: maas-cli node-group-interface353..program:: maas-cli node-group-interface
360354
361:samp:`read <uuid> <interface>`355:samp:`read <uuid> <interface>`
362 356
363 Returns the current settings for the given UUID and interface357 Returns the current settings for the given UUID and interface
364358
365:samp:`update [parameters]`359:samp:`update [parameters]`
366 360
367 Changes the settings for the interface according to the given361 Changes the settings for the interface according to the given
368 parameters::362 parameters::
369363
370 management= 0 | 1 | 2364 management= 0 | 1 | 2
371 The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP 365 The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
372 and DNS).366 and DNS).
373367
374 subnet_mask=<value>368 subnet_mask=<value>
375 Apply the given dotted decimal value as the subnet mask.369 Apply the given dotted decimal value as the subnet mask.
376370
377 broadcast_ip=<value>371 broadcast_ip=<value>
378 Apply the given dotted decimal value as the broadcast IP address for 372 Apply the given dotted decimal value as the broadcast IP address for
379 this subnet.373 this subnet.
380374
381 router_ip=<value>375 router_ip=<value>
382 Apply the given dotted decimal value as the default router address 376 Apply the given dotted decimal value as the default router address
383 for this subnet.377 for this subnet.
384378
385 ip_range_low=<value>379 ip_range_low=<value>
386 The lowest value of IP address to allocate via DHCP380 The lowest value of IP address to allocate via DHCP
387381
388 ip_range_high=<value>382 ip_range_high=<value>
389 The highest value of IP address to allocate via DHCP 383 The highest value of IP address to allocate via DHCP
390384
391:samp:`delete <uuid> <interface>`385:samp:`delete <uuid> <interface>`
392386
393 Removes the entry for the given UUID and interface.387 Removes the entry for the given UUID and interface.
394 388
395.. _cli-dhcp:389.. _cli-dhcp:
396390
397Example:391Example:
398Configuring DHCP and DNS.392Configuring DHCP and DNS.
399393
400To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant 394To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
401interface information. To do this we need to first determine the UUID of the395interface information. To do this we need to first determine the UUID of the
402node group affected::396node group affected::
403397
404 $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)398 $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)
405 399
406Once we have the UUID we can use this to update the node-group-interface for400Once we have the UUID we can use this to update the node-group-interface for
407that nodegroup, and pass it the relevant interface details::401that nodegroup, and pass it the relevant interface details::
408402
@@ -413,12 +407,13 @@
413 broadcast_ip=192.168.123.255 \407 broadcast_ip=192.168.123.255 \
414 router_ip=192.168.123.1 \408 router_ip=192.168.123.1 \
415409
416Replacing the example values with those required for this network. The only 410Replacing the example values with those required for this network. The
417non-obvious parameter is 'management' which takes the values 0 (no management), 1411only non-obvious parameter is 'management' which takes the values 0
418(manage DHCP) and 2 (manage DHCP and DNS).412(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
419413
420414
421.. _node-group-interfaces415.. _node-group-interfaces:
416
422node-group-interfaces417node-group-interfaces
423^^^^^^^^^^^^^^^^^^^^^418^^^^^^^^^^^^^^^^^^^^^
424419
@@ -433,7 +428,7 @@
433:samp:`-d, --debug`428:samp:`-d, --debug`
434429
435 Displays debug information listing the API responses.430 Displays debug information listing the API responses.
436 431
437:samp:`-h, --help`432:samp:`-h, --help`
438433
439 Display usage information.434 Display usage information.
@@ -447,25 +442,24 @@
447 Lists the current stored configurations for the given identifier442 Lists the current stored configurations for the given identifier
448 <label> in a key:value format which should be easy to decipher.443 <label> in a key:value format which should be easy to decipher.
449444
450
451:samp:`new <label> ip=<value> interface=<if_device> [parameters...]`445:samp:`new <label> ip=<value> interface=<if_device> [parameters...]`
452 446
453 Creates a new interface group. The required parameters are the IP447 Creates a new interface group. The required parameters are the IP
454 address and the network interface this appies to (e.g. eth0). In448 address and the network interface this appies to (e.g. eth0). In
455 order to do anything useful, further parameters are required::449 order to do anything useful, further parameters are required::
456450
457 management= 0 | 1 | 2 451 management= 0 | 1 | 2
458 The service to be managed on the interface452 The service to be managed on the interface
459 ( 0= none, 1=DHCP, 2=DHCP and DNS).453 ( 0= none, 1=DHCP, 2=DHCP and DNS).
460454
461 subnet_mask=<value>455 subnet_mask=<value>
462 Apply the given dotted decimal value as the subnet mask.456 Apply the given dotted decimal value as the subnet mask.
463457
464 broadcast_ip=<value> 458 broadcast_ip=<value>
465 Apply the given dotted decimal value as the459 Apply the given dotted decimal value as the
466 broadcast IP address for this subnet.460 broadcast IP address for this subnet.
467461
468 router_ip=<value> 462 router_ip=<value>
469 Apply the given dotted decimal value as the463 Apply the given dotted decimal value as the
470 default router address for this subnet.464 default router address for this subnet.
471465
@@ -476,18 +470,16 @@
476 The highest value of IP address to allocate via DHCP470 The highest value of IP address to allocate via DHCP
477471
478472
479473tag
480
481tag
482^^^474^^^
483475
484Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |476Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
485 nodes | delete 477 nodes | delete
486478
487.. program:: maas-cli tag479.. program:: maas-cli tag
488480
489:samp:`read <tag_name>`481:samp:`read <tag_name>`
490 482
491 Returns information on the tag specified by <name>483 Returns information on the tag specified by <name>
492484
493:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]`485:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]`
@@ -500,10 +492,10 @@
500492
501:samp:`rebuild`493:samp:`rebuild`
502494
503 Triggers a rebuild of the tag to node mapping. 495 Triggers a rebuild of the tag to node mapping.
504496
505:samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`497:samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`
506 498
507 Updates the tag identified by tag_name. Any or all of name,comment499 Updates the tag identified by tag_name. Any or all of name,comment
508 and definition may be supplied as parameters. If no parameters are500 and definition may be supplied as parameters. If no parameters are
509 supplied, this command returns the current values.501 supplied, this command returns the current values.
@@ -516,12 +508,17 @@
516508
517 Deletes the given tag.509 Deletes the given tag.
518510
519tags 511
520^^^^ 512tags
521Tags are a really useful way of identifying nodes with particular 513^^^^
522characteristics. 514
523515Tags are a really useful way of identifying nodes with particular
524.. only:: html For more information on how to use them effectively, please see :ref:`deploy-tags`516characteristics.
517
518.. only:: html
519
520 For more information on how to use them effectively, please see
521 :ref:`deploy-tags`
525522
526Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k523Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
527--insecure] list | new524--insecure] list | new
@@ -531,39 +528,38 @@
531:samp:`-d, --debug`528:samp:`-d, --debug`
532529
533 Displays debug information listing the API responses.530 Displays debug information listing the API responses.
534 531
535:samp:`-h, --help`532:samp:`-h, --help`
536533
537 Display usage information.534 Display usage information.
538535
539:samp:`-k, --insecure` 536:samp:`-k, --insecure`
540537
541 Disables the SSL certificate check.538 Disables the SSL certificate check.
542539
543:samp:`list`540:samp:`list`
544 541
545 Returns a JSON object listing all the current tags known by the MAAS server542 Returns a JSON object listing all the current tags known by the MAAS server
546543
547:samp:`create name=<value> definition=<value> [comment=<value>]`544:samp:`create name=<value> definition=<value> [comment=<value>]`
548545
549 Creates a new tag with the given name and definition. A comment is546 Creates a new tag with the given name and definition. A comment is
550 optional. Names must be unique, obviously - an error will be547 optional. Names must be unique, obviously - an error will be
551 returned if the given name already exists. The definition is in the form of 548 returned if the given name already exists. The definition is in the
552 an XPath expression which parses the XML returned by running ``lshw`` on the 549 form of an XPath expression which parses the XML returned by
553 node.550 running ``lshw`` on the node.
554 551
555Example:552Example:
556Adding a tag to all nodes which have an Intel GPU::553Adding a tag to all nodes which have an Intel GPU::
557554
558 $ maas-cli maas tags new name='intel-gpu' \555 $ maas-cli maas tags new name='intel-gpu' \
559 comment='Machines which have an Intel display driver' \556 comment='Machines which have an Intel display driver' \
560 definition='contains(//node[@id="display"]/vendor, "Intel")557 definition='contains(//node[@id="display"]/vendor, "Intel")
561 558
562559
563unused commands 560unused commands
564^^^^^^^^^^^^^^^ 561^^^^^^^^^^^^^^^
562
565Because the ``maas-cli`` command exposes all of the API, it also lists563Because the ``maas-cli`` command exposes all of the API, it also lists
566some command options which are not really intended for end users, such564some command options which are not really intended for end users, such
567as the "file" and "boot-images" options.565as the "file" and "boot-images" options.
568
569
570566
=== modified file 'docs/man/maas-cli.8.rst'
--- docs/man/maas-cli.8.rst 2012-11-20 16:45:09 +0000
+++ docs/man/maas-cli.8.rst 2012-11-21 11:51:34 +0000
@@ -1,4 +1,3 @@
1
2maas-cli1maas-cli
3--------2--------
43
@@ -7,9 +6,9 @@
7^^^^^6^^^^^
87
9 $ maas-cli <profile> <command> [parameters]8 $ maas-cli <profile> <command> [parameters]
10 9
11The available commands are dependent on the API you are connecting to and the10The available commands are dependent on the API you are connecting to and the
12profile you use. The currently available options are explained below. 11profile you use. The currently available options are explained below.
1312
1413
15Description14Description
@@ -17,12 +16,14 @@
1716
18.. include:: ../maascli.rst17.. include:: ../maascli.rst
1918
19
20Further Documentation20Further Documentation
21^^^^^^^^^^^^^^^^^^^^^21^^^^^^^^^^^^^^^^^^^^^
22
22For more documentation of MAAS, please see https://maas.ubuntu.com/docs23For more documentation of MAAS, please see https://maas.ubuntu.com/docs
2324
25
24See Also26See Also
25^^^^^^^^27^^^^^^^^
28
26`maas`29`maas`
27
28
2930
=== modified file 'docs/man/maas.8.rst'
--- docs/man/maas.8.rst 2012-11-20 16:45:09 +0000
+++ docs/man/maas.8.rst 2012-11-21 11:51:34 +0000
@@ -1,23 +1,25 @@
1maas1maas
2----2----
33
4USAGE4
5Usage
5^^^^^6^^^^^
67
7maas [-h, --help] createsuperuser | changepassword | shell8maas [-h, --help] createsuperuser | changepassword | shell
89
9DESCRIPTION10
11Description
10^^^^^^^^^^^12^^^^^^^^^^^
1113
12The `maas` command is part of Canonical's Metal As A Service software. It is 14The `maas` command is part of Canonical's Metal As A Service software. It is
13derived from and can be used similarly to the `django-admin` command, and must 15derived from and can be used similarly to the `django-admin` command, and must
14be run with root privileges. 16be run with root privileges.
1517
16For the end user, there are only three subcommands of interest.18For the end user, there are only three subcommands of interest.
1719
18**createsuperuser**20**createsuperuser**
19 This subcommand is used to create a superuser for the21 This subcommand is used to create a superuser for the
20 MAAS install. The suggested username is "root". This command usually only 22 MAAS install. The suggested username is "root". This command usually only
21 needs to be run when installing MAAS for the first time.23 needs to be run when installing MAAS for the first time.
2224
23**changepassword**25**changepassword**
@@ -26,16 +28,18 @@
26 enter it once again to verify.28 enter it once again to verify.
2729
28**shell**30**shell**
29 This subcommand may be useful for debugging installed systems. It 31 This subcommand may be useful for debugging installed systems. It
30 will open a new python shell environment with the correct django environment32 will open a new python shell environment with the correct django environment
31 for working with the installed MAAS software.33 for working with the installed MAAS software.
3234
33 35
34Further Documentation36Further Documentation
35^^^^^^^^^^^^^^^^^^^^^37^^^^^^^^^^^^^^^^^^^^^
38
36For more documentation of MAAS, please see https://maas.ubuntu.com/docs39For more documentation of MAAS, please see https://maas.ubuntu.com/docs
3740
41
38See Also42See Also
39^^^^^^^^43^^^^^^^^
44
40`maas-cli`45`maas-cli`
41
4246
=== modified file 'docs/nodes.rst'
--- docs/nodes.rst 2012-10-11 13:23:54 +0000
+++ docs/nodes.rst 2012-11-21 11:51:34 +0000
@@ -1,10 +1,10 @@
1
2
3Adding nodes to the system1Adding nodes to the system
4==========================2==========================
53
6Now 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>`4Now that the MAAS controller is running, we need to make the nodes
75aware of MAAS and vice-versa. If you have set up DHCP correctly, and
6your nodes can boot via PXE then things really couldn't be much easier
7and you can use :ref:`the automatic discovery procedure <auto-enlist>`
88
99
10.. _auto-enlist:10.. _auto-enlist:
@@ -12,21 +12,29 @@
12Automatic Discovery12Automatic Discovery
13-------------------13-------------------
1414
15With 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.15With nodes set to boot from a PXE image, they will start, look for a
1616DHCP server, receive the PXE boot details, boot the image, contact the
17During 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.17MAAS server and shut down.
18When the nodes have been accepted the selected series of Ubuntu will be installed.18
1919During this process, the MAAS server will be passed information about
20To 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>`::20the node, including the architecture, MAC address and other details
21which will be stored in the database of nodes. You can accept and
22comission the nodes via the web interface. When the nodes have been
23accepted the selected series of Ubuntu will be installed.
24
25To save time, you can also accept and commission all nodes from the
26commandline. This requires that you first login with the API key,
27which :ref:`you can retrieve from the web interface <api-key>`::
2128
22 $ maas-cli maas nodes accept-all29 $ maas-cli maas nodes accept-all
2330
2431
25
26Enlist nodes via boot media32Enlist nodes via boot media
27---------------------------33---------------------------
2834
29Using 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.35Using Boot media such as an AVAHI boot image or the Ubuntu Server
36install disk, it is possible to perform the discovery and enlistment
37process without using DHCP/PXE.
3038
31Boot from the media and follow the instructions.39Boot from the media and follow the instructions.
3240
@@ -34,4 +42,5 @@
34Manually add nodes42Manually add nodes
35------------------43------------------
3644
37If you know the MAC address of a node, you can manually enter details about the node through the web interface.45If you know the MAC address of a node, you can manually enter details
46about the node through the web interface.
3847
=== modified file 'docs/orientation.rst'
--- docs/orientation.rst 2012-10-04 15:14:12 +0000
+++ docs/orientation.rst 2012-11-21 11:51:34 +0000
@@ -1,30 +1,46 @@
1.. _orientation:1.. _orientation:
2 2
3Orientation3Orientation
4===========4===========
55
6
6MAAS in Brief7MAAS in Brief
7-------------8-------------
89
9Canonical’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.10Canonical’s MAAS brings the dynamism of cloud computing to the world
1011of physical provisioning and Ubuntu. Connect, commission and deploy
11MAAS 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.12physical servers in record time, re-allocate nodes between services
1213dynamically, and keep them up to date and in due course, retire them
13In 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.14from use.
15
16MAAS is a new way of thinking about physical infrastructure. Compute,
17storage and network are commodities in the virtual world, and for
18large-scale deployments the same is true of the metal. “Metal as a
19service” lets you treat farms of servers as a malleable resource for
20allocation to specific problems, and re-allocation on a dynamic basis.
21
22In conjunction with the Juju service orchestration software (see
23https://juju.ubuntu.com/docs/), MAAS will enable you to get the most
24out of your physical hardware and dynamically deploy complex services
25with ease and confidence.
26
1427
15Do I Need MAAS?28Do I Need MAAS?
16---------------29---------------
1730
18MAAS certainly isn't for everyone, but why not ask yourself these questions? 31MAAS certainly isn't for everyone, but why not ask yourself these
32questions?
1933
20You probably *SHOULD* use MAAS if any or all of the following statements are true:34You probably *SHOULD* use MAAS if any or all of the following
35statements are true:
2136
22 * You are trying to manage many physical servers.37 * You are trying to manage many physical servers.
23 * You want to deploy services with the minimum fuss.38 * You want to deploy services with the minimum fuss.
24 * You need to get the most from your resources.39 * You need to get the most from your resources.
25 * You want things to work, repeatably and reliably.40 * You want things to work, repeatably and reliably.
2641
27You probably don't need MAAS if any or all of these statements are true:42You probably don't need MAAS if any or all of these statements are
43true:
2844
29 * You don't need to manage physical hardware45 * You don't need to manage physical hardware
30 * You relish time spent in the server room46 * You relish time spent in the server room
@@ -36,17 +52,18 @@
36A Typical MAAS setup52A Typical MAAS setup
37--------------------53--------------------
3854
39MAAS 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:55MAAS is designed to work with your physical hardware, whether your
56setup includes thousands of server boxes or only a few. The key
57components of the MAAS software are:
4058
41 * Region controller59 * Region controller
42 * Cluster controller(s)60 * Cluster controller(s)
43 * Nodes61 * Nodes
4462
45For 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). 63For small (in terms of number of nodes) setups, you will probably just
64install the Region controller and a cluster controller on the same
65server - it is only worth having multiple region controllers if you
66need to organise your nodes into different subnets (e.g. if you have a
67lot of nodes).
4668
47.. image:: media/orientation_architecture-diagram.*69.. image:: media/orientation_architecture-diagram.*
48
49
50
51
52
5370
=== modified file 'docs/tags.rst'
--- docs/tags.rst 2012-10-25 13:09:16 +0000
+++ docs/tags.rst 2012-11-21 11:51:34 +0000
@@ -1,65 +1,69 @@
1
2.. _deploy-tags:1.. _deploy-tags:
2
3Making use of Tags3Making use of Tags
4==================4==================
55
6MAAS implements a system of tags based on the physical properties of the nodes.6MAAS implements a system of tags based on the physical properties of
7The idea behind this is that you can use the tags to identify nodes with7the nodes. The idea behind this is that you can use the tags to
8particular abilities which may be useful when it comes to deploying services.8identify nodes with particular abilities which may be useful when it
99comes to deploying services.
10A real world example of this might be to identify nodes which have fast GPUs 10
11installed, if you were planning on deploying software which used CUDA or 11A real world example of this might be to identify nodes which have
12OpenCL which would make use of this hardware.12fast GPUs installed, if you were planning on deploying software which
13used CUDA or OpenCL which would make use of this hardware.
14
1315
14Tag definitions16Tag definitions
15---------------17---------------
1618
17
18Before we can create a tag we need to know how we will select which nodes it19Before we can create a tag we need to know how we will select which nodes it
19gets applied to. MAAS collects hardware information from the nodes using the 20gets applied to. MAAS collects hardware information from the nodes using the
20`"lshw" utility <http://ezix.org/project/wiki/HardwareLiSter>`_ to return 21`"lshw" utility <http://ezix.org/project/wiki/HardwareLiSter>`_ to return
21detailed information in XML format. The definitions used in creating a tag are 22detailed information in XML format. The definitions used in creating a tag are
22then constructed using XPath expressions.23then constructed using XPath expressions.
23If you are unfamiliar with XPath expressions, it is well worth checking out the 24If you are unfamiliar with XPath expressions, it is well worth checking out the
24`w3schools documentation <http://www.w3schools.com/xpath/xpath_syntax.asp>`_.25`w3schools documentation <http://www.w3schools.com/xpath/xpath_syntax.asp>`_.
25For the lshw XML, we will just check all the available nodes for some properties.26For the lshw XML, we will just check all the available nodes for some properties.
26In our example case, we might want to find GPUs with a clock speed of over 1GHz. 27In our example case, we might want to find GPUs with a clock speed of over 1GHz.
27In this case, the relevant XML node from the output will be labelled "display"28In this case, the relevant XML node from the output will be labelled "display"
28and does have a property called clock, so it will look like this::29and does have a property called clock, so it will look like this::
29 30
30 //node[@id="display"]/clock > 100000000031 //node[@id="display"]/clock > 1000000000
3132
32Now we have a definition, we can go ahead and create a tag.33Now we have a definition, we can go ahead and create a tag.
3334
35
34Creating a tag36Creating a tag
35--------------37--------------
3638
37Once we have sorted out what definition we will be using, creating the tag is 39Once we have sorted out what definition we will be using, creating the
38easy using the ``maas-cli`` command. You will need to :ref:`be logged in to the API first <api-key>`::40tag is easy using the ``maas-cli`` command. You will need to :ref:`be
41logged in to the API first <api-key>`::
3942
40 $ maas-cli maas tags new name='gpu' \43 $ maas-cli maas tags new name='gpu' \
41 comment='GPU with clock speed >1GHz for running CUDA type operations.' \44 comment='GPU with clock speed >1GHz for running CUDA type operations.' \
42 definition='//node[@id="display"]/clock > 1000000000'45 definition='//node[@id="display"]/clock > 1000000000'
4346
44The comment is really for your benefit. It pays to keep the actual tag name 47The comment is really for your benefit. It pays to keep the actual tag name
45short and to the point as you will be using it frequently in commands, but it 48short and to the point as you will be using it frequently in commands, but it
46may subsequently be hard to work out what exactly was the difference between49may subsequently be hard to work out what exactly was the difference between
47tags like "gpu" and "fastgpu" unless you have a good comment. Something which 50tags like "gpu" and "fastgpu" unless you have a good comment. Something which
48explains the definition in plain language is always a good idea!51explains the definition in plain language is always a good idea!
4952
50To check which nodes this tag applies to we can use the tag command::53To check which nodes this tag applies to we can use the tag command::
5154
52 $ maas-cli maas tag nodes gpu 55 $ maas-cli maas tag nodes gpu
5356
54The process of updating the tags does take some time - not a lot of time, but 57The process of updating the tags does take some time - not a lot of time, but
55if nothing shows up straight away, try running the command again after a minute 58if nothing shows up straight away, try running the command again after a minute
56or so.59or so.
5760
61
58Using the tag62Using the tag
59-------------63-------------
6064
61You can use the tag in the web interface to discover applicable nodes, but the 65You can use the tag in the web interface to discover applicable nodes, but the
62real significance of it is when using juju to deploy services. Tags can be used 66real significance of it is when using juju to deploy services. Tags can be used
63with juju constraints to make sure that a particular service only gets deployed67with juju constraints to make sure that a particular service only gets deployed
64on hardware with the tag you have created.68on hardware with the tag you have created.
6569
@@ -68,12 +72,11 @@
6872
69 $ juju deploy --constraints maas-tags=gpu cuda73 $ juju deploy --constraints maas-tags=gpu cuda
7074
71You could list several tags if required, and mix in other juju constraints if 75You could list several tags if required, and mix in other juju constraints if
72needed::76needed::
7377
74 $ juju deploy --constraints "mem=1024 maas-tags=gpu,intel" cuda78 $ juju deploy --constraints "mem=1024 maas-tags=gpu,intel" cuda
75 79
76
7780
78Manually assigning tags81Manually assigning tags
79-----------------------82-----------------------
@@ -81,7 +84,7 @@
81MAAS supports the creation of arbitrary tags which don't depend on XPath84MAAS supports the creation of arbitrary tags which don't depend on XPath
82definitions ("nodes which make a lot of noise" perhaps). If a tag is created85definitions ("nodes which make a lot of noise" perhaps). If a tag is created
83without specifying the definition parameter then it will simply be ignored by86without specifying the definition parameter then it will simply be ignored by
84tag refresh mechanism, but the MAAS administrator will be able to manually add 87tag refresh mechanism, but the MAAS administrator will be able to manually add
85and remove the tag from specific nodes.88and remove the tag from specific nodes.
8689
87In this example we are assuming you are using the 'maas' profile and you want90In this example we are assuming you are using the 'maas' profile and you want
@@ -90,10 +93,10 @@
90 $ maas-cli maas tags new name='my_tag' comment='nodes which go ping'93 $ maas-cli maas tags new name='my_tag' comment='nodes which go ping'
91 $ maas-cli maas tag update-nodes my_tag add="<system_id>"94 $ maas-cli maas tag update-nodes my_tag add="<system_id>"
9295
93The first line creates a new tag but omits the definition, so no nodes are 96The first line creates a new tag but omits the definition, so no nodes are
94automatically added to it. The second line applies that tag to a specific node 97automatically added to it. The second line applies that tag to a specific node
95referenced by its system id property.98referenced by its system id property.
96 99
97You can easily remove a tag from a particular node, or indeed add100You can easily remove a tag from a particular node, or indeed add
98and remove them at the same time::101and remove them at the same time::
99102
@@ -105,7 +108,7 @@
105subsequently edit it to remove the definition. From this point the tag behaves108subsequently edit it to remove the definition. From this point the tag behaves
106as if you had manually created it, but it still retains all the existing109as if you had manually created it, but it still retains all the existing
107associations it has with nodes. This is particularly useful if you have some110associations it has with nodes. This is particularly useful if you have some
108hardware which is conceptually similar but doesn't easily fit within a single 111hardware which is conceptually similar but doesn't easily fit within a single
109tag definition::112tag definition::
110113
111 $ maas-cli maas tag new name='my_tag' comment='nodes I like ' \114 $ maas-cli maas tag new name='my_tag' comment='nodes I like ' \
@@ -113,15 +116,7 @@
113 $ maas-cli maas tag update my_tag definition=''116 $ maas-cli maas tag update my_tag definition=''
114 $ maas-cli mass tag update-nodes my_tag add=<system_id>117 $ maas-cli mass tag update-nodes my_tag add=<system_id>
115118
116
117.. tip::119.. tip::
120
118 If you add and remove the same node in one operation, it ends up having121 If you add and remove the same node in one operation, it ends up having
119 the tag removed (even if the tag was in place before the operation).122 the tag removed (even if the tag was in place before the operation).
120
121
122
123
124
125
126
127
128123
=== modified file 'docs/troubleshooting.rst'
--- docs/troubleshooting.rst 2012-10-12 12:51:17 +0000
+++ docs/troubleshooting.rst 2012-11-21 11:51:34 +0000
@@ -1,6 +1,7 @@
1********************1********************
2MAAS Troubleshooting2MAAS Troubleshooting
3********************3********************
4
4Some parts of MAAS may still be a little confusing, and sometimes you might be5Some parts of MAAS may still be a little confusing, and sometimes you might be
5trying to do things that are just plain impossible. This section covers some of6trying to do things that are just plain impossible. This section covers some of
6the most commonly encountered problems and tries its best to make them gone.7the most commonly encountered problems and tries its best to make them gone.
@@ -13,8 +14,10 @@
13**Nodes hang on "Commissioning"**14**Nodes hang on "Commissioning"**
14=================================15=================================
1516
17
16Possible Cause: Timing issues18Possible Cause: Timing issues
17-----------------------------19-----------------------------
20
18Various parts of MAAS rely on OAuth to negotiate a connection to nodes. If the21Various parts of MAAS rely on OAuth to negotiate a connection to nodes. If the
19current time reported by the hardware clock on your node differs significantly22current time reported by the hardware clock on your node differs significantly
20from that on the MAAS server, the connection will not be made.23from that on the MAAS server, the connection will not be made.
@@ -23,6 +26,7 @@
23adjust them. This can usually be done from within the system BIOS, without26adjust them. This can usually be done from within the system BIOS, without
24needing to install an OS27needing to install an OS
2528
29
26Possible Cause: Network drivers30Possible Cause: Network drivers
27-------------------------------31-------------------------------
2832
@@ -34,17 +38,21 @@
34network adaptor. It *is* theoretically possible to modify the boot image to38network adaptor. It *is* theoretically possible to modify the boot image to
35include proprietary drivers, but it is not a straightforward task.39include proprietary drivers, but it is not a straightforward task.
3640
41
37**Nodes fail to PXE boot**42**Nodes fail to PXE boot**
38==========================43==========================
3944
45
40Possible Cause: Using an incorrectly configured VM46Possible Cause: Using an incorrectly configured VM
41--------------------------------------------------47--------------------------------------------------
48
42Some Virtual Machine setups include emulation of network hardware that does not49Some Virtual Machine setups include emulation of network hardware that does not
43support PXE booting, and in most setups, you will need to explicitly set up the50support PXE booting, and in most setups, you will need to explicitly set up the
44VM to boot via PXE. 51VM to boot via PXE.
4552
46**SOLUTION**: Consult the VM docs for details of PXE booting.53**SOLUTION**: Consult the VM docs for details of PXE booting.
4754
55
48Possible Cause: DHCP conflict56Possible Cause: DHCP conflict
49-----------------------------57-----------------------------
50If you are using MAAS in a setup with an existing DHCP, *DO NOT SET UP THE MAAS58If you are using MAAS in a setup with an existing DHCP, *DO NOT SET UP THE MAAS
@@ -53,7 +61,6 @@
5361
54**SOLUTION**: You will need to either:62**SOLUTION**: You will need to either:
5563
56
57* Configure your existing DHCP server to point to the MAAS server.64* Configure your existing DHCP server to point to the MAAS server.
5865
59 or66 or
@@ -62,30 +69,31 @@
62 this, please see https://wiki.ubuntu.com/ServerTeam/MAAS/AvahiBoot69 this, please see https://wiki.ubuntu.com/ServerTeam/MAAS/AvahiBoot
6370
6471
65
66**Can't log in to node**72**Can't log in to node**
67========================73========================
6874
69Sometimes you may wish to login directly to a node on your system. If you have75Sometimes you may wish to login directly to a node on your system. If
70set up Juju and MAAS, the attached nodes will automatically receive existing ssh76you have set up Juju and MAAS, the attached nodes will automatically
71keys and sets up ssh on the node to authenticate via key, so you can just login77receive existing ssh keys and sets up ssh on the node to authenticate
72with no password from the server.78via key, so you can just login with no password from the server.
73There is also an option in the MAAS web interface to add new ssh keys to the79There is also an option in the MAAS web interface to add new ssh keys
74nodes (via Preferences in the drop down menu which appears when clicking your80to the nodes (via Preferences in the drop down menu which appears when
75username in the top-right of the page).81clicking your username in the top-right of the page).
82
7683
77**Forgot MAAS superuser password**84**Forgot MAAS superuser password**
78==================================85==================================
7986
80As long as you have sudo privileges, this is not a disaster. You can use the87As long as you have sudo privileges, this is not a disaster. You can
81``maas`` command to change the password for the MAAS superuser on the MAAS88use the ``maas`` command to change the password for the MAAS superuser
82server:89on the MAAS server:
8390
84 ``sudo maas changepassword root``91 ``sudo maas changepassword root``
8592
8693
87**Need to reconfigure server IP address**94**Need to reconfigure server IP address**
88=========================================95=========================================
96
89If you made a mistake during setup or you just need to reconfigure your MAAS97If you made a mistake during setup or you just need to reconfigure your MAAS
90server, you can simply run the setup again:98server, you can simply run the setup again:
9199
@@ -109,7 +117,3 @@
109 #. If you are still getting "404 - Page not found" errors, check that the MAAS117 #. If you are still getting "404 - Page not found" errors, check that the MAAS
110 web interface has been installed in the right place. There should be a file118 web interface has been installed in the right place. There should be a file
111 present called /usr/share/maas/maas/urls.py119 present called /usr/share/maas/maas/urls.py
112
113
114
115