Merge lp:~allenap/maas/markdownify into lp:~maas-committers/maas/trunk

[Gavin Panella]

Convert MAAS docs from ReStructuredText using Sphinx to GitHub-Flavoured Markdown, with some extensions. This approach is taken from the Juju documentation (http://github.com/juju/docs).

Still to do:

* Convert template/doc.txt

* Render api.rst as Markdown instead.

* Convert README.

* Check for remaining references to RST, SPHINX, and so on.

* Move rendering of pages into the region server, done on the fly.

* Static rendering should perhaps be done in a separate branch.
   This would pull in the docs for 1.5, 1.7, 1.8, and trunk.

[MAAS Lander (maas-lander)]

Transitioned to Git.

lp:maas has now moved from Bzr to Git.
Please propose your branches with Launchpad using Git.

git clone https://git.launchpad.net/maas

Unmerged revisions

3842. By Gavin Panella on 2015-04-17

Remove remaining Sphinx machinery.

3841. By Gavin Panella on 2015-04-17

Include the rst-to-md convertion script.

3840. By Gavin Panella on 2015-04-17

3rd attempt at converting the docs from rst to markdown.

3839. By Gavin Panella on 2015-04-17

Undo 1st conversion of docs.

3838. By Gavin Panella on 2015-04-17

Undo 2nd conversion of docs.

3837. By Gavin Panella on 2015-04-17

Render docs into HTML.

3836. By Gavin Panella on 2015-04-17

Documentation plugins borrowed from http://github.com/juju/docs.

3835. By Gavin Panella on 2015-04-17

Update Makefile.

3834. By Gavin Panella on 2015-04-17

Update rendered man pages.

3833. By Gavin Panella on 2015-04-17

Convert all documentation to Markdown using pandoc, 2nd attempt.

=== modified file '.bzrignore'
--- .bzrignore	2015-03-25 20:32:06 +0000
+++ .bzrignore	2015-04-17 21:06:27 +0000
@@ -19,15 +19,12 @@
 ./db
 ./develop-eggs
 ./dist
-./docs/_autosummary
-./docs/_build
 ./docs/api.rst
 ./eggs
 ./include
 ./lib
 ./local
 ./logs/*
-./man/.doctrees
 ./media/demo/*
 ./media/development
 ./parts
 
=== modified file '.gitignore'
--- .gitignore	2015-03-23 15:15:54 +0000
+++ .gitignore	2015-04-17 21:06:27 +0000
@@ -19,15 +19,12 @@
 /db
 /develop-eggs
 /dist
-/docs/_autosummary
-/docs/_build
 /docs/api.rst
 /eggs
 /include
 /lib
 /local
 /logs/*
-/man/.doctrees
 /media/demo/*
 /media/development
 /parts
 
=== modified symlink 'CHANGELOG'
=== target changed u'docs/changelog.rst' => u'docs/changelog.md'
=== added symlink 'HACKING'
=== target is u'docs/hacking.md'
=== added symlink 'INSTALL'
=== target is u'docs/install.md'
=== modified file 'Makefile'
--- Makefile	2015-04-16 11:51:27 +0000
+++ Makefile	2015-04-17 21:06:27 +0000
@@ -141,14 +141,6 @@
 	$(buildout) install flake8
 	@touch --no-create $@
 
-bin/rst-lint: bin/buildout buildout.cfg versions.cfg setup.py
-	$(buildout) install rst-lint
-	@touch --no-create $@
-
-bin/sphinx bin/sphinx-build: bin/buildout buildout.cfg versions.cfg setup.py
-	$(buildout) install sphinx
-	@touch --no-create $@
-
 bin/py bin/ipy: bin/buildout buildout.cfg versions.cfg setup.py
 	$(buildout) install repl
 	@touch --no-create bin/py bin/ipy
@@ -206,7 +198,7 @@
 	@$(error Use `$(MAKE) test` to generate coverage data, or invoke a \
             test script using the `--with-coverage` flag)
 
-lint: lint-py lint-js lint-doc lint-rst
+lint: lint-py lint-js lint-doc
 
 pocketlint = $(call available,pocketlint,python-pocket-lint)
 
@@ -230,16 +222,6 @@
 lint-doc:
 	@utilities/doc-lint
 
-# lint-rst 0.11.1 shouldn't be used on our documentation because it
-# doesn't understand Sphinx's extensions, and doesn't grok linking
-# between documents, hence complaints about broken links. However,
-# Sphinx itself warns about lint when building the docs.
-lint-rst: sources = README HACKING.txt schema/README.rst
-lint-rst: bin/rst-lint
-	@find $(sources) -type f \
-	    -printf 'Linting %p...\n' \
-	    -exec bin/rst-lint --encoding=utf8 {} \;
-
 # JavaScript lint is checked in parallel for speed.  The -n20 -P4 seetting
 # worked well on a multicore SSD machine with the files cached, roughly
 # doubling the speed, but it may need tuning for slower systems or cold caches.
@@ -260,16 +242,19 @@
 sampledata: bin/maas-region-admin bin/database syncdb
 	$(dbrun) bin/maas-region-admin loaddata src/maasserver/fixtures/dev_fixture.yaml
 
-doc: bin/sphinx docs/api.rst
-	bin/sphinx
-
-doc-with-versions: bin/sphinx docs/api.rst
-	cd docs/_build; make SPHINXOPTS="-A add_version_switcher=true" html
-
-man: $(patsubst docs/man/%.rst,man/%,$(wildcard docs/man/*.rst))
-
-man/%: docs/man/%.rst | bin/sphinx-build
-	bin/sphinx-build -b man docs man $^
+doc: $(patsubst %.md,%.html,$(shell find docs -name '*.md'))
+
+%.html: %.md
+	PYTHONPATH="docs/plugins:docs/plugins/gfm" markdown_py \
+	    -x callouts -x anchors_away -x foldouts -x meta -x def_list \
+	    -x attr_list -e utf8 --file=$@ $^
+	@# FIXME: broken plugin: partial_gfm
+	@# FIXME: render these pages on-the-fly into a template.
+
+man: $(patsubst docs/man/%.md,man/%,$(wildcard docs/man/*.md))
+
+man/%: docs/man/%.md
+	pandoc -s -f markdown_github -t man $^ -o $@
 
 enums: $(js_enums)
 
@@ -290,8 +275,6 @@
 	$(RM) $(js_enums)
 	$(RM) *.log
 	$(RM) docs/api.rst
-	$(RM) -r docs/_autosummary docs/_build
-	$(RM) -r man/.doctrees
 	$(RM) coverage.data coverage.xml
 	$(RM) -r coverage
 
 
=== modified file 'buildout.cfg'
--- buildout.cfg	2015-04-10 13:58:31 +0000
+++ buildout.cfg	2015-04-17 21:06:27 +0000
@@ -9,7 +9,6 @@
   region
   region-test
   repl
-  sphinx
   testing-test
 extensions = buildout-versions
 buildout_versions_file = versions.cfg
@@ -245,22 +244,6 @@
 entry-points =
   flake8=flake8.run:main
 
-[rst-lint]
-recipe = zc.recipe.egg
-eggs =
-  restructuredtext-lint
-scripts =
-  rst-lint
-
-[sphinx]
-recipe = collective.recipe.sphinxbuilder
-source = ${buildout:directory}/docs
-build = ${buildout:directory}/docs/_build
-extra-paths = ${common:extra-paths}
-eggs =
-  ${region:eggs}
-  ${cluster:eggs}
-
 # Convenient REPLs with all eggs available.
 [repl]
 recipe = z3c.recipe.scripts
 
=== removed directory 'docs/_static'
=== removed file 'docs/_static/versions.js'
--- docs/_static/versions.js	2014-04-14 21:42:00 +0000
+++ docs/_static/versions.js	1970-01-01 00:00:00 +0000
@@ -1,91 +0,0 @@
-/* Javascript utilities to create a version switcher widget.
-
-This is mostly done, but not limited to support creating links
-between the different versions of the MAAS documentation on
-maas.ubuntu.com.
-
-*/
-
-function page_exists(url) {
-    // Returns wether a page at the give URL exists or not.
-    var result = false;
-    $.ajax({
-        type: 'HEAD',
-        url: url,
-        async: false,
-        success: function () {
-            result = true;
-        }
-    });
-    return result;
-};
-
-function doc_page(version, doc_prefix) {
-    // Returns the URL of the page equivalent to the current page but from
-    // the given version of the documentation.
-    // e.g. if the current page is 'http://host/<doc_prefix>1.6/somepage.html', calling
-    // doc_page('1.7') will return 'http://host/<doc_prefix>1.7/somepage.html'.
-    var pattern = new RegExp('\/' + doc_prefix + '([\\d\\.]*)\/')
-    var newpathname = window.location.pathname.replace(
-        pattern, '/' + doc_prefix + version + '/');
-    return window.location.origin + newpathname + window.location.hash;
-};
-
-function doc_homepage(version, doc_prefix) {
-    // Returns the URL of the homepage for the documentation of the given
-    // version.
-    return window.location.origin + '/' + doc_prefix + version + '/';
-};
-
-
-function set_up_version_switcher(selector, doc_prefix) {
-    // Create version switcher widget.
-    $(selector).replaceWith($('\
-        <h3>Version</h3> \
-        <select id="id_sidebar_release" name="release"> \
-        </select>'));
-
-    release_select = $("#id_sidebar_release");
-
-    // Request version list and populate version switcher widget with it.
-    var json_url = "/" + doc_prefix + "/_static/versions.json";
-    var jqxhr = $.getJSON(json_url, function(data) {
-        var first = true;
-        $.each(data, function (value, text) {
-            var option_value = value;
-            if (first) {
-                // The first element corresponds to the documentation for trunk.
-                option_value = '';
-                first = false;
-            }
-            var option = $("<option></option>").attr("value", option_value).text(text);
-            if (value == DOCUMENTATION_OPTIONS.VERSION) {
-                option.attr('selected', 'selected');
-            }
-            release_select.append(option);
-        });
-    });
-
-    // jqxhr.fail only exists in recent versions of jQuery;
-    // it's not there with the version shipped with Sphinx
-    // on Precise.
-    if ($.isFunction(jqxhr.fail)) {
-    	jqxhr.fail(function(jqXHR) {
-	        console.log("error requesting versions file");
-	        console.log(jqXHR);
-	    });
-    }
-
-    // Handle version switcher change: redirect to the equivalent page in the
-    // selected version of the documentation if that page exists, redirects to the
-    // homepage of the selected version of the documentation otherwise.
-    $("#id_sidebar_release").change(function () {
-        var version = $(this).find('option:selected').val();
-        var same_page_in_other_version = doc_page(version, doc_prefix);
-        if (page_exists(same_page_in_other_version)) {
-            window.location = same_page_in_other_version;
-        } else {
-            window.location = doc_homepage(version, doc_prefix);
-        }
-    });
-};
 
=== removed directory 'docs/_templates'
=== removed directory 'docs/_templates/maas'
=== removed file 'docs/_templates/maas/layout.html'
--- docs/_templates/maas/layout.html	2014-06-11 15:27:54 +0000
+++ docs/_templates/maas/layout.html	1970-01-01 00:00:00 +0000
@@ -1,31 +0,0 @@
-{%- extends "basic/layout.html" %}
-{% set css_files = ['https://assets.ubuntu.com/sites/guidelines/css/latest/ubuntu-styles.css', 'https://assets.ubuntu.com/sites/ubuntu/latest/u/css/global.css', '_static/css/main.css'] %}
-
-{% block sidebarlogo %}
-<a style="border:0" title="MAAS Documentation Homepage" href="{{ pathto('index.html', 1) }}"><img src="{{ pathto('_static/maas-logo-200.png',1) }}" alt="MAAS logo"/></a>
-<h2 style="text-align:center;">MAAS</h2>
-<p style="font-style:italic;font-size:0.9em; text-align:center; margin-bottom:1.5em">Metal As A Service.</p>
-<span id="version_switcher"></span>
-<br/>
-<br/>
-{% endblock %}
-
-{# Remove 'modules' and 'index' from rellinks: they point to
-   autogenerated code documentation pages that we don't want
-   to advertise too much.
-#}
-{%- set rellinks = rellinks[2:] %}
-
-{%- block footer %}
-<footer class="global clearfix">
-  <div class="legal clearfix">
-    <p>&copy; Copyright {{ copyright }}. Ubuntu and Canonical are registered trademarks of
-      <a href="http://canonical.com">Canonical Ltd</a>.
-    </p>
-    <p>
-      Revision {{ bzr_last_revision_number}} ({{ bzr_last_revision_date }}).
-      Documentation generation date: {{ bzr_build_date }}.
-    </p>
-  </div>
-</footer>
-{%- endblock %}
 
=== removed file 'docs/_templates/maas/localtoc.html'
--- docs/_templates/maas/localtoc.html	2013-12-06 19:26:05 +0000
+++ docs/_templates/maas/localtoc.html	1970-01-01 00:00:00 +0000
@@ -1,3 +0,0 @@
-{%- if display_toc %}
-  {{ toc }}
-{%- endif %}
 
=== removed file 'docs/_templates/maas/relations.html'
--- docs/_templates/maas/relations.html	2014-04-08 20:58:05 +0000
+++ docs/_templates/maas/relations.html	1970-01-01 00:00:00 +0000
@@ -1,31 +0,0 @@
-<script type="text/javascript">
-$(document).ready(function () {
-  if ({{ add_version_switcher }}) {
-    $.ajaxSetup({cache: true});
-    $.getScript('{{ versions_json_path }}', function() {
-      console.log( "Versions script loaded." );
-      set_up_version_switcher('#version_switcher', '{{ doc_prefix }}');
-    });
-}
-});
-</script>
-
-<h3>Related Topics</h3>
-<ul>
-  <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul>
-  {%- for parent in parents %}
-  <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul>
-  {%- endfor %}
-    {%- if prev %}
-      <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter')
-        }}">{{ prev.title }}</a></li>
-    {%- endif %}
-    {%- if next %}
-      <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter')
-        }}">{{ next.title }}</a></li>
-    {%- endif %}
-  {%- for parent in parents %}
-  </ul></li>
-  {%- endfor %}
-  </ul></li>
-</ul>
 
=== removed directory 'docs/_templates/maas/static'
=== removed directory 'docs/_templates/maas/static/css'
=== removed file 'docs/_templates/maas/static/css/main.css'
--- docs/_templates/maas/static/css/main.css	2014-06-09 16:25:19 +0000
+++ docs/_templates/maas/static/css/main.css	1970-01-01 00:00:00 +0000
@@ -1,75 +0,0 @@
-pre {
-  background-color:#EEEEEE;
-  background-position:initial initial;
-  background-repeat:initial initial;
-  line-height:1.3em;
-  margin:15px 0px;
-  padding:7px 30px;
-}
-
-div.document {
-  width: 984px;
-  margin: 10px auto 0 auto;
-}
-
-div.body h1 {
-  margin-top: 20px;
-  padding-top: 0;
-  font-size: 250%;
-}
-
-.bodywrapper ul ul {
-  margin-top: .4em;
-  margin-bottom: .4em;
-}
-
-div.sphinxsidebar ul ul {
-  margin-top: .4em;
-  margin-bottom: .4em;
-}
-
-body {
-  padding-top: 0px;
-}
-
-div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6, div.admonition p.admonition-title {
-  font-family: Ubuntu,Arial,"libra sans",sans-serif;
-}
-
-div.admonition {
-  margin: 20px 0px;
-  color: #3E4349;
-}
-
-div.admonition p.admonition-title {
-  font-size: 20px;
-}
-
-.document {
-    -moz-box-sizing: border-box;
-    background: none repeat scroll 0 0 #FFFFFF;
-    border-radius: 4px;
-    box-shadow: 0 0 3px #C9C9C9;
-}
-
-div.sphinxsidebarwrapper {
-  padding: 18px 10px 18px 20px;
-}
-
-form input[type="text"] {
-  display: inline;
-}
-
-div.sphinxsidebar #searchbox input[type="text"] {
-  width: 110px;
-  padding: 4px 3px;
-}
-
-div.sphinxsidebar #searchbox input[type="submit"] {
-  width: 40px;
-}
-
-a:active, a:focus, a:hover {
-  text-decoration: none;
-  border-bottom: 1px solid #6D4100;
-}
 
=== removed file 'docs/_templates/maas/static/flasky.css_t'
--- docs/_templates/maas/static/flasky.css_t	2014-06-09 16:25:19 +0000
+++ docs/_templates/maas/static/flasky.css_t	1970-01-01 00:00:00 +0000
@@ -1,564 +0,0 @@
-/*
- * flasky.css_t
- * ~~~~~~~~~~~~
- *
- * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz.
- * :license: Flask Design License, see LICENSE for details.
- */
-
-{% set page_width = '940px' %}
-{% set sidebar_width = '220px' %}
-
-@import url("basic.css");
-
-/* -- page layout ----------------------------------------------------------- */
-
-body {
-    font-family: "Georgia", "Open Sans", OpenSansRegular, sans-serif;
-    font-size: 16px;
-    background: #fff;
-    font-weight: 400;
-    color: #000;
-    margin: 0;
-    padding: 0;
-}
-
-div.document {
-    width: {{ page_width }};
-    margin: 10px auto 0 auto;
-}
-
-div.documentwrapper {
-    float: left;
-    width: 100%;
-}
-
-div.bodywrapper {
-    margin: 0 0 0 {{ sidebar_width }};
-}
-
-div.sphinxsidebar {
-    width: {{ sidebar_width }};
-}
-
-hr {
-    border: 1px solid #B1B4B6;
-}
-
-div.body {
-    background-color: white;
-    color: #3E4349;
-    padding: 0 30px 0 30px;
-}
-
-img.floatingflask {
-    padding: 0 0 10px 10px;
-    float: right;
-}
-
-div.footer {
-    width: {{ page_width }};
-    margin: 20px auto 30px auto;
-    font-size: 14px;
-    color: #888;
-    text-align: right;
-}
-
-div.footer a {
-    color: #888;
-}
-
-div.related {
-    width: {{ page_width }};
-    margin: 10px auto 0 auto;
-}
-
-div.related h3 {
-    display: none;
-}
-
-div.sphinxsidebar a {
-    color: #444;
-    text-decoration: none;
-    border-bottom: 1px dotted #999;
-}
-
-div.sphinxsidebar a:hover {
-    border-bottom: 1px solid #999;
-}
-
-div.sphinxsidebar {
-    font-size: 14px;
-    line-height: 1.5;
-}
-
-div.sphinxsidebarwrapper {
-    padding: 18px 10px;
-}
-
-div.sphinxsidebarwrapper p.logo {
-    padding: 0;
-    margin: -10px 0 0 -20px;
-    text-align: center;
-}
-
-div.sphinxsidebar h3,
-div.sphinxsidebar h4 {
-    font-family: 'Antic Slab' ,'Garamond', 'Georgia', serif;
-    color: #000;
-    font-size: 24px;
-    font-weight: normal;
-    margin: 30px 0 5px 0;
-    padding: 0;
-}
-
-div.sphinxsidebar h4 {
-    font-size: 20px;
-}
-
-div.sphinxsidebar h3 a {
-    color: #000;
-}
-
-div.sphinxsidebar p.logo a,
-div.sphinxsidebar h3 a,
-div.sphinxsidebar p.logo a:hover,
-div.sphinxsidebar h3 a:hover {
-    border: none;
-}
-
-div.sphinxsidebar p {
-    color: #555;
-    margin: 10px 0;
-}
-
-div.sphinxsidebar ul {
-    margin: 10px 0px;
-    padding: 0;
-    color: #000;
-}
-
-div.sphinxsidebar input {
-    border: 1px solid #ccc;
-    font-family: 'Georgia', serif;
-    font-size: 1em;
-}
-
-/* -- body styles ----------------------------------------------------------- */
-
-a {
-    color: #004B6B;
-    text-decoration: underline;
-}
-
-a:hover {
-    color: #6D4100;
-    text-decoration: underline;
-}
-
-div.body h1,
-div.body h2,
-div.body h3,
-div.body h4,
-div.body h5,
-div.body h6 {
-    font-family: 'Antic Slab', serif;
-    font-weight: normal;
-    margin: 30px 0px 10px 0px;
-    padding: 0;
-    text-shadow: 1px 1px 3px #ddd;
-    color: #000;
-}
-
-div.body h1 { margin-top: 0; padding-top: 0; font-size: 250%; }
-div.body h2 { font-size: 190%; }
-div.body h3 { font-size: 160%; }
-div.body h4 { font-size: 140%; }
-div.body h5 { font-size: 110%; }
-div.body h6 { font-size: 110%; }
-
-a.headerlink {
-    color: #ddd;
-    padding: 0 4px;
-    text-decoration: none;
-}
-
-a.headerlink:hover {
-    color: #444;
-    background: #eaeaea;
-}
-
-div.body p, div.body dd, div.body li {
-    line-height: 1.4em;
-}
-
-div.admonition {
-    background: #fafafa;
-    margin: 20px -30px;
-    padding: 10px 30px;
-    border-top: 1px solid #ccc;
-    border-bottom: 1px solid #ccc;
-}
-
-div.admonition tt.xref, div.admonition a tt {
-    border-bottom: 1px solid #fafafa;
-}
-
-dd div.admonition {
-    margin-left: -60px;
-    padding-left: 60px;
-}
-
-div.admonition p.admonition-title {
-    font-family: 'Garamond', 'Georgia', serif;
-    font-weight: normal;
-    font-size: 24px;
-    margin: 0 0 10px 0;
-    padding: 0;
-    line-height: 1;
-}
-
-div.admonition p.last {
-    margin-bottom: 0;
-}
-
-div.highlight {
-    background-color: white;
-}
-
-dt:target, .highlight {
-    background: #FAF3E8;
-}
-
-div.note {
-    background-color: #eee;
-    border: 1px solid #ccc;
-}
-
-div.seealso {
-    background-color: #ffc;
-    border: 1px solid #ff6;
-}
-
-div.topic {
-    background-color: #eee;
-}
-
-p.admonition-title {
-    display: inline;
-}
-
-p.admonition-title:after {
-    content: ":";
-}
-
-pre {
-    font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
-    font-size: 0.88em;
-}
-
-tt {
-    font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
-    font-size: 0.95em;
-}
-
-img.screenshot {
-}
-
-tt.descname, tt.descclassname {
-    font-size: 0.95em;
-}
-
-tt.descname {
-    padding-right: 0.08em;
-}
-
-img.screenshot {
-    -moz-box-shadow: 2px 2px 4px #eee;
-    -webkit-box-shadow: 2px 2px 4px #eee;
-    box-shadow: 2px 2px 4px #eee;
-}
-
-table.docutils {
-    border: 1px solid #888;
-    -moz-box-shadow: 2px 2px 4px #eee;
-    -webkit-box-shadow: 2px 2px 4px #eee;
-    box-shadow: 2px 2px 4px #eee;
-}
-
-table.docutils td, table.docutils th {
-    border: 1px solid #888;
-    padding: 0.25em 0.7em;
-}
-
-table.field-list, table.footnote {
-    border: none;
-    -moz-box-shadow: none;
-    -webkit-box-shadow: none;
-    box-shadow: none;
-}
-
-table.footnote {
-    margin: 15px 0;
-    width: 100%;
-    border: 1px solid #eee;
-    background: #fdfdfd;
-    font-size: 0.9em;
-}
-
-table.footnote + table.footnote {
-    margin-top: -15px;
-    border-top: none;
-}
-
-table.field-list th {
-    padding: 0 0.8em 0 0;
-}
-
-table.field-list td {
-    padding: 0;
-}
-
-table.footnote td.label {
-    width: 0px;
-    padding: 0.3em 0 0.3em 0.5em;
-}
-
-table.footnote td {
-    padding: 0.3em 0.5em;
-}
-
-dl {
-    margin: 0;
-    padding: 0;
-}
-
-dl dd {
-    margin-left: 30px;
-}
-
-blockquote {
-    margin: 0 0 0 30px;
-    padding: 0;
-}
-
-ul, ol {
-    margin: 10px 0 10px 30px;
-    padding: 0;
-}
-
-pre {
-    background: #eee;
-    padding: 7px 30px;
-    margin: 15px -30px;
-    line-height: 1.3em;
-}
-
-dl pre, blockquote pre, li pre {
-    margin-left: 0px;
-    padding-left: 15px;
-}
-
-dl dl pre {
-    margin-left: 0px;
-    padding-left: 15px;
-}
-
-tt {
-    background-color: #ecf0f3;
-    color: #222;
-    /* padding: 1px 2px; */
-}
-
-tt.xref, a tt {
-    background-color: #FBFBFB;
-    color: #2277bb;
-    border-bottom: 1px solid white;
-}
-
-a.reference {
-    text-decoration: none;
-    border-bottom: 1px dotted #004B6B;
-}
-
-a.reference:hover {
-    border-bottom: 1px solid #6D4100;
-}
-
-a.footnote-reference {
-    text-decoration: none;
-    font-size: 0.7em;
-    vertical-align: top;
-    border-bottom: 1px dotted #004B6B;
-}
-
-a.footnote-reference:hover {
-    border-bottom: 1px solid #6D4100;
-}
-
-a:hover tt {
-    background: #EEE;
-}
-
-li {
-  margin-bottom: 0.3em;
-}
-
-
-@media screen and (max-width: 870px) {
-
-    div.sphinxsidebar {
-    	display: none;
-    }
-
-    div.document {
-       width: 100%;
-
-    }
-
-    div.documentwrapper {
-    	margin-left: 0;
-    	margin-top: 0;
-    	margin-right: 0;
-    	margin-bottom: 0;
-    }
-
-    div.bodywrapper {
-    	margin-top: 0;
-    	margin-right: 0;
-    	margin-bottom: 0;
-    	margin-left: 0;
-    }
-
-    ul {
-    	margin-left: 0;
-    }
-
-    .document {
-    	width: auto;
-    }
-
-    .footer {
-    	width: auto;
-    }
-
-    .bodywrapper {
-    	margin: 0;
-    }
-
-    .footer {
-    	width: auto;
-    }
-
-    .github {
-        display: none;
-    }
-
-
-
-}
-
-
-
-@media screen and (max-width: 875px) {
-
-    body {
-        margin: 0;
-        padding: 20px 30px;
-    }
-
-    div.documentwrapper {
-        float: none;
-        background: white;
-    }
-
-    div.sphinxsidebar {
-        display: block;
-        float: none;
-        width: 102.5%;
-        margin: 50px -30px -20px -30px;
-        padding: 10px 20px;
-        background: #333;
-        color: white;
-    }
-
-    div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
-    div.sphinxsidebar h3 a {
-        color: white;
-    }
-
-    div.sphinxsidebar a {
-        color: #aaa;
-    }
-
-    div.sphinxsidebar p.logo {
-        display: none;
-    }
-
-    div.document {
-        width: 100%;
-        margin: 0;
-    }
-
-    div.related {
-        display: block;
-        margin: 0;
-        padding: 10px 0 20px 0;
-    }
-
-    div.related ul,
-    div.related ul li {
-        margin: 0;
-        padding: 0;
-    }
-
-    div.footer {
-        display: none;
-    }
-
-    div.bodywrapper {
-        margin: 0;
-    }
-
-    div.body {
-        min-height: 0;
-        padding: 0;
-    }
-
-
-    .rtd_doc_footer {
-        display: none;
-    }
-
-    .document {
-        width: auto;
-    }
-
-    .footer {
-        width: auto;
-    }
-
-    .footer {
-        width: auto;
-    }
-
-    .github {
-        display: none;
-    }
-}
-
-
-/* misc. */
-
-.revsys-inline {
-    display: none!important;
-}
-
-div.sphinxsidebar #searchbox input[type="text"] {
-    width: 140px;
-    padding: 4px 3px;
-}
-
-.highlight .nv {
-    color: #C65D09!important;
-}
 
