launchpad-reviewers team mailing list archive
-
launchpad-reviewers team
-
Mailing list archive
-
Message #14401
[Merge] lp:~allenap/maas/docs-and-man-tidy into lp:maas
Gavin Panella has proposed merging lp:~allenap/maas/docs-and-man-tidy into lp:maas with lp:~evilnick/maas/rm-import-pxe-references as a prerequisite.
Commit message:
Wrap and tidy documentation, and address many doc generation errors.
Requested reviews:
Launchpad code reviewers (launchpad-reviewers)
For more details, see:
https://code.launchpad.net/~allenap/maas/docs-and-man-tidy/+merge/135248
--
https://code.launchpad.net/~allenap/maas/docs-and-man-tidy/+merge/135248
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~allenap/maas/docs-and-man-tidy into lp:maas.
=== modified file '.bzrignore'
--- .bzrignore 2012-11-20 21:48:20 +0000
+++ .bzrignore 2012-11-20 21:48:20 +0000
@@ -10,7 +10,6 @@
./acceptance/source
./bin
./build
-./celerybeat-schedule
./db
./develop-eggs
./dist
@@ -22,6 +21,7 @@
./lib
./local
./logs/*
+./man
./media/demo/*
./media/development
./parts
@@ -31,4 +31,3 @@
./TAGS
./tags
dropin.cache
-./man
=== modified file 'INSTALL.txt'
--- INSTALL.txt 2012-11-20 21:48:20 +0000
+++ INSTALL.txt 2012-11-20 21:48:20 +0000
@@ -1,16 +1,18 @@
.. -*- mode: rst -*-
-
+
Installing MAAS
===============
There are two main ways to install MAAS
- * :ref:`From Ubuntu's package archive on an existing Ubuntu install. <pkg-install>`
- * :ref:`As a fresh install from Ubuntu Server install media. <disc-install>`
-
+ * :ref:`From Ubuntu's package archive on an existing Ubuntu
+ install. <pkg-install>`
+ * :ref:`As a fresh install from Ubuntu Server install
+ media. <disc-install>`
-If you are interested in testing the latest development version you can also check out the very latest source and build MAAS yourself.
+If you are interested in testing the latest development version you
+can also check out the very latest source and build MAAS yourself.
.. _pkg-install:
@@ -18,17 +20,34 @@
Installing MAAS from the archive
--------------------------------
-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:
+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:
- * ``maas`` - seed cloud setup, which includes both the region controller and the cluster controller below.
+ * ``maas`` - seed cloud setup, which includes both the region
+ controller and the cluster controller below.
* ``maas-region-controller`` - includes the web UI, API and database.
- * ``maas-cluster-controller`` - controls a group ("cluster") of nodes including DHCP management.
+ * ``maas-cluster-controller`` - controls a group ("cluster") of nodes
+ including DHCP management.
* ``maas-dhcp``/``maas-dns`` - required when managing dhcp/dns.
-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).
-
-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`
-
+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).
+
+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`
+
Install packages
^^^^^^^^^^^^^^^^
@@ -37,83 +56,118 @@
$ sudo apt-get install maas maas-dhcp maas-dns
-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.
+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.
-The configuration for the MAAS controller will automatically run and pop up this config screen:
+The configuration for the MAAS controller will automatically run and
+pop up this config screen:
.. image:: media/install_cluster-config.*
-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.
+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.
-Once the configuration scripts have run you should see this message telling you that the system is ready to use:
+Once the configuration scripts have run you should see this message
+telling you that the system is ready to use:
.. image:: media/install_controller-config.*
-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`
+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`
+
.. _disc-install:
Installing MAAS from Ubuntu Server boot media
---------------------------------------------
-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.
-Boot from the Ubuntu Server media and you will be greeted with the usual language selection screen:
+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. Boot from
+the Ubuntu Server media and you will be greeted with the usual
+language selection screen:
.. image:: media/install_01.*
-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.
+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.
.. image:: media/install_02.*
-The installer then runs through the usual language and keyboard options. Make your selections using Tab/Cursor keys/Enter to proceed through the install.
-The installer will then load various drivers, which may take a moment or two.
+The installer then runs through the usual language and keyboard
+options. Make your selections using Tab/Cursor keys/Enter to proceed
+through the install. The installer will then load various drivers,
+which may take a moment or two.
.. image:: media/install_03.*
-The next screen asks for the hostname for this server. Choose something appropriate for your network.
-
+The next screen asks for the hostname for this server. Choose
+something appropriate for your network.
.. image:: media/install_04.*
-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.
+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.
.. image:: media/install_05.*
-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!)
+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!)
.. image:: media/install_06.*
-As usual you will have the chance to encrypt your home directory. Continue to make selections based on whatever settings suit your usage.
+As usual you will have the chance to encrypt your home
+directory. Continue to make selections based on whatever settings suit
+your usage.
.. image:: media/install_07.*
-After making selections and partitioning storage, the system software will start to be installed. This part should only take a few minutes.
+After making selections and partitioning storage, the system software
+will start to be installed. This part should only take a few minutes.
.. image:: media/install_09.*
-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.
+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.
.. image:: media/install_10.*
-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)
+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)
.. image:: media/install_cluster-config.*
-The next screen will confirm the web address that will be used to the web interface.
+The next screen will confirm the web address that will be used to the
+web interface.
.. image:: media/install_controller-config.*
-After configuring any other packages the installer will finally come to and end. At this point you should eject the boot media.
+After configuring any other packages the installer will finally come
+to and end. At this point you should eject the boot media.
.. image:: media/install_14.*
-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.
-
+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.
.. image:: media/install_15.*
-
-**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::
+**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::
$ sudo apt-get install maas-dhcp maas-dns
@@ -121,13 +175,19 @@
.. _post_install:
+
Post-Install tasks
==================
-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:
+
+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:
.. image:: media/install_web-init.*
-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.
+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.
+
Create a superuser account
--------------------------
@@ -137,29 +197,37 @@
$ sudo maas createsuperuser
-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).
+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).
Import the boot images
----------------------
MAAS will check for and download new Ubuntu images once a week.
-However, you'll need to download them manually the first time. To do this you will need to
-connect to the MAAS API using the maas-cli tool. (see :ref:`api_key` for details of logging
-in).
-Then you need to run the command::
+However, you'll need to download them manually the first time. To do
+this you will need to connect to the MAAS API using the maas-cli
+tool. (see :ref:`Logging in <api-key>` for details). Then you need to
+run the command::
$ maas-cli maas node-groups import-boot-images
-(substitute in a different profile name for 'maas' if you have called yours something else)
-This will initiate downloading the required image files. Note that this may take some time
-depending on your network connection.
+(substitute in a different profile name for 'maas' if you have called
+yours something else) This will initiate downloading the required
+image files. Note that this may take some time depending on your
+network connection.
Login to the server
-------------------
-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.
+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.
.. image:: media/install-login.*
@@ -167,7 +235,9 @@
Configure DHCP
--------------
-If you are using MAAS to control DHCP, you need to set this via the web interface.
-However, if you are manually configuring a DHCP server, you should take a look at :ref:`manual-dhcp`
+If you are using MAAS to control DHCP, you need to set this via the
+web interface. However, if you are manually configuring a DHCP
+server, you should take a look at :ref:`manual-dhcp`
-Once everything is set up and running, you are ready to :doc:`start enlisting nodes <nodes>`
+Once everything is set up and running, you are ready to :doc:`start
+enlisting nodes <nodes>`
=== modified file 'Makefile'
--- Makefile 2012-11-20 21:48:20 +0000
+++ Makefile 2012-11-20 21:48:20 +0000
@@ -153,13 +153,13 @@
$(MAKE) -C acceptance $@
find . -type f -name '*.py[co]' -print0 | xargs -r0 $(RM)
find . -type f -name '*~' -print0 | xargs -r0 $(RM)
+ find . -type f -name dropin.cache -print0 | xargs -r0 $(RM)
$(RM) -r media/demo/* media/development
$(RM) $(js_enums)
$(RM) *.log
- $(RM) celerybeat-schedule
$(RM) docs/api.rst
- $(RM) -r docs/_autosummary
- $(RM) man/*
+ $(RM) -r docs/_autosummary docs/_build
+ $(RM) -r man
distclean: clean stop
$(RM) -r bin include lib local
@@ -167,9 +167,7 @@
$(RM) -r build dist logs/* parts
$(RM) tags TAGS .installed.cfg
$(RM) -r *.egg *.egg-info src/*.egg-info
- $(RM) -r docs/_build
$(RM) -r run/* services/*/supervise
- $(RM) twisted/plugins/dropin.cache
harness: bin/maas bin/database
$(dbrun) bin/maas shell --settings=maas.demo
=== modified file 'docs/about.rst'
--- docs/about.rst 2012-10-03 20:16:24 +0000
+++ docs/about.rst 2012-11-20 21:48:20 +0000
@@ -1,19 +1,35 @@
About this documentation
========================
-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.
-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.
+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.
+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.
+
Getting it
----------
-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.
-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
+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. 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
+
Contributing
------------
-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
-
-
-
+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
=== modified file 'docs/configure.rst'
--- docs/configure.rst 2012-10-03 20:16:24 +0000
+++ docs/configure.rst 2012-11-20 21:48:20 +0000
@@ -1,14 +1,19 @@
Additional Configuration
========================
+
.. _manual-dhcp:
Manual DHCP configuration
-------------------------
-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.
+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.
-At the very least the next-server should point to the MAAS controller host address and the filename should be set to pxelinux.0
+At the very least the next-server should point to the MAAS controller
+host address and the filename should be set to pxelinux.0
The configuration entry may look something like this::
@@ -21,7 +26,9 @@
range dynamic-bootp 192.168.122.5 192.168.122.135;
}
+
.. _ssl:
+
SSL Support
-----------
@@ -43,4 +50,3 @@
the default SSL certificate is insecure. Please generate your own and then
edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the
certificate.
-
=== modified file 'docs/index.rst'
--- docs/index.rst 2012-10-16 14:54:36 +0000
+++ docs/index.rst 2012-11-20 21:48:20 +0000
@@ -4,12 +4,12 @@
Metal As A Service: MAAS
########################
-
This is the documentation for the MAAS project http://maas.ubuntu.com
+
************
Introduction
-************
+************
.. toctree::
:maxdepth: 2
@@ -17,6 +17,7 @@
about
orientation
+
***************
Getting started
***************
@@ -27,7 +28,7 @@
install
configure
nodes
-
+
******************
Deploying services
@@ -38,7 +39,8 @@
juju-quick-start
tags
-
+
+
******************************
Using the maas-cli commandline
******************************
@@ -48,6 +50,7 @@
maascli
+
**********
Appendices
**********
@@ -56,11 +59,12 @@
:maxdepth: 2
troubleshooting
- hacking
+ hacking
api
models
enum
+
Indices and tables
==================
=== 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-20 21:48:20 +0000
@@ -156,5 +156,3 @@
Note that each charm runs on its own host, so each deployment will
actually take as long as it took to bootstrap. Have a beer, drown your
sorrows in liquor, or, my preference, have another cup of tea.
-
-----
=== modified file 'docs/maascli.rst'
--- docs/maascli.rst 2012-11-13 11:30:52 +0000
+++ docs/maascli.rst 2012-11-20 21:48:20 +0000
@@ -1,9 +1,9 @@
-
As well as the web interface, many tasks can be performed by accessing
the MAAS API directly through the maas-cli command. This section
details how to login with this tool and perform some common
operations.
+
.. _api-key:
Logging in
@@ -19,8 +19,9 @@
.. only:: html
.. image:: media/maascli-prefs.*
-A new page will load...
+A new page will load...
+.. only:: html
.. image:: media/maascli-key.*
The very first item is a list of MAAS keys. One will have already been
@@ -30,21 +31,21 @@
$ maas-cli login <profile-name> <hostname> <key>
-The profile created is an easy way of associating your credentials with any
-subsequent call to the API. So an example login might look like this::
+The profile created is an easy way of associating your credentials
+with any subsequent call to the API. So an example login might look
+like this::
$ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
-which creates the profile 'maas' and registers it with the given key at the
-specified API endpoint.
-If you omit the credentials, they will be prompted for in the console. It is
-also possible to use a hyphen, '-' in place of the credentials. In this case a
-single line will be read from stdin, stripped of any whitespace and used as the
-credentials, which can be useful if you are devolping scripts for specific
-tasks.
-If an empty string is passed instead of the credentials, the profile will be
-logged in anonymously (and consequently some of the API calls will not be
-available)
+which creates the profile 'maas' and registers it with the given key
+at the specified API endpoint. If you omit the credentials, they will
+be prompted for in the console. It is also possible to use a hyphen,
+'-' in place of the credentials. In this case a single line will be
+read from stdin, stripped of any whitespace and used as the
+credentials, which can be useful if you are devolping scripts for
+specific tasks. If an empty string is passed instead of the
+credentials, the profile will be logged in anonymously (and
+consequently some of the API calls will not be available)
maas-cli commands
@@ -76,7 +77,7 @@
Logs in to the MAAS controller API at the given URL, using the key
provided and associates this connection with the given profile name.
-:samp:`logout <profile>`
+:samp:`logout <profile>`
Logs out from the given profile, flushing the stored credentials.
@@ -107,12 +108,12 @@
:samp:`-d, --debug`
Displays debug information listing the API responses.
-
+
:samp:`-h, --help`
Display usage information.
-:samp:`-k, --insecure`
+:samp:`-k, --insecure`
Disables the SSL certificate check.
@@ -126,8 +127,6 @@
Removes the given key from the list of authorisation tokens.
-
-
.. boot-images - not useful in user context
.. ^^^^^^^^^^^
@@ -158,51 +157,50 @@
Releases the node given by *<system_id>*
:samp:`start <system_id>`
-
+
Powers up the node identified by *<system_id>* (where MAAS has
information for power management for this node).
:samp:`stop <system_id>`
-
+
Powers off the node identified by *<system_id>* (where MAAS has
information for power management for this node).
:samp:`delete <system_id>`
-
+
Removes the given node from the MAAS database.
:samp:`read <system_id>`
-
+
Returns all the current known information about the node specified
by *<system_id>*
:samp:`update <system_id> [parameters...]`
-
+
Used to change or set specific values for the node. The valid
parameters are listed below::
hostname=<value>
The new hostname for this node.
- architecture=<value>
+ architecture=<value>
Sets the architecture type, where <value>
is a string containing a valid architecture type,
e.g. "i386/generic"
- power_type=<value>
- Apply the given dotted decimal value as the broadcast IP address
+ power_type=<value>
+ Apply the given dotted decimal value as the broadcast IP address
for this subnet.
- power_parameters_{param1}... =<value>
- Set the given power parameters. Note that the valid options for these
+ power_parameters_{param1}... =<value>
+ Set the given power parameters. Note that the valid options for these
depend on the power type chosen.
- power_parameters_skip_check 'true' | 'false'
- Whether to sanity check the supplied parameters against this node's
+ power_parameters_skip_check 'true' | 'false'
+ Whether to sanity check the supplied parameters against this node's
declared power type. The default is 'false'.
-
.. _cli-power:
Example: Setting the power parameters for an ipmi enabled node::
@@ -214,8 +212,6 @@
power_parameters_power_pass=ubuntu;
-
-
nodes
^^^^^
@@ -295,7 +291,6 @@
$ maas-cli maas nodes list architecture="i386/generic"
-
node-groups
^^^^^^^^^^^
Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
@@ -306,7 +301,7 @@
:samp:`-d, --debug`
Displays debug information listing the API responses.
-
+
:samp:`-h, --help`
Display usage information.
@@ -316,7 +311,7 @@
Disables the SSL certificate check.
:samp:`register uuid=<value> name=<value> interfaces=<json_string>`
-
+
Registers a new node group with the given name and uuid. The
interfaces parameter must be supplied in the form of a JSON string
comprising the key/value data for the interface to be used, for
@@ -327,7 +322,7 @@
:samp:`list`
- Returns a JSON list of all currently defined node groups.
+ Returns a JSON list of all currently defined node groups.
:samp:`refresh_workers`
@@ -338,7 +333,7 @@
nodes.
:samp:`accept <uuid>`
-
+
Accepts a node-group or number of nodegroups indicated by the
supplied UUID
@@ -348,10 +343,9 @@
supplied UUID
-
node-group-interface
^^^^^^^^^^^^^^^^^^^^
-For managing the interfaces. See also :ref:`node_group_interfaces`
+For managing the interfaces. See also :ref:`node-group-interfaces`
Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
--help] [-k --insecure] read | update | delete [parameters...]
@@ -359,50 +353,50 @@
..program:: maas-cli node-group-interface
:samp:`read <uuid> <interface>`
-
+
Returns the current settings for the given UUID and interface
:samp:`update [parameters]`
-
+
Changes the settings for the interface according to the given
parameters::
management= 0 | 1 | 2
- The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
+ The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP
and DNS).
subnet_mask=<value>
Apply the given dotted decimal value as the subnet mask.
broadcast_ip=<value>
- Apply the given dotted decimal value as the broadcast IP address for
+ Apply the given dotted decimal value as the broadcast IP address for
this subnet.
router_ip=<value>
- Apply the given dotted decimal value as the default router address
+ Apply the given dotted decimal value as the default router address
for this subnet.
ip_range_low=<value>
The lowest value of IP address to allocate via DHCP
ip_range_high=<value>
- The highest value of IP address to allocate via DHCP
+ The highest value of IP address to allocate via DHCP
:samp:`delete <uuid> <interface>`
Removes the entry for the given UUID and interface.
-
+
.. _cli-dhcp:
Example:
Configuring DHCP and DNS.
-To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
+To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant
interface information. To do this we need to first determine the UUID of the
node group affected::
$ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4)
-
+
Once we have the UUID we can use this to update the node-group-interface for
that nodegroup, and pass it the relevant interface details::
@@ -413,12 +407,13 @@
broadcast_ip=192.168.123.255 \
router_ip=192.168.123.1 \
-Replacing the example values with those required for this network. The only
-non-obvious parameter is 'management' which takes the values 0 (no management), 1
-(manage DHCP) and 2 (manage DHCP and DNS).
-
-
-.. _node-group-interfaces
+Replacing the example values with those required for this network. The
+only non-obvious parameter is 'management' which takes the values 0
+(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
+
+
+.. _node-group-interfaces:
+
node-group-interfaces
^^^^^^^^^^^^^^^^^^^^^
@@ -433,7 +428,7 @@
:samp:`-d, --debug`
Displays debug information listing the API responses.
-
+
:samp:`-h, --help`
Display usage information.
@@ -447,25 +442,24 @@
Lists the current stored configurations for the given identifier
<label> in a key:value format which should be easy to decipher.
-
:samp:`new <label> ip=<value> interface=<if_device> [parameters...]`
-
+
Creates a new interface group. The required parameters are the IP
address and the network interface this appies to (e.g. eth0). In
order to do anything useful, further parameters are required::
- management= 0 | 1 | 2
+ management= 0 | 1 | 2
The service to be managed on the interface
( 0= none, 1=DHCP, 2=DHCP and DNS).
subnet_mask=<value>
Apply the given dotted decimal value as the subnet mask.
- broadcast_ip=<value>
+ broadcast_ip=<value>
Apply the given dotted decimal value as the
broadcast IP address for this subnet.
- router_ip=<value>
+ router_ip=<value>
Apply the given dotted decimal value as the
default router address for this subnet.
@@ -476,18 +470,16 @@
The highest value of IP address to allocate via DHCP
-
-
-tag
+tag
^^^
Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
- nodes | delete
+ nodes | delete
.. program:: maas-cli tag
:samp:`read <tag_name>`
-
+
Returns information on the tag specified by <name>
:samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]`
@@ -500,10 +492,10 @@
:samp:`rebuild`
- Triggers a rebuild of the tag to node mapping.
+ Triggers a rebuild of the tag to node mapping.
:samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`
-
+
Updates the tag identified by tag_name. Any or all of name,comment
and definition may be supplied as parameters. If no parameters are
supplied, this command returns the current values.
@@ -516,12 +508,17 @@
Deletes the given tag.
-tags
-^^^^
-Tags are a really useful way of identifying nodes with particular
-characteristics.
-
-.. only:: html For more information on how to use them effectively, please see :ref:`deploy-tags`
+
+tags
+^^^^
+
+Tags are a really useful way of identifying nodes with particular
+characteristics.
+
+.. only:: html
+
+ For more information on how to use them effectively, please see
+ :ref:`deploy-tags`
Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
--insecure] list | new
@@ -531,39 +528,38 @@
:samp:`-d, --debug`
Displays debug information listing the API responses.
-
+
:samp:`-h, --help`
Display usage information.
-:samp:`-k, --insecure`
+:samp:`-k, --insecure`
Disables the SSL certificate check.
:samp:`list`
-
+
Returns a JSON object listing all the current tags known by the MAAS server
:samp:`create name=<value> definition=<value> [comment=<value>]`
Creates a new tag with the given name and definition. A comment is
optional. Names must be unique, obviously - an error will be
- returned if the given name already exists. The definition is in the form of
- an XPath expression which parses the XML returned by running ``lshw`` on the
- node.
-
+ returned if the given name already exists. The definition is in the
+ form of an XPath expression which parses the XML returned by
+ running ``lshw`` on the node.
+
Example:
Adding a tag to all nodes which have an Intel GPU::
$ maas-cli maas tags new name='intel-gpu' \
comment='Machines which have an Intel display driver' \
definition='contains(//node[@id="display"]/vendor, "Intel")
-
-
-unused commands
-^^^^^^^^^^^^^^^
+
+
+unused commands
+^^^^^^^^^^^^^^^
+
Because the ``maas-cli`` command exposes all of the API, it also lists
some command options which are not really intended for end users, such
as the "file" and "boot-images" options.
-
-
=== modified file 'docs/man/maas-cli.8.rst'
--- docs/man/maas-cli.8.rst 2012-11-20 21:48:20 +0000
+++ docs/man/maas-cli.8.rst 2012-11-20 21:48:20 +0000
@@ -1,4 +1,3 @@
-
maas-cli
--------
@@ -7,9 +6,9 @@
^^^^^
$ maas-cli <profile> <command> [parameters]
-
+
The available commands are dependent on the API you are connecting to and the
-profile you use. The currently available options are explained below.
+profile you use. The currently available options are explained below.
Description
@@ -17,12 +16,14 @@
.. include:: ../maascli.rst
+
Further Documentation
^^^^^^^^^^^^^^^^^^^^^
+
For more documentation of MAAS, please see https://maas.ubuntu.com/docs
+
See Also
^^^^^^^^
+
`maas`
-
-
=== modified file 'docs/man/maas.8.rst'
--- docs/man/maas.8.rst 2012-11-20 21:48:20 +0000
+++ docs/man/maas.8.rst 2012-11-20 21:48:20 +0000
@@ -1,23 +1,25 @@
maas
----
-USAGE
+
+Usage
^^^^^
maas [-h, --help] createsuperuser | changepassword | shell
-DESCRIPTION
+
+Description
^^^^^^^^^^^
-The `maas` command is part of Canonical's Metal As A Service software. It is
-derived from and can be used similarly to the `django-admin` command, and must
-be run with root privileges.
+The `maas` command is part of Canonical's Metal As A Service software. It is
+derived from and can be used similarly to the `django-admin` command, and must
+be run with root privileges.
For the end user, there are only three subcommands of interest.
**createsuperuser**
This subcommand is used to create a superuser for the
- MAAS install. The suggested username is "root". This command usually only
+ MAAS install. The suggested username is "root". This command usually only
needs to be run when installing MAAS for the first time.
**changepassword**
@@ -26,16 +28,18 @@
enter it once again to verify.
**shell**
- This subcommand may be useful for debugging installed systems. It
+ This subcommand may be useful for debugging installed systems. It
will open a new python shell environment with the correct django environment
for working with the installed MAAS software.
-
+
Further Documentation
^^^^^^^^^^^^^^^^^^^^^
+
For more documentation of MAAS, please see https://maas.ubuntu.com/docs
+
See Also
^^^^^^^^
+
`maas-cli`
-
=== modified file 'docs/nodes.rst'
--- docs/nodes.rst 2012-10-11 13:23:54 +0000
+++ docs/nodes.rst 2012-11-20 21:48:20 +0000
@@ -1,10 +1,10 @@
-
-
Adding nodes to the system
==========================
-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>`
-
+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>`
.. _auto-enlist:
@@ -12,21 +12,29 @@
Automatic Discovery
-------------------
-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.
-
-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.
-When the nodes have been accepted the selected series of Ubuntu will be installed.
-
-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>`::
+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.
+
+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. When the nodes have been
+accepted the selected series of Ubuntu will be installed.
+
+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>`::
$ maas-cli maas nodes accept-all
-
Enlist nodes via boot media
---------------------------
-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.
+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.
Boot from the media and follow the instructions.
@@ -34,4 +42,5 @@
Manually add nodes
------------------
-If you know the MAC address of a node, you can manually enter details about the node through the web interface.
+If you know the MAC address of a node, you can manually enter details
+about the node through the web interface.
=== modified file 'docs/orientation.rst'
--- docs/orientation.rst 2012-10-04 15:14:12 +0000
+++ docs/orientation.rst 2012-11-20 21:48:20 +0000
@@ -1,30 +1,46 @@
.. _orientation:
-
+
Orientation
===========
+
MAAS in Brief
-------------
-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.
-
-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.
-
-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.
+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.
+
+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.
+
+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.
+
Do I Need MAAS?
---------------
-MAAS certainly isn't for everyone, but why not ask yourself these questions?
+MAAS certainly isn't for everyone, but why not ask yourself these
+questions?
-You probably *SHOULD* use MAAS if any or all of the following statements are true:
+You probably *SHOULD* use MAAS if any or all of the following
+statements are true:
* You are trying to manage many physical servers.
* You want to deploy services with the minimum fuss.
* You need to get the most from your resources.
* You want things to work, repeatably and reliably.
-You probably don't need MAAS if any or all of these statements are true:
+You probably don't need MAAS if any or all of these statements are
+true:
* You don't need to manage physical hardware
* You relish time spent in the server room
@@ -36,17 +52,18 @@
A Typical MAAS setup
--------------------
-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:
+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:
* Region controller
* Cluster controller(s)
* Nodes
-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).
+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).
.. image:: media/orientation_architecture-diagram.*
-
-
-
-
-
=== modified file 'docs/tags.rst'
--- docs/tags.rst 2012-10-25 13:09:16 +0000
+++ docs/tags.rst 2012-11-20 21:48:20 +0000
@@ -1,65 +1,69 @@
-
.. _deploy-tags:
+
Making use of Tags
==================
-MAAS implements a system of tags based on the physical properties of the nodes.
-The idea behind this is that you can use the tags to identify nodes with
-particular abilities which may be useful when it comes to deploying services.
-
-A real world example of this might be to identify nodes which have fast GPUs
-installed, if you were planning on deploying software which used CUDA or
-OpenCL which would make use of this hardware.
+MAAS implements a system of tags based on the physical properties of
+the nodes. The idea behind this is that you can use the tags to
+identify nodes with particular abilities which may be useful when it
+comes to deploying services.
+
+A real world example of this might be to identify nodes which have
+fast GPUs installed, if you were planning on deploying software which
+used CUDA or OpenCL which would make use of this hardware.
+
Tag definitions
---------------
-
Before we can create a tag we need to know how we will select which nodes it
-gets applied to. MAAS collects hardware information from the nodes using the
-`"lshw" utility <http://ezix.org/project/wiki/HardwareLiSter>`_ to return
-detailed information in XML format. The definitions used in creating a tag are
+gets applied to. MAAS collects hardware information from the nodes using the
+`"lshw" utility <http://ezix.org/project/wiki/HardwareLiSter>`_ to return
+detailed information in XML format. The definitions used in creating a tag are
then constructed using XPath expressions.
-If you are unfamiliar with XPath expressions, it is well worth checking out the
+If you are unfamiliar with XPath expressions, it is well worth checking out the
`w3schools documentation <http://www.w3schools.com/xpath/xpath_syntax.asp>`_.
For the lshw XML, we will just check all the available nodes for some properties.
-In our example case, we might want to find GPUs with a clock speed of over 1GHz.
+In our example case, we might want to find GPUs with a clock speed of over 1GHz.
In this case, the relevant XML node from the output will be labelled "display"
and does have a property called clock, so it will look like this::
-
+
//node[@id="display"]/clock > 1000000000
Now we have a definition, we can go ahead and create a tag.
+
Creating a tag
--------------
-Once we have sorted out what definition we will be using, creating the tag is
-easy using the ``maas-cli`` command. You will need to :ref:`be logged in to the API first <api-key>`::
+Once we have sorted out what definition we will be using, creating the
+tag is easy using the ``maas-cli`` command. You will need to :ref:`be
+logged in to the API first <api-key>`::
$ maas-cli maas tags new name='gpu' \
comment='GPU with clock speed >1GHz for running CUDA type operations.' \
definition='//node[@id="display"]/clock > 1000000000'
-The comment is really for your benefit. It pays to keep the actual tag name
-short and to the point as you will be using it frequently in commands, but it
+The comment is really for your benefit. It pays to keep the actual tag name
+short and to the point as you will be using it frequently in commands, but it
may subsequently be hard to work out what exactly was the difference between
-tags like "gpu" and "fastgpu" unless you have a good comment. Something which
+tags like "gpu" and "fastgpu" unless you have a good comment. Something which
explains the definition in plain language is always a good idea!
To check which nodes this tag applies to we can use the tag command::
- $ maas-cli maas tag nodes gpu
+ $ maas-cli maas tag nodes gpu
-The process of updating the tags does take some time - not a lot of time, but
-if nothing shows up straight away, try running the command again after a minute
+The process of updating the tags does take some time - not a lot of time, but
+if nothing shows up straight away, try running the command again after a minute
or so.
+
Using the tag
-------------
-You can use the tag in the web interface to discover applicable nodes, but the
-real significance of it is when using juju to deploy services. Tags can be used
+You can use the tag in the web interface to discover applicable nodes, but the
+real significance of it is when using juju to deploy services. Tags can be used
with juju constraints to make sure that a particular service only gets deployed
on hardware with the tag you have created.
@@ -68,12 +72,11 @@
$ juju deploy --constraints maas-tags=gpu cuda
-You could list several tags if required, and mix in other juju constraints if
+You could list several tags if required, and mix in other juju constraints if
needed::
$ juju deploy --constraints "mem=1024 maas-tags=gpu,intel" cuda
-
-
+
Manually assigning tags
-----------------------
@@ -81,7 +84,7 @@
MAAS supports the creation of arbitrary tags which don't depend on XPath
definitions ("nodes which make a lot of noise" perhaps). If a tag is created
without specifying the definition parameter then it will simply be ignored by
-tag refresh mechanism, but the MAAS administrator will be able to manually add
+tag refresh mechanism, but the MAAS administrator will be able to manually add
and remove the tag from specific nodes.
In this example we are assuming you are using the 'maas' profile and you want
@@ -90,10 +93,10 @@
$ maas-cli maas tags new name='my_tag' comment='nodes which go ping'
$ maas-cli maas tag update-nodes my_tag add="<system_id>"
-The first line creates a new tag but omits the definition, so no nodes are
-automatically added to it. The second line applies that tag to a specific node
+The first line creates a new tag but omits the definition, so no nodes are
+automatically added to it. The second line applies that tag to a specific node
referenced by its system id property.
-
+
You can easily remove a tag from a particular node, or indeed add
and remove them at the same time::
@@ -105,7 +108,7 @@
subsequently edit it to remove the definition. From this point the tag behaves
as if you had manually created it, but it still retains all the existing
associations it has with nodes. This is particularly useful if you have some
-hardware which is conceptually similar but doesn't easily fit within a single
+hardware which is conceptually similar but doesn't easily fit within a single
tag definition::
$ maas-cli maas tag new name='my_tag' comment='nodes I like ' \
@@ -113,15 +116,7 @@
$ maas-cli maas tag update my_tag definition=''
$ maas-cli mass tag update-nodes my_tag add=<system_id>
-
.. tip::
+
If you add and remove the same node in one operation, it ends up having
the tag removed (even if the tag was in place before the operation).
-
-
-
-
-
-
-
-
=== modified file 'docs/troubleshooting.rst'
--- docs/troubleshooting.rst 2012-10-12 12:51:17 +0000
+++ docs/troubleshooting.rst 2012-11-20 21:48:20 +0000
@@ -1,6 +1,7 @@
********************
MAAS Troubleshooting
********************
+
Some parts of MAAS may still be a little confusing, and sometimes you might be
trying to do things that are just plain impossible. This section covers some of
the most commonly encountered problems and tries its best to make them gone.
@@ -13,8 +14,10 @@
**Nodes hang on "Commissioning"**
=================================
+
Possible Cause: Timing issues
-----------------------------
+
Various parts of MAAS rely on OAuth to negotiate a connection to nodes. If the
current time reported by the hardware clock on your node differs significantly
from that on the MAAS server, the connection will not be made.
@@ -23,6 +26,7 @@
adjust them. This can usually be done from within the system BIOS, without
needing to install an OS
+
Possible Cause: Network drivers
-------------------------------
@@ -34,17 +38,21 @@
network adaptor. It *is* theoretically possible to modify the boot image to
include proprietary drivers, but it is not a straightforward task.
+
**Nodes fail to PXE boot**
==========================
+
Possible Cause: Using an incorrectly configured VM
--------------------------------------------------
+
Some Virtual Machine setups include emulation of network hardware that does not
support PXE booting, and in most setups, you will need to explicitly set up the
-VM to boot via PXE.
+VM to boot via PXE.
**SOLUTION**: Consult the VM docs for details of PXE booting.
+
Possible Cause: DHCP conflict
-----------------------------
If you are using MAAS in a setup with an existing DHCP, *DO NOT SET UP THE MAAS
@@ -53,7 +61,6 @@
**SOLUTION**: You will need to either:
-
* Configure your existing DHCP server to point to the MAAS server.
or
@@ -62,30 +69,31 @@
this, please see https://wiki.ubuntu.com/ServerTeam/MAAS/AvahiBoot
-
**Can't log in to node**
========================
-Sometimes you may wish to login directly to a node on your system. If you have
-set up Juju and MAAS, the attached nodes will automatically receive existing ssh
-keys and sets up ssh on the node to authenticate via key, so you can just login
-with no password from the server.
-There is also an option in the MAAS web interface to add new ssh keys to the
-nodes (via Preferences in the drop down menu which appears when clicking your
-username in the top-right of the page).
+Sometimes you may wish to login directly to a node on your system. If
+you have set up Juju and MAAS, the attached nodes will automatically
+receive existing ssh keys and sets up ssh on the node to authenticate
+via key, so you can just login with no password from the server.
+There is also an option in the MAAS web interface to add new ssh keys
+to the nodes (via Preferences in the drop down menu which appears when
+clicking your username in the top-right of the page).
+
**Forgot MAAS superuser password**
==================================
-As long as you have sudo privileges, this is not a disaster. You can use the
-``maas`` command to change the password for the MAAS superuser on the MAAS
-server:
+As long as you have sudo privileges, this is not a disaster. You can
+use the ``maas`` command to change the password for the MAAS superuser
+on the MAAS server:
``sudo maas changepassword root``
**Need to reconfigure server IP address**
=========================================
+
If you made a mistake during setup or you just need to reconfigure your MAAS
server, you can simply run the setup again:
@@ -109,7 +117,3 @@
#. If you are still getting "404 - Page not found" errors, check that the MAAS
web interface has been installed in the right place. There should be a file
present called /usr/share/maas/maas/urls.py
-
-
-
-
