Merge lp:~evilnick/maas/docs-preeseed+man-page-fixes into lp:~maas-committers/maas/trunk

[Nick Veitch]

added preseed docs and fixed man page links

added section on editing preseed
fixed man page/html clash for now

Unmerged revisions

1369. By Nick Veitch on 2012-11-23

new preseed, man page fixes

=== modified file 'INSTALL.txt'
--- INSTALL.txt	2012-11-20 21:46:37 +0000
+++ INSTALL.txt	2012-11-23 13:00:36 +0000
@@ -1,18 +1,17 @@
 .. -*- 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:
@@ -21,33 +20,29 @@
 --------------------------------
 
 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:
+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
 ^^^^^^^^^^^^^^^^
@@ -56,118 +51,110 @@
 
   $ 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
+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
 
@@ -175,19 +162,15 @@
 
 .. _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
 --------------------------
@@ -197,37 +180,35 @@
 
   $ 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:`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.
+However, you'll need to download them manually the first time::
+
+  $ sudo maas-import-pxe-files
+
+If you are using an HTTP proxy, bear in mind that the "sudo" will not
+pass your http_proxy environment variable on to the script.  If that is
+a problem, pass it on explicitly::
+
+  $ sudo http_proxy=$http_proxy maas-import-pxe-files
 
 
 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.*
 
@@ -235,9 +216,11 @@
 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 configure this using the 
+commandline interface, first by :ref:`logging on to the server API <api-key>` 
+and then :ref:`setting up the interface <cli-dhcp>` 
+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 'docs/configure.rst'
--- docs/configure.rst	2012-11-22 03:18:35 +0000
+++ docs/configure.rst	2012-11-23 13:00:36 +0000
@@ -1,22 +1,23 @@
 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 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::
 
    subnet 192.168.122.0 netmask 255.255.255.0 {
+       next-server 192.168.122.136;
        filename "pxelinux.0";
        option subnet-mask 255.255.255.0;
        option broadcast-address 192.168.122.255;
@@ -24,12 +25,10 @@
        range dynamic-bootp 192.168.122.5 192.168.122.135;
    }
 
-
 .. _ssl:
 
 SSL Support
 -----------
-
 If you want secure access to your MAAS web UI/API, you need to do a few
 things. First, turn on SSL support in Apache::
 
@@ -48,3 +47,133 @@
 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.
+
+
+Choosing a series to install
+----------------------------
+
+You may have some specific reason to choose a particular version of Ubuntu
+to install on your nodes, perhaps based around package avaiability,
+hardware support or some other reason. 
+It is possible to choose a specific series from those available in a 
+number of ways.
+
+From the user interface
+^^^^^^^^^^^^^^^^^^^^^^^
+
+For individual nodes it is a straightforward task to select the Ubuntu
+series to install from the user interface. When either adding a node 
+manually, or on the node page when the node has been automatically
+discovered but before it is accepted, there is a drop down menu to select 
+the version of Ubuntu you wish to install.
+
+.. image:: media/series.*
+
+The menu will always list all the currently available series according
+to which images are available.
+
+Using the maas-cli command
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is also possible to select a series using the maas-cli command. This
+can be done on a per node basis with::
+
+ $ maas-cli <profile> node update <system_id> distro_series="<value>"
+
+Where the string contains one of the valid, available distro series, or
+is empty for the default value.
+
+
+.. _preseed:
+
+Altering the Preseed file
+-------------------------
+
+.. warning::
+  Do not try to alter the preseed files if you don't have a good 
+  understanding of what you are doing. Altering the installed version 
+  of Ubuntu can prevent MAAS from working as intended, and may have
+  security and stability consequences. 
+
+When MAAS commissions a node it installs a version of Ubuntu. The 
+installation is performed using a 'preseed' file, which is 
+effectively a list of answers to the questions you would get were 
+you to run the installer manually.
+The preseed file used by MAAS is carefully made so that the 
+target node can be brought up and do all the jobs expected of it.
+However, in exceptional circumstances, you may wish to alter the 
+pressed file to work around some issue.
+There are actually two preseed files, stored here::
+
+  /usr/share/maas/preseeds/generic
+  /usr/share/maas/preseeds/preseed-master
+
+The generic file actually references the preseed-master file, and is 
+used to set conditional parameters based on the type of series and 
+architecture to install as well as to define the minimum set of install
+packages and to tidy up the PXE boot process if that has been used for 
+the node. Unless you have a specific need to change where install 
+packages come from, you should not need to edit this file.
+
+For the more usual sorts of things you may wish to change, you should 
+edit the preseed-master file. For example, depending on your network
+you may wish to change the clock settings::
+
+    # Local clock (set to UTC and use ntp)
+    d-i     clock-setup/utc boolean true
+    d-i     clock-setup/ntp boolean true
+    d-i     clock-setup/ntp-server  string ntp.ubuntu.com
+
+Having consistent clocks is very important to the working of your MAAS
+system overall. If your nodes however cannot freely access the internet,
+the supplied ntp server is not going to be very useful, and you may
+find it better to run an ntp service on the MAAS controller and substitute
+`ntp.ubuntu.com` in the last line for something else.
+
+One thing you may wish to alter in the preseed file is the disk
+partitioning. This is a simple recipe that creates a swap partition and 
+uses the rest of the disk for one large root filesystem::
+
+	partman-auto/text/atomic_scheme ::
+
+	500 10000 1000000 ext3
+		$primary{ }
+		$bootable{ }
+		method{ format }
+		format{ }
+		use_filesystem{ }
+		filesystem{ ext3 }
+		mountpoint{ / } .
+
+	64 512 300% linux-swap
+		method{ swap }
+		format{ } .
+
+
+Here the root partition must be at least 500 mb, and has effectively no
+maximum size. The swap partition ranges from 64 mb to 3 times the system's
+ram.
+Adding `$bootable{ }` to make the partition bootable, and $primary{ }
+marks it as the primary partition. The other specifiers used are:
+
+*method{ format }*
+	Used to make the partition be formatted. For swap partitions,
+	change it to "swap". To create a new partition but do not
+	format it, change "format" to "keep" (such a partition can be
+	used to reserve for future use some disk space).
+*format{ }*
+	Also needed to make the partition be formatted.
+*use_filesystem{ }*
+	Specifies that the partition has a filesystem on it.
+*filesystem{ ext3 }*
+	Specifies the filesystem to put on the partition.
+*mountpoint{ / }*
+	Where to mount the partition.
+
+For more information on preseed option, you should refer to 
+`the official Ubuntu documentation <https://help.ubuntu.com/12.04/installation-guide/i386/preseed-contents.html>`_
+
+.. note::
+  Future versions of MAAS are likely to replace this type of automatic 
+  installation with a different installer.
+