=== removed file 'docs/_templates/maas/theme.conf'
--- docs/_templates/maas/theme.conf	2013-12-06 15:11:12 +0000
+++ docs/_templates/maas/theme.conf	1970-01-01 00:00:00 +0000
@@ -1,6 +0,0 @@
-[theme]
-inherit = basic
-stylesheet = flasky.css
-
-headfont = Ubuntu
-bodyfont = free-sans,sans,sans-serif
 
=== renamed file 'docs/about.rst' => 'docs/about.md'
--- docs/about.rst	2014-11-10 16:39:12 +0000
+++ docs/about.md	2015-04-17 21:06:27 +0000
@@ -1,50 +1,17 @@
 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 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 (in the top-level ``docs/``
-directory). 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 additional sections,
-or more helpful and 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`_.
-
-.. _http://maas.ubuntu.com:
-  http://maas.ubuntu.com
-
+In a cunning move, the current documentation always lives, and is built from, the main MAAS source code (in the top-level `docs/` directory). 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 additional sections, or more helpful and 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.  Please `File a bug report`_ or `contact us directly`_.  In addition
-you can talk to us on the Freenode IRC channel #maas.
-
-.. _File a bug report:
-  https://bugs.launchpad.net/maas/+filebug
-
-.. _contact us directly:
-  https://launchpad.net/~maas-maintainers/+contactuser
-
-If you see something wrong with this documentation, you can help us fix it.
-Download the source to MAAS by following the instructions in
-:doc:`the hacking guide <hacking>`, make your changes, and propose a merge
-against lp:maas on Launchpad.  The documentation source lives in the top-level
-``docs/`` directory.
+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. Please [File a bug report](https://bugs.launchpad.net/maas/+filebug) or [contact us directly](https://launchpad.net/~maas-maintainers/+contactuser). In addition you can talk to us on the Freenode IRC channel \#maas.
+
+If you see something wrong with this documentation, you can help us fix it. Download the source to MAAS by following the instructions in the hacking guide \<hacking\>, make your changes, and propose a merge against lp:maas on Launchpad. The documentation source lives in the top-level `docs/` directory.
+
 
=== renamed file 'docs/api_authentication.rst' => 'docs/api_authentication.md'
--- docs/api_authentication.rst	2015-02-13 10:11:07 +0000
+++ docs/api_authentication.md	2015-04-17 21:06:27 +0000
@@ -1,78 +1,64 @@
-.. -*- mode: rst -*-
-
-.. _api_authentication:
-
 API authentication
 ==================
 
-MAAS's API uses OAuth_ as its authentication mechanism.  There isn't a third
-party involved (as in 3-legged OAuth) and so the process used is what's
-commonly referred to as 0-legged OAuth: the consumer accesses protected
-resources by submitting OAuth signed requests.
-
-.. _OAuth: http://en.wikipedia.org/wiki/OAuth
-
-Note that some API endpoints support unauthenticated requests (i.e.
-anonymous access).  See the :doc:`API documentation <api>` for details.
-
+MAAS's API uses [OAuth](http://en.wikipedia.org/wiki/OAuth) as its authentication mechanism. There isn't a third party involved (as in 3-legged OAuth) and so the process used is what's commonly referred to as 0-legged OAuth: the consumer accesses protected resources by submitting OAuth signed requests.
+
+Note that some API endpoints support unauthenticated requests (i.e. anonymous access). See the API documentation \<api\> for details.
 
 Examples
 ========
 
-Here are two examples on how to perform an authenticated GET request to
-retrieve the list of nodes.  The <key>, <secret>, <consumer_key> tokens
-are the three elements that compose the API key (API key =
-'<consumer_key>:<key>:<secret>').
+Here are two examples on how to perform an authenticated GET request to retrieve the list of nodes. The \<key\>, \<secret\>, \<consumer\_key\> tokens are the three elements that compose the API key (API key = '\<consumer\_key\>:\<key\>:\<secret\>').
 
 Python
 ------
 
-.. code:: python
-
-    import oauth.oauth as oauth
-    import httplib2
-    import uuid
-
-    def perform_API_request(site, uri, method, key, secret, consumer_key):
-        resource_tok_string = "oauth_token_secret=%s&oauth_token=%s" % (
-            secret, key)
-        resource_token = oauth.OAuthToken.from_string(resource_tok_string)
-        consumer_token = oauth.OAuthConsumer(consumer_key, "")
-
-        oauth_request = oauth.OAuthRequest.from_consumer_and_token(
-            consumer_token, token=resource_token, http_url=site,
-            parameters={'oauth_nonce': uuid.uuid4().get_hex()})
-        oauth_request.sign_request(
-            oauth.OAuthSignatureMethod_PLAINTEXT(), consumer_token,
-            resource_token)
-        headers = oauth_request.to_header()
-        url = "%s%s" % (site, uri)
-        http = httplib2.Http()
-        return http.request(url, method, body=None, headers=headers)
-
-    # API key = '<consumer_key>:<key>:<secret>'
-    response = perform_API_request(
-        'http://server/MAAS/api/1.0', '/nodes/?op=list', 'GET', '<key>', '<secret>',
-        '<consumer_key>')
+``` {.sourceCode .python}
+import oauth.oauth as oauth
+import httplib2
+import uuid
+
+def perform_API_request(site, uri, method, key, secret, consumer_key):
+    resource_tok_string = "oauth_token_secret=%s&oauth_token=%s" % (
+        secret, key)
+    resource_token = oauth.OAuthToken.from_string(resource_tok_string)
+    consumer_token = oauth.OAuthConsumer(consumer_key, "")
+
+    oauth_request = oauth.OAuthRequest.from_consumer_and_token(
+        consumer_token, token=resource_token, http_url=site,
+        parameters={'oauth_nonce': uuid.uuid4().get_hex()})
+    oauth_request.sign_request(
+        oauth.OAuthSignatureMethod_PLAINTEXT(), consumer_token,
+        resource_token)
+    headers = oauth_request.to_header()
+    url = "%s%s" % (site, uri)
+    http = httplib2.Http()
+    return http.request(url, method, body=None, headers=headers)
+
+# API key = '<consumer_key>:<key>:<secret>'
+response = perform_API_request(
+    'http://server/MAAS/api/1.0', '/nodes/?op=list', 'GET', '<key>', '<secret>',
+    '<consumer_key>')
+```
 
 Ruby
 ----
 
-.. code:: ruby
-
-    require 'oauth'
-    require 'oauth/signature/plaintext'
-
-    def perform_API_request(site, uri, key, secret, consumer_key)
-        consumer = OAuth::Consumer.new(
-            consumer_key, "",
-            { :site => "http://localhost/MAAS/api/1.0",
-              :scheme => :header, :signature_method => "PLAINTEXT"})
-        access_token = OAuth::AccessToken.new(consumer, key, secret)
-        return access_token.request(:get, "/nodes/?op=list")
-    end
-
-    # API key = "<consumer_key>:<key>:<secret>"
-    response = perform_API_request(
-         "http://server/MAAS/api/1.0", "/nodes/?op=list", "<key>", "<secret>",
-         "consumer_key>")
+``` {.sourceCode .ruby}
+require 'oauth'
+require 'oauth/signature/plaintext'
+
+def perform_API_request(site, uri, key, secret, consumer_key)
+    consumer = OAuth::Consumer.new(
+        consumer_key, "",
+        { :site => "http://localhost/MAAS/api/1.0",
+          :scheme => :header, :signature_method => "PLAINTEXT"})
+    access_token = OAuth::AccessToken.new(consumer, key, secret)
+    return access_token.request(:get, "/nodes/?op=list")
+end
+
+# API key = "<consumer_key>:<key>:<secret>"
+response = perform_API_request(
+     "http://server/MAAS/api/1.0", "/nodes/?op=list", "<key>", "<secret>",
+     "consumer_key>")
+```
 
=== renamed file 'docs/bootsources.rst' => 'docs/bootsources.md'
--- docs/bootsources.rst	2015-02-06 17:07:56 +0000
+++ docs/bootsources.md	2015-04-17 21:06:27 +0000
@@ -1,21 +1,9 @@
-.. -*- mode: rst -*-
-
-.. _bootsources:
-
 Boot images import configuration
 ================================
 
-The configuration for where a region downloads its images is defined by
-a set of "sources".  Each "source" defines a Simplestreams repository
-location (``url``) from which images can be downloaded and a
-``keyring_filename`` (or ``keyring_data``) for validating index and image
-signatures from that location.  For each source, you can define a series of
-filters (``selections``) specifying which images should be downloaded from
-that source.
+The configuration for where a region downloads its images is defined by a set of "sources". Each "source" defines a Simplestreams repository location (`url`) from which images can be downloaded and a `keyring_filename` (or `keyring_data`) for validating index and image signatures from that location. For each source, you can define a series of filters (`selections`) specifying which images should be downloaded from that source.
 
-The following example use the MAAS CLI to list the boot sources and the boot
-source selections.  Assuming the CLI ``PROFILE`` is the name of the profile
-under which you're logged in to the server::
+The following example use the MAAS CLI to list the boot sources and the boot source selections. Assuming the CLI `PROFILE` is the name of the profile under which you're logged in to the server:
 
     $ maas $PROFILE boot-sources read
     [
@@ -46,22 +34,19 @@
         }
     ]
 
-
 Restricting the images being downloaded
 ---------------------------------------
 
-Let's say you want to add a previous LTS release to images being downloaded.
-Starting from the configuration described above, you would need to:
-
-- Add the "Precise" selection (the selection '1' of the source '1')::
-
-    $ maas $PROFILE boot-source-selection create 1 os="ubuntu" release="precise" arches="amd64" subarches="*" labels="*"
+Let's say you want to add a previous LTS release to images being downloaded. Starting from the configuration described above, you would need to:
+
+-   Add the "Precise" selection (the selection '1' of the source '1'):
+
+        $ maas $PROFILE boot-source-selection create 1 os="ubuntu" release="precise" arches="amd64" subarches="*" labels="*"
 
 Downloading the images from a different source
 ----------------------------------------------
 
-Let's say you want to import the images from a different location.  You would
-need to to change the source's url and keyring::
+Let's say you want to import the images from a different location. You would need to to change the source's url and keyring:
 
     $ maas $PROFILE boot-source update 1 url="http://custom.url" keyring_filename="" keyring_data@=./custom_keyring_file
     {
@@ -75,7 +60,7 @@
 Adding a source
 ---------------
 
-You can also add a new source::
+You can also add a new source:
 
     $ maas $PROFILE boot-sources create url=http://my.url keyring_filename="" keyring_data@=./ custom_keyring_file
     {
@@ -86,7 +71,7 @@
         "resource_uri": "<url omitted for readability>"
     }
 
-Inside that newly created source ('2') you can add selections::
+Inside that newly created source ('2') you can add selections:
 
     $ maas $PROFILE boot-source-selections create 2 os="ubuntu" release="trusty" arches="amd64" subarches="*" labels='*'
     {
@@ -98,11 +83,10 @@
         "resource_uri": "<url omitted for readability>"
     }
 
-Deleting a source
----------------
+Deleting a source ---------------
 
 Let's say you need to delete the newly added source.
 
-To delete the source::
+To delete the source:
 
     $ maas $PROFILE boot-source delete 2
 
=== renamed file 'docs/capabilities.rst' => 'docs/capabilities.md'
--- docs/capabilities.rst	2014-10-09 06:30:29 +0000
+++ docs/capabilities.md	2015-04-17 21:06:27 +0000
@@ -1,44 +1,26 @@
-.. -*- mode: rst -*-
-
-.. _capabilities:
-
 Capabilities
 ============
 
-MAAS publishes a special view at ``.../api/1.0/version/`` that returns a
-list of the server's capabilities. It's transferred as a JSON document::
+MAAS publishes a special view at `.../api/1.0/version/` that returns a list of the server's capabilities. It's transferred as a JSON document:
 
     {"capabilities": ["name-of-capability", ...]}
 
-.. note::
-
-  The view is called ``version`` because this will, later, include
-  version information too.
-
+> **note**
+>
+> The view is called `version` because this will, later, include version information too.
 
 List of capabilities
 --------------------
 
-Check for the following strings in the capabilities list to see what
-features the MAAS server supports. Use these in preference to gating on
-the version when creating a client application.
-
-.. _cap-networks-management:
-
-``networks-management``
-  Passive modelling of the network environment that cluster controllers
-  nodes are in, including network interfaces, subnets, VLAN tags, and
-  connectivity between them. See :ref:`networks` for more information.
-
-.. _cap-static-ipaddresses:
-
-``static-ipaddresses``
-  Static IP address allocation to nodes, including user-reserved IPs and admin-
-  allocated 'sticky' IPs. Available since version 1.6. See :ref:`static-ips`
-  for more information.
-
-.. _cap-ipv6-deployment-ubuntu:
-
-``ipv6-deployment-ubuntu``
-  Deploy Ubuntu nodes with IPv6 networking enabled.  See :ref:`ipv6` for more
-  about this feature.
+Check for the following strings in the capabilities list to see what features the MAAS server supports. Use these in preference to gating on the version when creating a client application.
+
+`networks-management`  
+Passive modelling of the network environment that cluster controllers nodes are in, including network interfaces, subnets, VLAN tags, and connectivity between them. See networks for more information.
+
+`static-ipaddresses`  
+Static IP address allocation to nodes, including user-reserved IPs and admin-allocated 'sticky' IPs. Available since version 1.6. See static-ips for more information.
+
+`ipv6-deployment-ubuntu`  
+Deploy Ubuntu nodes with IPv6 networking enabled. See ipv6 for more about this feature.
+
+
 
=== renamed file 'docs/changelog.rst' => 'docs/changelog.md'
--- docs/changelog.rst	2015-04-09 15:48:49 +0000
+++ docs/changelog.md	2015-04-17 21:06:27 +0000
@@ -1,1132 +1,696 @@
-=========
 Changelog
 =========
 
 1.7.3
-=====
-
-Bug Fix Update
---------------
-
-#1441933    Internal Server Error when saving a cluster without Router IP
-#1441133    MAAS version not exposed over the API
-#1437094    Sorting by mac address on webui causes internal server error
-#1439359    Automatically set correct boot resources selection and start import
-            after upgrade from MAAS 1.5; Ensures MAAS is usable after upgrade.
-#1439366    Backwards compatibility with MAAS 1.5 preseeds and custom preseeds.
-            Ensures that users dont have to manually change preseeds names.
+-----
+
+### Bug Fix Update
+
+\#1441933 Internal Server Error when saving a cluster without Router IP \#1441133 MAAS version not exposed over the API \#1437094 Sorting by mac address on webui causes internal server error \#1439359 Automatically set correct boot resources selection and start import after upgrade from MAAS 1.5; Ensures MAAS is usable after upgrade. \#1439366 Backwards compatibility with MAAS 1.5 preseeds and custom preseeds. Ensures that users dont have to manually change preseeds names.
 
 1.7.2
-=====
-
-Bug Fix Update
---------------
-
-#1331214    Support AMT Version > 8
-#1397567    Fix call to amttool when restarting a node to not fail disk erasing.
-#1415538    Do not generate the 'option routers' stanza if router IP is None.
-#1403909    Do not deallocate StaticIPAddress before node has powered off.
-#1405998    Remove all OOPS reporting.
-#1423931    Update the nodes host maps when a sticky ip address is claimed over the API.
-#1433697    Look for bootloaders in /usr/lib/EXTLINUX
-
+-----
+
+### Bug Fix Update
+
+\#1331214 Support AMT Version \> 8 \#1397567 Fix call to amttool when restarting a node to not fail disk erasing. \#1415538 Do not generate the 'option routers' stanza if router IP is None. \#1403909 Do not deallocate StaticIPAddress before node has powered off. \#1405998 Remove all OOPS reporting. \#1423931 Update the nodes host maps when a sticky ip address is claimed over the API. \#1433697 Look for bootloaders in /usr/lib/EXTLINUX
 
 1.7.1
-=====
-
-Minor feature improvements
---------------------------
-
-New CentOS Release support.
-  Further to the work done in the 1.7.0 MAAS Release, MAAS now supports
-  uploading various versions of CentOS. Previously MAAS would only
-  officially support 6.5.
-
-Power Monitoring for Seamicro 15000, Cisco UCS and HP Moonshot Chassis
-  Further the work done in the 1.7.0 MAAS release, it now supports power
-  query and monitoring for the Seamicro 15000 Chassis, the Cisco UCS
-  Chassis Manager and the HP Moonshot Chassis Manager.
-
-Node Listing Page and Node Event Log live refresh
-  The Node Listing page and the Node Event Log now have live refresh
-  every 10 seconds. This allows MAAS to display the latest node status
-  and events without forcing a browser refresh.
-
-IP Address Reservation
-  The static IP address reservation API now has an optional "mac"
-  parameter. Specifying a MAC address here will link the new static IP
-  to that MAC address. A DHCP host map will be created for the MAC
-  address. No other IPs may be reserved for that MAC address until the
-  current one is released.
-
-Bug fix update
---------------
-
-For full details see https://launchpad.net/maas/+milestone/1.7.1
-
-#1330765    If start_nodes() fails, it doesn't clean up after itself.
-#1373261    pserv.yaml rewrite breaks when previous generator URL uses IPv6 address
-#1386432    After update to the latest curtin that changes the log to install.log MAAS show's two installation logs
-#1386488    If rndc fails, you get an Internal Server Error page
-#1386502    No "failed" transition from "new"
-#1386914    twisted Unhandled Error when region can't reach upstream boot resource
-#1391139    Tagged VLAN on aliased NIC breaks migration 0099
-#1391161    Failure: twisted.internet.error.ConnectionDone: Connection was closed cleanly.
-#1391411    metadata API signal() is releasing host maps at the end of installation
-#1391897    Network names with dots cause internal server error when on node pages
-#1394382    maas does not know about VM "paused" state
-#1396308    Removing managed interface causes maas to delete nodes
-#1397356    Disk Wiping fails if installation is not Ubuntu
-#1398405    MAAS UI reports storage size in Gibibytes (base 2) but is labeled GB - Gigabytes (base 10).
-#1399331    MAAS leaking sensitive information in ps ax output
-#1400849    Check Power State disappears after upgrade to 1.7 bzr 3312
-#1401241    custom dd-tgz format images looked for in wrong path, so they don't work
-#1401983    Exception: deadlock detected
-#1403609    can not enlist chassis with maas admin node-group probe-and-enlist-mscm
-#1283106    MAAS allows the same subnet to be defined on two managed interfaces of the same cluster
-#1303925    commissioning fails silently if a node can't reach the region controller
-#1357073    power state changes are not reflected quickly enough in the UI
-#1360280    boot-source-selections api allows adding bogus and duplicated values
-#1368400    Can't power off nodes that are in Ready state but on
-#1370897    The node power monitoring service does not check nodes in parallel
-#1376024    gpg --batch [...]` error caused by race in BootSourceCacheService
-#1376716    AMT NUC stuck at boot prompt instead of powering down (no ACPI support in syslinux poweroff)
-#1378835    Config does not have a unique index on name
-#1379370    Consider removing transaction in claim_static_ip_addresses().
-#1379556    Panicky log warning that is irrelevant
-#1381444    Misleading error message in log "Unknown power_type 'sm15k'"
-#1382166    Message disclosing image import necessary visible while not logged in
-#1382237    UnicodeEncodeError when unable to create host maps
-#1383231    Error message when trying to reserve the same static IP twice is unhelpful
-#1383237    Error message trying to reserve an IP address when no static range is defined is misleading
-#1384424    Seamicro Machines do not have Power Status Tracking
-#1384428    HP Moonshot Chassis Manager lacks power status monitoring
-#1384924    need to provide a better upgrade message for images on the cluster but not on the region
-#1386517    DHCP leases are not released at the end of commissioning and possibly enlistment
-#1387239    MAAS does not provide an API for reserving a static IP for a given MAC address
-#1387414    Race when registering new event type
-#1388033    Trying to reserve a static IP when no more IPs are available results in 503 Service Unavailable with no error text
-#1389602    Inconsistent behavior in the checks to delete a node
-#1389733    node listing does not update the status and power of nodes
-#1390144    Node 'releasing' should have a timeout
-#1391193    API error documentation
-#1391421    Names of custom boot-resources not visible in the web UI
-#1391891    Spurious test failure: TestDNSForwardZoneConfig_GetGenerateDirectives.test_returns_single_entry_for_tiny_network
-#1393423    PowerKVM / VIrsh import should allow you to specify a prefix to filter VM's to import
-#1393953    dd-format images fail to deploy
-#1400909    Networks are being autocreated like eth0-eth0 instead of maas-eth0
-#1401349    Memory size changes to incorrect size when page is refreshed
-#1402237    Node event log queries are slow (over 1 second)
-#1402243    Nodes in 'Broken' state are being power queried constantly
-#1402736    clicking on zone link from node page - requested URL was not found on this server
-#1403043    Wrong top-level tab is selected when viewing a node
-#1381609    Misleading log message when a node has a MAC address not attached to a cluster interface
-#1386909    Misleading Error: Unable to identify boot image for (ubuntu/amd64/generic/trusty/local): cluster 'maas' does not have matching boot image.
-#1388373    Fresh image import of 3 archs displaying multiple rows for armhf and amd64
-#1398159    TFTP into MAAS server to get pxelinux.0 causes unhandled error
-#1383651    Node.start() and Node.stop() raise MulltipleFailures unnecessarily
-#1383668    null" when releasing an IP address is confusing
-#1389416    Power querying for UCSM not working
-#1399676    UX bug: mac address on the nodes page should be the MAC address it pxe booted from
-#1399736    MAAS should display memory sizes in properly labeld base 2 units - MiB, GiB, etc.
-#1401643    Documentation has wrong pattern for user provided preseeds
-#1401707    Slow web performance (5+ minute response time) on MAAS with many nodes
-#1403609    Fix MSCM chassis enlistment.
-#1409952    Correctly parse MAC Address for Power8 VM enlistment.
-#1409852    Do not fail when trying to perform an IP Address Reservation.
-#1413030    OS and Release no longer populate on Add Node page
-#1414036    Trying to add an empty network crashes (AddrFormatError)
-
+-----
+
+### Minor feature improvements
+
+New CentOS Release support.  
+Further to the work done in the 1.7.0 MAAS Release, MAAS now supports uploading various versions of CentOS. Previously MAAS would only officially support 6.5.
+
+Power Monitoring for Seamicro 15000, Cisco UCS and HP Moonshot Chassis  
+Further the work done in the 1.7.0 MAAS release, it now supports power query and monitoring for the Seamicro 15000 Chassis, the Cisco UCS Chassis Manager and the HP Moonshot Chassis Manager.
+
+Node Listing Page and Node Event Log live refresh  
+The Node Listing page and the Node Event Log now have live refresh every 10 seconds. This allows MAAS to display the latest node status and events without forcing a browser refresh.
+
+IP Address Reservation  
+The static IP address reservation API now has an optional "mac" parameter. Specifying a MAC address here will link the new static IP to that MAC address. A DHCP host map will be created for the MAC address. No other IPs may be reserved for that MAC address until the current one is released.
+
+### Bug fix update
+
+For full details see <https://launchpad.net/maas/+milestone/1.7.1>
+
+\#1330765 If start\_nodes() fails, it doesn't clean up after itself. \#1373261 pserv.yaml rewrite breaks when previous generator URL uses IPv6 address \#1386432 After update to the latest curtin that changes the log to install.log MAAS show's two installation logs \#1386488 If rndc fails, you get an Internal Server Error page \#1386502 No "failed" transition from "new" \#1386914 twisted Unhandled Error when region can't reach upstream boot resource \#1391139 Tagged VLAN on aliased NIC breaks migration 0099 \#1391161 Failure: twisted.internet.error.ConnectionDone: Connection was closed cleanly. \#1391411 metadata API signal() is releasing host maps at the end of installation \#1391897 Network names with dots cause internal server error when on node pages \#1394382 maas does not know about VM "paused" state \#1396308 Removing managed interface causes maas to delete nodes \#1397356 Disk Wiping fails if installation is not Ubuntu \#1398405 MAAS UI reports storage size in Gibibytes (base 2) but is labeled GB - Gigabytes (base 10). \#1399331 MAAS leaking sensitive information in ps ax output \#1400849 Check Power State disappears after upgrade to 1.7 bzr 3312 \#1401241 custom dd-tgz format images looked for in wrong path, so they don't work \#1401983 Exception: deadlock detected \#1403609 can not enlist chassis with maas admin node-group probe-and-enlist-mscm \#1283106 MAAS allows the same subnet to be defined on two managed interfaces of the same cluster \#1303925 commissioning fails silently if a node can't reach the region controller \#1357073 power state changes are not reflected quickly enough in the UI \#1360280 boot-source-selections api allows adding bogus and duplicated values \#1368400 Can't power off nodes that are in Ready state but on \#1370897 The node power monitoring service does not check nodes in parallel \#1376024 gpg --batch [...]\` error caused by race in BootSourceCacheService \#1376716 AMT NUC stuck at boot prompt instead of powering down (no ACPI support in syslinux poweroff) \#1378835 Config does not have a unique index on name \#1379370 Consider removing transaction in claim\_static\_ip\_addresses(). \#1379556 Panicky log warning that is irrelevant \#1381444 Misleading error message in log "Unknown power\_type 'sm15k'" \#1382166 Message disclosing image import necessary visible while not logged in \#1382237 UnicodeEncodeError when unable to create host maps \#1383231 Error message when trying to reserve the same static IP twice is unhelpful \#1383237 Error message trying to reserve an IP address when no static range is defined is misleading \#1384424 Seamicro Machines do not have Power Status Tracking \#1384428 HP Moonshot Chassis Manager lacks power status monitoring \#1384924 need to provide a better upgrade message for images on the cluster but not on the region \#1386517 DHCP leases are not released at the end of commissioning and possibly enlistment \#1387239 MAAS does not provide an API for reserving a static IP for a given MAC address \#1387414 Race when registering new event type \#1388033 Trying to reserve a static IP when no more IPs are available results in 503 Service Unavailable with no error text \#1389602 Inconsistent behavior in the checks to delete a node \#1389733 node listing does not update the status and power of nodes \#1390144 Node 'releasing' should have a timeout \#1391193 API error documentation \#1391421 Names of custom boot-resources not visible in the web UI \#1391891 Spurious test failure: TestDNSForwardZoneConfig\_GetGenerateDirectives.test\_returns\_single\_entry\_for\_tiny\_network \#1393423 PowerKVM / VIrsh import should allow you to specify a prefix to filter VM's to import \#1393953 dd-format images fail to deploy \#1400909 Networks are being autocreated like eth0-eth0 instead of maas-eth0 \#1401349 Memory size changes to incorrect size when page is refreshed \#1402237 Node event log queries are slow (over 1 second) \#1402243 Nodes in 'Broken' state are being power queried constantly \#1402736 clicking on zone link from node page - requested URL was not found on this server \#1403043 Wrong top-level tab is selected when viewing a node \#1381609 Misleading log message when a node has a MAC address not attached to a cluster interface \#1386909 Misleading Error: Unable to identify boot image for (ubuntu/amd64/generic/trusty/local): cluster 'maas' does not have matching boot image. \#1388373 Fresh image import of 3 archs displaying multiple rows for armhf and amd64 \#1398159 TFTP into MAAS server to get pxelinux.0 causes unhandled error \#1383651 Node.start() and Node.stop() raise MulltipleFailures unnecessarily \#1383668 null" when releasing an IP address is confusing \#1389416 Power querying for UCSM not working \#1399676 UX bug: mac address on the nodes page should be the MAC address it pxe booted from \#1399736 MAAS should display memory sizes in properly labeld base 2 units - MiB, GiB, etc. \#1401643 Documentation has wrong pattern for user provided preseeds \#1401707 Slow web performance (5+ minute response time) on MAAS with many nodes \#1403609 Fix MSCM chassis enlistment. \#1409952 Correctly parse MAC Address for Power8 VM enlistment. \#1409852 Do not fail when trying to perform an IP Address Reservation. \#1413030 OS and Release no longer populate on Add Node page \#1414036 Trying to add an empty network crashes (AddrFormatError)
 
 1.7.0
