launchpad-reviewers team mailing list archive
-
launchpad-reviewers team
-
Mailing list archive
-
Message #14830
[Merge] lp:~evilnick/maas/1.2-doc-backports into lp:maas/1.2
Nick Veitch has proposed merging lp:~evilnick/maas/1.2-doc-backports into lp:maas/1.2.
Commit message:
Backports of docs changes from trunk
Requested reviews:
MAAS Maintainers (maas-maintainers)
For more details, see:
https://code.launchpad.net/~evilnick/maas/1.2-doc-backports/+merge/140515
Backports of docs changes from trunk
--
https://code.launchpad.net/~evilnick/maas/1.2-doc-backports/+merge/140515
Your team MAAS Maintainers is requested to review the proposed merge of lp:~evilnick/maas/1.2-doc-backports into lp:maas/1.2.
=== modified file 'docs/about.rst'
--- docs/about.rst 2012-10-03 20:16:24 +0000
+++ docs/about.rst 2012-12-18 18:10:32 +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/conf.py'
--- docs/conf.py 2012-11-21 11:55:59 +0000
+++ docs/conf.py 2012-12-18 18:10:32 +0000
@@ -115,6 +115,8 @@
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
html_theme_path = ['_templates']
# The name for this set of Sphinx documents. If None, it defaults to
=== modified file 'docs/configure.rst'
--- docs/configure.rst 2012-11-22 03:24:37 +0000
+++ docs/configure.rst 2012-12-18 18:10:32 +0000
@@ -1,12 +1,16 @@
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.
@@ -20,7 +24,9 @@
range dynamic-bootp 192.168.122.5 192.168.122.135;
}
+
.. _ssl:
+
SSL Support
-----------
@@ -43,3 +49,180 @@
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 availability,
+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
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The web-based user interface makes it easy to select which Ubuntu series you
+wish to install on an individual node. 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 boot 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 (e.g.
+"precise") 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 change
+the `ntp.ubuntu.com` in the last line for a more appropriate server.
+
+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 options, 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.
+
+
+Installing additional clusters
+------------------------------
+
+In an environment comprising large numbers of nodes, it is likely that you will
+want to organise the nodes on a more distributed basis. The standard install of
+the MAAS region controller includes a cluster controller, but it is
+possible to add additional cluster controllers to the configuration, as
+shown in the diagram below:
+
+.. image:: media/orientation_architecture-diagram.*
+
+Each cluster controller will need to run on a separate Ubuntu server.
+Installing and configuring the software is straightforward though::
+
+ $ sudo apt-get install maas-cluster-controller
+
+This meta-package will install all the basic requirements of the system.
+However, you may also wish or need to run DHCP and/or DNS services, in
+which case you should also specify these::
+
+ $ sudo apt-get install maas-cluster-controller maas-dhcp maas-dns
+
+Configuring the cluster controller
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once the packages are installed, the cluster controller needs to know
+where to look for the region controller. This is achieved using `dpkg` to
+configure the software::
+
+ $ dpkg-reconfigure maas-cluster-controller
+
+.. image:: media/cluster-config.*
+
+The configuration script should then bring up a screen where you can
+enter the IP address of the region controller. Additionally, you will need
+to run the ``maas-import-pxe-files`` script to install the distro image files
+locally for commissioning::
+
+ $ maas-cli maas node-groups import-boot-images
+
+...and optionally set up the DHCP and DNS for
+the cluster by first :ref:`logging in to the API <api-key>` and then
+:ref:`following this procedure <cli-dhcp>`
+
+
=== modified file 'docs/index.rst'
--- docs/index.rst 2012-10-04 15:14:12 +0000
+++ docs/index.rst 2012-12-18 18:10:32 +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
@@ -37,6 +38,8 @@
:maxdepth: 2
juju-quick-start
+ tags
+
******************************
Using the maas-cli commandline
@@ -47,6 +50,7 @@
maascli
+
**********
Appendices
**********
@@ -55,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-12-18 18:10:32 +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:57:31 +0000
+++ docs/maascli.rst 2012-12-18 18:10:32 +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
@@ -16,10 +16,9 @@
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.
-.. only:: html
.. image:: media/maascli-prefs.*
-A new page will load...
+A new page will load...
.. image:: media/maascli-key.*
@@ -30,21 +29,22 @@
$ 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)
+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
@@ -76,7 +76,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 +107,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 +126,6 @@
Removes the given key from the list of authorisation tokens.
-
-
.. boot-images - not useful in user context
.. ^^^^^^^^^^^
@@ -158,51 +156,53 @@
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
+ distro_series=<value>
+ Sets the distro series of Ubuntu to use (e.g. "precise").
+
+ 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 +214,6 @@
power_parameters_power_pass=ubuntu;
-
-
nodes
^^^^^
@@ -295,7 +293,6 @@
$ maas-cli maas nodes list architecture="i386/generic"
-
node-groups
^^^^^^^^^^^
Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k
@@ -306,7 +303,7 @@
:samp:`-d, --debug`
Displays debug information listing the API responses.
-
+
:samp:`-h, --help`
Display usage information.
@@ -316,7 +313,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 +324,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 +335,7 @@
nodes.
:samp:`accept <uuid>`
-
+
Accepts a node-group or number of nodegroups indicated by the
supplied UUID
@@ -348,10 +345,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 +355,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 +409,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 +430,7 @@
:samp:`-d, --debug`
Displays debug information listing the API responses.
-
+
:samp:`-h, --help`
Display usage information.
@@ -447,25 +444,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,21 +472,26 @@
The highest value of IP address to allocate via DHCP
-
-
-tag
+tag
^^^
-
-Usage: maas-cli <profile> tag read | update-nodes | rebuild | update |
- nodes | delete
+The tag command is used to manually alter tags, tagged nodes or
+rebuild the automatic tags.
+
+ For more information on how to use them effectively, please see
+ :ref:`deploy-tags`
+
+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>]`
+: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
@@ -500,10 +501,11 @@
:samp:`rebuild`
- Triggers a rebuild of the tag to node mapping.
-
-:samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]`
-
+ 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,54 +518,58 @@
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
+--insecure] list | create
.. program:: maas-cli tag
: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
-^^^^^^^^^^^^^^^
+ 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.
-
-
=== modified file 'docs/man/maas-cli.8.rst'
--- docs/man/maas-cli.8.rst 2012-11-21 11:55:59 +0000
+++ docs/man/maas-cli.8.rst 2012-12-18 18:10:32 +0000
@@ -1,4 +1,3 @@
-
maas-cli
--------
@@ -7,22 +6,576 @@
^^^^^
$ 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.
+
+A new page will load...
+
+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, but before we delve into
+detail on the specifics, here is a sort of 'cheat-sheet' for common
+tasks you might want to do using ``maas-cli``.
+
+ * :ref:`Configure DHCP and DNS services <cli-dhcp>`
+
+ * :ref:`Commission all enlisted nodes <cli-commission>`
+
+ * :ref:`Setting IPMI power parameters for a node <cli-power>`
+
+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.
+
+
+.. boot-images - not useful in user context
+.. ^^^^^^^^^^^
+
+
+.. files - not useful in user context
+.. ^^^^^
+
+
+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"
+
+ 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
+ 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 :ref:`node-group-interfaces`
+
+Usage: maas-cli *<profile>* node-group-interfaces [-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.
+
+.. 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
+
+.. 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`
-
-
=== added file 'docs/media/series.png'
Binary files docs/media/series.png 1970-01-01 00:00:00 +0000 and docs/media/series.png 2012-12-18 18:10:32 +0000 differ
=== modified file 'docs/nodes.rst'
--- docs/nodes.rst 2012-10-04 15:14:12 +0000
+++ docs/nodes.rst 2012-12-18 18:10:32 +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>`::
-
- $ maas-cli api maas nodes accept-all
-
+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-12-18 18:10:32 +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/troubleshooting.rst'
--- docs/troubleshooting.rst 2012-10-03 20:16:24 +0000
+++ docs/troubleshooting.rst 2012-12-18 18:10:32 +0000
@@ -1,7 +1,10 @@
********************
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.
+
+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.
.. contents:: Contents
:depth: 1
@@ -11,60 +14,88 @@
**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.
-
-**SOLUTION:** Check that the hardware clocks are consistent, and if necessary, adjust them. This can usually be done from within the system BIOS, without needing to install an OS
+
+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.
+
+**SOLUTION:** Check that the hardware clocks are consistent, and if necessary,
+adjust them. This can usually be done from within the system BIOS, without
+needing to install an OS
+
Possible Cause: Network drivers
-------------------------------
-Sometimes the hardware can boot from PXE, but fail to load correct drivers when booting the received image. This is sometimes the case when no open source drivers are available for the network hardware.
-
-**SOLUTION:** The best fix for this problem is to install a Linux-friendly network adaptor. It *is* theoretically possible to modify the boot image to include proprietary drivers, but it is not a straightforward task.
+Sometimes the hardware can boot from PXE, but fail to load correct drivers when
+booting the received image. This is sometimes the case when no open source
+drivers are available for the network hardware.
+
+**SOLUTION:** The best fix for this problem is to install a Linux-friendly
+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.
+--------------------------------------------------
+
+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.
**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 DHCP SERVER* as this will cause no end of confusion to the rest of your network and most likely won't discover any nodes either.
+-----------------------------
+If you are using MAAS in a setup with an existing DHCP, *DO NOT SET UP THE MAAS
+DHCP SERVER* as this will cause no end of confusion to the rest of your network
+and most likely won't discover any nodes either.
**SOLUTION**: You will need to either:
-
* Configure your existing DHCP server to point to the MAAS server.
-or
-
-* Enlist nodes using avahi, which is the preferred option. For a quick guide to this, please see https://wiki.ubuntu.com/ServerTeam/MAAS/AvahiBoot
-
+ or
+
+* Enlist nodes using avahi, which is the preferred option. For a quick guide to
+ 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 maas-root``
+ ``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:
+
+If you made a mistake during setup or you just need to reconfigure your MAAS
+server, you can simply run the setup again:
``sudo dpkg-reconfigure maas``
@@ -72,12 +103,17 @@
**Can't find MAAS webpage**
===========================
-The default webpage is located at ``http://<hostname>/maas``. If you can't access it, there are a few things to try:
-
- #. Check that the webserver is running - By default the web interface uses Apache, which runs under the service name *apache2*. To check it, on the MAAS server box you can run ``sudo /etc/init.d/apache2 status``.
- #. Check that the hostname is correct - It may seem obvious, but check that the hostname is being resolved properly. Try running a browser (even a text mode one like lynx) on the same box as the MAAS server and navigating to the page. If that doesn't work, try ``http://127.0.0.1/maas``, which will always point at the local server.
- #. 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
-
-
-Getting help
-~~~~~~~~~~~~
+The default webpage is located at ``http://<hostname>/maas``. If you can't
+access it, there are a few things to try:
+
+ #. Check that the webserver is running - By default the web interface uses
+ Apache, which runs under the service name *apache2*. To check it, on the
+ MAAS server box you can run ``sudo /etc/init.d/apache2 status``.
+ #. Check that the hostname is correct - It may seem obvious, but check that
+ the hostname is being resolved properly. Try running a browser (even a text
+ mode one like lynx) on the same box as the MAAS server and navigating to
+ the page. If that doesn't work, try ``http://127.0.0.1/maas``, which will
+ always point at the local server.
+ #. 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
=== removed directory 'man'
=== removed file 'man/maas-cli.8'
--- man/maas-cli.8 2012-11-23 00:15:30 +0000
+++ man/maas-cli.8 1970-01-01 00:00:00 +0000
@@ -1,758 +0,0 @@
-.TH "MAAS-CLI" "8" "November 22, 2012" "12.10" "MAAS"
-.SH NAME
-maas-cli \- MAAS API commandline utility
-.
-.nr rst2man-indent-level 0
-.
-.de1 rstReportMargin
-\\$1 \\n[an-margin]
-level \\n[rst2man-indent-level]
-level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
--
-\\n[rst2man-indent0]
-\\n[rst2man-indent1]
-\\n[rst2man-indent2]
-..
-.de1 INDENT
-.\" .rstReportMargin pre:
-. RS \\$1
-. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
-. nr rst2man-indent-level +1
-.\" .rstReportMargin post:
-..
-.de UNINDENT
-. RE
-.\" indent \\n[an-margin]
-.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.nr rst2man-indent-level -1
-.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
-..
-.\" Man page generated from reStructeredText.
-.
-.SH USAGE
-.INDENT 0.0
-.INDENT 3.5
-$ maas\-cli <profile> <command> [parameters]
-.UNINDENT
-.UNINDENT
-.sp
-The available commands are dependent on the API you are connecting to and the
-profile you use. The currently available options are explained below.
-.SH DESCRIPTION
-.sp
-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.
-.sp
-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.
-.sp
-Login to the web interface on your MAAS. Click on the username in the
-top right corner and select \(aqPreferences\(aq from the menu which appears.
-[image]
-.sp
-A new page will load...
-[image]
-.sp
-The very first item is a list of MAAS keys. One will have already been
-generated when the system was installed. It\(aqs easiest to just select
-and copy the key (it\(aqs quite long!) and then paste it into the
-commandline. The format of the login command is:
-.sp
-.nf
-.ft C
-$ maas\-cli login <profile\-name> <hostname> <key>
-.ft P
-.fi
-.sp
-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:
-.sp
-.nf
-.ft C
-$ maas\-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2
-.ft P
-.fi
-.sp
-which creates the profile \(aqmaas\(aq 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,
-\(aq\-\(aq 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)
-.sp
-The \fBmaas\-cli\fP command exposes the whole API, so you can do anything
-you actually \fIcan\fP do with MAAS using this command. Unsurprisingly,
-this leaves us with a vast number of options, but before we delve into
-detail on the specifics, here is a sort of \(aqcheat\-sheet\(aq for common
-tasks you might want to do using \fBmaas\-cli\fP.
-.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-\fI\%Configure DHCP and DNS services\fP
-.IP \(bu 2
-\fI\%Commission all enlisted nodes\fP
-.IP \(bu 2
-\fI\%Setting IPMI power parameters for a node\fP
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-The main maas\-cli commands are:
-.sp
-\fBlist\fP
-.INDENT 0.0
-.INDENT 3.5
-lists the details [name url auth\-key] of all the currently logged\-in
-profiles.
-.UNINDENT
-.UNINDENT
-.sp
-\fBlogin <profile> <url> <key>\fP
-.INDENT 0.0
-.INDENT 3.5
-Logs in to the MAAS controller API at the given URL, using the key
-provided and associates this connection with the given profile name.
-.UNINDENT
-.UNINDENT
-.sp
-\fBlogout <profile>\fP
-.INDENT 0.0
-.INDENT 3.5
-Logs out from the given profile, flushing the stored credentials.
-.UNINDENT
-.UNINDENT
-.sp
-\fBrefresh\fP
-.INDENT 0.0
-.INDENT 3.5
-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.
-.UNINDENT
-.UNINDENT
-.sp
-\fB<profile> [command] [options] ...\fP
-.INDENT 0.0
-.INDENT 3.5
-Using the given profile name instructs \fBmaas\-cli\fP to direct the
-subsequent commands and options to the relevant MAAS, which for the
-current API are detailed below...
-.UNINDENT
-.UNINDENT
-.SH ACCOUNT
-.sp
-This command is used for creating and destroying the
-MAAS authorisation tokens associated with a profile.
-.sp
-Usage: maas\-cli \fI<profile>\fP account [\-d \-\-debug] [\-h \-\-help]
-create\-authorisation\-token | delete\-authorisation\-token [token_key=\fI<value>\fP]
-.sp
-\fB\-d, \-\-debug\fP
-.INDENT 0.0
-.INDENT 3.5
-Displays debug information listing the API responses.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-h, \-\-help\fP
-.INDENT 0.0
-.INDENT 3.5
-Display usage information.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-k, \-\-insecure\fP
-.INDENT 0.0
-.INDENT 3.5
-Disables the SSL certificate check.
-.UNINDENT
-.UNINDENT
-.sp
-\fBcreate\-authorisation\-token\fP
-.INDENT 0.0
-.INDENT 3.5
-Creates a new MAAS authorisation token for the current profile
-which can be used to authenticate connections to the API.
-.UNINDENT
-.UNINDENT
-.sp
-\fBdelete\-authorisation\-token token_key=<value>\fP
-.INDENT 0.0
-.INDENT 3.5
-Removes the given key from the list of authorisation tokens.
-.UNINDENT
-.UNINDENT
-.SH NODE
-.sp
-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 \fBmaas\-cli <profile> nodes list\fP command.
-.sp
-USAGE: maas\-cli <profile> node [\-h] release | start | stop | delete |
-read | update <system_id>
-.sp
-\fB\-h, \-\-help\fP
-.INDENT 0.0
-.INDENT 3.5
-Display usage information.
-.UNINDENT
-.UNINDENT
-.sp
-\fBrelease <system_id>\fP
-.INDENT 0.0
-.INDENT 3.5
-Releases the node given by \fI<system_id>\fP
-.UNINDENT
-.UNINDENT
-.sp
-\fBstart <system_id>\fP
-.INDENT 0.0
-.INDENT 3.5
-Powers up the node identified by \fI<system_id>\fP (where MAAS has
-information for power management for this node).
-.UNINDENT
-.UNINDENT
-.sp
-\fBstop <system_id>\fP
-.INDENT 0.0
-.INDENT 3.5
-Powers off the node identified by \fI<system_id>\fP (where MAAS has
-information for power management for this node).
-.UNINDENT
-.UNINDENT
-.sp
-\fBdelete <system_id>\fP
-.INDENT 0.0
-.INDENT 3.5
-Removes the given node from the MAAS database.
-.UNINDENT
-.UNINDENT
-.sp
-\fBread <system_id>\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns all the current known information about the node specified
-by \fI<system_id>\fP
-.UNINDENT
-.UNINDENT
-.sp
-\fBupdate <system_id> [parameters...]\fP
-.INDENT 0.0
-.INDENT 3.5
-Used to change or set specific values for the node. The valid
-parameters are listed below:
-.sp
-.nf
-.ft C
-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"
-
-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
- depend on the power type chosen.
-
-power_parameters_skip_check \(aqtrue\(aq | \(aqfalse\(aq
- Whether to sanity check the supplied parameters against this node\(aqs
- declared power type. The default is \(aqfalse\(aq.
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Example: Setting the power parameters for an ipmi enabled node:
-.sp
-.nf
-.ft C
-maas\-cli maas node update <system_id> \e
- power_type="ipmi" \e
- power_parameters_power_address=192.168.22.33 \e
- power_parameters_power_user=root \e
- power_parameters_power_pass=ubuntu;
-.ft P
-.fi
-.SH NODES
-.sp
-Usage: maas\-cli <profile> nodes [\-h] is\-registered | list\-allocated |
-acquire | list | accept | accept\-all | new | check\-commissioning
-.sp
-\fB\-h, \-\-help\fP
-.INDENT 0.0
-.INDENT 3.5
-Display usage information.
-.UNINDENT
-.UNINDENT
-.sp
-\fBaccept <system_id>\fP
-.INDENT 0.0
-.INDENT 3.5
-Accepts the node referenced by <system_id>.
-.UNINDENT
-.UNINDENT
-.sp
-\fBaccept\-all\fP
-.INDENT 0.0
-.INDENT 3.5
-Accepts all currently discovered but not previously accepted nodes.
-.UNINDENT
-.UNINDENT
-.sp
-\fBacquire\fP
-.INDENT 0.0
-.INDENT 3.5
-Allocates a node to the profile used to issue the command. Any
-ready node may be allocated.
-.UNINDENT
-.UNINDENT
-.sp
-\fBis\-registered mac_address=<address>\fP
-.INDENT 0.0
-.INDENT 3.5
-Checks to see whether the specified MAC address is registered to a
-node.
-.UNINDENT
-.UNINDENT
-.sp
-\fBlist\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns a JSON formatted object listing all the currently known
-nodes, their system_id, status and other details.
-.UNINDENT
-.UNINDENT
-.sp
-\fBlist\-allocated\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns a JSON formatted object listing all the currently allocated
-nodes, their system_id, status and other details.
-.UNINDENT
-.UNINDENT
-.sp
-\fBnew architecture=<value> mac_addresses=<value> [parameters]\fP
-.INDENT 0.0
-.INDENT 3.5
-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:
-.sp
-.nf
-.ft C
-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)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBcheck\-commissioning\fP
-.INDENT 0.0
-.INDENT 3.5
-Displays current status of nodes in the commissioning phase. Any
-that have not returned before the system timeout value are listed
-as "failed".
-.UNINDENT
-.UNINDENT
-.sp
-Examples:
-Accept and commission all discovered nodes:
-.sp
-.nf
-.ft C
-$ maas\-cli maas nodes accept\-all
-.ft P
-.fi
-.sp
-List all known nodes:
-.sp
-.nf
-.ft C
-$ maas\-cli maas nodes list
-.ft P
-.fi
-.sp
-Filter the list using specific key/value pairs:
-.sp
-.nf
-.ft C
-$ maas\-cli maas nodes list architecture="i386/generic"
-.ft P
-.fi
-.SH NODE-GROUPS
-.sp
-Usage: maas\-cli <profile> node\-groups [\-d \-\-debug] [\-h \-\-help] [\-k
-\-\-insecure] register | list | refresh\-workers | accept | reject
-.sp
-\fB\-d, \-\-debug\fP
-.INDENT 0.0
-.INDENT 3.5
-Displays debug information listing the API responses.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-h, \-\-help\fP
-.INDENT 0.0
-.INDENT 3.5
-Display usage information.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-k, \-\-insecure\fP
-.INDENT 0.0
-.INDENT 3.5
-Disables the SSL certificate check.
-.UNINDENT
-.UNINDENT
-.sp
-\fBregister uuid=<value> name=<value> interfaces=<json_string>\fP
-.INDENT 0.0
-.INDENT 3.5
-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=\(aq["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"}]\(aq
-.UNINDENT
-.UNINDENT
-.sp
-\fBlist\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns a JSON list of all currently defined node groups.
-.UNINDENT
-.UNINDENT
-.sp
-\fBrefresh_workers\fP
-.INDENT 0.0
-.INDENT 3.5
-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.
-.UNINDENT
-.UNINDENT
-.sp
-\fBaccept <uuid>\fP
-.INDENT 0.0
-.INDENT 3.5
-Accepts a node\-group or number of nodegroups indicated by the
-supplied UUID
-.UNINDENT
-.UNINDENT
-.sp
-\fBreject <uuid>\fP
-.INDENT 0.0
-.INDENT 3.5
-Rejects a node\-group or number of nodegroups indicated by the
-supplied UUID
-.UNINDENT
-.UNINDENT
-.SH NODE-GROUP-INTERFACE
-.sp
-For managing the interfaces. See also \fI\%node-group-interfaces\fP
-.sp
-Usage: maas\-cli \fI<profile>\fP node\-group\-interfaces [\-d \-\-debug] [\-h
-\-\-help] [\-k \-\-insecure] read | update | delete [parameters...]
-.sp
-..program:: maas\-cli node\-group\-interface
-.sp
-\fBread <uuid> <interface>\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns the current settings for the given UUID and interface
-.UNINDENT
-.UNINDENT
-.sp
-\fBupdate [parameters]\fP
-.INDENT 0.0
-.INDENT 3.5
-Changes the settings for the interface according to the given
-parameters:
-.sp
-.nf
-.ft C
-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
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBdelete <uuid> <interface>\fP
-.INDENT 0.0
-.INDENT 3.5
-Removes the entry for the given UUID and interface.
-.UNINDENT
-.UNINDENT
-.sp
-Example:
-Configuring DHCP and DNS.
-.sp
-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:
-.sp
-.nf
-.ft C
-$ uuid=$(maas\-cli <profile> node\-groups list | grep uuid | cut \-d\e" \-f4)
-.ft P
-.fi
-.sp
-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:
-.sp
-.nf
-.ft C
-$ maas\-cli <profile> node\-group\-interface update $uuid eth0 \e
- ip_range_high=192.168.123.200 \e
- ip_range_low=192.168.123.100 \e
- management=2 \e
- broadcast_ip=192.168.123.255 \e
- router_ip=192.168.123.1 \e
-.ft P
-.fi
-.sp
-Replacing the example values with those required for this network. The
-only non\-obvious parameter is \(aqmanagement\(aq which takes the values 0
-(no management), 1 (manage DHCP) and 2 (manage DHCP and DNS).
-.SH NODE-GROUP-INTERFACES
-.sp
-The node\-group\-interfaces commands are used for configuring the
-management of DHCP and DNS services where these are managed by MAAS.
-.sp
-Usage: maas\-cli \fI<profile>\fP node\-group\-interfaces [\-d \-\-debug] [\-h
-\-\-help] [\-k \-\-insecure] list | new [parameters...]
-.sp
-\fB\-d, \-\-debug\fP
-.INDENT 0.0
-.INDENT 3.5
-Displays debug information listing the API responses.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-h, \-\-help\fP
-.INDENT 0.0
-.INDENT 3.5
-Display usage information.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-k, \-\-insecure\fP
-.INDENT 0.0
-.INDENT 3.5
-Disables the SSL certificate check.
-.UNINDENT
-.UNINDENT
-.sp
-\fBlist <label>\fP
-.INDENT 0.0
-.INDENT 3.5
-Lists the current stored configurations for the given identifier
-<label> in a key:value format which should be easy to decipher.
-.UNINDENT
-.UNINDENT
-.sp
-\fBnew <label> ip=<value> interface=<if_device> [parameters...]\fP
-.INDENT 0.0
-.INDENT 3.5
-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:
-.sp
-.nf
-.ft C
-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
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SH TAG
-.INDENT 0.0
-.TP
-.B Usage: maas\-cli <profile> tag read | update\-nodes | rebuild | update |
-nodes | delete
-.UNINDENT
-.sp
-\fBread <tag_name>\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns information on the tag specified by <name>
-.UNINDENT
-.UNINDENT
-.sp
-\fBupdate\-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]\fP
-.INDENT 0.0
-.INDENT 3.5
-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.
-.UNINDENT
-.UNINDENT
-.sp
-\fBrebuild\fP
-.INDENT 0.0
-.INDENT 3.5
-Triggers a rebuild of the tag to node mapping.
-.UNINDENT
-.UNINDENT
-.sp
-\fBupdate <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]\fP
-.INDENT 0.0
-.INDENT 3.5
-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.
-.UNINDENT
-.UNINDENT
-.sp
-\fBnodes <tag_name>\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns a list of nodes which are associated with the given tag.
-.UNINDENT
-.UNINDENT
-.sp
-\fBdelete <tag_name>\fP
-.INDENT 0.0
-.INDENT 3.5
-Deletes the given tag.
-.UNINDENT
-.UNINDENT
-.SH TAGS
-.sp
-Tags are a really useful way of identifying nodes with particular
-characteristics.
-.sp
-Usage: maas\-cli <profile> tag [\-d \-\-debug] [\-h \-\-help] [\-k
-\-\-insecure] list | new
-.sp
-\fB\-d, \-\-debug\fP
-.INDENT 0.0
-.INDENT 3.5
-Displays debug information listing the API responses.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-h, \-\-help\fP
-.INDENT 0.0
-.INDENT 3.5
-Display usage information.
-.UNINDENT
-.UNINDENT
-.sp
-\fB\-k, \-\-insecure\fP
-.INDENT 0.0
-.INDENT 3.5
-Disables the SSL certificate check.
-.UNINDENT
-.UNINDENT
-.sp
-\fBlist\fP
-.INDENT 0.0
-.INDENT 3.5
-Returns a JSON object listing all the current tags known by the MAAS server
-.UNINDENT
-.UNINDENT
-.sp
-\fBcreate name=<value> definition=<value> [comment=<value>]\fP
-.INDENT 0.0
-.INDENT 3.5
-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 \fBlshw\fP on the node.
-.UNINDENT
-.UNINDENT
-.sp
-Example:
-Adding a tag to all nodes which have an Intel GPU:
-.sp
-.nf
-.ft C
-$ maas\-cli maas tags new name=\(aqintel\-gpu\(aq \e
- comment=\(aqMachines which have an Intel display driver\(aq \e
- definition=\(aqcontains(//node[@id="display"]/vendor, "Intel")
-.ft P
-.fi
-.SH UNUSED COMMANDS
-.sp
-Because the \fBmaas\-cli\fP 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.
-.SH FURTHER DOCUMENTATION
-.sp
-For more documentation of MAAS, please see \fI\%https://maas.ubuntu.com/docs\fP
-.SH SEE ALSO
-.sp
-\fImaas\fP
-.SH AUTHOR
-Canonical 2012
-.SH COPYRIGHT
-2012, MAAS Developers
-.\" Generated by docutils manpage writer.
-.\"
-.
=== removed file 'man/maas-import-pxe-files.8'
--- man/maas-import-pxe-files.8 2012-11-23 00:15:30 +0000
+++ man/maas-import-pxe-files.8 1970-01-01 00:00:00 +0000
@@ -1,81 +0,0 @@
-.TH "MAAS-IMPORT-PXE-FILES" "8" "November 22, 2012" "12.10" "MAAS"
-.SH NAME
-maas-import-pxe-files \- MAAS helper script
-.
-.nr rst2man-indent-level 0
-.
-.de1 rstReportMargin
-\\$1 \\n[an-margin]
-level \\n[rst2man-indent-level]
-level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
--
-\\n[rst2man-indent0]
-\\n[rst2man-indent1]
-\\n[rst2man-indent2]
-..
-.de1 INDENT
-.\" .rstReportMargin pre:
-. RS \\$1
-. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
-. nr rst2man-indent-level +1
-.\" .rstReportMargin post:
-..
-.de UNINDENT
-. RE
-.\" indent \\n[an-margin]
-.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.nr rst2man-indent-level -1
-.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
-..
-.\" Man page generated from reStructeredText.
-.
-.SH USAGE
-.sp
-maas\-import\-pxe\-files [\-h, \-\-help]
-.SH DESCRIPTION
-.sp
-This is a helper script for the MAAS software. It downloads Ubuntu
-images and organises them for use by MAAS in commissioning nodes.
-The script is usually run regularly by a cron task, though it
-needs to be run manually the first time a MAAS system is installed.
-Images that are already in place are kept unchanged, unless the
-version in the archive has since been updated.
-.sp
-The script reads a configuration file /etc/maas/import_pxe_files in
-order to determine:
-.sp
-\fBARCHIVE:\fP
-Location of the Ubuntu download archive
-.sp
-\fBRELEASES:\fP
-Ubuntu releases to download
-.sp
-\fBARCHES:\fP
-Architectures for which images should be downloaded
-.sp
-To support development setups that run directly from a code branch,
-it will also look for /etc/maas/import_pxe_files relative to the
-current directory.
-.sp
-The script uses \fIwget\fP to download the kernel and initrd image for
-each architecture in ARCHES and each release in RELEASES. In addition
-it copies the Intel\-architecture pre\-boot loader \fIpxelinux.0\fP (plus
-some of its modules such as \fIchain.c32\fP) from its installed location in
-/usr/lib/syslinux/.
-.sp
-These images are the minimum that\(aqs required to start installing a node.
-During installation, a node may download its packages over the network.
-.SH FURTHER DOCUMENTATION
-.sp
-For more documentation of MAAS, please see \fI\%https://maas.ubuntu.com/docs\fP
-.SH SEE ALSO
-.sp
-\fImaas\fP, \fImaas\-cli\fP
-.SH AUTHOR
-Canonical 2012
-.SH COPYRIGHT
-2012, MAAS Developers
-.\" Generated by docutils manpage writer.
-.\"
-.
=== removed file 'man/maas.8'
--- man/maas.8 2012-11-23 00:15:30 +0000
+++ man/maas.8 1970-01-01 00:00:00 +0000
@@ -1,72 +0,0 @@
-.TH "MAAS" "8" "November 22, 2012" "12.10" "MAAS"
-.SH NAME
-maas \- MAAS administration tool
-.
-.nr rst2man-indent-level 0
-.
-.de1 rstReportMargin
-\\$1 \\n[an-margin]
-level \\n[rst2man-indent-level]
-level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
--
-\\n[rst2man-indent0]
-\\n[rst2man-indent1]
-\\n[rst2man-indent2]
-..
-.de1 INDENT
-.\" .rstReportMargin pre:
-. RS \\$1
-. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
-. nr rst2man-indent-level +1
-.\" .rstReportMargin post:
-..
-.de UNINDENT
-. RE
-.\" indent \\n[an-margin]
-.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.nr rst2man-indent-level -1
-.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
-..
-.\" Man page generated from reStructeredText.
-.
-.SH USAGE
-.sp
-maas [\-h, \-\-help] createsuperuser | changepassword | shell
-.SH DESCRIPTION
-.sp
-The \fImaas\fP command is part of Canonical\(aqs Metal As A Service software. It is
-derived from and can be used similarly to the \fIdjango\-admin\fP command, and must
-be run with root privileges.
-.sp
-For the end user, there are only three subcommands of interest.
-.INDENT 0.0
-.TP
-.B \fBcreatesuperuser\fP
-This subcommand is used to create a superuser for the
-MAAS install. The suggested username is "root". This command usually only
-needs to be run when installing MAAS for the first time.
-.TP
-.B \fBchangepassword\fP
-This subcommand is used to change the superuser password
-for the MAAS install. You will be prompted to enter a new password, and then
-enter it once again to verify.
-.TP
-.B \fBshell\fP
-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.
-.UNINDENT
-.SH FURTHER DOCUMENTATION
-.sp
-For more documentation of MAAS, please see \fI\%https://maas.ubuntu.com/docs\fP
-.SH SEE ALSO
-.sp
-\fImaas\-cli\fP
-.SH AUTHOR
-Canonical 2012
-.SH COPYRIGHT
-2012, MAAS Developers
-.\" Generated by docutils manpage writer.
-.\"
-.
Follow ups
