Merge lp:~allenap/maas/keep-rendered-man-pages into lp:maas/trunk

[Gavin Panella]

Store generated man pages in the tree.

Building the man pages requires a full Django+MAAS stack, and unravelling that requires time. This is a not too ugly stop-gap.

[Julian Edwards (julian-edwards)]

review: Approve

[Julian Edwards (julian-edwards)]

FWIW I'd be happy with a test that checks consistency between source and generated page so it forces users to regenerate them before landing. This is probably much simpler than worrying about building them automatically.

=== modified file '.bzrignore'
--- .bzrignore	2012-11-20 20:59:00 +0000
+++ .bzrignore	2012-11-22 23:43:21 +0000
@@ -21,7 +21,7 @@
 ./lib
 ./local
 ./logs/*
-./man
+./man/.doctrees
 ./media/demo/*
 ./media/development
 ./parts

=== modified file 'Makefile'
--- Makefile	2012-11-21 11:19:38 +0000
+++ Makefile	2012-11-22 23:43:21 +0000
@@ -159,7 +159,7 @@
 	$(RM) *.log
 	$(RM) docs/api.rst
 	$(RM) -r docs/_autosummary docs/_build
-	$(RM) -r man
+	$(RM) -r man/.doctrees
 
 distclean: clean stop
 	$(RM) -r bin include lib local

=== added directory 'man'
=== added file 'man/maas-cli.8'
--- man/maas-cli.8	1970-01-01 00:00:00 +0000
+++ man/maas-cli.8	2012-11-22 23:43:21 +0000
@@ -0,0 +1,758 @@
+.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.
+.\" 
+.

=== added file 'man/maas-import-pxe-files.8'
--- man/maas-import-pxe-files.8	1970-01-01 00:00:00 +0000
+++ man/maas-import-pxe-files.8	2012-11-22 23:43:21 +0000
@@ -0,0 +1,81 @@
+.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.
+.\" 
+.

=== added file 'man/maas.8'
--- man/maas.8	1970-01-01 00:00:00 +0000
+++ man/maas.8	2012-11-22 23:43:21 +0000
@@ -0,0 +1,72 @@
+.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.
+.\" 
+.