=== modified file 'docs/maascli.rst'
--- docs/maascli.rst	2012-11-20 21:46:37 +0000
+++ docs/maascli.rst	2012-11-23 13:00:36 +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,7 +19,7 @@
 .. only:: html
 .. image:: media/maascli-prefs.*
 
-A new page will load...
+A new page will load... 
 
 .. only:: html
 .. image:: media/maascli-key.*
@@ -31,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
@@ -77,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.
 
@@ -108,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.
 
@@ -127,6 +127,8 @@
     Removes the given key from the list of authorisation tokens.
 
 
+
+
 .. boot-images - not useful in user context
 .. ^^^^^^^^^^^
 
@@ -157,50 +159,54 @@
    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
-           for this subnet.
-
-      power_parameters_{param1}... =<value>
-           Set the given power parameters. Note that the valid options for these
+      distro_series=<value>
+           Sets the series of Ubuntu to use.
+
+      power_type=<value> 
+           Sets the type of power management used on the node, e.g. "ipmi" or
+           "virsh".
+
+      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::
@@ -212,6 +218,8 @@
     power_parameters_power_pass=ubuntu;
 
 
+
+
 nodes
 ^^^^^
 
@@ -291,6 +299,7 @@
  $ maas-cli maas nodes list architecture="i386/generic"
 
 