-=====
-
-Important announcements
------------------------
-
-**Re-import your boot images**
- You must re-import your boot images, see below for details.
-
-**Update Curtin preseed files**
- Two changes were made to Curtin preseed files that need your attention
- if you made any customisations:
-
- *  The OS name must now appear in the filename.  The new schema is shown
-    here, each file pattern is tried in turn until a match is found::
-
-    {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}_{node_name}
-    {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}
-    {prefix}_{osystem}_{node_arch}_{node_subarch}
-    {prefix}_{osystem}_{node_arch}
-    {prefix}_{osystem}
-    {prefix}
-
- * If you are modifying ``/etc/network/interfaces`` in the preseed, it must be
-   moved so it is processed last in ``late_commands`` since MAAS now writes
-   to this file itself as part of IPv6 setup.  For example::
-
-    late_commands:
-      bonding_02: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
-
-   must now look like this::
-
-    late_commands:
-      zz_write_ifaces: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
-
-   The leading ``zz`` ensures the command sorts to the end of the
-   ``late_commands`` list.
-
-
-Major new features
-------------------
-
-**Improved image downloading and reporting.**
-  MAAS boot images are now downloaded centrally by the region controller
-  and disseminated to all registered cluster controllers.  This change includes
-  a new web UI under the `Images` tab that allows the admin to select
-  which images to import and shows the progress of the ongoing download.
-  This completely replaces any file-based configuration that used to take
-  place on cluster controllers.  The cluster page now shows whether it has
-  synchronised all the images from the region controller.
-
-  This process is also completely controllable using the API.
-
-.. Note::
-  Unfortunately due to a format change in the way images are stored, it
-  was not possible to migrate previously downloaded images to the new region
-  storage.  The cluster(s) will still be able to use the existing images,
-  however the region controller will be unaware of them until an import
-  is initiated.  When the import is finished, the cluster(s) will remove
-  older image resources.
-
-  This means that the first thing to do after upgrading to 1.7 is go to the
-  `Images` tab and re-import the images.
-
-**Increased robustness.**
-  A large amount of effort has been given to ensuring that MAAS remains
-  robust in the face of adversity.  An updated node state model has been
-  implemented that takes into account more of the situations in which a
-  node can be found including any failures at each stage.
-
-  When a node is getting deployed, it is now monitored to check that each
-  stage is reached in a timely fashion; if it does not then it is marked
-  as failed.
-
-  The core power driver was updated to check the state of the power on each
-  node and is reported in the web UI and API.  The core driver now also
-  handles retries when changing the power state of hardware, removing the
-  requirement that each power template handle it individually.
-
-**RPC security.**
-  As a step towards mutually verified TLS connections between MAAS's
-  components, 1.7 introduces a simple shared-secret mechanism to
-  authenticate the region with the clusters and vice-versa. For those
-  clusters that run on the same machine as the region controller (which
-  will account for most people), everything will continue to work
-  without intervention. However, if you're running a cluster on a
-  separate machine, you must install the secret:
-
-  1. After upgrading the region controller, view /var/lib/maas/secret
-     (it's text) and copy it.
-
-  2. On each cluster, run:
-
-       sudo -u maas maas-provision install-shared-secret
-
-     You'll be prompted for the secret; paste it in and press enter. It
-     is a password prompt, so the secret will not be echoed back to you.
-
-  That's it; the upgraded cluster controller will find the secret
-  without needing to be told.
-
-**RPC connections.**
-  Each cluster maintains a persistent connection to each region
-  controller process that's running. The ports on which the region is
-  listening are all high-numbered, and they are allocated randomly by
-  the OS. In a future release of MAAS we will narrow this down. For now,
-  each cluster controller needs unfiltered access to each machine in the
-  region on all high-numbered TCP ports.
-
-**Node event log.**
-  For every major event on nodes, it is now logged in a node-specific log.
-  This includes events such as power changes, deployments and any failures.
-
-**IPv6.**
-  It is now possible to deploy Ubuntu nodes that have IPv6 enabled.
-  See :doc:`ipv6` for more details.
-
-**Removal of Celery and RabbitMQ.**
-  While Celery was found to be very reliable it ultimately did not suit
-  the project's requirements as it is a largely fire-and-forget mechanism.
-  Additionally it was another moving part that caused some headaches for
-  users and admins alike, so the decision was taken to remove it and implement
-  a custom communications mechanism between the region controller and cluster
-  controllers.  The new mechanism is bidirectional and allowed the complex
-  interactions to take place that are required as part of the robustness
-  improvements.
-
-  Since a constant connection is maintained, as a side effect the web UI now
-  shows whether each cluster is connected or not.
-
-**Support for other OSes.**
-  Non-Ubuntu OSes are fully supported now. This includes:
-   - Windows
-   - Centos
-   - SuSE
-
-**Custom Images.**
-  MAAS now supports the deployment of Custom Images. Custom images can be
-  uploaded via the API. The usage of custom images allows the deployment of
-  other Ubuntu Flavors, such as Ubuntu Desktop.
-
-**maas-proxy.**
-  MAAS now uses maas-proxy as the default proxy solution instead of
-  squid-deb-proxy. On a fresh install, MAAS will use maas-proxy by default.
-  On upgrades from previous releases, MAAS will install maas-proxy instead of
-  squid-deb-proxy.
-
-Minor notable changes
----------------------
-
-**Better handling of networks.**
-  All networks referred to by cluster interfaces are now automatically
-  registered on the Network page.  Any node network interfaces are
-  automatically linked to the relevant Network.
-
-.. Note::
-  Commissioning currently requires an IP address to be available for each
-  network interface on a network that MAAS manages; this allows MAAS to
-  auto-populate its networks database.  In general you should use a
-  well-sized network (/16 recommended if you will be using containers and
-  VMs) and dynamic pool. If this feature risks causing IP exhaustion for
-  your deployment and you do not need the auto-populate functionality, you
-  can disable it by running the following command on your region controller::
-
-    sudo maas <profile> maas set-config name=enable_dhcp_discovery_on_unconfigured_interfaces value=False
-
-**Improved logging.**
-  A total overhaul of where logging is produced was undertaken, and now
-  all the main events in MAAS are selectively reported to syslog with the
-  "maas" prefix from both the region and cluster controllers alike.  If MAAS
-  is installed using the standard Ubuntu packaging, its syslog entries are
-  redirected to /var/log/maas/maas.log.
-
-  On the clusters, pserv.log is now less chatty and contains only errors.
-  On the region controller appservers, maas-django.log contains only appserver
-  errors.
-
-**Static IP selection.**
- The API was extended so that specific IPs can be pre-allocated for network
- interfaces on nodes and for user-allocated IPs.
-
-**Pronounceable random hostnames.**
- The old auto-generated 5-letter names were replaced with a pseudo-random
- name that is produced from a dictionary giving names of the form
- 'adjective-noun'.
-
-
-Known Problems & Workarounds
-----------------------------
-
-**Upgrade issues**
- There may be upgrade issues for users currently on MAAS 1.5 and 1.6; while we
- have attempted to reproduce and address all the issues reported, some bugs
- remain inconclusive. We recommend a full, tested backup of the MAAS servers
- before attempting the upgrade to 1.7. If you do encounter issues, please file
- these and flag them to the attention of the MAAS team and we will address them
- in point-releases.  See bugs `1381058`_, `1382266`_, `1379890`_, `1379532`_,
- and `1379144`_.
-
-.. _1381058:
-  https://launchpad.net/bugs/1381058
-.. _1382266:
-  https://launchpad.net/bugs/1382266
-.. _1379890:
-  https://launchpad.net/bugs/1379890
-.. _1379532:
-  https://launchpad.net/bugs/1379532
-.. _1379144:
-  https://launchpad.net/bugs/1379144
-
-**Split Region/Cluster set-ups**
- If you site your cluster on a separate host to the region, it needs a
- security key to be manually installed by running
- ``maas-provision install-shared-secret`` on the cluster host.
-
-**Private boot streams**
- If you had private boot image stream information configured in MAAS 1.5 or
- 1.6, upgrading to 1.7 will not take that into account and it will need to be
- manually entered on the settings page in the MAAS UI (bug `1379890`_)
-
-.. _1379890:
-  https://launchpad.net/bugs/1379890
-
-**Concurrency issues**
- Concurrency issues expose us to races when simultaneous operations are
- triggered. This is the source of many hard to reproduce issues which will
- require us to change the default database isolation level. We intend to address
- this in the first point release of 1.7.
-
-**Destroying a Juju environment**
- When attempting to "juju destroy" an environment, nodes must be in the DEPLOYED
- state; otherwise, the destroy will fail. You should wait for all in-progress
- actions on the MAAS cluster to conclude before issuing the command. (bug
- `1381619`_)
-
-.. _1381619:
-  https://launchpad.net/bugs/1381619
-
-**AMT power control**
- A few AMT-related issues remain, with workarounds:
-
-  * Commissioning NUC reboots instead of shutting down (bug `1368685`_).  There
-    is `a workaround in the power template`_
-
-  * MAAS (amttool) cannot control AMT version > 8. See `workaround described in
-    bug 1331214`_
-
-  * AMT NUC stuck at boot prompt instead of powering down (no ACPI support in
-    syslinux poweroff) (bug `1376716`_). See the `ACPI-only workaround`_
-
-.. _1368685:
-  https://bugs.launchpad.net/maas/+bug/1368685
-.. _a workaround in the power template:
-  https://bugs.launchpad.net/maas/+bug/1368685/comments/8
-.. _workaround described in bug 1331214:
-  https://bugs.launchpad.net/maas/+bug/1331214/comments/18
-.. _1376716:
-  https://bugs.launchpad.net/maas/+bug/1376716
-.. _ACPI-only workaround:
-  https://bugs.launchpad.net/maas/+bug/1376716/comments/12
-
-
-**Disk wiping**
- If you enable disk wiping, juju destroy-environment may fail for you. The
- current workaround is to wait and re-issue the command.  This will be fixed in
- future versions of MAAS & Juju. (bug `1386327`_)
-
-.. _1386327:
-  https://bugs.launchpad.net/maas/+bug/1386327
-
-**BIND with DNSSEC**
- If you are using BIND with a forwarder that uses DNSSEC and have not
- configured certificates, you will need to explicitly disable that feature in
- your BIND configuration (1384334)
-
-.. _1384334:
-  https://bugs.launchpad.net/maas/+bug/1384334
-
-**Boot source selections on the API**
- Use of API to change image selections can leave DB in a bad state
- (bug `1376812`_).  It can be fixed by issuing direct database updates.
-
-.. _1376812:
-  https://bugs.launchpad.net/maas/+bug/1376812
-
-**Disabling DNS**
- Disabling DNS may not work (bug `1383768`_)
-
-.. _1383768:
-  https://bugs.launchpad.net/maas/+bug/1383768
-
-**Stale DNS zone files**
- Stale DNS zone files may be left behind if the MAAS domainname is changed
- (bug `1383329`_)
-
-.. _1383329:
-  https://bugs.launchpad.net/maas/+bug/1383329
-
-
-
-Major bugs fixed in this release
---------------------------------
-
-See https://launchpad.net/maas/+milestone/1.7.0 for full details.
-
-#1081660    If maas-enlist fails to reach a DNS server, the node will be named ";; connection timed out; no servers could be reached"
-
-#1087183    MaaS cloud-init configuration specifies 'manage_etc_hosts: localhost'
-
-#1328351    ConstipationError: When the cluster runs the "import boot images" task it blocks other tasks
-
-#1342117    CLI command to set up node-group-interface fails with /usr/lib/python2.7/dist-packages/maascli/__main__.py: error: u'name'
-
-#1349254    Duplicate FQDN can be configured on MAAS via CLI or API
-
-#1352575    BMC password showing in the apache2 logs
-
-#1355534    UnknownPowerType traceback in appserver log
-
-#1363850    Auto-enlistment not reporting power parameters
-
-#1363900    Dev server errors while trying to write to '/var/lib/maas'
-
-#1363999    Not assigning static IP addresses
-
-#1364481    http 500 error doesn't contain a stack trace
-
-#1364993    500 error when trying to acquire a commissioned node (AddrFormatError: failed to detect a valid IP address from None)
-
-#1365130    django-admin prints spurious messages to stdout, breaking scripts
-
-#1365850    DHCP scan using cluster interface name as network interface?
-
-#1366172    NUC does not boot after power off/power on
-
-#1366212    Large dhcp leases file leads to tftp timeouts
-
-#1366652    Leaking temporary directories
-
-#1368269    internal server error when deleting a node
-
-#1368590    Power actions are not serialized.
-
-#1370534    Recurrent update of the power state of nodes crashes if the connection to the BMC fails.
-
-#1370958    excessive pserv logging
-
-#1372767    Twisted web client does not support IPv6 address
-
-#1372944    Twisted web client fails looking up IPv6 address hostname
-
-#1373031    Cannot register cluster
-
-#1373103    compose_curtin_network_preseed breaks installation of all other operating systems
-
-#1373368    Conflicting power actions being dropped on the floor can result in leaving a node in an inconsistent state
-
-#1373699    Cluster Listing Page lacks feedback about the images each cluster has
-
-#1374102    No retries for AMT power?
-
-#1375980    Nodes failed to transition out of "New" state on bulk commission
-
-#1376023    After performing bulk action on maas nodes, Internal Server Error
-
-#1376888    Nodes can't be deleted if DHCP management is off.
-
-#1377099    Bulk operation leaves nodes in inconsistent state
-
-#1379209    When a node has multiple interfaces on a network MAAS manages, MAAS assigns static IP addresses to all of them
-
-#1379744    Cluster registration is fragile and insecure
-
-#1380932    MAAS does not cope with changes of the dhcp daemons
-
-#1381605    Not all the DNS records are being added when deploying multiple nodes
-
-#1012954    If a power script fails, there is no UI feedback
-
-#1186196    "Starting a node" has different meanings in the UI and in the API.
-
-#1237215    maas and curtin do not indicate failure reasonably
-
-#1273222    MAAS doesn't check return values of power actions
-
-#1288502    archive and proxy settings not honoured for commissioning
-
-#1316919    Checks don't exist to confirm a node will actually boot
-
-#1321885    IPMI detection and automatic setting fail in ubuntu 14.04 maas
-
-#1325610    node marked "Ready" before poweroff complete
-
-#1340188    unallocated node started manually, causes AssertionError for purpose poweroff
-
-#1341118    No feedback when IPMI credentials fail
-
-#1341121    No feedback to user when cluster is not running
-
-#1341581    power state is not represented in api and ui
-
-#1341800    MAAS doesn't support soft power off through the API
-
-#1344177    hostnames can't be changed while a node is acquired
-
-#1347518    Confusing error message when API key is wrong
-
-#1349496    Unable to request a specific static IP on the API
-
-#1349736    MAAS logging is too verbose and not very useful
-
-#1349917    guess_server_address() can return IPAddress or hostname
-
-#1350103    No support for armhf/keystone architecture
-
-#1350856    Can't constrain acquisition of nodes by not having a tag
-
-#1356880    MAAS shouldn't allow changing the hostname of a deployed node
-
-#1357714    Virsh power driver does not seem to work at all
-
-#1358859    Commissioning output xml is hard to understand, would be nice to have yaml as an output option.
-
-#1359169    MAAS should handle invalid consumers gracefully
-
-#1359822    Gateway is missing in network definition
-
-#1363913    Impossible to remove last MAC from network in UI
-
-#1364228    Help text for node hostname is wrong
-
-#1364591    MAAS Archive Mirror does not respect non-default port
-
-#1365616    Non-admin access to cluster controller config
-
-#1365619    DNS should be an optional field in the network definition
-
-#1365776    commissioning results view for a node also shows installation results
-
-#1366812    Old boot resources are not being removed on clusters
-
-#1367455    MAC address for node's IPMI is reversed looked up to yield IP address using case sensitive comparison
-
-#1373580    [SRU] Glen m700 cartridge list as ARM64/generic after enlist
-
-#1373723    Releasing a node without power parameters ends up in not being able to release a node
-
-#1233158    no way to get power parameters in api
-
-#1319854    `maas login` tells you you're logged in successfully when you're not
-
-#1368480    Need API to gather image metadata across all of MAAS
-
-#1281406    Disk/memory space on Node edit page have no units
-
-#1299231    MAAS DHCP/DNS can't manage more than a /16 network
-
-#1357381    maas-region-admin createadmin shows error if not params given
-
-#1376393    powerkvm boot loader installs even when not needed
-
-#1287224    MAAS random generated hostnames are not pronounceable
-
-#1348364    non-maas managed subnets cannot query maas DNS
-
+-----
+
+### Important announcements
+
+**Re-import your boot images**  
+You must re-import your boot images, see below for details.
+
+**Update Curtin preseed files**  
+Two changes were made to Curtin preseed files that need your attention if you made any customisations:
+
+-   The OS name must now appear in the filename. The new schema is shown here, each file pattern is tried in turn until a match is found:
+
+    {prefix}\_{osystem}\_{node\_arch}\_{node\_subarch}\_{release}\_{node\_name} {prefix}\_{osystem}\_{node\_arch}\_{node\_subarch}\_{release} {prefix}\_{osystem}\_{node\_arch}\_{node\_subarch} {prefix}\_{osystem}\_{node\_arch} {prefix}\_{osystem} {prefix}
+
+-   If you are modifying `/etc/network/interfaces` in the preseed, it must be moved so it is processed last in `late_commands` since MAAS now writes to this file itself as part of IPv6 setup. For example:
+
+        late_commands:
+          bonding_02: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
+
+    must now look like this:
+
+        late_commands:
+          zz_write_ifaces: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
+
+    The leading `zz` ensures the command sorts to the end of the `late_commands` list.
+
+### Major new features
+
+**Improved image downloading and reporting.**  
+MAAS boot images are now downloaded centrally by the region controller and disseminated to all registered cluster controllers. This change includes a new web UI under the Images tab that allows the admin to select which images to import and shows the progress of the ongoing download. This completely replaces any file-based configuration that used to take place on cluster controllers. The cluster page now shows whether it has synchronised all the images from the region controller.
+
+This process is also completely controllable using the API.
+
+> **note**
+
+> Unfortunately due to a format change in the way images are stored, it was not possible to migrate previously downloaded images to the new region storage. The cluster(s) will still be able to use the existing images, however the region controller will be unaware of them until an import is initiated. When the import is finished, the cluster(s) will remove older image resources.
+>
+> This means that the first thing to do after upgrading to 1.7 is go to the Images tab and re-import the images.
+
+**Increased robustness.**  
+A large amount of effort has been given to ensuring that MAAS remains robust in the face of adversity. An updated node state model has been implemented that takes into account more of the situations in which a node can be found including any failures at each stage.
+
+When a node is getting deployed, it is now monitored to check that each stage is reached in a timely fashion; if it does not then it is marked as failed.
+
+The core power driver was updated to check the state of the power on each node and is reported in the web UI and API. The core driver now also handles retries when changing the power state of hardware, removing the requirement that each power template handle it individually.
+
+**RPC security.**  
+As a step towards mutually verified TLS connections between MAAS's components, 1.7 introduces a simple shared-secret mechanism to authenticate the region with the clusters and vice-versa. For those clusters that run on the same machine as the region controller (which will account for most people), everything will continue to work without intervention. However, if you're running a cluster on a separate machine, you must install the secret:
+
+1.  After upgrading the region controller, view /var/lib/maas/secret (it's text) and copy it.
+2.  On each cluster, run:
+
+    > sudo -u maas maas-provision install-shared-secret
+
+    You'll be prompted for the secret; paste it in and press enter. It is a password prompt, so the secret will not be echoed back to you.
+
+That's it; the upgraded cluster controller will find the secret without needing to be told.
+
+**RPC connections.**  
+Each cluster maintains a persistent connection to each region controller process that's running. The ports on which the region is listening are all high-numbered, and they are allocated randomly by the OS. In a future release of MAAS we will narrow this down. For now, each cluster controller needs unfiltered access to each machine in the region on all high-numbered TCP ports.
+
+**Node event log.**  
+For every major event on nodes, it is now logged in a node-specific log. This includes events such as power changes, deployments and any failures.
+
+**IPv6.**  
+It is now possible to deploy Ubuntu nodes that have IPv6 enabled. See ipv6 for more details.
+
+**Removal of Celery and RabbitMQ.**  
+While Celery was found to be very reliable it ultimately did not suit the project's requirements as it is a largely fire-and-forget mechanism. Additionally it was another moving part that caused some headaches for users and admins alike, so the decision was taken to remove it and implement a custom communications mechanism between the region controller and cluster controllers. The new mechanism is bidirectional and allowed the complex interactions to take place that are required as part of the robustness improvements.
+
+Since a constant connection is maintained, as a side effect the web UI now shows whether each cluster is connected or not.
+
+**Support for other OSes.**  
+Non-Ubuntu OSes are fully supported now. This includes:  
+-   Windows
+-   Centos
+-   SuSE
+
+**Custom Images.**  
+MAAS now supports the deployment of Custom Images. Custom images can be uploaded via the API. The usage of custom images allows the deployment of other Ubuntu Flavors, such as Ubuntu Desktop.
+
+**maas-proxy.**  
+MAAS now uses maas-proxy as the default proxy solution instead of squid-deb-proxy. On a fresh install, MAAS will use maas-proxy by default. On upgrades from previous releases, MAAS will install maas-proxy instead of squid-deb-proxy.
+
+### Minor notable changes
+
+**Better handling of networks.**  
+All networks referred to by cluster interfaces are now automatically registered on the Network page. Any node network interfaces are automatically linked to the relevant Network.
+
+> **note**
+
+> Commissioning currently requires an IP address to be available for each network interface on a network that MAAS manages; this allows MAAS to auto-populate its networks database. In general you should use a well-sized network (/16 recommended if you will be using containers and VMs) and dynamic pool. If this feature risks causing IP exhaustion for your deployment and you do not need the auto-populate functionality, you can disable it by running the following command on your region controller:
+>
+>     sudo maas <profile> maas set-config name=enable_dhcp_discovery_on_unconfigured_interfaces value=False
+
+**Improved logging.**  
+A total overhaul of where logging is produced was undertaken, and now all the main events in MAAS are selectively reported to syslog with the "maas" prefix from both the region and cluster controllers alike. If MAAS is installed using the standard Ubuntu packaging, its syslog entries are redirected to /var/log/maas/maas.log.
+
+On the clusters, pserv.log is now less chatty and contains only errors. On the region controller appservers, maas-django.log contains only appserver errors.
+
+**Static IP selection.**  
+The API was extended so that specific IPs can be pre-allocated for network interfaces on nodes and for user-allocated IPs.
+
+**Pronounceable random hostnames.**  
+The old auto-generated 5-letter names were replaced with a pseudo-random name that is produced from a dictionary giving names of the form 'adjective-noun'.
+
+### Known Problems & Workarounds
+
+**Upgrade issues**  
+There may be upgrade issues for users currently on MAAS 1.5 and 1.6; while we have attempted to reproduce and address all the issues reported, some bugs remain inconclusive. We recommend a full, tested backup of the MAAS servers before attempting the upgrade to 1.7. If you do encounter issues, please file these and flag them to the attention of the MAAS team and we will address them in point-releases. See bugs [1381058](https://launchpad.net/bugs/1381058), [1382266](https://launchpad.net/bugs/1382266), [1379890](https://launchpad.net/bugs/1379890), [1379532](https://launchpad.net/bugs/1379532), and [1379144](https://launchpad.net/bugs/1379144).
+
+**Split Region/Cluster set-ups**  
+If you site your cluster on a separate host to the region, it needs a security key to be manually installed by running `maas-provision install-shared-secret` on the cluster host.
+
+**Private boot streams**  
+If you had private boot image stream information configured in MAAS 1.5 or 1.6, upgrading to 1.7 will not take that into account and it will need to be manually entered on the settings page in the MAAS UI (bug [1379890](https://launchpad.net/bugs/1379890))
+
+**Concurrency issues**  
+Concurrency issues expose us to races when simultaneous operations are triggered. This is the source of many hard to reproduce issues which will require us to change the default database isolation level. We intend to address this in the first point release of 1.7.
+
+**Destroying a Juju environment**  
+When attempting to "juju destroy" an environment, nodes must be in the DEPLOYED state; otherwise, the destroy will fail. You should wait for all in-progress actions on the MAAS cluster to conclude before issuing the command. (bug [1381619](https://launchpad.net/bugs/1381619))
+
+**AMT power control**  
+A few AMT-related issues remain, with workarounds:
+
+> -   Commissioning NUC reboots instead of shutting down (bug [1368685](https://bugs.launchpad.net/maas/+bug/1368685)). There is [a workaround in the power template](https://bugs.launchpad.net/maas/+bug/1368685/comments/8)
+> -   MAAS (amttool) cannot control AMT version \> 8. See [workaround described in bug 1331214](https://bugs.launchpad.net/maas/+bug/1331214/comments/18)
+> -   AMT NUC stuck at boot prompt instead of powering down (no ACPI support in syslinux poweroff) (bug [1376716](https://bugs.launchpad.net/maas/+bug/1376716)). See the [ACPI-only workaround](https://bugs.launchpad.net/maas/+bug/1376716/comments/12)
+
+**Disk wiping**  
+If you enable disk wiping, juju destroy-environment may fail for you. The current workaround is to wait and re-issue the command. This will be fixed in future versions of MAAS & Juju. (bug [1386327](https://bugs.launchpad.net/maas/+bug/1386327))
+
+**BIND with DNSSEC**  
+If you are using BIND with a forwarder that uses DNSSEC and have not configured certificates, you will need to explicitly disable that feature in your BIND configuration (1384334)
+
+**Boot source selections on the API**  
+Use of API to change image selections can leave DB in a bad state (bug [1376812](https://bugs.launchpad.net/maas/+bug/1376812)). It can be fixed by issuing direct database updates.
+
+**Disabling DNS**  
+Disabling DNS may not work (bug [1383768](https://bugs.launchpad.net/maas/+bug/1383768))
+
+**Stale DNS zone files**  
+Stale DNS zone files may be left behind if the MAAS domainname is changed (bug [1383329](https://bugs.launchpad.net/maas/+bug/1383329))
+
+### Major bugs fixed in this release
+
+See <https://launchpad.net/maas/+milestone/1.7.0> for full details.
+
+\#1081660 If maas-enlist fails to reach a DNS server, the node will be named ";; connection timed out; no servers could be reached"
+
+\#1087183 MaaS cloud-init configuration specifies 'manage\_etc\_hosts: localhost'
+
+\#1328351 ConstipationError: When the cluster runs the "import boot images" task it blocks other tasks
+
+\#1342117 CLI command to set up node-group-interface fails with /usr/lib/python2.7/dist-packages/maascli/\_\_main\_\_.py: error: u'name'
+
+\#1349254 Duplicate FQDN can be configured on MAAS via CLI or API
+
+\#1352575 BMC password showing in the apache2 logs
+
+\#1355534 UnknownPowerType traceback in appserver log
+
+\#1363850 Auto-enlistment not reporting power parameters
+
+\#1363900 Dev server errors while trying to write to '/var/lib/maas'
+
+\#1363999 Not assigning static IP addresses
+
+\#1364481 http 500 error doesn't contain a stack trace
+
+\#1364993 500 error when trying to acquire a commissioned node (AddrFormatError: failed to detect a valid IP address from None)
+
+\#1365130 django-admin prints spurious messages to stdout, breaking scripts
+
+\#1365850 DHCP scan using cluster interface name as network interface?
+
+\#1366172 NUC does not boot after power off/power on
+
+\#1366212 Large dhcp leases file leads to tftp timeouts
+
+\#1366652 Leaking temporary directories
+
+\#1368269 internal server error when deleting a node
+
+\#1368590 Power actions are not serialized.
+
+\#1370534 Recurrent update of the power state of nodes crashes if the connection to the BMC fails.
+
+\#1370958 excessive pserv logging
+
+\#1372767 Twisted web client does not support IPv6 address
+
+\#1372944 Twisted web client fails looking up IPv6 address hostname
+
+\#1373031 Cannot register cluster
+
+\#1373103 compose\_curtin\_network\_preseed breaks installation of all other operating systems
+
+\#1373368 Conflicting power actions being dropped on the floor can result in leaving a node in an inconsistent state
+
+\#1373699 Cluster Listing Page lacks feedback about the images each cluster has
+
+\#1374102 No retries for AMT power?
+
+\#1375980 Nodes failed to transition out of "New" state on bulk commission
+
+\#1376023 After performing bulk action on maas nodes, Internal Server Error
+
+\#1376888 Nodes can't be deleted if DHCP management is off.
+
+\#1377099 Bulk operation leaves nodes in inconsistent state
+
+\#1379209 When a node has multiple interfaces on a network MAAS manages, MAAS assigns static IP addresses to all of them
+
+\#1379744 Cluster registration is fragile and insecure
+
+\#1380932 MAAS does not cope with changes of the dhcp daemons
+
+\#1381605 Not all the DNS records are being added when deploying multiple nodes
+
+\#1012954 If a power script fails, there is no UI feedback
+
+\#1186196 "Starting a node" has different meanings in the UI and in the API.
+
+\#1237215 maas and curtin do not indicate failure reasonably
+
+\#1273222 MAAS doesn't check return values of power actions
+
+\#1288502 archive and proxy settings not honoured for commissioning
+
+\#1316919 Checks don't exist to confirm a node will actually boot
+
+\#1321885 IPMI detection and automatic setting fail in ubuntu 14.04 maas
+
+\#1325610 node marked "Ready" before poweroff complete
+
+\#1340188 unallocated node started manually, causes AssertionError for purpose poweroff
+
+\#1341118 No feedback when IPMI credentials fail
+
+\#1341121 No feedback to user when cluster is not running
+
+\#1341581 power state is not represented in api and ui
+
+\#1341800 MAAS doesn't support soft power off through the API
+
+\#1344177 hostnames can't be changed while a node is acquired
+
+\#1347518 Confusing error message when API key is wrong
+
+\#1349496 Unable to request a specific static IP on the API
+
+\#1349736 MAAS logging is too verbose and not very useful
+
+\#1349917 guess\_server\_address() can return IPAddress or hostname
+
+\#1350103 No support for armhf/keystone architecture
+
+\#1350856 Can't constrain acquisition of nodes by not having a tag
+
+\#1356880 MAAS shouldn't allow changing the hostname of a deployed node
+
+\#1357714 Virsh power driver does not seem to work at all
+
+\#1358859 Commissioning output xml is hard to understand, would be nice to have yaml as an output option.
+
+\#1359169 MAAS should handle invalid consumers gracefully
+
+\#1359822 Gateway is missing in network definition
+
+\#1363913 Impossible to remove last MAC from network in UI
+
+\#1364228 Help text for node hostname is wrong
+
+\#1364591 MAAS Archive Mirror does not respect non-default port
+
+\#1365616 Non-admin access to cluster controller config
+
+\#1365619 DNS should be an optional field in the network definition
+
+\#1365776 commissioning results view for a node also shows installation results
+
+\#1366812 Old boot resources are not being removed on clusters
+
+\#1367455 MAC address for node's IPMI is reversed looked up to yield IP address using case sensitive comparison
+
+\#1373580 [SRU] Glen m700 cartridge list as ARM64/generic after enlist
+
+\#1373723 Releasing a node without power parameters ends up in not being able to release a node
+
+\#1233158 no way to get power parameters in api
+
+\#1319854 maas login tells you you're logged in successfully when you're not
+
+\#1368480 Need API to gather image metadata across all of MAAS
+
+\#1281406 Disk/memory space on Node edit page have no units
+
+\#1299231 MAAS DHCP/DNS can't manage more than a /16 network
+
+\#1357381 maas-region-admin createadmin shows error if not params given
+
+\#1376393 powerkvm boot loader installs even when not needed
+
+\#1287224 MAAS random generated hostnames are not pronounceable
+
+\#1348364 non-maas managed subnets cannot query maas DNS
 
 1.6.1
-=====
-
-Bug fix update
---------------
-
-- Auto-link node MACs to Networks (LP: #1341619)
-  MAAS will now auto-create a Network from a cluster interface, and
-  if an active lease exists for a node's MAC then it will be linked to
-  that Network.
-
+-----
+
+### Bug fix update
+
+-   Auto-link node MACs to Networks (LP: \#1341619) MAAS will now auto-create a Network from a cluster interface, and if an active lease exists for a node's MAC then it will be linked to that Network.
 
 1.6.0
-=====
-
-Special notice:
-  Cluster interfaces now have static IP ranges in order to give nodes stable
-  IP addresses.  You need to set the range in each interface to turn on this
-  feature.  See below for details.
-
-
-Major new features
-------------------
-
-IP addresses overhaul.
-  This release contains a total reworking of IP address allocation.  You can
-  now define a separate "static" range in each cluster interface configuration
-  that is separate from the DHCP server's dynamic range.  Any node in use by
-  a user will receive an IP address from the static range that is guaranteed
-  not to change during its allocated lifetime.  Previously, this was at the
-  whim of the DHCP server despite MAAS placing host maps in its configuration.
-
-  Currently, dynamic IP addresses will continue to receive DNS entries so as
-  to maintain backward compatibility with installations being upgraded from
-  1.5.  However, this will be changed in a future release to only give
-  DNS entries to static IPs.
-
-  You can also use the API to `reserve IP addresses`_ on a per-user basis.
-
-.. _reserve IP addresses: http://maas.ubuntu.com/docs1.6/api.html#ip-addresses
-
-Support for additional OSes.
-  MAAS can now install operating systems other than Ubuntu on nodes.
-  Preliminary beta support exists for CentOS and SuSE via the `Curtin`_ "fast"
-  installer.  This has not been thoroughly tested yet and has been provided
-  in case anyone finds this useful and is willing to help find and report bugs.
-
-
-Minor notable changes
----------------------
-
-DNS entries
-  In 1.5 DNS entries for nodes were a CNAME record.  As of 1.6, they are now
-  all "A" records, which allows for reliable reverse look-ups.
-
-  Only nodes that are allocated to a user and started will receive "A" record
-  entries.  Unallocated nodes no longer have DNS entries.
-
-Removal of bootresources.yaml
-  The bootresources.yaml file, which had to be configured separately on each
-  cluster controller, is no longer in use.  Instead, the configuration for
-  which images to download is now held by the region controller, and defaults
-  to downloading all images for LTS releases.  A `rudimentary API`_ is
-  available to manipulate this configuration.
-
-.. _rudimentary API: http://maas.ubuntu.com/docs1.6/api.html#boot-source
-
-Fast installer is now the default
-  Prevously, the slower Debian installer was used by default.  Any newly-
-  enlisted nodes will now use the newer `fast installer`_.  Existing nodes
-  will keep the installer setting that they already have.
-
-.. _fast installer: https://launchpad.net/curtin
-
-
-Bugs fixed in this release
---------------------------
-#1307779    fallback from specific to generic subarch broken
-#1310082    d-i with precise+hwe-s stops at "Architecture not supported"
-#1314174    Autodetection of the IPMI IP address fails when the 'power_address'
-of the power parameters is empty.
-#1314267    MAAS dhcpd will re-issue leases for nodes
-#1317675    Exception powering down a virsh machine
-#1322256    Import boot resources failing to verify keyring
-#1322336    import_boot_images crashes with KeyError on 'keyring'
-#1322606    maas-import-pxe-files fails when run from the command line
-#1324237    call_and_check does not report error output
-#1328659    import_boot_images task fails on utopic
-#1332596    AddrFormatError: failed to detect a valid IP address from None executing upload_dhcp_leases task
-#1250370    "sudo maas-import-ephemerals" steps on ~/.gnupg/pubring.gpg
-#1250435    CNAME record leaks into juju's private-address, breaks host based access control
-#1305758    Import fails while writing maas.meta: No such file or directory
-#1308292    Unhelpful error when re-enlisting a previously enlisted node
-#1309601    maas-enlist prints "successfully enlisted" even when enlistment fail
-s.
-#1309729    Fast path installer is not the default
-#1310844    find_ip_via_arp() results in unpredictable, and in some cases, incorrect IP addresses
-#1310846    amt template gives up way too easily
-#1312863    MAAS fails to detect SuperMicro-based server's power type
-#1314536    Copyright date in web UI is 2012
-#1315160    no support for different operating systems
-#1316627    API needed to allocate and return an extra IP for a container
-#1323291    Can't re-commission a commissioning node
-#1324268    maas-cli 'nodes list' or 'node read <system_id>' doesn't display the osystem or distro_series node fields
-#1325093    install centos using curtin
-#1325927    YUI.Array.each not working as expected
-#1328656    MAAS sends multiple stop_dhcp_server tasks even though there's no dhcp server running.
-#1331139    IP is inconsistently capitalized on the 'edit a cluster interface' p
-age
-#1331148    When editing a cluster interface, last 3 fields are unintuitive
-#1331165    Please do not hardcode the IP address of Canonical services into MAAS managed DHCP configs
-#1338851    Add MAAS arm64/xgene support
-#1307693    Enlisting a SeaMicro or Virsh chassis twice will not replace the missing entries
-#1311726    No documentation about the supported power types and the related power parameters
-#1331982    API documentation for nodegroup op=details missing parameter
-#1274085    error when maas can't meet juju constraints is confusing and not helpful
-#1330778    MAAS needs support for managing nodes via the Moonshot HP iLO Chassis Manager CLI
-#1337683    The API client MAASClient doesn't encode list parameters when doing a GET
-#1190986    ERROR Nonce already used
-#1342135    Allow domains to be used for NTP server configuration, not just IPs
-#1337437    Allow 14.10 Utopic Unicorn as a deployable series
-#1350235    Package fails to install when the default route is through an aliased/tagged interface
-#1353597    PowerNV: format_bootif should make sure mac address is all lowercase
+-----
+
+Special notice:  
+Cluster interfaces now have static IP ranges in order to give nodes stable IP addresses. You need to set the range in each interface to turn on this feature. See below for details.
+
+### Major new features
+
+IP addresses overhaul.  
+This release contains a total reworking of IP address allocation. You can now define a separate "static" range in each cluster interface configuration that is separate from the DHCP server's dynamic range. Any node in use by a user will receive an IP address from the static range that is guaranteed not to change during its allocated lifetime. Previously, this was at the whim of the DHCP server despite MAAS placing host maps in its configuration.
+
+Currently, dynamic IP addresses will continue to receive DNS entries so as to maintain backward compatibility with installations being upgraded from 1.5. However, this will be changed in a future release to only give DNS entries to static IPs.
+
+You can also use the API to [reserve IP addresses](http://maas.ubuntu.com/docs1.6/api.html#ip-addresses) on a per-user basis.
+
+Support for additional OSes.  
+MAAS can now install operating systems other than Ubuntu on nodes. Preliminary beta support exists for CentOS and SuSE via the [Curtin](https://launchpad.net/curtin) "fast" installer. This has not been thoroughly tested yet and has been provided in case anyone finds this useful and is willing to help find and report bugs.
+
+### Minor notable changes
+
+DNS entries  
+In 1.5 DNS entries for nodes were a CNAME record. As of 1.6, they are now all "A" records, which allows for reliable reverse look-ups.
+
+Only nodes that are allocated to a user and started will receive "A" record entries. Unallocated nodes no longer have DNS entries.
+
+Removal of bootresources.yaml  
+The bootresources.yaml file, which had to be configured separately on each cluster controller, is no longer in use. Instead, the configuration for which images to download is now held by the region controller, and defaults to downloading all images for LTS releases. A [rudimentary API](http://maas.ubuntu.com/docs1.6/api.html#boot-source) is available to manipulate this configuration.
+
+Fast installer is now the default  
+Prevously, the slower Debian installer was used by default. Any newly-enlisted nodes will now use the newer [fast installer](https://launchpad.net/curtin). Existing nodes will keep the installer setting that they already have.
+
+### Bugs fixed in this release
+
+\#1307779 fallback from specific to generic subarch broken \#1310082 d-i with precise+hwe-s stops at "Architecture not supported" \#1314174 Autodetection of the IPMI IP address fails when the 'power\_address' of the power parameters is empty. \#1314267 MAAS dhcpd will re-issue leases for nodes \#1317675 Exception powering down a virsh machine \#1322256 Import boot resources failing to verify keyring \#1322336 import\_boot\_images crashes with KeyError on 'keyring' \#1322606 maas-import-pxe-files fails when run from the command line \#1324237 call\_and\_check does not report error output \#1328659 import\_boot\_images task fails on utopic \#1332596 AddrFormatError: failed to detect a valid IP address from None executing upload\_dhcp\_leases task \#1250370 "sudo maas-import-ephemerals" steps on \~/.gnupg/pubring.gpg \#1250435 CNAME record leaks into juju's private-address, breaks host based access control \#1305758 Import fails while writing maas.meta: No such file or directory \#1308292 Unhelpful error when re-enlisting a previously enlisted node \#1309601 maas-enlist prints "successfully enlisted" even when enlistment fail s. \#1309729 Fast path installer is not the default \#1310844 find\_ip\_via\_arp() results in unpredictable, and in some cases, incorrect IP addresses \#1310846 amt template gives up way too easily \#1312863 MAAS fails to detect SuperMicro-based server's power type \#1314536 Copyright date in web UI is 2012 \#1315160 no support for different operating systems \#1316627 API needed to allocate and return an extra IP for a container \#1323291 Can't re-commission a commissioning node \#1324268 maas-cli 'nodes list' or 'node read \<system\_id\>' doesn't display the osystem or distro\_series node fields \#1325093 install centos using curtin \#1325927 YUI.Array.each not working as expected \#1328656 MAAS sends multiple stop\_dhcp\_server tasks even though there's no dhcp server running. \#1331139 IP is inconsistently capitalized on the 'edit a cluster interface' p age \#1331148 When editing a cluster interface, last 3 fields are unintuitive \#1331165 Please do not hardcode the IP address of Canonical services into MAAS managed DHCP configs \#1338851 Add MAAS arm64/xgene support \#1307693 Enlisting a SeaMicro or Virsh chassis twice will not replace the missing entries \#1311726 No documentation about the supported power types and the related power parameters \#1331982 API documentation for nodegroup op=details missing parameter \#1274085 error when maas can't meet juju constraints is confusing and not helpful \#1330778 MAAS needs support for managing nodes via the Moonshot HP iLO Chassis Manager CLI \#1337683 The API client MAASClient doesn't encode list parameters when doing a GET \#1190986 ERROR Nonce already used \#1342135 Allow domains to be used for NTP server configuration, not just IPs \#1337437 Allow 14.10 Utopic Unicorn as a deployable series \#1350235 Package fails to install when the default route is through an aliased/tagged interface \#1353597 PowerNV: format\_bootif should make sure mac address is all lowercase
 
 1.5.3
-=====
-
-Bug fix update
---------------
-
- - Reduce number of celery tasks emitted when updating a cluster controller
-   (LP: #1324944)
- - Fix VirshSSH template which was referencing invalid attributes
-   (LP: #1324966)
- - Fix a start up problem where a database lock was being taken outside of
-   a transaction (LP: #1325759)
- - Reformat badly formatted Architecture error message (LP: #1301465)
- - Final changes to support ppc64el (now known as PowerNV) (LP: #1315154)
-
+-----
+
+### Bug fix update
+
+> -   Reduce number of celery tasks emitted when updating a cluster controller (LP: \#1324944)
+> -   Fix VirshSSH template which was referencing invalid attributes (LP: \#1324966)
+> -   Fix a start up problem where a database lock was being taken outside of a transaction (LP: \#1325759)
+> -   Reformat badly formatted Architecture error message (LP: \#1301465)
+> -   Final changes to support ppc64el (now known as PowerNV) (LP: \#1315154)
 
 1.5.2
-=====
-
-Minor feature changes
----------------------
-
-Boot resource download changes.
-  Further to the work done in the 1.5 (Ubuntu 14.04) release, MAAS no
-  longer stores the configuration for downloading boot resources in
-  ``/etc/maas/bootresources.yaml``; this file is now obsolete. The
-  sources list is now stored on the region controller and passed to the
-  cluster controller when the job to download boot resources is started.
-  It is still possible to pass a list of sources to
-  ``maas-import-pxe-files`` when running the script manually.
-
+-----
+
+### Minor feature changes
+
+Boot resource download changes.  
+Further to the work done in the 1.5 (Ubuntu 14.04) release, MAAS no longer stores the configuration for downloading boot resources in `/etc/maas/bootresources.yaml`; this file is now obsolete. The sources list is now stored on the region controller and passed to the cluster controller when the job to download boot resources is started. It is still possible to pass a list of sources to `maas-import-pxe-files` when running the script manually.
 
 1.5.1
-=====
-
-Bug fix update
---------------
-
-For full details see https://launchpad.net/maas/+milestone/1.5.1
-
-#1303915    Powering SM15k RESTAPI v2.0 doesn't force PXE boot
-#1307780    no armhf commissioning template
-#1310076    lost connectivity to a node when using fastpath-installer with precise+hwe-s
-#1310082    d-i with precise+hwe-s stops at "Architecture not supported"
-#1311151    MAAS imports Trusty's 'rc' images by default.
-#1311433    REGRESSION: AttributeError: 'functools.partial' object has no attribute '__module__'
-#1313556    API client blocks when deleting a resource
-#1314409    parallel juju deployments race on the same maas
-#1316396    When stopping a node from the web UI that was started from the API, distro_series is not cleared
-#1298784    Vulnerable to user-interface redressing (e.g. clickjacking)
-#1308772    maas has no way to specify alternate IP addresses for AMT template
-#1300476    Unable to setup BMC/UCS user on Cisco B200 M3
+-----
+
+### Bug fix update
+
+For full details see <https://launchpad.net/maas/+milestone/1.5.1>
+
+\#1303915 Powering SM15k RESTAPI v2.0 doesn't force PXE boot \#1307780 no armhf commissioning template \#1310076 lost connectivity to a node when using fastpath-installer with precise+hwe-s \#1310082 d-i with precise+hwe-s stops at "Architecture not supported" \#1311151 MAAS imports Trusty's 'rc' images by default. \#1311433 REGRESSION: AttributeError: 'functools.partial' object has no attribute '\_\_module\_\_' \#1313556 API client blocks when deleting a resource \#1314409 parallel juju deployments race on the same maas \#1316396 When stopping a node from the web UI that was started from the API, distro\_series is not cleared \#1298784 Vulnerable to user-interface redressing (e.g. clickjacking) \#1308772 maas has no way to specify alternate IP addresses for AMT template \#1300476 Unable to setup BMC/UCS user on Cisco B200 M3
 
 1.5
-===
+---
 
 (released in Ubuntu 14.04)
 
-Major new features
-------------------
-
-Advanced Networking.
-  MAAS will now support multiple managed network interfaces on a single
-  cluster.  It will track networks (including tagged VLANs) to which each node
-  is able to connect and provides this information in the API.  API clients may
-  also use networking information in acquisition constraints when asking for a
-  new node allocation.
-
-  See :ref:`The full Networking documentation <networks>`.
-
-Zones.
-  A Zone is an arbitrary grouping of nodes.  MAAS now allows admins to define
-  Zones, and place in them any of the region's nodes.  Once defined, API
-  clients can use the zone name as acquisition constraints for new node
-  allocations.
-
-  See :doc:`physical-zones` for more detail.
-
-Hardware Enablement Kernels.
-  MAAS is now able to fetch and use hardware enablement kernels which allow
-  kernels for newer Ubuntu releases to be used on older releases.
-
-  See :doc:`hardware-enablement-kernels`
-
-Minor feature changes
----------------------
-
-Maas-Test.
-  A new project `maas-test`_ was created to put a piece of hardware through MAAS's
-  test suite to see if it's suitable for use in MAAS, and optionally report the results
-  to a bug in Launchpad's maas-test project.
-
-.. _maas-test: https://launchpad.net/maas-test/
-
-IPMI improvements.
-  Many improvements were made to IPMI handling, including better detection
-  during enlistment.  Many IPMI-based systems that previously failed to work
-  with MAAS will now work correctly.
-
-Completion of image downloading changes.
-  Further to the work done in the 1.4 (Ubuntu 13.10) release, MAAS now uses indexed
-  "simplestreams" data published by Canonical to fetch not only the ephemeral
-  images, but now also the kernels and ramdisks.  The resource download
-  configuration is now in a new file ``/etc/maas/bootresources.yaml`` on
-  each cluster controller.  All previous configuration files for image
-  downloads are now obsolete.  The new file will be pre-configured based on
-  images that are already present on the cluster.
-
-  This change also enables end-users to provide their own simplestreams data
-  and thusly their own custom images.
-
-Cluster-driven hardware availability.
-  When adding or editing node hardware in the region controller, MAAS will
-  contact the relevant cluster controller to validate the node's settings.
-  As of release, the only validation made is the architecture and the power
-  settings.  Available architectures are based on which images have been
-  imported on the cluster.  In the future, this will enable new cluster
-  controllers to be added that contain drivers for new hardware without
-  restarting the region controller.
-
-Seamicro hardware.
-  MAAS now supports the Seamicro 15000 hardware for power control and API-based
-  enlistment.
-
-AMT.
-  MAAS now supports power control using `Intel AMT`_.
-
-.. _Intel AMT: http://www.intel.com/content/www/us/en/architecture-and-technology/intel-active-management-technology.html
-
-DNS forwarders.
-  In MAAS's settings it's now possible to configure an upstream DNS, which will
-  be set in the bind daemon's 'forwarders' option.
-
-Foreign DHCP servers.
-  MAAS detects and shows you if any other DHCP servers are active on the
-  networks that are on the cluster controller.
-
-Commissioning Results.
-  A node's commissioning results are now shown in the UI.
-
-Renamed commands.
-  ``maas`` is renamed to ``maas-region-admin``.  ``maas-cli`` is now just
-  ``maas``.
-
-
-Bugs fixed in this release
---------------------------
-For full details see https://launchpad.net/maas/+milestone/14.04
-
-#1227035 If a template substitution fails, the appserver crashes
-
-#1255479    MaaS Internal Server Error 500 while parsing tags with namespaces in definition upon commissioning
-
-#1269648    OAuth unauthorised errors mask the actual error text
-
-#1270052    Adding an SSH key fails due to a UnicodeDecodeError
-
-#1274024    kernel parameters are not set up in the installed OS's grub cfg
-
-#1274190    periodic_probe_dhcp task raises IOError('No such device')
-
-#1274912    Internal server error when trying to stop a node with no power type
-
-#1274926    A node's nodegroup is autodetected using the request's IP even when the request is a manual
-
-#1278895    When any of the commissioning scripts fails, the error reported contains the list of the scripts that *didn't* fail
-
-#1279107    maas_ipmi_autodetect.py ignores command failures
-
-#1282828    Almost impossible to provide a valid nodegroup ID when enlisting new node on API
-
-#1283114    MAAS' DHCP server is not stopped when the number of managed interfaces is zero
-
-#1285244    Deleting a node sometimes fails with omshell error
-
-#1285607    maas_ipmi_autodetect mistakes empty slot for taken slot
-
-#1287274    On OCPv3 Roadrunner, maas_ipmi_autodetect fails because LAN Channel settings can't be changed
-
-#1287512    OCPv3 roadrunner detects IPMI as 1.5
-
-#1289456    maas IPMI user creation fails on some DRAC systems
-
-#1290622    report_boot_images does not remove images that were deleted from the cluster
-
-#1293676    internal server error when marking nodes as using fast-path installer
-
-#1300587    Cloud-archive selection widget is obsolete
-
-#1301809    Report boot images no directory traceback
-
-#1052339    MAAS only supports one "managed" (DNS/DHCP) interface per cluster controller.
-
-#1058126    maas dbshell stacktraces in package
-
-#1064212    If a machine is booted manually when in status "Declared" or "Ready", TFTP server tracebacks
-
-#1073460    Node-specific kernel and ramdisk is not possible
-
-#1177932    Unable to select which pxe files to download by both series and architecture.
-
-#1181334    i386 required to install amd64
-
-#1184589    When external commands, issued by MAAS, fail, the log output does not give any information about the failure.
-
-#1187851    Newline added to end of files obtained with maas-cli
-
-#1190986    ERROR Nonce already used
-
-#1191735    TFTP server not listening on all interfaces
-
-#1210393    MAAS ipmi fails on OCPv3 Roadrunner
-
-#1228205    piston hijacks any TypeError raised by MAAS
-
-#1234880    HP ilo4 consoles default to autodetect protocol, which doesn't work
-
-#1237197    No scheduled job for images download
-
-#1238284    multiple ip address displayed for a node
-
-#1243917    'maas createsuperuser' errors out if no email address is entered.
-
-#1246531    dhcpd.conf not updated when user hits "Save cluster controller"
-
-#1246625    The power parameters used by the virsh power template are inconsistent.
-
-#1247708    Cluster interface shows up with no interface name
-
-#1248893    maas-cli listing nodes filtered by hostname doesn't work
-
-#1249435    kernel options not showing up in WebUI and not being passed at install time to one node
-
-#1250410    Search box renders incorrectly in Firefox
-
-#1268795    unable to automatically commission Cisco UCS server due to BMC user permissions
-
-#1270131    1 CPU when there are multiple cores on Intel NUC
-
-#1271056    API call for listing nodes filtered by zone
-
-#1273650    Fastpath installer does not pick up package mirror settings from MAAS
-
-#1274017    MAAS new user creation requires E-Mail address, throws wrong error when not provided
-
-#1274465    Network identity shows broadcast address instead of the network's address
-
-#1274499    dhcp lease rollover causes loss of access to management IP
-
-#1275643    When both IPMI 1.5 and 2.0 are available, MAAS should use 2.0
-
-#1279304    Node commissioning results are not displayed in the UI
-
-#1279728    Storage capacity isn't always detected
-
-#1287964    MAAS incorrectly detects / sets-up BMC information on Dell PowerEdge servers
-
-#1292491    pserv traceback when region controller not yet ready
-
-#1293661    cannot use fast path installer to deploy other than trusty
-
-#1294302    fast installer fails to PXE boot on armhf/highbank
-
-#1295035    The UI doesn't display the list of available boot images
-
-#1297814    MAAS does not advertise its capabilities
-
-#1298790    Logout page vulnerable to CSRF
-
-#1271189    support switching image streams in import ephemerals
-
-#1287310    hard to determine valid values for power parameters
-
-#1272014    MAAS prompts user to run `maas createadmin`; instead of `maas createsuperuser`
-
-#1108319    maascli could have a way to tell which cluster controllers don't have the pxe files
-
+### Major new features
+
+Advanced Networking.  
+MAAS will now support multiple managed network interfaces on a single cluster. It will track networks (including tagged VLANs) to which each node is able to connect and provides this information in the API. API clients may also use networking information in acquisition constraints when asking for a new node allocation.
+
+See The full Networking documentation \<networks\>.
+
+Zones.  
+A Zone is an arbitrary grouping of nodes. MAAS now allows admins to define Zones, and place in them any of the region's nodes. Once defined, API clients can use the zone name as acquisition constraints for new node allocations.
+
+See physical-zones for more detail.
+
+Hardware Enablement Kernels.  
+MAAS is now able to fetch and use hardware enablement kernels which allow kernels for newer Ubuntu releases to be used on older releases.
+
+See hardware-enablement-kernels
+
+### Minor feature changes
+
+Maas-Test.  
+A new project [maas-test](https://launchpad.net/maas-test/) was created to put a piece of hardware through MAAS's test suite to see if it's suitable for use in MAAS, and optionally report the results to a bug in Launchpad's maas-test project.
+
+IPMI improvements.  
+Many improvements were made to IPMI handling, including better detection during enlistment. Many IPMI-based systems that previously failed to work with MAAS will now work correctly.
+
+Completion of image downloading changes.  
+Further to the work done in the 1.4 (Ubuntu 13.10) release, MAAS now uses indexed "simplestreams" data published by Canonical to fetch not only the ephemeral images, but now also the kernels and ramdisks. The resource download configuration is now in a new file `/etc/maas/bootresources.yaml` on each cluster controller. All previous configuration files for image downloads are now obsolete. The new file will be pre-configured based on images that are already present on the cluster.
+
+This change also enables end-users to provide their own simplestreams data and thusly their own custom images.
+
+Cluster-driven hardware availability.  
+When adding or editing node hardware in the region controller, MAAS will contact the relevant cluster controller to validate the node's settings. As of release, the only validation made is the architecture and the power settings. Available architectures are based on which images have been imported on the cluster. In the future, this will enable new cluster controllers to be added that contain drivers for new hardware without restarting the region controller.
+
+Seamicro hardware.  
+MAAS now supports the Seamicro 15000 hardware for power control and API-based enlistment.
+
+AMT.  
+MAAS now supports power control using [Intel AMT](http://www.intel.com/content/www/us/en/architecture-and-technology/intel-active-management-technology.html).
+
+DNS forwarders.  
+In MAAS's settings it's now possible to configure an upstream DNS, which will be set in the bind daemon's 'forwarders' option.
+
+Foreign DHCP servers.  
+MAAS detects and shows you if any other DHCP servers are active on the networks that are on the cluster controller.
+
+Commissioning Results.  
+A node's commissioning results are now shown in the UI.
+
+Renamed commands.  
+`maas` is renamed to `maas-region-admin`. `maas-cli` is now just `maas`.
+
+### Bugs fixed in this release
+
+For full details see <https://launchpad.net/maas/+milestone/14.04>
+
+\#1227035 If a template substitution fails, the appserver crashes
+
+\#1255479 MaaS Internal Server Error 500 while parsing tags with namespaces in definition upon commissioning
+
+\#1269648 OAuth unauthorised errors mask the actual error text
+
+\#1270052 Adding an SSH key fails due to a UnicodeDecodeError
+
+\#1274024 kernel parameters are not set up in the installed OS's grub cfg
+
+\#1274190 periodic\_probe\_dhcp task raises IOError('No such device')
+
+\#1274912 Internal server error when trying to stop a node with no power type
+
+\#1274926 A node's nodegroup is autodetected using the request's IP even when the request is a manual
+
+\#1278895 When any of the commissioning scripts fails, the error reported contains the list of the scripts that *didn't* fail
+
+\#1279107 maas\_ipmi\_autodetect.py ignores command failures
+
+\#1282828 Almost impossible to provide a valid nodegroup ID when enlisting new node on API
+
+\#1283114 MAAS' DHCP server is not stopped when the number of managed interfaces is zero
+
+\#1285244 Deleting a node sometimes fails with omshell error
+
+\#1285607 maas\_ipmi\_autodetect mistakes empty slot for taken slot
+
+\#1287274 On OCPv3 Roadrunner, maas\_ipmi\_autodetect fails because LAN Channel settings can't be changed
+
+\#1287512 OCPv3 roadrunner detects IPMI as 1.5
+
+\#1289456 maas IPMI user creation fails on some DRAC systems
+
+\#1290622 report\_boot\_images does not remove images that were deleted from the cluster
+
+\#1293676 internal server error when marking nodes as using fast-path installer
+
+\#1300587 Cloud-archive selection widget is obsolete
+
+\#1301809 Report boot images no directory traceback
+
+\#1052339 MAAS only supports one "managed" (DNS/DHCP) interface per cluster controller.
+
+\#1058126 maas dbshell stacktraces in package
+
+\#1064212 If a machine is booted manually when in status "Declared" or "Ready", TFTP server tracebacks
+
+\#1073460 Node-specific kernel and ramdisk is not possible
+
+\#1177932 Unable to select which pxe files to download by both series and architecture.
+
+\#1181334 i386 required to install amd64
+
+\#1184589 When external commands, issued by MAAS, fail, the log output does not give any information about the failure.
+
+\#1187851 Newline added to end of files obtained with maas-cli
+
+\#1190986 ERROR Nonce already used
+
+\#1191735 TFTP server not listening on all interfaces
+
+\#1210393 MAAS ipmi fails on OCPv3 Roadrunner
+
+\#1228205 piston hijacks any TypeError raised by MAAS
+
+\#1234880 HP ilo4 consoles default to autodetect protocol, which doesn't work
+
+\#1237197 No scheduled job for images download
+
+\#1238284 multiple ip address displayed for a node
+
+\#1243917 'maas createsuperuser' errors out if no email address is entered.
+
+\#1246531 dhcpd.conf not updated when user hits "Save cluster controller"
+
+\#1246625 The power parameters used by the virsh power template are inconsistent.
+
+\#1247708 Cluster interface shows up with no interface name
+
+\#1248893 maas-cli listing nodes filtered by hostname doesn't work
+
+\#1249435 kernel options not showing up in WebUI and not being passed at install time to one node
+
+\#1250410 Search box renders incorrectly in Firefox
+
+\#1268795 unable to automatically commission Cisco UCS server due to BMC user permissions
+
+\#1270131 1 CPU when there are multiple cores on Intel NUC
+
+\#1271056 API call for listing nodes filtered by zone
+
+\#1273650 Fastpath installer does not pick up package mirror settings from MAAS
+
+\#1274017 MAAS new user creation requires E-Mail address, throws wrong error when not provided
+
+\#1274465 Network identity shows broadcast address instead of the network's address
+
+\#1274499 dhcp lease rollover causes loss of access to management IP
+
+\#1275643 When both IPMI 1.5 and 2.0 are available, MAAS should use 2.0
+
+\#1279304 Node commissioning results are not displayed in the UI
+
+\#1279728 Storage capacity isn't always detected
+
+\#1287964 MAAS incorrectly detects / sets-up BMC information on Dell PowerEdge servers
+
+\#1292491 pserv traceback when region controller not yet ready
+
+\#1293661 cannot use fast path installer to deploy other than trusty
+
+\#1294302 fast installer fails to PXE boot on armhf/highbank
+
+\#1295035 The UI doesn't display the list of available boot images
+
+\#1297814 MAAS does not advertise its capabilities
+
+\#1298790 Logout page vulnerable to CSRF
+
+\#1271189 support switching image streams in import ephemerals
+
+\#1287310 hard to determine valid values for power parameters
+
+\#1272014 MAAS prompts user to run maas createadmin; instead of maas createsuperuser
+
+\#1108319 maascli could have a way to tell which cluster controllers don't have the pxe files
 
 1.4
-===
+---
 
 (released in Ubuntu 13.10)
 
-Major new features
-------------------
-
-LLDP collection.
-  MAAS now collects LLDP data on each node during its
-  commissioning cycle.  The router to which the node is connected will have
-  its MAC address parsed out of the data and made available for using as a
-  placement constraint (passing connected_to or not_connected_to to the
-  acquire() API call), or you can define tags using expressions such as
-  ``//lldp:chassis/lldp:id[@type="mac"]/text() = "20:4e:7f:94:2e:10"``
-  which would tag nodes with a router using that MAC address.
-
-New faster installer for nodes.
-  MAAS will now make use of the new Curtin_ installer which is much quicker
-  than the old Debian Installer process.  Typically an installation now
-  takes a couple of minutes instead of upwards of 10 minutes.  To have a node
-  use the faster installer, add the ``use-fastpath-installer`` tag to it,
-  or click the "Use the fast installer" button on the node page.
-
-.. _Curtin: https://launchpad.net/curtin
-
-More extensible templates for DHCP, power control, PXE and DNS.
-  Templates supplied for these activities are now all in their own template
-  file that is customisable by the user.  The files now generally live under
-  /etc/maas/ rather than embedded in the code tree itself.
-
-Minor feature changes
----------------------
-
-Reworked ephemeral downloading
-  While there is no end-user visible change, the ephemeral image download
-  process is now driven by a data stream published by Canonical at
-  http://maas.ubuntu.com/images/streams. In the future this will allow end
-  users to use their own customised images by creating their own stream.
-  The configuration for this is now also part of ``pserv.yaml``, obsoleting
-  the maas_import_ephemerals configuration file.  The config will be auto-
-  migrated on the first run of the ``maas-import-ephemerals`` script.
-
-Improved maas-cli support
-  Users can now manage their SSH keys and API credentials via the maas-cli
-  tool.
-
-Django 1.5
-  MAAS is updated to work with Django 1.5
-
-HP Moonshot Systems support.
-  MAAS can now manage HP Moonshot Systems as any other hardware. However,
-  in order for MAAS to power manage these systems, it requires the user
-  to manually specify the iLO credentials before the enlistment process
-  begins. This can be done in the ``maas_moonshot_autodetect.py``
-  template under ``/etc/maas/templates/commissioning-user-data/snippets/``.
-
-Bugs fixed in this release
---------------------------
-#1039513  maas-import-pxe-files doesn't cryptographically verify what
-it downloads
-
-#1158425  maas-import-pxe-files sources path-relative config
-
-#1204507  MAAS rejects empty files
-
-#1208497  netboot flag defaults to 'true' on upgrade, even for allocated
-nodes
-
-#1227644  Releasing a node using the API errors with "TypeError:
-00:e0:81:dd:d1:0b is not JSON serializable"
-
-#1234853  MAAS returns HTTP/500 when adding a second managed interface
-to cluster controller
-
-#971349  With 100% of nodes in 'declared' state, pie chart is white on white
-
-#974035  Node listing does not support bulk operations
-
-#1045725  SAY clauses in PXE configs are being evaluated as they're
-encountered, not when the label is branched to
-
-#1054518  distro_series can be None or ""
-
-#1064777  If a node's IP address is known, it's not shown anywhere
-
-#1084807  Users are editing the machine-generated dhcpd.conf
-
-#1155607  Conflict between "DNS zone name" in Cluster controller and
-"Default domain for new nodes" in settings
-
-#1172336  MAAS server reference to AvahiBoot wiki page that does not exist
-
-#1185160  no way to see what user has a node allocated
-
-#1202314  Discrepancy between docs and behavior
-
-#1206222  Documentation Feedback and Site suggestions
-
-#1209039  Document that MAAS requires 'portfast' on switch ports connected
-to nodes
-
-#1215750  No way of tracing/debugging http traffic content in the appserver.
-
-#1223157  start_commissioning needlessly sets owner on commissioning nodes
-
-#1227081  Error in apache's log "No handlers could be found for logger
-"maasserver""
-
-#1233069  maas-import-pxe-files fails when md5 checksums can't be downloaded
-
-#1117415  maas dhcp responses do not have domain-name or domain-search
-
-#1136449  maas-cli get-config and set-config documentation
-
-#1175405  Pie chart says "deployed" which is inconsistent with the node
-list's "allocated"
-
-#1233833  Usability: deleting nodes is too easy
-
-#1185897  expose ability to re-commission node in api and cli
-
-#997092  Can't delete allocated node even if owned by self
+### Major new features
+
+LLDP collection.  
+MAAS now collects LLDP data on each node during its commissioning cycle. The router to which the node is connected will have its MAC address parsed out of the data and made available for using as a placement constraint (passing connected\_to or not\_connected\_to to the acquire() API call), or you can define tags using expressions such as `//lldp:chassis/lldp:id[@type="mac"]/text() = "20:4e:7f:94:2e:10"` which would tag nodes with a router using that MAC address.
+
+New faster installer for nodes.  
+MAAS will now make use of the new [Curtin](https://launchpad.net/curtin) installer which is much quicker than the old Debian Installer process. Typically an installation now takes a couple of minutes instead of upwards of 10 minutes. To have a node use the faster installer, add the `use-fastpath-installer` tag to it, or click the "Use the fast installer" button on the node page.
+
+More extensible templates for DHCP, power control, PXE and DNS.  
+Templates supplied for these activities are now all in their own template file that is customisable by the user. The files now generally live under /etc/maas/ rather than embedded in the code tree itself.
+
+### Minor feature changes
+
+Reworked ephemeral downloading  
+While there is no end-user visible change, the ephemeral image download process is now driven by a data stream published by Canonical at <http://maas.ubuntu.com/images/streams>. In the future this will allow end users to use their own customised images by creating their own stream. The configuration for this is now also part of `pserv.yaml`, obsoleting the maas\_import\_ephemerals configuration file. The config will be auto-migrated on the first run of the `maas-import-ephemerals` script.
+
+Improved maas-cli support  
+Users can now manage their SSH keys and API credentials via the maas-cli tool.
+
+Django 1.5  
+MAAS is updated to work with Django 1.5
+
+HP Moonshot Systems support.  
+MAAS can now manage HP Moonshot Systems as any other hardware. However, in order for MAAS to power manage these systems, it requires the user to manually specify the iLO credentials before the enlistment process begins. This can be done in the `maas_moonshot_autodetect.py` template under `/etc/maas/templates/commissioning-user-data/snippets/`.
+
+### Bugs fixed in this release
+
+\#1039513 maas-import-pxe-files doesn't cryptographically verify what it downloads
+
+\#1158425 maas-import-pxe-files sources path-relative config
+
+\#1204507 MAAS rejects empty files
+
+\#1208497 netboot flag defaults to 'true' on upgrade, even for allocated nodes
+
+\#1227644 Releasing a node using the API errors with "TypeError: 00:e0:81:dd:d1:0b is not JSON serializable"
+
+\#1234853 MAAS returns HTTP/500 when adding a second managed interface to cluster controller
+
+\#971349 With 100% of nodes in 'declared' state, pie chart is white on white
+
+\#974035 Node listing does not support bulk operations
+
+\#1045725 SAY clauses in PXE configs are being evaluated as they're encountered, not when the label is branched to
+
+\#1054518 distro\_series can be None or ""
+
+\#1064777 If a node's IP address is known, it's not shown anywhere
+
+\#1084807 Users are editing the machine-generated dhcpd.conf
+
+\#1155607 Conflict between "DNS zone name" in Cluster controller and "Default domain for new nodes" in settings
+
+\#1172336 MAAS server reference to AvahiBoot wiki page that does not exist
+
+\#1185160 no way to see what user has a node allocated
+
+\#1202314 Discrepancy between docs and behavior
+
+\#1206222 Documentation Feedback and Site suggestions
+
+\#1209039 Document that MAAS requires 'portfast' on switch ports connected to nodes
+
+\#1215750 No way of tracing/debugging http traffic content in the appserver.
+
+\#1223157 start\_commissioning needlessly sets owner on commissioning nodes
+
+\#1227081 Error in apache's log "No handlers could be found for logger "maasserver""
+
+\#1233069 maas-import-pxe-files fails when md5 checksums can't be downloaded
+
+\#1117415 maas dhcp responses do not have domain-name or domain-search
+
+\#1136449 maas-cli get-config and set-config documentation
+
+\#1175405 Pie chart says "deployed" which is inconsistent with the node list's "allocated"
+
+\#1233833 Usability: deleting nodes is too easy
+
+\#1185897 expose ability to re-commission node in api and cli
+
+\#997092 Can't delete allocated node even if owned by self
 
 
=== renamed file 'docs/cluster-configuration.rst' => 'docs/cluster-configuration.md'
--- docs/cluster-configuration.rst	2014-08-22 00:13:24 +0000
+++ docs/cluster-configuration.md	2015-04-17 21:06:27 +0000
@@ -1,146 +1,71 @@
-.. -*- mode: rst -*-
-
-.. _cluster-configuration:
-
 Cluster Configuration
 =====================
 
-Before any of MAAS's features can be used for the first time, you must have
-a cluster controller and configure it to manage at least one network of
-nodes.  Each node in the cluster should be attached to one of these networks.
-(In addition, a node can be attached to any number of networks that are not
-managed by MAAS.)
-
-Managing a network normally means that MAAS will serve DHCP from the cluster
-controller.  **Do this only on a network that was set up with this in mind.**
-Running your own DHCP server that competes with an existing one that's
-already managing the network can cause serious disruption, and it can be hard
-for administrators to track the source of the problem.  Worse, the problems
-may not become immediately noticeable.  Make sure you understand the
-implications of running a DHCP server before doing this.  If MAAS detects any
-DHCP servers already running on these networks, it will show them on the
-cluster's configuration page.
-
+Before any of MAAS's features can be used for the first time, you must have a cluster controller and configure it to manage at least one network of nodes. Each node in the cluster should be attached to one of these networks. (In addition, a node can be attached to any number of networks that are not managed by MAAS.)
+
+Managing a network normally means that MAAS will serve DHCP from the cluster controller. **Do this only on a network that was set up with this in mind.** Running your own DHCP server that competes with an existing one that's already managing the network can cause serious disruption, and it can be hard for administrators to track the source of the problem. Worse, the problems may not become immediately noticeable. Make sure you understand the implications of running a DHCP server before doing this. If MAAS detects any DHCP servers already running on these networks, it will show them on the cluster's configuration page.
 
 Network requirements
 --------------------
 
-The cluster controller manages a network of nodes through one of its interfaces
-as defined in MAAS.  Cluster interfaces are discovered automatically, though
-this may not happen e.g. if the network interface was down when MAAS was
-installed.
-
-When a cluster controller manages nodes on a network through one of its
-interfaces, the nodes must be on the same subnet as the cluster interface.
-This is for two reasons:
-
-1. If the cluster controller is configured to manage DHCP, the nodes must be
-   able to configure their own network interfaces using MAAS's DHCP server.
-   This means that either they must be on the same subnet, or that DHCP packets
-   are being specially routed between the nodes' subnet and MAAS's DHCP server.
-2. The cluster controller must be able to find nodes' IP addresses based on
-   their MAC addresses, by inspecting its ARP cache.  This implies that the
-   nodes and the cluster controller must be on the same physical subnet.
-
+The cluster controller manages a network of nodes through one of its interfaces as defined in MAAS. Cluster interfaces are discovered automatically, though this may not happen e.g. if the network interface was down when MAAS was installed.
+
+When a cluster controller manages nodes on a network through one of its interfaces, the nodes must be on the same subnet as the cluster interface. This is for two reasons:
+
+1.  If the cluster controller is configured to manage DHCP, the nodes must be able to configure their own network interfaces using MAAS's DHCP server. This means that either they must be on the same subnet, or that DHCP packets are being specially routed between the nodes' subnet and MAAS's DHCP server.
+2.  The cluster controller must be able to find nodes' IP addresses based on their MAC addresses, by inspecting its ARP cache. This implies that the nodes and the cluster controller must be on the same physical subnet.
 
 Cluster acceptance
 ------------------
 
-If you install your first cluster controller on the same system as the region
-controller, as is the case when you install the full "maas" ubuntu package,
-it will be automatically accepted by default (but not yet configured, see
-below).  Any other cluster controllers you set up will show up in the user
-interface as "pending," until you manually accept them into the MAAS.
-
-To accept a cluster controller, visit the "pending clusters" section of the
-Clusters page:
-
-.. image:: media/cluster-accept.png
-
-You can either click on "Accept all" or click on the edit icon to edit
-the cluster.  After clicking on the edit icon, you will see this page:
-
-.. image:: media/cluster-edit.png
-
-Here you can change the cluster's name as it appears in the UI, its DNS
-zone, and its status.  Accepting the cluster changes its status from
-"pending" to "accepted."
-
-Now that the cluster controller is accepted, you can configure one or more of
-its network interfaces to be managed by MAAS.  This will enable the cluster
-controller to manage nodes attached to those networks.  The next section
-explains how to do this and what choices are to be made.
-
+If you install your first cluster controller on the same system as the region controller, as is the case when you install the full "maas" ubuntu package, it will be automatically accepted by default (but not yet configured, see below). Any other cluster controllers you set up will show up in the user interface as "pending," until you manually accept them into the MAAS.
+
+To accept a cluster controller, visit the "pending clusters" section of the Clusters page:
+
+![image](media/cluster-accept.png)
+
+You can either click on "Accept all" or click on the edit icon to edit the cluster. After clicking on the edit icon, you will see this page:
+
+![image](media/cluster-edit.png)
+
+Here you can change the cluster's name as it appears in the UI, its DNS zone, and its status. Accepting the cluster changes its status from "pending" to "accepted."
+
+Now that the cluster controller is accepted, you can configure one or more of its network interfaces to be managed by MAAS. This will enable the cluster controller to manage nodes attached to those networks. The next section explains how to do this and what choices are to be made.
 
 Cluster interface management
 ----------------------------
 
-MAAS automatically recognises the network interfaces on each cluster
-controller.  Some (though not necessarily all) of these will be connected to
-networks where you want to manage nodes.  A connection between a cluster
-controller and a network is called a `cluster interface`.  Each cluster
-interface is built on exactly one network interface, though it's possible for
-two cluster interfaces to use the same network interface card.
-
-We recommend letting your cluster controller act as a DHCP server for the
-networks it manages, by configuring the corresponding cluster interfaces in
-the MAAS user interface.
-
-As an example, we will configure the cluster controller to manage a network
-on interface ``eth0``.  Click on the edit icon for the cluster interface on
-network interface ``eth0``, which takes us to this page:
-
-.. image:: media/cluster-interface-edit.png
-
-Here you can select to what extent you want the cluster controller to manage
-the network:
-
-#. DHCP only - this will run a DHCP server on your cluster
-#. DHCP and DNS - this will run a DHCP server on the cluster *and* configure
-   the DNS server included with the region controller so that it can be used
-   to look up hosts on this network by name.
-
-If you set the interface to be managed, you now need to provide all of the
-usual DHCP details in the input fields below.  Once done, click "Save
-interface". The cluster controller will now be able to boot nodes on this
-network.
-
-There is also an option to leave the network unmanaged.  Use this for
-networks where you don't want to manage any nodes.  Or, if you do want to
-manage nodes but don't want the cluster controller to serve DHCP, you may be
-able to get by without it.  This is explained in :ref:`manual-dhcp`.
-
-.. _static-ip-address:
-
-Static vs Dynamic IP Addresses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-On the cluster interface edit page, there are fields to enter both a dynamic
-and a static range of IP addresses.  It is mandatory to enter the dynamic range
-if you are managing DHCP on this interface, but the static range is optional.
-
-Dynamic addresses are given to both unknown devices booting on this network,
-and Nodes that are commissioning.  Dynamic addresses are allocated by the
-DHCP server and may change at any time.
-
-Static addresses are given to Nodes when they are allocated to a user and
-started up, and returned to the pool only when the Node is de-allocated.
-Static addresses are allocated by MAAS, and are guaranteed not to change while
-allocated.  If you are managing DNS on this network, only static IP addresses
-are given DNS entries with the Node's name.
-
-If you do not configure the static range, then nodes will only get dynamic
-IP addresses and will never get a DNS entry.
-
-IP addresses in the static range are also available for reservation by users
-using the :doc:`api`.  This prevents MAAS from allocating the reserved
-IP to any Nodes or other devices, which allows users to assign it freely
-to their own hosts/devices on the same network, such as LXC containers.
-
+MAAS automatically recognises the network interfaces on each cluster controller. Some (though not necessarily all) of these will be connected to networks where you want to manage nodes. A connection between a cluster controller and a network is called a cluster interface. Each cluster interface is built on exactly one network interface, though it's possible for two cluster interfaces to use the same network interface card.
+
+We recommend letting your cluster controller act as a DHCP server for the networks it manages, by configuring the corresponding cluster interfaces in the MAAS user interface.
+
+As an example, we will configure the cluster controller to manage a network on interface `eth0`. Click on the edit icon for the cluster interface on network interface `eth0`, which takes us to this page:
+
+![image](media/cluster-interface-edit.png)
+
+Here you can select to what extent you want the cluster controller to manage the network:
+
+1.  DHCP only - this will run a DHCP server on your cluster
+2.  DHCP and DNS - this will run a DHCP server on the cluster *and* configure the DNS server included with the region controller so that it can be used to look up hosts on this network by name.
+
+If you set the interface to be managed, you now need to provide all of the usual DHCP details in the input fields below. Once done, click "Save interface". The cluster controller will now be able to boot nodes on this network.
+
+There is also an option to leave the network unmanaged. Use this for networks where you don't want to manage any nodes. Or, if you do want to manage nodes but don't want the cluster controller to serve DHCP, you may be able to get by without it. This is explained in manual-dhcp.
+
+### Static vs Dynamic IP Addresses
+
+On the cluster interface edit page, there are fields to enter both a dynamic and a static range of IP addresses. It is mandatory to enter the dynamic range if you are managing DHCP on this interface, but the static range is optional.
+
+Dynamic addresses are given to both unknown devices booting on this network, and Nodes that are commissioning. Dynamic addresses are allocated by the DHCP server and may change at any time.
+
+Static addresses are given to Nodes when they are allocated to a user and started up, and returned to the pool only when the Node is de-allocated. Static addresses are allocated by MAAS, and are guaranteed not to change while allocated. If you are managing DNS on this network, only static IP addresses are given DNS entries with the Node's name.
+
+If you do not configure the static range, then nodes will only get dynamic IP addresses and will never get a DNS entry.
+
+IP addresses in the static range are also available for reservation by users using the api. This prevents MAAS from allocating the reserved IP to any Nodes or other devices, which allows users to assign it freely to their own hosts/devices on the same network, such as LXC containers.
 
 Multiple networks
 -----------------
 
-A single cluster controller can manage more than one network, each from a
-different cluster interface.  This may help you scale your cluster to larger
-numbers of nodes, or it may be a requirement of your network architecture.
+A single cluster controller can manage more than one network, each from a different cluster interface. This may help you scale your cluster to larger numbers of nodes, or it may be a requirement of your network architecture.
+
 
=== removed file 'docs/conf.py'
--- docs/conf.py	2015-03-25 13:22:48 +0000
+++ docs/conf.py	1970-01-01 00:00:00 +0000
@@ -1,305 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# MAAS documentation build configuration file, created by
-# sphinx-quickstart on Thu Jan 19 14:48:25 2012.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# Import maas' settings.
-from os import environ
-
-
-environ.setdefault("DJANGO_SETTINGS_MODULE", "maas.settings")
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-import sys, os
-# Include '.' in the path so that our custom extension, 'versions', can
-# be found.
-sys.path.insert(0, os.path.abspath('.'))
-
-# -- Multiple documentation options.
-
-# Add a widget to switch between different versions of the documentation to
-# each generated page.
-add_version_switcher = False
-
-# In order for the version widget to be able to redirect correctly to the
-# other versions of the documentation, each version of the documentation
-# has to be accessible at the following addresses:
-# /<doc_prefix>/ -> documentation for trunk.
-# /<doc_prefix>1.4/ ->  documentation for 1.4.
-# etc.
-doc_prefix = 'docs'
-
-# Path of the JSON document, relative to homepage of the documentation for trunk
-# (i.e. '/<doc_prefix>/'), with the list of the versions to include in the
-# version switcher widget.
-versions_path = '_static/versions.js'
-
-# Versions to include in the version switcher.
-# Note that the version switcher fetches the list of the documentation versions
-# from the list published by the trunk documentation (i.e. in '/<doc_prefix>/').
-# This means the following list is meaningful only for trunk.   
-# The first item should be the development version.
-from collections import OrderedDict
-doc_versions = OrderedDict([
-    ('dev', 'Development trunk'),
-    ('1.7', 'MAAS 1.7'),
-    ('1.6', 'MAAS 1.6'),
-    ('1.5', 'MAAS 1.5'),
-    ('1.4', 'MAAS 1.4'),
-    ('1.3', 'MAAS 1.3'),
-    ('1.2', 'MAAS 1.2'),
-])
-
-# -- General configuration -----------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.pngmath',
-    'sphinx.ext.viewcode',
-    'versions',
-    ]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'MAAS'
-copyright = u'2012-2014, MAAS Developers'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = doc_versions.items()[0][0]
-# The full version, including alpha/beta/rc tags.
-release = version
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['_build', '_templates']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# AutoDoc <http://sphinx.pocoo.org/ext/autodoc.html>
-autodoc_default_flags = ['members', 'show-inheritance']
-autodoc_member_order = 'bysource'
-autodoc_docstring_signature = True
-
-# AutoSummary <http://sphinx.pocoo.org/ext/autosummary.html>
-autosummary_generate = True
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'maas'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#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
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-html_logo = 'media/maas-logo-200.png'
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-html_favicon = 'media/maas.ico'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'MAASdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-latex_paper_size = 'a4'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-  ('index', 'MAAS.tex', u'MAAS Documentation',
-   u'MAAS Developers', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output --------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    ('man/maas.8', 'maas', u'MAAS API commandline utility',
-     [u'Canonical 2013-2014'], 8),
-    ('man/maas-region-admin.8', 'maas-region-admin', u'MAAS administration tool',
-     [u'Canonical 2013-2014'], 8)
-]
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
-
-# Gather information about the branch and the build date.
-from subprocess import check_output, CalledProcessError
-try:
-    bzr_last_revision_number = check_output(['bzr', 'revno'])
-    bzr_last_revision_date = check_output(['bzr', 'version-info', '--template={date}', '--custom'])
-    bzr_build_date = check_output(['bzr', 'version-info', '--template={build_date}', '--custom'])
-except (CalledProcessError):
-    # not a bzr repository
-    bzr_last_revision_number = 'unknown'
-    bzr_last_revision_date = check_output(['date', '-u', '+%Y-%m-%d %H:%M:%S %z'])
-    bzr_build_date = bzr_last_revision_date
-
-
-# Populate html_context with the variables used in the templates.
-html_context = {
-    'add_version_switcher': 'true' if add_version_switcher else 'false',
-    'versions_json_path': '/'.join(['', doc_prefix, versions_path]),
-    'doc_prefix': doc_prefix,
-    'bzr_last_revision_date': bzr_last_revision_date,
-    'bzr_last_revision_number': bzr_last_revision_number,
-    'bzr_build_date': bzr_build_date,
-}
 
=== renamed file 'docs/configure.rst' => 'docs/configure.md'
--- docs/configure.rst	2015-03-25 13:22:48 +0000
+++ docs/configure.md	2015-04-17 21:06:27 +0000
@@ -1,268 +1,175 @@
 Additional Configuration
 ========================
 
-
-.. _manual-dhcp:
-
 Manual DHCP configuration
 -------------------------
 
-DHCP is needed in order for MAAS to boot and control nodes.  However, there
-are some circumstances under which you may not wish a cluster controller to
-handle DHCP address assignments 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.
-
-.. note::
-  If you don't let MAAS manage DHCP, then MAAS will not be able to allocate
-  its :ref:`static IP addresses <static-ip-address>` to Nodes.
+DHCP is needed in order for MAAS to boot and control nodes. However, there are some circumstances under which you may not wish a cluster controller to handle DHCP address assignments 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.
+
+> **note**
+
+> If you don't let MAAS manage DHCP, then MAAS will not be able to allocate its static IP addresses \<static-ip-address\> to Nodes.
 
 At the very least the "filename" option should be set to "pxelinux.0".
 
-How to configure this depends on what software you use as a DHCP server.  If
-you are using the ISC DHCP server, for example, the configuration entry might
-look something like this::
-
-   subnet 192.168.122.0 netmask 255.255.255.0 {
-       filename "pxelinux.0";
-       option subnet-mask 255.255.255.0;
-       option broadcast-address 192.168.122.255;
-       option domain-name-servers 192.168.122.136;
-       range dynamic-bootp 192.168.122.5 192.168.122.135;
-   }
-
-When doing this, leave the cluster controller's interface in the "unmanaged"
-state.
-
-If your cluster controller is in charge of nodes on more than one network
-through different network interfaces, there is an additional complication.
-Without the DHCP server built into the cluster controller, MAAS may not
-know which of the cluster controller's IP addresses each node should use
-for downloading its installer image.  If you want to support this situation,
-ensure that all of the nodes can reach all of the cluster controller's
-network addresses.
-
-
-.. _ssl:
+How to configure this depends on what software you use as a DHCP server. If you are using the ISC DHCP server, for example, the configuration entry might look something like this:
+
+    subnet 192.168.122.0 netmask 255.255.255.0 {
+        filename "pxelinux.0";
+        option subnet-mask 255.255.255.0;
+        option broadcast-address 192.168.122.255;
+        option domain-name-servers 192.168.122.136;
+        range dynamic-bootp 192.168.122.5 192.168.122.135;
+    }
+
+When doing this, leave the cluster controller's interface in the "unmanaged" state.
+
+If your cluster controller is in charge of nodes on more than one network through different network interfaces, there is an additional complication. Without the DHCP server built into the cluster controller, MAAS may not know which of the cluster controller's IP addresses each node should use for downloading its installer image. If you want to support this situation, ensure that all of the nodes can reach all of the cluster controller's network addresses.
 
 SSL Support
 -----------
 
-If you want secure access to your MAAS web UI/API, you need to do a few
-things. First, turn on SSL support in Apache::
-
-  $ sudo a2enmod ssl
-
-Ensure that the Apache config file from ``etc/maas/maas-http.conf`` is
-included in ``/etc/apache2/conf.d/``, then edit
-``/etc/maas/maas_local_settings.py`` and change DEFAULT_MAAS_URL so that it
-uses https instead of http.
-
-Now, restart Apache::
-
-  $ sudo service apache2 restart
-
-At this point you will be able to access the MAAS web server using https but
-the default SSL certificate is insecure.  Please generate your own and then
-edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the
-certificate.
-
+If you want secure access to your MAAS web UI/API, you need to do a few things. First, turn on SSL support in Apache:
+
+    $ sudo a2enmod ssl
+
+Ensure that the Apache config file from `etc/maas/maas-http.conf` is included in `/etc/apache2/conf.d/`, then edit `/etc/maas/maas_local_settings.py` and change DEFAULT\_MAAS\_URL so that it uses https instead of http.
+
+Now, restart Apache:
+
+    $ sudo service apache2 restart
+
+At this point you will be able to access the MAAS web server using https but the default SSL certificate is insecure. Please generate your own and then edit `/etc/apache2/conf.d/maas-http.conf` to set the location of the certificate.
 
 Choosing a series to install
 ----------------------------
 
-You may have some specific reason to choose a particular version of Ubuntu
-to install on your nodes, perhaps based around package 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 command
-^^^^^^^^^^^^^^^^^^^^^^
-
-It is also possible to select a series using the maas command. This
-can be done on a per node basis with::
-
- $ maas <profile> node update <system_id> distro_series="<value>"
-
-Where the string contains one of the valid, available distro series (e.g.
-"trusty") or is empty for the default value.
-
-
-.. _preseed:
+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 command
+
+It is also possible to select a series using the maas command. This can be done on a per node basis with:
+
+    $ maas <profile> node update <system_id> distro_series="<value>"
+
+Where the string contains one of the valid, available distro series (e.g. "trusty") or is empty for the default value.
 
 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::
-
-  /etc/maas/preseeds/generic
-  /etc/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::
+> **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:
+
+    /etc/maas/preseeds/generic
+    /etc/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.
-
+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 import the distro image files locally for commissioning::
-
-  $ maas maas node-groups import-boot-images
+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 import the distro image files locally for commissioning:
+
+    $ maas maas node-groups import-boot-images
 
 …and optionally set up the DHCP and DNS for the cluster by either:
 
-*Using the web UI*
-  Follow the instructions at :doc:`cluster-configuration` to
-  use the web UI to set up your cluster controller.
-
-*Using the command line client*
-  First :ref:`logging in to the API <api-key>` and then
-  :ref:`following this procedure <cli-dhcp>`
-
+*Using the web UI*  
+Follow the instructions at cluster-configuration to use the web UI to set up your cluster controller.
+
+*Using the command line client*  
+First logging in to the API \<api-key\> and then following this procedure \<cli-dhcp\>
 
 Client-side DNS configuration
 -----------------------------
 
-When using a third party tool such as ``juju`` it will need to be able to
-resolve the hostnames that the MAAS API returns to it.  In order for this to
-happen, *client-side DNS* must be configured to point to MAAS's DNS
-server.  Generally speaking, this is a simple case of adding the following
-line to the ``/etc/resolv.conf`` file on your client host::
-
-  nameserver <IP OF MAAS DNS HOST>
-
-replacing the <IP OF MAAS DNS HOST> with the actual IP address of the host
-running the MAAS DNS server.
-
-However, for hosts using the ``resolvconf`` package, please read its
-documentation for more information.
+When using a third party tool such as `juju` it will need to be able to resolve the hostnames that the MAAS API returns to it. In order for this to happen, *client-side DNS* must be configured to point to MAAS's DNS server. Generally speaking, this is a simple case of adding the following line to the `/etc/resolv.conf` file on your client host:
+
+    nameserver <IP OF MAAS DNS HOST>
+
+replacing the \<IP OF MAAS DNS HOST\> with the actual IP address of the host running the MAAS DNS server.
+
+However, for hosts using the `resolvconf` package, please read its documentation for more information.
+
 
=== renamed file 'docs/development/building-packages.rst' => 'docs/development/building-packages.md'
--- docs/development/building-packages.rst	2014-02-26 16:56:23 +0000
+++ docs/development/building-packages.md	2015-04-17 21:06:27 +0000
@@ -1,76 +1,61 @@
 Building Ubuntu packages of MAAS
 ================================
 
-Using a virtual machine from a cloud provider seems to be easier and
-less hassle than using a local VM or LXC container, but the same
-recipe ought to apply.
-
-You need to build on the same OS that the package will be targeted to,
-so use a Precise instance to make packages for Precise, for example.
-
-#. Start up an instance, log in, and bring it up to date::
-
-     sudo apt-get update && sudo apt-get upgrade
-
-#. Get the appropriate packaging branch::
-
-     bzr branch lp:~maas-maintainers/maas/packaging{...}
-
-   The `MAAS Maintainers <https://launchpad.net/~maas-maintainers>`_
-   own all the `official MAAS branches`_.
-
-#. Move into the new branch directory.
-
-#. Check that all the build dependencies are installed. The
-   dependencies are defined in ``debian/control``::
-
-     fgrep -i build-depends -A 10 debian/control
-
-   This will yield, for example::
-
-     Build-Depends: debhelper (>= 8.1.0~),
-                    dh-apport,
-                    po-debconf,
-                    python (>= 2.7),
-                    python-distribute,
-                    python-django
-     Standards-Version: 3.9.3
-     ...
-
-   Install these dependencies::
-
-     sudo apt get install \
-         debhelper dh-apport po-debconf python \
-         python-distribute python-django
-
-#. Edit ``debian/changelog`` so it contains:
-
-   * the right upstream revision number in the version,
-
-   * the series you're building for; if ``UNRELEASED`` appears in the
-     first entry, ``s/UNRELEASED/trusty/`` (or the series you want),
-
-   * the name and email address that correspond to the PGP key you
-     want to use to sign the package; these appear near the end of the
-     topmost entry.
-
-#. Build::
-
-     bzr bd -S -- -uc -us
-
-   The latter options tell it not to sign the files. You need to do
-   this because the remote machine will not have your GPG key.
-
-#. Sign the build on your local machine::
-
-     debsign -r user@host '~/*.changes'
-
-   where ``user@host`` is an SSH string for accessing the remote
-   instance. This will scp the changes and dsc locally, sign them, and
-   put them back.
-
-#. On the remote instance you can optionally upload to a PPA::
-
-     dput -fu ppa:maas-maintainers/name-of-ppa *.changes
-
-.. _official MAAS branches: https://code.launchpad.net/~maas-maintainers
+Using a virtual machine from a cloud provider seems to be easier and less hassle than using a local VM or LXC container, but the same recipe ought to apply.
+
+You need to build on the same OS that the package will be targeted to, so use a Precise instance to make packages for Precise, for example.
+
+1.  Start up an instance, log in, and bring it up to date:
+
+        sudo apt-get update && sudo apt-get upgrade
+
+2.  Get the appropriate packaging branch:
+
+        bzr branch lp:~maas-maintainers/maas/packaging{...}
+
+    The [MAAS Maintainers](https://launchpad.net/~maas-maintainers) own all the [official MAAS branches](https://code.launchpad.net/~maas-maintainers).
+
+3.  Move into the new branch directory.
+4.  Check that all the build dependencies are installed. The dependencies are defined in `debian/control`:
+
+        fgrep -i build-depends -A 10 debian/control
+
+    This will yield, for example:
+
+        Build-Depends: debhelper (>= 8.1.0~),
+                       dh-apport,
+                       po-debconf,
+                       python (>= 2.7),
+                       python-distribute,
+                       python-django
+        Standards-Version: 3.9.3
+        ...
+
+    Install these dependencies:
+
+        sudo apt get install \
+            debhelper dh-apport po-debconf python \
+            python-distribute python-django
+
+5.  Edit `debian/changelog` so it contains:
+    -   the right upstream revision number in the version,
+    -   the series you're building for; if `UNRELEASED` appears in the first entry, `s/UNRELEASED/trusty/` (or the series you want),
+    -   the name and email address that correspond to the PGP key you want to use to sign the package; these appear near the end of the topmost entry.
+
+6.  Build:
+
+        bzr bd -S -- -uc -us
+
+    The latter options tell it not to sign the files. You need to do this because the remote machine will not have your GPG key.
+
+7.  Sign the build on your local machine:
+
+        debsign -r user@host '~/*.changes'
+
+    where `user@host` is an SSH string for accessing the remote instance. This will scp the changes and dsc locally, sign them, and put them back.
+
+8.  On the remote instance you can optionally upload to a PPA:
+
+        dput -fu ppa:maas-maintainers/name-of-ppa *.changes
+
+
 
=== renamed file 'docs/development/cluster-bootstrap.rst' => 'docs/development/cluster-bootstrap.md'
--- docs/development/cluster-bootstrap.rst	2015-01-14 16:24:44 +0000
+++ docs/development/cluster-bootstrap.md	2015-04-17 21:06:27 +0000
@@ -1,81 +1,49 @@
 Bootstrapping a cluster
 =======================
 
-
 Considerations
 --------------
 
-A new cluster needs to register itself with the region. At the same
-moment that it's accepted by the region, the region starts configuring
-it via RPC, so we need an RPC connection open when registering.
-
-Before a cluster is accepted, we want to restrict the available RPC
-calls to a small set, both on the region and the cluster.
-
-Before a cluster is accepted, we also do not want to start some services
-on the cluster, like lease uploads, DHCP scanning, and so forth, because
-the region will reject interaction from them.
-
+A new cluster needs to register itself with the region. At the same moment that it's accepted by the region, the region starts configuring it via RPC, so we need an RPC connection open when registering.
+
+Before a cluster is accepted, we want to restrict the available RPC calls to a small set, both on the region and the cluster.
+
+Before a cluster is accepted, we also do not want to start some services on the cluster, like lease uploads, DHCP scanning, and so forth, because the region will reject interaction from them.
 
 Start-up procedure
 ------------------
 
-This procedure will be followed by existing clusters and new clusters
-alike:
-
-#. Cluster starts.
-
-#. If shared secret not available, shutdown, **DONE**.
-
-#. ``ClusterClientService`` starts.
-
-#. Services other than ``log`` are **not** started.
-
-#. Wait for a connection to the region to become available.
-
-#. Do not allow any RPC calls other than ``Identify`` and ``Authenticate``.
-
-#. Call ``Identify``.
-
-#. Call ``Authenticate``.
-
-   - On success, continue.
-
-   - On failure, shutdown, **DONE**.
-
-#. Permit all other RPC calls.
-
-   - This allows for side-effects from calling ``Register`` next, like DHCP
-     configuration.
-
-#. Call ``Register``. Region accepts cluster.
-
-#. Start all services.
-
-#. **DONE**.
-
+This procedure will be followed by existing clusters and new clusters alike:
+
+1.  Cluster starts.
+2.  If shared secret not available, shutdown, **DONE**.
+3.  `ClusterClientService` starts.
+4.  Services other than `log` are **not** started.
+5.  Wait for a connection to the region to become available.
+6.  Do not allow any RPC calls other than `Identify` and `Authenticate`.
+7.  Call `Identify`.
+8.  Call `Authenticate`.
+    -   On success, continue.
+    -   On failure, shutdown, **DONE**.
+
+9.  Permit all other RPC calls.
+    -   This allows for side-effects from calling `Register` next, like DHCP configuration.
+
+10. Call `Register`. Region accepts cluster.
+11. Start all services.
+12. **DONE**.
 
 Work items
 ----------
 
-#. **DONE:** Add ``Authenticate`` RPC call.
-
-#. **DONE:** Add ``Register`` RPC call.
-
-#. **DONE:** Command-line to install shared-secret.
-
-#. **DONE:** Check for shared-secret during start-up (packaging change too?).
-
-#. **DONE:** Perform ``Authenticate`` handshake.
-
-#. **DONE:** Perform ``Register`` handshake.
-
-#. **DONE:** Pass MAAS_URL in ``Register`` call. This replicates functionality
-   found in ``update_nodegroup_maas_url``, which is no longer used.
-
-#. Display secret to admins in UI, or provide tool to obtain secret
-   locally on region controller's machine.
-
-#. Mechanism to limit available RPC calls.
-
-#. Mechanism to defer start-up of "full" services.
+1.  **DONE:** Add `Authenticate` RPC call.
+2.  **DONE:** Add `Register` RPC call.
+3.  **DONE:** Command-line to install shared-secret.
+4.  **DONE:** Check for shared-secret during start-up (packaging change too?).
+5.  **DONE:** Perform `Authenticate` handshake.
+6.  **DONE:** Perform `Register` handshake.
+7.  **DONE:** Pass MAAS\_URL in `Register` call. This replicates functionality found in `update_nodegroup_maas_url`, which is no longer used.
+8.  Display secret to admins in UI, or provide tool to obtain secret locally on region controller's machine.
+9.  Mechanism to limit available RPC calls.
+10. Mechanism to defer start-up of "full" services.
+
 
=== renamed file 'docs/development/cluster-registration.rst' => 'docs/development/cluster-registration.md'
--- docs/development/cluster-registration.rst	2015-02-19 21:49:54 +0000
+++ docs/development/cluster-registration.md	2015-04-17 21:06:27 +0000
@@ -1,72 +1,46 @@
-======================================
 How cluster registration works in MAAS
 ======================================
 
-A region controller associates with one or more cluster controllers, each
-of which is responsible for contacting the region controller itself and
-announcing its presence.  An admin must accept or reject each cluster that
-registers itself with the region controller, except in the special
-circumstance mentioned in :ref:`first-cluster`.
-
-There is always at least one cluster controller in MAAS (known as a
-NodeGroup in the code) which is known as the 'master'. The Nodegroup entry
-always exists even if no cluster controllers have contacted the region
-controller yet, so that it can be used as a default when adding nodes in the
-API or UI before the cluster controller is defined.  Once a real cluster
-controller connects it will become this master.
-
-This logic was originally implemented as an easy way to upgrade older
-installations that were created before nodegroups were introduced.
+A region controller associates with one or more cluster controllers, each of which is responsible for contacting the region controller itself and announcing its presence. An admin must accept or reject each cluster that registers itself with the region controller, except in the special circumstance mentioned in first-cluster.
+
+There is always at least one cluster controller in MAAS (known as a NodeGroup in the code) which is known as the 'master'. The Nodegroup entry always exists even if no cluster controllers have contacted the region controller yet, so that it can be used as a default when adding nodes in the API or UI before the cluster controller is defined. Once a real cluster controller connects it will become this master.
+
+This logic was originally implemented as an easy way to upgrade older installations that were created before nodegroups were introduced.
 
 Region Controller Location
 --------------------------
 
-The cluster obviously needs to know where the region controller is, and this is
-configured in a file ``/etc/maas/maas_cluster.conf`` (or
-``etc/demo_maas_cluster.conf`` for development environments).
+The cluster obviously needs to know where the region controller is, and this is configured in a file `/etc/maas/maas_cluster.conf` (or `etc/demo_maas_cluster.conf` for development environments).
 
 Cluster configuration file
 --------------------------
 
-This config file generally contains two items like this::
-
-  MAAS_URL=http://0.0.0.0:5240/
-  CLUSTER_UUID="adfd3977-f251-4f2c-8d61-745dbd690bf2"
-
-The values here are the defaults in the development environment.  MAAS_URL
-tells the cluster controller where to find the region controller.
-
-``CLUSTER_UUID`` is what the region uses to tell clusters apart when they
-connect.  Each cluster is free to generate its own UUID but the development
-environment fixes it in advance.  The Ubuntu packaging generates a new UUID for
-a cluster controller each time it is installed.
-
-.. warning::
-  The format of this config file is very sensitive due to the code that parses
-  it.  It will not accept quoting, or any kind of comments.
-
-.. _first-cluster:
+This config file generally contains two items like this:
+
+    MAAS_URL=http://0.0.0.0:5240/
+    CLUSTER_UUID="adfd3977-f251-4f2c-8d61-745dbd690bf2"
+
+The values here are the defaults in the development environment. MAAS\_URL tells the cluster controller where to find the region controller.
+
+`CLUSTER_UUID` is what the region uses to tell clusters apart when they connect. Each cluster is free to generate its own UUID but the development environment fixes it in advance. The Ubuntu packaging generates a new UUID for a cluster controller each time it is installed.
+
+> **warning**
+
+> The format of this config file is very sensitive due to the code that parses it. It will not accept quoting, or any kind of comments.
 
 First cluster to connect
 ------------------------
 
-For the convenience of small setups (and the development environment), the
-first cluster controller to connect to the region controller becomes the
-'master' nodegroup, and if the cluster connects *from the same host*, it
-is automatically accepted.
+For the convenience of small setups (and the development environment), the first cluster controller to connect to the region controller becomes the 'master' nodegroup, and if the cluster connects *from the same host*, it is automatically accepted.
 
 The logic currently looks like this:
 
-#. If there is one, the oldest nodegroup is the master.
-
-#. If none exists, the code creates a placeholder master nodegroup on the fly,
-   pre-accepted but without a UUID.
-
-#. If the placeholder is the only nodegroup, the first cluster controller to
-   register becomes the master.
-
-Sadly, there is some code complexity to clear up here as this logic is not
-encapsulated in a single place, but instead in both:
-
-* ``NodeGroup.objects.ensure_data()`` and
-* ``AnonNodeGroupsHandler.register()``.
+1.  If there is one, the oldest nodegroup is the master.
+2.  If none exists, the code creates a placeholder master nodegroup on the fly, pre-accepted but without a UUID.
+3.  If the placeholder is the only nodegroup, the first cluster controller to register becomes the master.
+
+Sadly, there is some code complexity to clear up here as this logic is not encapsulated in a single place, but instead in both:
+
+-   `NodeGroup.objects.ensure_data()` and
+-   `AnonNodeGroupsHandler.register()`.
+
 
=== renamed file 'docs/development/lease-scanning-and-dns.rst' => 'docs/development/lease-scanning-and-dns.md'
--- docs/development/lease-scanning-and-dns.rst	2014-11-14 22:03:20 +0000
+++ docs/development/lease-scanning-and-dns.md	2015-04-17 21:06:27 +0000
@@ -1,36 +1,24 @@
-.. -*- mode: rst -*-
-
-***************************
 DHCP lease scanning and DNS
-***************************
+===========================
 
 Overview
-========
-
-In a MAAS system, cluster controllers may optionally manage the DHCP, and the
-region controller may optionally manage the DNS.
-
-The region controller periodically tells the cluster controllers to report
-their DCHP leases.  When a cluster controller reports new leases, the region
-controller creates DNS records for them, and instructs the cluster controller
-to convert the leases to static host mappings.
-
+--------
+
+In a MAAS system, cluster controllers may optionally manage the DHCP, and the region controller may optionally manage the DNS.
+
+The region controller periodically tells the cluster controllers to report their DCHP leases. When a cluster controller reports new leases, the region controller creates DNS records for them, and instructs the cluster controller to convert the leases to static host mappings.
 
 Leases scanning
-===============
-
-MAAS will periodically scan the DHCP leases file using the
-``LeaseUploadService()`` pserv service.
-
-As leases are discovered, it calls the RPC function ``UpdateLeases`` which
-stores the active leases in the DHCPLease table.
-
+---------------
+
+MAAS will periodically scan the DHCP leases file using the `LeaseUploadService()` pserv service.
+
+As leases are discovered, it calls the RPC function `UpdateLeases` which stores the active leases in the DHCPLease table.
 
 Updating one or more DNS zone files
-===================================
-
-If a new lease is found then the dns.dns_update_zones() function gets called
-which takes two steps::
-
- #. Write out updated zone files.
- #. Ask BIND to reload the zone.
+-----------------------------------
+
+If a new lease is found then the dns.dns\_update\_zones() function gets called which takes two steps:
+
+    #. Write out updated zone files.
+    #. Ask BIND to reload the zone.
 
=== renamed file 'docs/development/metadata.rst' => 'docs/development/metadata.md'
--- docs/development/metadata.rst	2014-08-21 20:10:47 +0000
+++ docs/development/metadata.md	2015-04-17 21:06:27 +0000
@@ -1,127 +1,71 @@
 The Metadata API
 ================
 
-A MAAS region controller provides a separate API (the metadata API) for the
-benefit of the nodes themselves.  This is where a node obtains the details of
-how it should be set up, such as which SSH keys should be installed in order to
-give a particular user remote access to the system.
-
-As a MAAS user or administrator, you do not need to request this information
-yourself.  It is normally up to ``cloud-init`` to do this while setting up the
-node.  You'll find more about how this works in cloud-init's datasources_
-documentation.
-
-.. _datasources: http://cloudinit.readthedocs.org/en/latest/topics/datasources.html
-
+A MAAS region controller provides a separate API (the metadata API) for the benefit of the nodes themselves. This is where a node obtains the details of how it should be set up, such as which SSH keys should be installed in order to give a particular user remote access to the system.
+
+As a MAAS user or administrator, you do not need to request this information yourself. It is normally up to `cloud-init` to do this while setting up the node. You'll find more about how this works in cloud-init's [datasources](http://cloudinit.readthedocs.org/en/latest/topics/datasources.html) documentation.
 
 Similarity to EC2
 -----------------
 
-The metadata API is very similar, and partly identical, to the EC2 metadata
-service.  It follows a similar directory structure and provides several items
-in the same formats.  For example, in order to find out its own host name, a
-node would perform an http GET request for::
-
-  /2012-03-01/meta-data/local-hostname
-
-The first item in the path is the API version.  The API has been extended since
-March 2012, but not changed incompatibly and so that date is still the current
-version number.
-
-The items following that form a directory hierarchy based on that of the EC2
-metadata service.  The metadata service "knows" which node makes the request,
-and so there is no need for the request URL to identify the node whose hostname
-should be retrieved.  The request automatically returns the hostname for the
-node which requested it.
-
-Just like EC2, the MAAS metadata API will accept GET requests to::
-
-  /
-  /2012-03-01/
-  /2012-03-01/meta-data/
-  /2012-03-01/meta-data/instance-id
-  /2012-03-01/meta-data/local-hostname
-  /2012-03-01/meta-data/public-keys
-  /2012-03-01/user-data
-
-Hopefully their meanings are fairly obvious.  The ``public-keys`` will contain
-the user's SSH keys.
-
-MAAS adds a tarball of scripts that a node should run during its commissioning
-phase::
-
-  /2012-03-01/meta-data/maas-commissioning-scripts
-
-There are other differences.  Where EC2 makes the metadata service available at
-a fixed IP address, MAAS configures the location of the metadata service on the
-node while installing its operating system.  It does this through installation
-:ref:`preseeds <preseeds>`.  These preseeds also include the node's access
-credentials.
-
+The metadata API is very similar, and partly identical, to the EC2 metadata service. It follows a similar directory structure and provides several items in the same formats. For example, in order to find out its own host name, a node would perform an http GET request for:
+
+    /2012-03-01/meta-data/local-hostname
+
+The first item in the path is the API version. The API has been extended since March 2012, but not changed incompatibly and so that date is still the current version number.
+
+The items following that form a directory hierarchy based on that of the EC2 metadata service. The metadata service "knows" which node makes the request, and so there is no need for the request URL to identify the node whose hostname should be retrieved. The request automatically returns the hostname for the node which requested it.
+
+Just like EC2, the MAAS metadata API will accept GET requests to:
+
+    /
+    /2012-03-01/
+    /2012-03-01/meta-data/
+    /2012-03-01/meta-data/instance-id
+    /2012-03-01/meta-data/local-hostname
+    /2012-03-01/meta-data/public-keys
+    /2012-03-01/user-data
+
+Hopefully their meanings are fairly obvious. The `public-keys` will contain the user's SSH keys.
+
+MAAS adds a tarball of scripts that a node should run during its commissioning phase:
+
+    /2012-03-01/meta-data/maas-commissioning-scripts
+
+There are other differences. Where EC2 makes the metadata service available at a fixed IP address, MAAS configures the location of the metadata service on the node while installing its operating system. It does this through installation preseeds \<preseeds\>. These preseeds also include the node's access credentials.
 
 Additional Directory Trees
 --------------------------
 
-.. _enlistment-tree:
-
-MAAS adds some entirely new directories as well.  An enlisting node
-(which does not have access credentials for the metadata API yet) can
-anonymously request the same items for itself under ``/enlist/``, e.g.::
-
-  /enlist/2012-03-01/meta-data/local-hostname
-
-If you set the ``ALLOW_UNSAFE_METADATA_ACCESS`` configuration item, the
-metadata service will also provide the information on arbitrary nodes to
-authenticated users under a separate sub-tree.  For security reasons this is
-not recommended, but it may be useful in debugging.  With this option enabled,
-the information for the node with MAC address 99:99:99:99:99:99 is available
-at::
-
-  /2012-03-01/by-mac/99:99:99:99:99:99/meta-data/local-hostname
-
-And so on for the other information.  There is a similar facility keyed by
-MAAS system identifiers.
-
-.. _curtin-tree:
-
-Finally, a curtin-specific metadata API with largely the same information lives
-in the ``/curtin/`` subtree::
-
-  /curtin/2012-03-01/meta-data/local-hostname
-
-The curtin subtree however differs in the ``user-data`` endpoint.  It returns a
-curtin-specific form of user data.
-
+MAAS adds some entirely new directories as well. An enlisting node (which does not have access credentials for the metadata API yet) can anonymously request the same items for itself under `/enlist/`, e.g.:
+
+    /enlist/2012-03-01/meta-data/local-hostname
+
+If you set the `ALLOW_UNSAFE_METADATA_ACCESS` configuration item, the metadata service will also provide the information on arbitrary nodes to authenticated users under a separate sub-tree. For security reasons this is not recommended, but it may be useful in debugging. With this option enabled, the information for the node with MAC address 99:99:99:99:99:99 is available at:
+
+    /2012-03-01/by-mac/99:99:99:99:99:99/meta-data/local-hostname
+
+And so on for the other information. There is a similar facility keyed by MAAS system identifiers.
+
+Finally, a curtin-specific metadata API with largely the same information lives in the `/curtin/` subtree:
+
+    /curtin/2012-03-01/meta-data/local-hostname
+
+The curtin subtree however differs in the `user-data` endpoint. It returns a curtin-specific form of user data.
 
 Authentication
 --------------
 
-Most metadata requests are authenticated similar to ones to the
-region-controller API, through OAuth.  Every node in a MAAS has its own OAuth
-key.  (On the region controller side, these keys collectively belong to a
-single special user called ``node-init``.  You will not see such special users
-listed in the UI, however.)  When a node asks for information about itself, the
-OAuth key is what tells the metadata service which node that is.
-
-Not all requests are authenticated in this way.  For instance, a node can
-access the items under the enlistment subdirectory (see
-:ref:`above <enlistment-tree>`) anonymously.  The metadata service will
-identify the requesting node by its IP address.
-
+Most metadata requests are authenticated similar to ones to the region-controller API, through OAuth. Every node in a MAAS has its own OAuth key. (On the region controller side, these keys collectively belong to a single special user called `node-init`. You will not see such special users listed in the UI, however.) When a node asks for information about itself, the OAuth key is what tells the metadata service which node that is.
+
+Not all requests are authenticated in this way. For instance, a node can access the items under the enlistment subdirectory (see above \<enlistment-tree\>) anonymously. The metadata service will identify the requesting node by its IP address.
 
 API Operations
 --------------
 
-The MAAS metadata API supports a few non-GET operations.  These work just like
-the ones on the main :ref:`region-controller API <region-controller-api>`, but they are meant to be invoked by
-nodes.  The URL for these calls is ``/2013-03-01/``, and the operation name is
-passed as a multipart form item called "op".  Other parameters are passed in
-the same way.
-
-The ``signal`` call notifies the region controller of the state of a
-commissioning node.  The node sends running updates, as well as output produced
-by the commissioning scripts, and finally completion information through this
-call.
-
-When a node is done installing, it may call POST operations ``netboot_on`` and
-``netboot_off`` to instruct MAAS to enable or disable its network boot setting.
+The MAAS metadata API supports a few non-GET operations. These work just like the ones on the main region-controller API \<region-controller-api\>, but they are meant to be invoked by nodes. The URL for these calls is `/2013-03-01/`, and the operation name is passed as a multipart form item called "op". Other parameters are passed in the same way.
+
+The `signal` call notifies the region controller of the state of a commissioning node. The node sends running updates, as well as output produced by the commissioning scripts, and finally completion information through this call.
+
+When a node is done installing, it may call POST operations `netboot_on` and `netboot_off` to instruct MAAS to enable or disable its network boot setting.
+
 
=== renamed file 'docs/development/philosophy.rst' => 'docs/development/philosophy.md'
--- docs/development/philosophy.rst	2013-12-06 15:12:09 +0000
+++ docs/development/philosophy.md	2015-04-17 21:06:27 +0000
@@ -1,51 +1,25 @@
-------------------
 Philosophy of MAAS
-------------------
-
-This is a declaration of what we’re aiming for while designing and
-developing MAAS. We may fall short in many regards right now, but this
-is where we’re heading. Each fix, enhancement, and feature is
-conceived and built with these principles in mind.
-
-It is concise and to the point. If in doubt about including something,
-don’t, or talk about it first. Think of it as a reference point for
-the core development team, as well as a starting point for external
-contributors.
-
+==================
+
+This is a declaration of what we’re aiming for while designing and developing MAAS. We may fall short in many regards right now, but this is where we’re heading. Each fix, enhancement, and feature is conceived and built with these principles in mind.
+
+It is concise and to the point. If in doubt about including something, don’t, or talk about it first. Think of it as a reference point for the core development team, as well as a starting point for external contributors.
 
 Feedback loops
 --------------
 
-When MAAS modifies an external system there should be a feedback loop
-so it can know the actual state of the external system, take periodic
-or continuous action to converge the external system towards its
-notion of truth, and notice when there are problems influencing the
-external system.
-
-For example, when sending out a command to boot a machine from the
-network, MAAS should know that (a) the machine has actually powered
-on, and (b) that it has obtained boot instructions from the TFTP
-server.
-
+When MAAS modifies an external system there should be a feedback loop so it can know the actual state of the external system, take periodic or continuous action to converge the external system towards its notion of truth, and notice when there are problems influencing the external system.
+
+For example, when sending out a command to boot a machine from the network, MAAS should know that (a) the machine has actually powered on, and (b) that it has obtained boot instructions from the TFTP server.
 
 UI
----
+--
 
-It should be possible to decompose all operations in the UI down to
-API calls.
+It should be possible to decompose all operations in the UI down to API calls.
 
 The UI need not have the same granularity as the API.
 
-The UI should never do something that is not possible in the API
-unless it is entirely specific to its medium (i.e. HTTP + browser).
-
-Addendum: though the UI should be decomposable down to API calls, it
-does not need to be implemented as such (even though it would be great
-if it was).
-
-
-.. TODO
-   ----
-   Security
-   Persistence
-   Testing
+The UI should never do something that is not possible in the API unless it is entirely specific to its medium (i.e. HTTP + browser).
+
+Addendum: though the UI should be decomposable down to API calls, it does not need to be implemented as such (even though it would be great if it was).
+
 
=== renamed file 'docs/development/preseeds.rst' => 'docs/development/preseeds.md'
--- docs/development/preseeds.rst	2015-04-03 11:36:37 +0000
+++ docs/development/preseeds.md	2015-04-17 21:06:27 +0000
@@ -1,71 +1,55 @@
-.. _preseeds:
-
-=========================
 How preseeds work in MAAS
 =========================
 
-A preseed is what MAAS sends to the ``cloud-init`` process that starts up
-as part of node enlistment, commissioning and installation.  It is a
-specially formatted chunk of text.  MAAS does not care what that formatting
-is, it just knows it is text and uses Tempita_ templates to render a final
-file based on variables that are required depending on the context.
-
-.. _Tempita: http://pythonpaste.org/tempita/
-
+A preseed is what MAAS sends to the `cloud-init` process that starts up as part of node enlistment, commissioning and installation. It is a specially formatted chunk of text. MAAS does not care what that formatting is, it just knows it is text and uses [Tempita](http://pythonpaste.org/tempita/) templates to render a final file based on variables that are required depending on the context.
 
 Preseed templates
 -----------------
 
-On a live system, the preseed templates live in ``/etc/maas/preseeds/``.
+On a live system, the preseed templates live in `/etc/maas/preseeds/`.
 
 Each template uses a prefix that corresponds to a particular "phase":
 
-+---------------+--------------------------+
-| Phase         | Prefix used              |
-+===============+==========================+
-| Enlistment    | enlist                   |
-+---------------+--------------------------+
-| Commissioning | commissioning            |
-+---------------+--------------------------+
-| Installation  | preseed_master (DI_) or  |
-|               | curtin (Curtin_)         |
-+---------------+--------------------------+
-
-.. _DI: https://www.debian.org/devel/debian-installer/
-
-.. _Curtin: https://launchpad.net/curtin
-
-Note that the preseed information is in fact composed of two files: the
-preseed file per se which usually contains little more than a URL and the
-credentials where to get the "user data" which, in turn, contains most of
-the logic to be executed.
+<table>
+<colgroup>
+<col width="22%" />
+<col width="37%" />
+</colgroup>
+<thead>
+<tr class="header">
+<th align="left">Phase</th>
+<th align="left">Prefix used</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td align="left">Enlistment</td>
+<td align="left">enlist</td>
+</tr>
+<tr class="even">
+<td align="left">Commissioning</td>
+<td align="left">commissioning</td>
+</tr>
+<tr class="odd">
+<td align="left">Installation</td>
+<td align="left">preseed_master (<a href="https://www.debian.org/devel/debian-installer/">DI</a>) or curtin (<a href="https://launchpad.net/curtin">Curtin</a>)</td>
+</tr>
+</tbody>
+</table>
+
+Note that the preseed information is in fact composed of two files: the preseed file per se which usually contains little more than a URL and the credentials where to get the "user data" which, in turn, contains most of the logic to be executed.
 
 Installation preseed
 --------------------
 
-The installation preseed is broken into the three files because the
-requirements are different depending on the installer being used.  The
-`Debian Installer`_ uses ``preseed_master`` and the newer Curtin_ installer
-uses ``curtin_userdata``.
-
-.. _Debian Installer: https://www.debian.org/devel/debian-installer/
-
-.. _Curtin: https://launchpad.net/curtin
-
-The base of both of these is ``generic``, which defines some variables
-and then selects the right one depending on the installer being used.  Note
-that Tempita's inheritance mechanism is a little weird; the ``generic``
-template inherits the right file but in effect this is in reverse, the
-inherited file becomes the new template and it can then reference the
-variables defined in ``generic``.
-
+The installation preseed is broken into the three files because the requirements are different depending on the installer being used. The [Debian Installer](https://www.debian.org/devel/debian-installer/) uses `preseed_master` and the newer [Curtin](https://launchpad.net/curtin) installer uses `curtin_userdata`.
+
+The base of both of these is `generic`, which defines some variables and then selects the right one depending on the installer being used. Note that Tempita's inheritance mechanism is a little weird; the `generic` template inherits the right file but in effect this is in reverse, the inherited file becomes the new template and it can then reference the variables defined in `generic`.
 
 User-provided preseeds
 ----------------------
 
-In addition to the standard preseed files, the base preseeds can be
-overridden on a per-OS, architecture, subarchitecture, OS release and
-node name basis. The templates are looked up in the following order::
+In addition to the standard preseed files, the base preseeds can be overridden on a per-OS, architecture, subarchitecture, OS release and node name basis. The templates are looked up in the following order:
 
     {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}_{node_name}
     {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}
@@ -90,60 +74,34 @@
     {prefix}
     'generic'
 
-``prefix`` is either empty (in which case the following underscore is also
-ommitted: e.g. {osystem}_{node_arch}_{node_subarch}_{release}) or one of
-``enlist``, ``enlist_userdata``, ``commissioning``, ``curtin``,
-``curtin_userdata`` or ``preseed_master``.
-
-As you can see this mechanism is also used to calculate the base preseeds for
-all of installation, enlistment and commissioning.  It allows end users to
-add, for example, a file named ``curtin_ubuntu_amd64_generic`` that would be
-used at installation time.
-
+`prefix` is either empty (in which case the following underscore is also ommitted: e.g. {osystem}\_{node\_arch}\_{node\_subarch}\_{release}) or one of `enlist`, `enlist_userdata`, `commissioning`, `curtin`, `curtin_userdata` or `preseed_master`.
+
+As you can see this mechanism is also used to calculate the base preseeds for all of installation, enlistment and commissioning. It allows end users to add, for example, a file named `curtin_ubuntu_amd64_generic` that would be used at installation time.
 
 Curtin configuration
 --------------------
 
-Curtin_ is the tool responsible for performing the OS installation.  If you
-need to customize the installation, you need to change Curtin's user data
-(by either changing the existing ``curtin_userdata`` file or adding a custom
-version as described above).
-
-.. _Curtin: https://launchpad.net/curtin
-
-There isn't a complete documentation on how to customize Curtin at the time of
-this writing but the following instructions and examples should cover most of
-the use cases.
-
-Curtin provides hooks to execute custom code before (`early`) or after (`late`)
-the installation takes place.  You can override these hooks to execute code,
-either code that will run in the ephemeral environment or in the machine being
-installed itself (`in-target`).  Note that you can execute `in-target` code
-only in a `late` command.
-
-Example: early command
-======================
-
-Here is an example of an early command (i.e. one that will run before the
-installation takes place) that runs in the ephemeral environment and
-pings an external machine to signal that the installation is about to start.
-
-.. code:: yaml
-
-  early_commands:
-    signal: [wget, '--no-proxy', 'http://example.com/', '--post-data', 'system_id={{node.system_id}}&signal=starting_install', '-O', '/dev/null']
-
-Example: late command
-======================
-
-Here is an example of two late commands (i.e. commands that will run after the
-installation has been performed).  Both run `in-target` (i.e. in the machine
-being installed).  The first command adds a PPA to the machine.  The second
-command create a file containing the node's system_id.  (Note that these are
-just examples of the things that can be done.)
-
-.. code:: yaml
-
-  late_commands:
-    add_repo: ["curtin", "in-target", "--", "add-apt-repository", "-y", "ppa:my/ppa"]
-    custom: curtin in-target -- sh -c "/bin/echo -en 'Installed {{node.system_id}}' > /tmp/maas_system_id"
+[Curtin](https://launchpad.net/curtin) is the tool responsible for performing the OS installation. If you need to customize the installation, you need to change Curtin's user data (by either changing the existing `curtin_userdata` file or adding a custom version as described above).
+
+There isn't a complete documentation on how to customize Curtin at the time of this writing but the following instructions and examples should cover most of the use cases.
+
+Curtin provides hooks to execute custom code before (early) or after (late) the installation takes place. You can override these hooks to execute code, either code that will run in the ephemeral environment or in the machine being installed itself (in-target). Note that you can execute in-target code only in a late command.
+
+### Example: early command
+
+Here is an example of an early command (i.e. one that will run before the installation takes place) that runs in the ephemeral environment and pings an external machine to signal that the installation is about to start.
+
+``` {.sourceCode .yaml}
+early_commands:
+  signal: [wget, '--no-proxy', 'http://example.com/', '--post-data', 'system_id={{node.system_id}}&signal=starting_install', '-O', '/dev/null']
+```
+
+### Example: late command
+
+Here is an example of two late commands (i.e. commands that will run after the installation has been performed). Both run in-target (i.e. in the machine being installed). The first command adds a PPA to the machine. The second command create a file containing the node's system\_id. (Note that these are just examples of the things that can be done.)
+
+``` {.sourceCode .yaml}
+late_commands:
+  add_repo: ["curtin", "in-target", "--", "add-apt-repository", "-y", "ppa:my/ppa"]
+  custom: curtin in-target -- sh -c "/bin/echo -en 'Installed {{node.system_id}}' > /tmp/maas_system_id"
+```
 
=== renamed file 'docs/development/rpc.rst' => 'docs/development/rpc.md'
--- docs/development/rpc.rst	2014-08-21 20:10:47 +0000
+++ docs/development/rpc.md	2015-04-17 21:06:27 +0000
@@ -1,181 +1,105 @@
-.. -*- mode: rst -*-
-
 RPC HOWTO
 =========
 
-MAAS contains an RPC mechanism such that every process in the region is
-connected to every process in the cluster (strictly, every pserv
-process). It's based on AMP_, specifically `Twisted's implementation`_.
-
-.. _AMP:
-  http://amp-protocol.net/
-
-.. _Twisted's implementation:
-  http://twistedmatrix.com/documents/current/core/howto/amp.html
-
+MAAS contains an RPC mechanism such that every process in the region is connected to every process in the cluster (strictly, every pserv process). It's based on [AMP](http://amp-protocol.net/), specifically [Twisted's implementation](http://twistedmatrix.com/documents/current/core/howto/amp.html).
 
 Where do I start?
 -----------------
 
-Start in the :py:mod:`provisioningserver.rpc` package. The first two files to
-look at are ``cluster.py`` and ``region.py``. This contain the
-declarations of what commands are available on clusters and regions
-respectively.
-
-A new command could be declared like so::
-
-  from twisted.protocols import amp
-
-  class EatCheez(amp.Command):
-      arguments = [
-          (b"name", amp.Unicode()),
-          (b"origin", amp.Unicode()),
-      ]
-      response = [
-          (b"rating", amp.Integer()),
-      ]
-
-It's also possible to map exceptions across the wire using an ``errors``
-attribute; see the docs or code for more information.
-
-Note that byte-strings are used for parameter names. Twisted gets quite
-fussy about this, so remember to do it.