+
 node-groups
 ^^^^^^^^^^^
 Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
@@ -301,7 +310,7 @@
 :samp:`-d, --debug`
 
    Displays debug information listing the API responses.
-
+	
 :samp:`-h, --help`
 
    Display usage information.
@@ -311,7 +320,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
@@ -322,7 +331,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`
 
@@ -333,7 +342,7 @@
    nodes.
 
 :samp:`accept <uuid>`
-
+   
    Accepts a node-group or number of nodegroups indicated by the
    supplied UUID
 
@@ -343,60 +352,62 @@
    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 <node_group_interfaces>`
 
-Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
+Usage: maas-cli *<profile>* node-group-interface [-d --debug] [-h
 --help] [-k --insecure] read | update | delete [parameters...]
 
 ..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::
 
@@ -407,13 +418,12 @@
          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).
+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
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -428,7 +438,7 @@
 :samp:`-d, --debug`
 
    Displays debug information listing the API responses.
-
+	
 :samp:`-h, --help`
 
    Display usage information.
@@ -442,24 +452,25 @@
    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.
 
@@ -470,16 +481,18 @@
            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>]`
@@ -492,10 +505,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.
@@ -508,17 +521,12 @@
 
    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
@@ -528,38 +536,39 @@
 :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:46:37 +0000
+++ docs/man/maas-cli.8.rst	2012-11-23 13:00:36 +0000
@@ -1,29 +1,564 @@
+
 maas-cli
 --------
 
-
 Usage
 ^^^^^
 
  $ 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
 ^^^^^^^^^^^
 
-.. include:: ../maascli.rst
-
+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.
+
+
+Logging in
+----------
+
+Before the API will accept any commands from maas-cli, you must first
+login. To do this, you need the API key which can be found in the user
+interface.
+
+Login to the web interface on your MAAS. Click on the username in the
+top right corner and select 'Preferences' from the menu which appears.
+
+The very first item is a list of MAAS keys. One will have already been
+generated when the system was installed. It's easiest to just select
+and copy the key (it's quite long!) and then paste it into the
+commandline. The format of the login command is::
+
+ $ 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::
+
+$ 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)
+
+
+maas-cli commands
+-----------------
+
+The ``maas-cli`` command exposes the whole API, so you can do anything
+you actually *can* do with MAAS using this command. Unsurprisingly,
+this leaves us with a vast number of options.
+
+The main maas-cli commands are:
+
+.. program:: maas-cli
+
+:samp:`list`
+
+  lists the details [name url auth-key] of all the currently logged-in
+  profiles.
+
+:samp:`login <profile> <url> <key>`
+
+  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>` 
+
+  Logs out from the given profile, flushing the stored credentials.
+
+:samp:`refresh`
+
+  Refreshes the API descriptions of all the current logged in
+  profiles. This may become necessary for example when upgrading the
+  maas packages to ensure the command-line options match with the API.
+
+:samp:`<profile> [command] [options] ...`
+
+  Using the given profile name instructs ``maas-cli`` to direct the
+  subsequent commands and options to the relevant MAAS, which for the
+  current API are detailed below...
+
+
+account
+^^^^^^^
+This command is used for creating and destroying the
+MAAS authorisation tokens associated with a profile.
+
+Usage: maas-cli *<profile>* account [-d --debug] [-h --help]
+create-authorisation-token | delete-authorisation-token [token_key=\
+*<value>*]
+
+.. program:: maas-cli account
+
+:samp:`-d, --debug`
+
+   Displays debug information listing the API responses.
+	
+:samp:`-h, --help`
+
+   Display usage information.
+
+:samp:`-k, --insecure` 
+
+   Disables the SSL certificate check.
+
+:samp:`create-authorisation-token`
+
+    Creates a new MAAS authorisation token for the current profile
+    which can be used to authenticate connections to the API.
+
+:samp:`delete-authorisation-token token_key=<value>`
+
+    Removes the given key from the list of authorisation tokens.
+
+
+node
+^^^^
+
+API calls which operate on individual nodes. With these commands, the
+node is always identified by its "system_id" property - a unique tag
+allocated at the time of enlistment. To discover the value of the
+system_id, you can use the ``maas-cli <profile> nodes list`` command.
+
+USAGE: maas-cli <profile> node [-h] release | start | stop | delete |
+read | update <system_id>
+
+.. program:: maas-cli node
+
+:samp:`-h, --help`
+
+   Display usage information.
+
+:samp:`release <system_id>`
+
+   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> 
+           Sets the architecture type, where <value>
+           is a string containing a valid architecture type,
+           e.g. "i386/generic"
+
+      distro_series=<value>
+           Sets the series of Ubuntu to use.
+
+      power_type=<value> 
+           Sets the type of power management used on the node, e.g. "ipmi" or
+           "virsh".
+
+      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 
+           declared power type. The default is 'false'.
+
+
+
+.. _cli-power:
+
+Example: Setting the power parameters for an ipmi enabled node::
+
+  maas-cli maas node update <system_id> \
+    power_type="ipmi" \
+    power_parameters_power_address=192.168.22.33 \
+    power_parameters_power_user=root \
+    power_parameters_power_pass=ubuntu;
+
+
+
+
+nodes
+^^^^^
+
+Usage: maas-cli <profile> nodes [-h] is-registered | list-allocated |
+acquire | list | accept | accept-all | new | check-commissioning
+
+.. program:: maas-cli nodes
+
+:samp:`-h, --help`
+
+   Display usage information.
+
+
+:samp:`accept <system_id>`
+
+   Accepts the node referenced by <system_id>.
+
+:samp:`accept-all`
+
+   Accepts all currently discovered but not previously accepted nodes.
+
+:samp:`acquire`
+
+   Allocates a node to the profile used to issue the command. Any
+   ready node may be allocated.
+
+:samp:`is-registered mac_address=<address>`
+
+   Checks to see whether the specified MAC address is registered to a
+   node.
+
+:samp:`list`
+
+   Returns a JSON formatted object listing all the currently known
+   nodes, their system_id, status and other details.
+
+:samp:`list-allocated`
+
+   Returns a JSON formatted object listing all the currently allocated
+   nodes, their system_id, status and other details.
+
+:samp:`new architecture=<value> mac_addresses=<value> [parameters]`
+
+   Creates a new node entry given the provided key=value information
+   for the node. A minimum of the MAC address and architecture must be
+   provided. Other parameters may also be supplied::
+
+     architecture="<value>" - The architecture of the node, must be
+     one of the recognised architecture strings (e.g. "i386/generic")
+     hostname="<value>" - a name for this node. If not supplied a name
+     will be generated.
+     mac_addresses="<value>" - The mac address(es)
+     allocated to this node.
+     powertype="<value>" - the power type of
+     the node (e.g. virsh, ipmi)
+
+
+:samp:`check-commissioning`
+
+   Displays current status of nodes in the commissioning phase. Any
+   that have not returned before the system timeout value are listed
+   as "failed".
+
+Examples:
+Accept and commission all discovered nodes::
+
+ $ maas-cli maas nodes accept-all
+
+List all known nodes::
+
+ $ maas-cli maas nodes list
+
+Filter the list using specific key/value pairs::
+
+ $ maas-cli maas nodes list architecture="i386/generic"
+
+
+
+node-groups
+^^^^^^^^^^^
+Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
+--insecure] register | list | refresh-workers | accept | reject
+
+.. program:: maas-cli node-groups
+
+:samp:`-d, --debug`
+
+   Displays debug information listing the API responses.
+	
+:samp:`-h, --help`
+
+   Display usage information.
+
+:samp:`-k, --insecure`
+
+   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
+   example: interface='["ip":"192.168.21.5","interface":"eth1", \
+   "subnet_mask":"255.255.255.0","broadcast_ip":"192.168.21.255", \
+   "router_ip":"192.168.21.1", "ip_range_low":"192.168.21.10", \
+   "ip_range_high":"192.168.21.50"}]'
+
+:samp:`list`
+
+   Returns a JSON list of all currently defined node groups.   
+
+:samp:`refresh_workers`
+
+   It sounds a bit like they will get a cup of tea and a
+   biscuit. Actually this just sends each node-group worker an update
+   of its credentials (API key, node-group name). This command is
+   usually not needed at a user level, but is often used by worker
+   nodes.
+
+:samp:`accept <uuid>`
+   
+   Accepts a node-group or number of nodegroups indicated by the
+   supplied UUID
+
+:samp:`reject <uuid>`
+
+   Rejects a node-group or number of nodegroups indicated by the
+   supplied UUID
+
+
+
+node-group-interface
+^^^^^^^^^^^^^^^^^^^^
+For managing the interfaces. See also 
+"node_group_interfaces"
+
+Usage: maas-cli *<profile>* node-group-interface [-d --debug] [-h
+--help] [-k --insecure] read | update | delete [parameters...]
+
+..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 
+           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 
+           this subnet.
+
+      router_ip=<value>
+           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 
+
+:samp:`delete <uuid> <interface>`
+
+   Removes the entry for the given UUID and interface.
+   
+
+Example:
+Configuring DHCP and DNS.
+
+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::
+
+ $ maas-cli <profile> node-group-interface update $uuid eth0 \
+         ip_range_high=192.168.123.200    \
+         ip_range_low=192.168.123.100     \
+         management=2                     \
+         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
+^^^^^^^^^^^^^^^^^^^^^
+
+The node-group-interfaces commands are used for configuring the
+management of DHCP and DNS services where these are managed by MAAS.
+
+Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h
+--help] [-k --insecure] list | new [parameters...]
+
+.. program:: maas-cli node-group-interfaces
+
+:samp:`-d, --debug`
+
+   Displays debug information listing the API responses.
+	
+:samp:`-h, --help`
+
+   Display usage information.
+
+:samp:`-k, --insecure`
+
+   Disables the SSL certificate check.
+
+:samp:`list <label>`
+
+   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 
+           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 this subnet.
+
+      router_ip=<value> 
+           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
+
+
+
+
+tag 
+^^^
+
+Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
+  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>]`
+
+   Applies or removes the given tag from a list of nodes specified by
+   either or both of add="<system_id>" and remove="<system_id>". The
+   nodegroup parameter, which restricts the operations to a particular
+   nodegroup, is optional, but only the superuser can execute this
+   command without it.
+
+:samp:`rebuild`
+
+   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.
+
+:samp:`nodes <tag_name>`
+
+   Returns a list of nodes which are associated with the given tag.
+
+:samp:`delete <tag_name>`
+
+   Deletes the given tag.
+
+tags 
+^^^^ 
+Tags are a really useful way of identifying nodes with particular 
+characteristics. 
+
+Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k
+--insecure] list | new
+
+.. program:: maas-cli tag
+
+:samp:`-d, --debug`
+
+   Displays debug information listing the API responses.
+	
+:samp:`-h, --help`
+
+   Display usage information.
+
+: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.
+   
+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 
+^^^^^^^^^^^^^^^ 
+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.
 
 Further Documentation
 ^^^^^^^^^^^^^^^^^^^^^
-
 For more documentation of MAAS, please see https://maas.ubuntu.com/docs
 
-
 See Also
 ^^^^^^^^
-
 `maas`
+
+