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

Proposed by Gavin Panella
Status: Rejected
Rejected by: MAAS Lander
Proposed branch: lp:~allenap/maas/markdownify
Merge into: lp:maas/trunk
Diff against target: 13972 lines (+4839/-7644)
84 files modified
.bzrignore (+0/-3)
.gitignore (+0/-3)
Makefile (+14/-31)
buildout.cfg (+0/-17)
docs/_static/versions.js (+0/-91)
docs/_templates/maas/layout.html (+0/-31)
docs/_templates/maas/localtoc.html (+0/-3)
docs/_templates/maas/relations.html (+0/-31)
docs/_templates/maas/static/css/main.css (+0/-75)
docs/_templates/maas/static/flasky.css_t (+0/-564)
docs/_templates/maas/theme.conf (+0/-6)
docs/about.md (+6/-39)
docs/api_authentication.md (+49/-63)
docs/bootsources.md (+12/-28)
docs/capabilities.md (+16/-34)
docs/changelog.md (+665/-1101)
docs/cluster-configuration.md (+52/-127)
docs/conf.py (+0/-305)
docs/configure.md (+137/-230)
docs/development/building-packages.md (+58/-73)
docs/development/cluster-bootstrap.md (+35/-67)
docs/development/cluster-registration.md (+28/-54)
docs/development/lease-scanning-and-dns.md (+17/-29)
docs/development/metadata.md (+52/-108)
docs/development/philosophy.md (+14/-40)
docs/development/preseeds.md (+61/-103)
docs/development/rpc.md (+74/-150)
docs/development/security.md (+11/-36)
docs/development/tagging.md (+42/-78)
docs/development/transactions.md (+36/-82)
docs/enum.md (+0/-17)
docs/getting-help.md (+24/-35)
docs/hacking.md (+164/-343)
docs/hardware-enablement-kernels.md (+25/-55)
docs/index.md (+32/-138)
docs/install.md (+147/-282)
docs/installing-ubuntu.md (+32/-63)
docs/ipv6.md (+57/-132)
docs/juju-quick-start.md (+90/-131)
docs/kernel-options.md (+18/-24)
docs/maascli.md (+427/-583)
docs/man/maas-region-admin.8.md (+21/-32)
docs/man/maas.8.md (+404/-538)
docs/models.md (+0/-17)
docs/networks.md (+69/-164)
docs/nodes.md (+28/-58)
docs/orientation.md (+42/-89)
docs/physical-zones.md (+46/-113)
docs/plugins/gfm/LICENSE (+24/-0)
docs/plugins/gfm/README.md (+6/-0)
docs/plugins/gfm/gfm/__init__.py (+17/-0)
docs/plugins/gfm/gfm/autolink.py (+44/-0)
docs/plugins/gfm/gfm/automail.py (+24/-0)
docs/plugins/gfm/gfm/hidden_hilite.py (+16/-0)
docs/plugins/gfm/gfm/semi_sane_lists.py (+30/-0)
docs/plugins/gfm/gfm/spaced_link.py (+41/-0)
docs/plugins/gfm/gfm/strikethrough.py (+17/-0)
docs/plugins/gfm/mdx_gfm/__init__.py (+28/-0)
docs/plugins/gfm/mdx_partial_gfm/__init__.py (+44/-0)
docs/plugins/gfm/test.py (+31/-0)
docs/plugins/gfm/tests/test_autolink.py (+46/-0)
docs/plugins/gfm/tests/test_automail.py (+32/-0)
docs/plugins/gfm/tests/test_case.py (+29/-0)
docs/plugins/gfm/tests/test_gfm.py (+111/-0)
docs/plugins/gfm/tests/test_hidden_hilite.py (+49/-0)
docs/plugins/gfm/tests/test_semi_sane_lists.py (+40/-0)
docs/plugins/gfm/tests/test_spaced_link.py (+147/-0)
docs/plugins/gfm/tests/test_strikethrough.py (+39/-0)
docs/plugins/mdx_anchors_away/__init__.py (+37/-0)
docs/plugins/mdx_callouts/__init__.py (+42/-0)
docs/plugins/mdx_foldouts/__init__.py (+54/-0)
docs/sstreams-mirror.md (+26/-42)
docs/static-ips.md (+28/-44)
docs/tags.md (+53/-102)
docs/troubleshooting.md (+111/-173)
docs/versions.py (+0/-47)
man/maas-region-admin.8 (+43/-70)
man/maas.8 (+571/-699)
required-packages/doc (+2/-3)
schema/README.md (+13/-31)
setup.py (+0/-4)
utilities/convert-rst-docs-to-markdown (+22/-0)
utilities/doc-lint (+17/-6)
versions.cfg (+0/-7)
To merge this branch: bzr merge lp:~allenap/maas/markdownify
Reviewer Review Type Date Requested Status
MAAS Maintainers Pending
Review via email: mp+256718@code.launchpad.net

Description of the change

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.

To post a comment you must log in.
Revision history for this message
MAAS Lander (maas-lander) wrote :

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

Remove remaining Sphinx machinery.

3841. By Gavin Panella

Include the rst-to-md convertion script.

3840. By Gavin Panella

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

3839. By Gavin Panella

Undo 1st conversion of docs.

3838. By Gavin Panella

Undo 2nd conversion of docs.

3837. By Gavin Panella

Render docs into HTML.

3836. By Gavin Panella

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

3835. By Gavin Panella

Update Makefile.

3834. By Gavin Panella

Update rendered man pages.

3833. By Gavin Panella

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

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file '.bzrignore'
2--- .bzrignore 2015-03-25 20:32:06 +0000
3+++ .bzrignore 2015-04-17 21:06:27 +0000
4@@ -19,15 +19,12 @@
5 ./db
6 ./develop-eggs
7 ./dist
8-./docs/_autosummary
9-./docs/_build
10 ./docs/api.rst
11 ./eggs
12 ./include
13 ./lib
14 ./local
15 ./logs/*
16-./man/.doctrees
17 ./media/demo/*
18 ./media/development
19 ./parts
20
21=== modified file '.gitignore'
22--- .gitignore 2015-03-23 15:15:54 +0000
23+++ .gitignore 2015-04-17 21:06:27 +0000
24@@ -19,15 +19,12 @@
25 /db
26 /develop-eggs
27 /dist
28-/docs/_autosummary
29-/docs/_build
30 /docs/api.rst
31 /eggs
32 /include
33 /lib
34 /local
35 /logs/*
36-/man/.doctrees
37 /media/demo/*
38 /media/development
39 /parts
40
41=== modified symlink 'CHANGELOG'
42=== target changed u'docs/changelog.rst' => u'docs/changelog.md'
43=== added symlink 'HACKING'
44=== target is u'docs/hacking.md'
45=== added symlink 'INSTALL'
46=== target is u'docs/install.md'
47=== modified file 'Makefile'
48--- Makefile 2015-04-16 11:51:27 +0000
49+++ Makefile 2015-04-17 21:06:27 +0000
50@@ -141,14 +141,6 @@
51 $(buildout) install flake8
52 @touch --no-create $@
53
54-bin/rst-lint: bin/buildout buildout.cfg versions.cfg setup.py
55- $(buildout) install rst-lint
56- @touch --no-create $@
57-
58-bin/sphinx bin/sphinx-build: bin/buildout buildout.cfg versions.cfg setup.py
59- $(buildout) install sphinx
60- @touch --no-create $@
61-
62 bin/py bin/ipy: bin/buildout buildout.cfg versions.cfg setup.py
63 $(buildout) install repl
64 @touch --no-create bin/py bin/ipy
65@@ -206,7 +198,7 @@
66 @$(error Use `$(MAKE) test` to generate coverage data, or invoke a \
67 test script using the `--with-coverage` flag)
68
69-lint: lint-py lint-js lint-doc lint-rst
70+lint: lint-py lint-js lint-doc
71
72 pocketlint = $(call available,pocketlint,python-pocket-lint)
73
74@@ -230,16 +222,6 @@
75 lint-doc:
76 @utilities/doc-lint
77
78-# lint-rst 0.11.1 shouldn't be used on our documentation because it
79-# doesn't understand Sphinx's extensions, and doesn't grok linking
80-# between documents, hence complaints about broken links. However,
81-# Sphinx itself warns about lint when building the docs.
82-lint-rst: sources = README HACKING.txt schema/README.rst
83-lint-rst: bin/rst-lint
84- @find $(sources) -type f \
85- -printf 'Linting %p...\n' \
86- -exec bin/rst-lint --encoding=utf8 {} \;
87-
88 # JavaScript lint is checked in parallel for speed. The -n20 -P4 seetting
89 # worked well on a multicore SSD machine with the files cached, roughly
90 # doubling the speed, but it may need tuning for slower systems or cold caches.
91@@ -260,16 +242,19 @@
92 sampledata: bin/maas-region-admin bin/database syncdb
93 $(dbrun) bin/maas-region-admin loaddata src/maasserver/fixtures/dev_fixture.yaml
94
95-doc: bin/sphinx docs/api.rst
96- bin/sphinx
97-
98-doc-with-versions: bin/sphinx docs/api.rst
99- cd docs/_build; make SPHINXOPTS="-A add_version_switcher=true" html
100-
101-man: $(patsubst docs/man/%.rst,man/%,$(wildcard docs/man/*.rst))
102-
103-man/%: docs/man/%.rst | bin/sphinx-build
104- bin/sphinx-build -b man docs man $^
105+doc: $(patsubst %.md,%.html,$(shell find docs -name '*.md'))
106+
107+%.html: %.md
108+ PYTHONPATH="docs/plugins:docs/plugins/gfm" markdown_py \
109+ -x callouts -x anchors_away -x foldouts -x meta -x def_list \
110+ -x attr_list -e utf8 --file=$@ $^
111+ @# FIXME: broken plugin: partial_gfm
112+ @# FIXME: render these pages on-the-fly into a template.
113+
114+man: $(patsubst docs/man/%.md,man/%,$(wildcard docs/man/*.md))
115+
116+man/%: docs/man/%.md
117+ pandoc -s -f markdown_github -t man $^ -o $@
118
119 enums: $(js_enums)
120
121@@ -290,8 +275,6 @@
122 $(RM) $(js_enums)
123 $(RM) *.log
124 $(RM) docs/api.rst
125- $(RM) -r docs/_autosummary docs/_build
126- $(RM) -r man/.doctrees
127 $(RM) coverage.data coverage.xml
128 $(RM) -r coverage
129
130
131=== modified file 'buildout.cfg'
132--- buildout.cfg 2015-04-10 13:58:31 +0000
133+++ buildout.cfg 2015-04-17 21:06:27 +0000
134@@ -9,7 +9,6 @@
135 region
136 region-test
137 repl
138- sphinx
139 testing-test
140 extensions = buildout-versions
141 buildout_versions_file = versions.cfg
142@@ -245,22 +244,6 @@
143 entry-points =
144 flake8=flake8.run:main
145
146-[rst-lint]
147-recipe = zc.recipe.egg
148-eggs =
149- restructuredtext-lint
150-scripts =
151- rst-lint
152-
153-[sphinx]
154-recipe = collective.recipe.sphinxbuilder
155-source = ${buildout:directory}/docs
156-build = ${buildout:directory}/docs/_build
157-extra-paths = ${common:extra-paths}
158-eggs =
159- ${region:eggs}
160- ${cluster:eggs}
161-
162 # Convenient REPLs with all eggs available.
163 [repl]
164 recipe = z3c.recipe.scripts
165
166=== removed directory 'docs/_static'
167=== removed file 'docs/_static/versions.js'
168--- docs/_static/versions.js 2014-04-14 21:42:00 +0000
169+++ docs/_static/versions.js 1970-01-01 00:00:00 +0000
170@@ -1,91 +0,0 @@
171-/* Javascript utilities to create a version switcher widget.
172-
173-This is mostly done, but not limited to support creating links
174-between the different versions of the MAAS documentation on
175-maas.ubuntu.com.
176-
177-*/
178-
179-function page_exists(url) {
180- // Returns wether a page at the give URL exists or not.
181- var result = false;
182- $.ajax({
183- type: 'HEAD',
184- url: url,
185- async: false,
186- success: function () {
187- result = true;
188- }
189- });
190- return result;
191-};
192-
193-function doc_page(version, doc_prefix) {
194- // Returns the URL of the page equivalent to the current page but from
195- // the given version of the documentation.
196- // e.g. if the current page is 'http://host/<doc_prefix>1.6/somepage.html', calling
197- // doc_page('1.7') will return 'http://host/<doc_prefix>1.7/somepage.html'.
198- var pattern = new RegExp('\/' + doc_prefix + '([\\d\\.]*)\/')
199- var newpathname = window.location.pathname.replace(
200- pattern, '/' + doc_prefix + version + '/');
201- return window.location.origin + newpathname + window.location.hash;
202-};
203-
204-function doc_homepage(version, doc_prefix) {
205- // Returns the URL of the homepage for the documentation of the given
206- // version.
207- return window.location.origin + '/' + doc_prefix + version + '/';
208-};
209-
210-
211-function set_up_version_switcher(selector, doc_prefix) {
212- // Create version switcher widget.
213- $(selector).replaceWith($('\
214- <h3>Version</h3> \
215- <select id="id_sidebar_release" name="release"> \
216- </select>'));
217-
218- release_select = $("#id_sidebar_release");
219-
220- // Request version list and populate version switcher widget with it.
221- var json_url = "/" + doc_prefix + "/_static/versions.json";
222- var jqxhr = $.getJSON(json_url, function(data) {
223- var first = true;
224- $.each(data, function (value, text) {
225- var option_value = value;
226- if (first) {
227- // The first element corresponds to the documentation for trunk.
228- option_value = '';
229- first = false;
230- }
231- var option = $("<option></option>").attr("value", option_value).text(text);
232- if (value == DOCUMENTATION_OPTIONS.VERSION) {
233- option.attr('selected', 'selected');
234- }
235- release_select.append(option);
236- });
237- });
238-
239- // jqxhr.fail only exists in recent versions of jQuery;
240- // it's not there with the version shipped with Sphinx
241- // on Precise.
242- if ($.isFunction(jqxhr.fail)) {
243- jqxhr.fail(function(jqXHR) {
244- console.log("error requesting versions file");
245- console.log(jqXHR);
246- });
247- }
248-
249- // Handle version switcher change: redirect to the equivalent page in the
250- // selected version of the documentation if that page exists, redirects to the
251- // homepage of the selected version of the documentation otherwise.
252- $("#id_sidebar_release").change(function () {
253- var version = $(this).find('option:selected').val();
254- var same_page_in_other_version = doc_page(version, doc_prefix);
255- if (page_exists(same_page_in_other_version)) {
256- window.location = same_page_in_other_version;
257- } else {
258- window.location = doc_homepage(version, doc_prefix);
259- }
260- });
261-};
262
263=== removed directory 'docs/_templates'
264=== removed directory 'docs/_templates/maas'
265=== removed file 'docs/_templates/maas/layout.html'
266--- docs/_templates/maas/layout.html 2014-06-11 15:27:54 +0000
267+++ docs/_templates/maas/layout.html 1970-01-01 00:00:00 +0000
268@@ -1,31 +0,0 @@
269-{%- extends "basic/layout.html" %}
270-{% 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'] %}
271-
272-{% block sidebarlogo %}
273-<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>
274-<h2 style="text-align:center;">MAAS</h2>
275-<p style="font-style:italic;font-size:0.9em; text-align:center; margin-bottom:1.5em">Metal As A Service.</p>
276-<span id="version_switcher"></span>
277-<br/>
278-<br/>
279-{% endblock %}
280-
281-{# Remove 'modules' and 'index' from rellinks: they point to
282- autogenerated code documentation pages that we don't want
283- to advertise too much.
284-#}
285-{%- set rellinks = rellinks[2:] %}
286-
287-{%- block footer %}
288-<footer class="global clearfix">
289- <div class="legal clearfix">
290- <p>&copy; Copyright {{ copyright }}. Ubuntu and Canonical are registered trademarks of
291- <a href="http://canonical.com">Canonical Ltd</a>.
292- </p>
293- <p>
294- Revision {{ bzr_last_revision_number}} ({{ bzr_last_revision_date }}).
295- Documentation generation date: {{ bzr_build_date }}.
296- </p>
297- </div>
298-</footer>
299-{%- endblock %}
300
301=== removed file 'docs/_templates/maas/localtoc.html'
302--- docs/_templates/maas/localtoc.html 2013-12-06 19:26:05 +0000
303+++ docs/_templates/maas/localtoc.html 1970-01-01 00:00:00 +0000
304@@ -1,3 +0,0 @@
305-{%- if display_toc %}
306- {{ toc }}
307-{%- endif %}
308
309=== removed file 'docs/_templates/maas/relations.html'
310--- docs/_templates/maas/relations.html 2014-04-08 20:58:05 +0000
311+++ docs/_templates/maas/relations.html 1970-01-01 00:00:00 +0000
312@@ -1,31 +0,0 @@
313-<script type="text/javascript">
314-$(document).ready(function () {
315- if ({{ add_version_switcher }}) {
316- $.ajaxSetup({cache: true});
317- $.getScript('{{ versions_json_path }}', function() {
318- console.log( "Versions script loaded." );
319- set_up_version_switcher('#version_switcher', '{{ doc_prefix }}');
320- });
321-}
322-});
323-</script>
324-
325-<h3>Related Topics</h3>
326-<ul>
327- <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul>
328- {%- for parent in parents %}
329- <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul>
330- {%- endfor %}
331- {%- if prev %}
332- <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter')
333- }}">{{ prev.title }}</a></li>
334- {%- endif %}
335- {%- if next %}
336- <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter')
337- }}">{{ next.title }}</a></li>
338- {%- endif %}
339- {%- for parent in parents %}
340- </ul></li>
341- {%- endfor %}
342- </ul></li>
343-</ul>
344
345=== removed directory 'docs/_templates/maas/static'
346=== removed directory 'docs/_templates/maas/static/css'
347=== removed file 'docs/_templates/maas/static/css/main.css'
348--- docs/_templates/maas/static/css/main.css 2014-06-09 16:25:19 +0000
349+++ docs/_templates/maas/static/css/main.css 1970-01-01 00:00:00 +0000
350@@ -1,75 +0,0 @@
351-pre {
352- background-color:#EEEEEE;
353- background-position:initial initial;
354- background-repeat:initial initial;
355- line-height:1.3em;
356- margin:15px 0px;
357- padding:7px 30px;
358-}
359-
360-div.document {
361- width: 984px;
362- margin: 10px auto 0 auto;
363-}
364-
365-div.body h1 {
366- margin-top: 20px;
367- padding-top: 0;
368- font-size: 250%;
369-}
370-
371-.bodywrapper ul ul {
372- margin-top: .4em;
373- margin-bottom: .4em;
374-}
375-
376-div.sphinxsidebar ul ul {
377- margin-top: .4em;
378- margin-bottom: .4em;
379-}
380-
381-body {
382- padding-top: 0px;
383-}
384-
385-div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6, div.admonition p.admonition-title {
386- font-family: Ubuntu,Arial,"libra sans",sans-serif;
387-}
388-
389-div.admonition {
390- margin: 20px 0px;
391- color: #3E4349;
392-}
393-
394-div.admonition p.admonition-title {
395- font-size: 20px;
396-}
397-
398-.document {
399- -moz-box-sizing: border-box;
400- background: none repeat scroll 0 0 #FFFFFF;
401- border-radius: 4px;
402- box-shadow: 0 0 3px #C9C9C9;
403-}
404-
405-div.sphinxsidebarwrapper {
406- padding: 18px 10px 18px 20px;
407-}
408-
409-form input[type="text"] {
410- display: inline;
411-}
412-
413-div.sphinxsidebar #searchbox input[type="text"] {
414- width: 110px;
415- padding: 4px 3px;
416-}
417-
418-div.sphinxsidebar #searchbox input[type="submit"] {
419- width: 40px;
420-}
421-
422-a:active, a:focus, a:hover {
423- text-decoration: none;
424- border-bottom: 1px solid #6D4100;
425-}
426
427=== removed file 'docs/_templates/maas/static/flasky.css_t'
428--- docs/_templates/maas/static/flasky.css_t 2014-06-09 16:25:19 +0000
429+++ docs/_templates/maas/static/flasky.css_t 1970-01-01 00:00:00 +0000
430@@ -1,564 +0,0 @@
431-/*
432- * flasky.css_t
433- * ~~~~~~~~~~~~
434- *
435- * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz.
436- * :license: Flask Design License, see LICENSE for details.
437- */
438-
439-{% set page_width = '940px' %}
440-{% set sidebar_width = '220px' %}
441-
442-@import url("basic.css");
443-
444-/* -- page layout ----------------------------------------------------------- */
445-
446-body {
447- font-family: "Georgia", "Open Sans", OpenSansRegular, sans-serif;
448- font-size: 16px;
449- background: #fff;
450- font-weight: 400;
451- color: #000;
452- margin: 0;
453- padding: 0;
454-}
455-
456-div.document {
457- width: {{ page_width }};
458- margin: 10px auto 0 auto;
459-}
460-
461-div.documentwrapper {
462- float: left;
463- width: 100%;
464-}
465-
466-div.bodywrapper {
467- margin: 0 0 0 {{ sidebar_width }};
468-}
469-
470-div.sphinxsidebar {
471- width: {{ sidebar_width }};
472-}
473-
474-hr {
475- border: 1px solid #B1B4B6;
476-}
477-
478-div.body {
479- background-color: white;
480- color: #3E4349;
481- padding: 0 30px 0 30px;
482-}
483-
484-img.floatingflask {
485- padding: 0 0 10px 10px;
486- float: right;
487-}
488-
489-div.footer {
490- width: {{ page_width }};
491- margin: 20px auto 30px auto;
492- font-size: 14px;
493- color: #888;
494- text-align: right;
495-}
496-
497-div.footer a {
498- color: #888;
499-}
500-
501-div.related {
502- width: {{ page_width }};
503- margin: 10px auto 0 auto;
504-}
505-
506-div.related h3 {
507- display: none;
508-}
509-
510-div.sphinxsidebar a {
511- color: #444;
512- text-decoration: none;
513- border-bottom: 1px dotted #999;
514-}
515-
516-div.sphinxsidebar a:hover {
517- border-bottom: 1px solid #999;
518-}
519-
520-div.sphinxsidebar {
521- font-size: 14px;
522- line-height: 1.5;
523-}
524-
525-div.sphinxsidebarwrapper {
526- padding: 18px 10px;
527-}
528-
529-div.sphinxsidebarwrapper p.logo {
530- padding: 0;
531- margin: -10px 0 0 -20px;
532- text-align: center;
533-}
534-
535-div.sphinxsidebar h3,
536-div.sphinxsidebar h4 {
537- font-family: 'Antic Slab' ,'Garamond', 'Georgia', serif;
538- color: #000;
539- font-size: 24px;
540- font-weight: normal;
541- margin: 30px 0 5px 0;
542- padding: 0;
543-}
544-
545-div.sphinxsidebar h4 {
546- font-size: 20px;
547-}
548-
549-div.sphinxsidebar h3 a {
550- color: #000;
551-}
552-
553-div.sphinxsidebar p.logo a,
554-div.sphinxsidebar h3 a,
555-div.sphinxsidebar p.logo a:hover,
556-div.sphinxsidebar h3 a:hover {
557- border: none;
558-}
559-
560-div.sphinxsidebar p {
561- color: #555;
562- margin: 10px 0;
563-}
564-
565-div.sphinxsidebar ul {
566- margin: 10px 0px;
567- padding: 0;
568- color: #000;
569-}
570-
571-div.sphinxsidebar input {
572- border: 1px solid #ccc;
573- font-family: 'Georgia', serif;
574- font-size: 1em;
575-}
576-
577-/* -- body styles ----------------------------------------------------------- */
578-
579-a {
580- color: #004B6B;
581- text-decoration: underline;
582-}
583-
584-a:hover {
585- color: #6D4100;
586- text-decoration: underline;
587-}
588-
589-div.body h1,
590-div.body h2,
591-div.body h3,
592-div.body h4,
593-div.body h5,
594-div.body h6 {
595- font-family: 'Antic Slab', serif;
596- font-weight: normal;
597- margin: 30px 0px 10px 0px;
598- padding: 0;
599- text-shadow: 1px 1px 3px #ddd;
600- color: #000;
601-}
602-
603-div.body h1 { margin-top: 0; padding-top: 0; font-size: 250%; }
604-div.body h2 { font-size: 190%; }
605-div.body h3 { font-size: 160%; }
606-div.body h4 { font-size: 140%; }
607-div.body h5 { font-size: 110%; }
608-div.body h6 { font-size: 110%; }
609-
610-a.headerlink {
611- color: #ddd;
612- padding: 0 4px;
613- text-decoration: none;
614-}
615-
616-a.headerlink:hover {
617- color: #444;
618- background: #eaeaea;
619-}
620-
621-div.body p, div.body dd, div.body li {
622- line-height: 1.4em;
623-}
624-
625-div.admonition {
626- background: #fafafa;
627- margin: 20px -30px;
628- padding: 10px 30px;
629- border-top: 1px solid #ccc;
630- border-bottom: 1px solid #ccc;
631-}
632-
633-div.admonition tt.xref, div.admonition a tt {
634- border-bottom: 1px solid #fafafa;
635-}
636-
637-dd div.admonition {
638- margin-left: -60px;
639- padding-left: 60px;
640-}
641-
642-div.admonition p.admonition-title {
643- font-family: 'Garamond', 'Georgia', serif;
644- font-weight: normal;
645- font-size: 24px;
646- margin: 0 0 10px 0;
647- padding: 0;
648- line-height: 1;
649-}
650-
651-div.admonition p.last {
652- margin-bottom: 0;
653-}
654-
655-div.highlight {
656- background-color: white;
657-}
658-
659-dt:target, .highlight {
660- background: #FAF3E8;
661-}
662-
663-div.note {
664- background-color: #eee;
665- border: 1px solid #ccc;
666-}
667-
668-div.seealso {
669- background-color: #ffc;
670- border: 1px solid #ff6;
671-}
672-
673-div.topic {
674- background-color: #eee;
675-}
676-
677-p.admonition-title {
678- display: inline;
679-}
680-
681-p.admonition-title:after {
682- content: ":";
683-}
684-
685-pre {
686- font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
687- font-size: 0.88em;
688-}
689-
690-tt {
691- font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
692- font-size: 0.95em;
693-}
694-
695-img.screenshot {
696-}
697-
698-tt.descname, tt.descclassname {
699- font-size: 0.95em;
700-}
701-
702-tt.descname {
703- padding-right: 0.08em;
704-}
705-
706-img.screenshot {
707- -moz-box-shadow: 2px 2px 4px #eee;
708- -webkit-box-shadow: 2px 2px 4px #eee;
709- box-shadow: 2px 2px 4px #eee;
710-}
711-
712-table.docutils {
713- border: 1px solid #888;
714- -moz-box-shadow: 2px 2px 4px #eee;
715- -webkit-box-shadow: 2px 2px 4px #eee;
716- box-shadow: 2px 2px 4px #eee;
717-}
718-
719-table.docutils td, table.docutils th {
720- border: 1px solid #888;
721- padding: 0.25em 0.7em;
722-}
723-
724-table.field-list, table.footnote {
725- border: none;
726- -moz-box-shadow: none;
727- -webkit-box-shadow: none;
728- box-shadow: none;
729-}
730-
731-table.footnote {
732- margin: 15px 0;
733- width: 100%;
734- border: 1px solid #eee;
735- background: #fdfdfd;
736- font-size: 0.9em;
737-}
738-
739-table.footnote + table.footnote {
740- margin-top: -15px;
741- border-top: none;
742-}
743-
744-table.field-list th {
745- padding: 0 0.8em 0 0;
746-}
747-
748-table.field-list td {
749- padding: 0;
750-}
751-
752-table.footnote td.label {
753- width: 0px;
754- padding: 0.3em 0 0.3em 0.5em;
755-}
756-
757-table.footnote td {
758- padding: 0.3em 0.5em;
759-}
760-
761-dl {
762- margin: 0;
763- padding: 0;
764-}
765-
766-dl dd {
767- margin-left: 30px;
768-}
769-
770-blockquote {
771- margin: 0 0 0 30px;
772- padding: 0;
773-}
774-
775-ul, ol {
776- margin: 10px 0 10px 30px;
777- padding: 0;
778-}
779-
780-pre {
781- background: #eee;
782- padding: 7px 30px;
783- margin: 15px -30px;
784- line-height: 1.3em;
785-}
786-
787-dl pre, blockquote pre, li pre {
788- margin-left: 0px;
789- padding-left: 15px;
790-}
791-
792-dl dl pre {
793- margin-left: 0px;
794- padding-left: 15px;
795-}
796-
797-tt {
798- background-color: #ecf0f3;
799- color: #222;
800- /* padding: 1px 2px; */
801-}
802-
803-tt.xref, a tt {
804- background-color: #FBFBFB;
805- color: #2277bb;
806- border-bottom: 1px solid white;
807-}
808-
809-a.reference {
810- text-decoration: none;
811- border-bottom: 1px dotted #004B6B;
812-}
813-
814-a.reference:hover {
815- border-bottom: 1px solid #6D4100;
816-}
817-
818-a.footnote-reference {
819- text-decoration: none;
820- font-size: 0.7em;
821- vertical-align: top;
822- border-bottom: 1px dotted #004B6B;
823-}
824-
825-a.footnote-reference:hover {
826- border-bottom: 1px solid #6D4100;
827-}
828-
829-a:hover tt {
830- background: #EEE;
831-}
832-
833-li {
834- margin-bottom: 0.3em;
835-}
836-
837-
838-@media screen and (max-width: 870px) {
839-
840- div.sphinxsidebar {
841- display: none;
842- }
843-
844- div.document {
845- width: 100%;
846-
847- }
848-
849- div.documentwrapper {
850- margin-left: 0;
851- margin-top: 0;
852- margin-right: 0;
853- margin-bottom: 0;
854- }
855-
856- div.bodywrapper {
857- margin-top: 0;
858- margin-right: 0;
859- margin-bottom: 0;
860- margin-left: 0;
861- }
862-
863- ul {
864- margin-left: 0;
865- }
866-
867- .document {
868- width: auto;
869- }
870-
871- .footer {
872- width: auto;
873- }
874-
875- .bodywrapper {
876- margin: 0;
877- }
878-
879- .footer {
880- width: auto;
881- }
882-
883- .github {
884- display: none;
885- }
886-
887-
888-
889-}
890-
891-
892-
893-@media screen and (max-width: 875px) {
894-
895- body {
896- margin: 0;
897- padding: 20px 30px;
898- }
899-
900- div.documentwrapper {
901- float: none;
902- background: white;
903- }
904-
905- div.sphinxsidebar {
906- display: block;
907- float: none;
908- width: 102.5%;
909- margin: 50px -30px -20px -30px;
910- padding: 10px 20px;
911- background: #333;
912- color: white;
913- }
914-
915- div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
916- div.sphinxsidebar h3 a {
917- color: white;
918- }
919-
920- div.sphinxsidebar a {
921- color: #aaa;
922- }
923-
924- div.sphinxsidebar p.logo {
925- display: none;
926- }
927-
928- div.document {
929- width: 100%;
930- margin: 0;
931- }
932-
933- div.related {
934- display: block;
935- margin: 0;
936- padding: 10px 0 20px 0;
937- }
938-
939- div.related ul,
940- div.related ul li {
941- margin: 0;
942- padding: 0;
943- }
944-
945- div.footer {
946- display: none;
947- }
948-
949- div.bodywrapper {
950- margin: 0;
951- }
952-
953- div.body {
954- min-height: 0;
955- padding: 0;
956- }
957-
958-
959- .rtd_doc_footer {
960- display: none;
961- }
962-
963- .document {
964- width: auto;
965- }
966-
967- .footer {
968- width: auto;
969- }
970-
971- .footer {
972- width: auto;
973- }
974-
975- .github {
976- display: none;
977- }
978-}
979-
980-
981-/* misc. */
982-
983-.revsys-inline {
984- display: none!important;
985-}
986-
987-div.sphinxsidebar #searchbox input[type="text"] {
988- width: 140px;
989- padding: 4px 3px;
990-}
991-
992-.highlight .nv {
993- color: #C65D09!important;
994-}
995
996=== removed file 'docs/_templates/maas/theme.conf'
997--- docs/_templates/maas/theme.conf 2013-12-06 15:11:12 +0000
998+++ docs/_templates/maas/theme.conf 1970-01-01 00:00:00 +0000
999@@ -1,6 +0,0 @@
1000-[theme]
1001-inherit = basic
1002-stylesheet = flasky.css
1003-
1004-headfont = Ubuntu
1005-bodyfont = free-sans,sans,sans-serif
1006
1007=== renamed file 'docs/about.rst' => 'docs/about.md'
1008--- docs/about.rst 2014-11-10 16:39:12 +0000
1009+++ docs/about.md 2015-04-17 21:06:27 +0000
1010@@ -1,50 +1,17 @@
1011 About this documentation
1012 ========================
1013
1014-This is the documentation for Canonical's MAAS software. If you aren't
1015-sure what that is, you should probably skip everything else and head
1016-straight to the :ref:`orientation` section where it is explained.
1017-Like any software though, it can be frustrating if you don't know how
1018-bits of it work, how to achieve certain goals or what to do when
1019-things go wrong. Amongst its various sections, this manual aims to
1020-answer all those questions and plenty more you haven't even thought of
1021-yet.
1022-
1023+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.
1024
1025 Getting it
1026 ----------
1027
1028-In a cunning move, the current documentation always lives, and is
1029-built from, the main MAAS source code (in the top-level ``docs/``
1030-directory). That means that whatever MAAS package you have installed,
1031-or even if you are really living life on the edge and have checked out
1032-a development version from Launchpad, this documentation should be the
1033-latest and most appropriate version for the software you are running.
1034-However, it is also possible that there have been additional sections,
1035-or more helpful and clearer bits added since the package you are using
1036-was made. For this reason you can always find the latest documentation
1037-online here: `http://maas.ubuntu.com`_.
1038-
1039-.. _http://maas.ubuntu.com:
1040- http://maas.ubuntu.com
1041-
1042+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\_.
1043
1044 Contributing
1045 ------------
1046
1047-If you have some extra information to add, or think you have spotted
1048-an error or something out of date, we really want to hear about
1049-it. Please `File a bug report`_ or `contact us directly`_. In addition
1050-you can talk to us on the Freenode IRC channel #maas.
1051-
1052-.. _File a bug report:
1053- https://bugs.launchpad.net/maas/+filebug
1054-
1055-.. _contact us directly:
1056- https://launchpad.net/~maas-maintainers/+contactuser
1057-
1058-If you see something wrong with this documentation, you can help us fix it.
1059-Download the source to MAAS by following the instructions in
1060-:doc:`the hacking guide <hacking>`, make your changes, and propose a merge
1061-against lp:maas on Launchpad. The documentation source lives in the top-level
1062-``docs/`` directory.
1063+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.
1064+
1065+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.
1066+
1067
1068=== renamed file 'docs/api_authentication.rst' => 'docs/api_authentication.md'
1069--- docs/api_authentication.rst 2015-02-13 10:11:07 +0000
1070+++ docs/api_authentication.md 2015-04-17 21:06:27 +0000
1071@@ -1,78 +1,64 @@
1072-.. -*- mode: rst -*-
1073-
1074-.. _api_authentication:
1075-
1076 API authentication
1077 ==================
1078
1079-MAAS's API uses OAuth_ as its authentication mechanism. There isn't a third
1080-party involved (as in 3-legged OAuth) and so the process used is what's
1081-commonly referred to as 0-legged OAuth: the consumer accesses protected
1082-resources by submitting OAuth signed requests.
1083-
1084-.. _OAuth: http://en.wikipedia.org/wiki/OAuth
1085-
1086-Note that some API endpoints support unauthenticated requests (i.e.
1087-anonymous access). See the :doc:`API documentation <api>` for details.
1088-
1089+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.
1090+
1091+Note that some API endpoints support unauthenticated requests (i.e. anonymous access). See the API documentation \<api\> for details.
1092
1093 Examples
1094 ========
1095
1096-Here are two examples on how to perform an authenticated GET request to
1097-retrieve the list of nodes. The <key>, <secret>, <consumer_key> tokens
1098-are the three elements that compose the API key (API key =
1099-'<consumer_key>:<key>:<secret>').
1100+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\>').
1101
1102 Python
1103 ------
1104
1105-.. code:: python
1106-
1107- import oauth.oauth as oauth
1108- import httplib2
1109- import uuid
1110-
1111- def perform_API_request(site, uri, method, key, secret, consumer_key):
1112- resource_tok_string = "oauth_token_secret=%s&oauth_token=%s" % (
1113- secret, key)
1114- resource_token = oauth.OAuthToken.from_string(resource_tok_string)
1115- consumer_token = oauth.OAuthConsumer(consumer_key, "")
1116-
1117- oauth_request = oauth.OAuthRequest.from_consumer_and_token(
1118- consumer_token, token=resource_token, http_url=site,
1119- parameters={'oauth_nonce': uuid.uuid4().get_hex()})
1120- oauth_request.sign_request(
1121- oauth.OAuthSignatureMethod_PLAINTEXT(), consumer_token,
1122- resource_token)
1123- headers = oauth_request.to_header()
1124- url = "%s%s" % (site, uri)
1125- http = httplib2.Http()
1126- return http.request(url, method, body=None, headers=headers)
1127-
1128- # API key = '<consumer_key>:<key>:<secret>'
1129- response = perform_API_request(
1130- 'http://server/MAAS/api/1.0', '/nodes/?op=list', 'GET', '<key>', '<secret>',
1131- '<consumer_key>')
1132+``` {.sourceCode .python}
1133+import oauth.oauth as oauth
1134+import httplib2
1135+import uuid
1136+
1137+def perform_API_request(site, uri, method, key, secret, consumer_key):
1138+ resource_tok_string = "oauth_token_secret=%s&oauth_token=%s" % (
1139+ secret, key)
1140+ resource_token = oauth.OAuthToken.from_string(resource_tok_string)
1141+ consumer_token = oauth.OAuthConsumer(consumer_key, "")
1142+
1143+ oauth_request = oauth.OAuthRequest.from_consumer_and_token(
1144+ consumer_token, token=resource_token, http_url=site,
1145+ parameters={'oauth_nonce': uuid.uuid4().get_hex()})
1146+ oauth_request.sign_request(
1147+ oauth.OAuthSignatureMethod_PLAINTEXT(), consumer_token,
1148+ resource_token)
1149+ headers = oauth_request.to_header()
1150+ url = "%s%s" % (site, uri)
1151+ http = httplib2.Http()
1152+ return http.request(url, method, body=None, headers=headers)
1153+
1154+# API key = '<consumer_key>:<key>:<secret>'
1155+response = perform_API_request(
1156+ 'http://server/MAAS/api/1.0', '/nodes/?op=list', 'GET', '<key>', '<secret>',
1157+ '<consumer_key>')
1158+```
1159
1160 Ruby
1161 ----
1162
1163-.. code:: ruby
1164-
1165- require 'oauth'
1166- require 'oauth/signature/plaintext'
1167-
1168- def perform_API_request(site, uri, key, secret, consumer_key)
1169- consumer = OAuth::Consumer.new(
1170- consumer_key, "",
1171- { :site => "http://localhost/MAAS/api/1.0",
1172- :scheme => :header, :signature_method => "PLAINTEXT"})
1173- access_token = OAuth::AccessToken.new(consumer, key, secret)
1174- return access_token.request(:get, "/nodes/?op=list")
1175- end
1176-
1177- # API key = "<consumer_key>:<key>:<secret>"
1178- response = perform_API_request(
1179- "http://server/MAAS/api/1.0", "/nodes/?op=list", "<key>", "<secret>",
1180- "consumer_key>")
1181+``` {.sourceCode .ruby}
1182+require 'oauth'
1183+require 'oauth/signature/plaintext'
1184+
1185+def perform_API_request(site, uri, key, secret, consumer_key)
1186+ consumer = OAuth::Consumer.new(
1187+ consumer_key, "",
1188+ { :site => "http://localhost/MAAS/api/1.0",
1189+ :scheme => :header, :signature_method => "PLAINTEXT"})
1190+ access_token = OAuth::AccessToken.new(consumer, key, secret)
1191+ return access_token.request(:get, "/nodes/?op=list")
1192+end
1193+
1194+# API key = "<consumer_key>:<key>:<secret>"
1195+response = perform_API_request(
1196+ "http://server/MAAS/api/1.0", "/nodes/?op=list", "<key>", "<secret>",
1197+ "consumer_key>")
1198+```
1199
1200=== renamed file 'docs/bootsources.rst' => 'docs/bootsources.md'
1201--- docs/bootsources.rst 2015-02-06 17:07:56 +0000
1202+++ docs/bootsources.md 2015-04-17 21:06:27 +0000
1203@@ -1,21 +1,9 @@
1204-.. -*- mode: rst -*-
1205-
1206-.. _bootsources:
1207-
1208 Boot images import configuration
1209 ================================
1210
1211-The configuration for where a region downloads its images is defined by
1212-a set of "sources". Each "source" defines a Simplestreams repository
1213-location (``url``) from which images can be downloaded and a
1214-``keyring_filename`` (or ``keyring_data``) for validating index and image
1215-signatures from that location. For each source, you can define a series of
1216-filters (``selections``) specifying which images should be downloaded from
1217-that source.
1218+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.
1219
1220-The following example use the MAAS CLI to list the boot sources and the boot
1221-source selections. Assuming the CLI ``PROFILE`` is the name of the profile
1222-under which you're logged in to the server::
1223+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:
1224
1225 $ maas $PROFILE boot-sources read
1226 [
1227@@ -46,22 +34,19 @@
1228 }
1229 ]
1230
1231-
1232 Restricting the images being downloaded
1233 ---------------------------------------
1234
1235-Let's say you want to add a previous LTS release to images being downloaded.
1236-Starting from the configuration described above, you would need to:
1237-
1238-- Add the "Precise" selection (the selection '1' of the source '1')::
1239-
1240- $ maas $PROFILE boot-source-selection create 1 os="ubuntu" release="precise" arches="amd64" subarches="*" labels="*"
1241+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:
1242+
1243+- Add the "Precise" selection (the selection '1' of the source '1'):
1244+
1245+ $ maas $PROFILE boot-source-selection create 1 os="ubuntu" release="precise" arches="amd64" subarches="*" labels="*"
1246
1247 Downloading the images from a different source
1248 ----------------------------------------------
1249
1250-Let's say you want to import the images from a different location. You would
1251-need to to change the source's url and keyring::
1252+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:
1253
1254 $ maas $PROFILE boot-source update 1 url="http://custom.url" keyring_filename="" keyring_data@=./custom_keyring_file
1255 {
1256@@ -75,7 +60,7 @@
1257 Adding a source
1258 ---------------
1259
1260-You can also add a new source::
1261+You can also add a new source:
1262
1263 $ maas $PROFILE boot-sources create url=http://my.url keyring_filename="" keyring_data@=./ custom_keyring_file
1264 {
1265@@ -86,7 +71,7 @@
1266 "resource_uri": "<url omitted for readability>"
1267 }
1268
1269-Inside that newly created source ('2') you can add selections::
1270+Inside that newly created source ('2') you can add selections:
1271
1272 $ maas $PROFILE boot-source-selections create 2 os="ubuntu" release="trusty" arches="amd64" subarches="*" labels='*'
1273 {
1274@@ -98,11 +83,10 @@
1275 "resource_uri": "<url omitted for readability>"
1276 }
1277
1278-Deleting a source
1279----------------
1280+Deleting a source ---------------
1281
1282 Let's say you need to delete the newly added source.
1283
1284-To delete the source::
1285+To delete the source:
1286
1287 $ maas $PROFILE boot-source delete 2
1288
1289=== renamed file 'docs/capabilities.rst' => 'docs/capabilities.md'
1290--- docs/capabilities.rst 2014-10-09 06:30:29 +0000
1291+++ docs/capabilities.md 2015-04-17 21:06:27 +0000
1292@@ -1,44 +1,26 @@
1293-.. -*- mode: rst -*-
1294-
1295-.. _capabilities:
1296-
1297 Capabilities
1298 ============
1299
1300-MAAS publishes a special view at ``.../api/1.0/version/`` that returns a
1301-list of the server's capabilities. It's transferred as a JSON document::
1302+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:
1303
1304 {"capabilities": ["name-of-capability", ...]}
1305
1306-.. note::
1307-
1308- The view is called ``version`` because this will, later, include
1309- version information too.
1310-
1311+> **note**
1312+>
1313+> The view is called `version` because this will, later, include version information too.
1314
1315 List of capabilities
1316 --------------------
1317
1318-Check for the following strings in the capabilities list to see what
1319-features the MAAS server supports. Use these in preference to gating on
1320-the version when creating a client application.
1321-
1322-.. _cap-networks-management:
1323-
1324-``networks-management``
1325- Passive modelling of the network environment that cluster controllers
1326- nodes are in, including network interfaces, subnets, VLAN tags, and
1327- connectivity between them. See :ref:`networks` for more information.
1328-
1329-.. _cap-static-ipaddresses:
1330-
1331-``static-ipaddresses``
1332- Static IP address allocation to nodes, including user-reserved IPs and admin-
1333- allocated 'sticky' IPs. Available since version 1.6. See :ref:`static-ips`
1334- for more information.
1335-
1336-.. _cap-ipv6-deployment-ubuntu:
1337-
1338-``ipv6-deployment-ubuntu``
1339- Deploy Ubuntu nodes with IPv6 networking enabled. See :ref:`ipv6` for more
1340- about this feature.
1341+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.
1342+
1343+`networks-management`
1344+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.
1345+
1346+`static-ipaddresses`
1347+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.
1348+
1349+`ipv6-deployment-ubuntu`
1350+Deploy Ubuntu nodes with IPv6 networking enabled. See ipv6 for more about this feature.
1351+
1352+
1353
1354=== renamed file 'docs/changelog.rst' => 'docs/changelog.md'
1355--- docs/changelog.rst 2015-04-09 15:48:49 +0000
1356+++ docs/changelog.md 2015-04-17 21:06:27 +0000
1357@@ -1,1132 +1,696 @@
1358-=========
1359 Changelog
1360 =========
1361
1362 1.7.3
1363-=====
1364-
1365-Bug Fix Update
1366---------------
1367-
1368-#1441933 Internal Server Error when saving a cluster without Router IP
1369-#1441133 MAAS version not exposed over the API
1370-#1437094 Sorting by mac address on webui causes internal server error
1371-#1439359 Automatically set correct boot resources selection and start import
1372- after upgrade from MAAS 1.5; Ensures MAAS is usable after upgrade.
1373-#1439366 Backwards compatibility with MAAS 1.5 preseeds and custom preseeds.
1374- Ensures that users dont have to manually change preseeds names.
1375+-----
1376+
1377+### Bug Fix Update
1378+
1379+\#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.
1380
1381 1.7.2
1382-=====
1383-
1384-Bug Fix Update
1385---------------
1386-
1387-#1331214 Support AMT Version > 8
1388-#1397567 Fix call to amttool when restarting a node to not fail disk erasing.
1389-#1415538 Do not generate the 'option routers' stanza if router IP is None.
1390-#1403909 Do not deallocate StaticIPAddress before node has powered off.
1391-#1405998 Remove all OOPS reporting.
1392-#1423931 Update the nodes host maps when a sticky ip address is claimed over the API.
1393-#1433697 Look for bootloaders in /usr/lib/EXTLINUX
1394-
1395+-----
1396+
1397+### Bug Fix Update
1398+
1399+\#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
1400
1401 1.7.1
1402-=====
1403-
1404-Minor feature improvements
1405---------------------------
1406-
1407-New CentOS Release support.
1408- Further to the work done in the 1.7.0 MAAS Release, MAAS now supports
1409- uploading various versions of CentOS. Previously MAAS would only
1410- officially support 6.5.
1411-
1412-Power Monitoring for Seamicro 15000, Cisco UCS and HP Moonshot Chassis
1413- Further the work done in the 1.7.0 MAAS release, it now supports power
1414- query and monitoring for the Seamicro 15000 Chassis, the Cisco UCS
1415- Chassis Manager and the HP Moonshot Chassis Manager.
1416-
1417-Node Listing Page and Node Event Log live refresh
1418- The Node Listing page and the Node Event Log now have live refresh
1419- every 10 seconds. This allows MAAS to display the latest node status
1420- and events without forcing a browser refresh.
1421-
1422-IP Address Reservation
1423- The static IP address reservation API now has an optional "mac"
1424- parameter. Specifying a MAC address here will link the new static IP
1425- to that MAC address. A DHCP host map will be created for the MAC
1426- address. No other IPs may be reserved for that MAC address until the
1427- current one is released.
1428-
1429-Bug fix update
1430---------------
1431-
1432-For full details see https://launchpad.net/maas/+milestone/1.7.1
1433-
1434-#1330765 If start_nodes() fails, it doesn't clean up after itself.
1435-#1373261 pserv.yaml rewrite breaks when previous generator URL uses IPv6 address
1436-#1386432 After update to the latest curtin that changes the log to install.log MAAS show's two installation logs
1437-#1386488 If rndc fails, you get an Internal Server Error page
1438-#1386502 No "failed" transition from "new"
1439-#1386914 twisted Unhandled Error when region can't reach upstream boot resource
1440-#1391139 Tagged VLAN on aliased NIC breaks migration 0099
1441-#1391161 Failure: twisted.internet.error.ConnectionDone: Connection was closed cleanly.
1442-#1391411 metadata API signal() is releasing host maps at the end of installation
1443-#1391897 Network names with dots cause internal server error when on node pages
1444-#1394382 maas does not know about VM "paused" state
1445-#1396308 Removing managed interface causes maas to delete nodes
1446-#1397356 Disk Wiping fails if installation is not Ubuntu
1447-#1398405 MAAS UI reports storage size in Gibibytes (base 2) but is labeled GB - Gigabytes (base 10).
1448-#1399331 MAAS leaking sensitive information in ps ax output
1449-#1400849 Check Power State disappears after upgrade to 1.7 bzr 3312
1450-#1401241 custom dd-tgz format images looked for in wrong path, so they don't work
1451-#1401983 Exception: deadlock detected
1452-#1403609 can not enlist chassis with maas admin node-group probe-and-enlist-mscm
1453-#1283106 MAAS allows the same subnet to be defined on two managed interfaces of the same cluster
1454-#1303925 commissioning fails silently if a node can't reach the region controller
1455-#1357073 power state changes are not reflected quickly enough in the UI
1456-#1360280 boot-source-selections api allows adding bogus and duplicated values
1457-#1368400 Can't power off nodes that are in Ready state but on
1458-#1370897 The node power monitoring service does not check nodes in parallel
1459-#1376024 gpg --batch [...]` error caused by race in BootSourceCacheService
1460-#1376716 AMT NUC stuck at boot prompt instead of powering down (no ACPI support in syslinux poweroff)
1461-#1378835 Config does not have a unique index on name
1462-#1379370 Consider removing transaction in claim_static_ip_addresses().
1463-#1379556 Panicky log warning that is irrelevant
1464-#1381444 Misleading error message in log "Unknown power_type 'sm15k'"
1465-#1382166 Message disclosing image import necessary visible while not logged in
1466-#1382237 UnicodeEncodeError when unable to create host maps
1467-#1383231 Error message when trying to reserve the same static IP twice is unhelpful
1468-#1383237 Error message trying to reserve an IP address when no static range is defined is misleading
1469-#1384424 Seamicro Machines do not have Power Status Tracking
1470-#1384428 HP Moonshot Chassis Manager lacks power status monitoring
1471-#1384924 need to provide a better upgrade message for images on the cluster but not on the region
1472-#1386517 DHCP leases are not released at the end of commissioning and possibly enlistment
1473-#1387239 MAAS does not provide an API for reserving a static IP for a given MAC address
1474-#1387414 Race when registering new event type
1475-#1388033 Trying to reserve a static IP when no more IPs are available results in 503 Service Unavailable with no error text
1476-#1389602 Inconsistent behavior in the checks to delete a node
1477-#1389733 node listing does not update the status and power of nodes
1478-#1390144 Node 'releasing' should have a timeout
1479-#1391193 API error documentation
1480-#1391421 Names of custom boot-resources not visible in the web UI
1481-#1391891 Spurious test failure: TestDNSForwardZoneConfig_GetGenerateDirectives.test_returns_single_entry_for_tiny_network
1482-#1393423 PowerKVM / VIrsh import should allow you to specify a prefix to filter VM's to import
1483-#1393953 dd-format images fail to deploy
1484-#1400909 Networks are being autocreated like eth0-eth0 instead of maas-eth0
1485-#1401349 Memory size changes to incorrect size when page is refreshed
1486-#1402237 Node event log queries are slow (over 1 second)
1487-#1402243 Nodes in 'Broken' state are being power queried constantly
1488-#1402736 clicking on zone link from node page - requested URL was not found on this server
1489-#1403043 Wrong top-level tab is selected when viewing a node
1490-#1381609 Misleading log message when a node has a MAC address not attached to a cluster interface
1491-#1386909 Misleading Error: Unable to identify boot image for (ubuntu/amd64/generic/trusty/local): cluster 'maas' does not have matching boot image.
1492-#1388373 Fresh image import of 3 archs displaying multiple rows for armhf and amd64
1493-#1398159 TFTP into MAAS server to get pxelinux.0 causes unhandled error
1494-#1383651 Node.start() and Node.stop() raise MulltipleFailures unnecessarily
1495-#1383668 null" when releasing an IP address is confusing
1496-#1389416 Power querying for UCSM not working
1497-#1399676 UX bug: mac address on the nodes page should be the MAC address it pxe booted from
1498-#1399736 MAAS should display memory sizes in properly labeld base 2 units - MiB, GiB, etc.
1499-#1401643 Documentation has wrong pattern for user provided preseeds
1500-#1401707 Slow web performance (5+ minute response time) on MAAS with many nodes
1501-#1403609 Fix MSCM chassis enlistment.
1502-#1409952 Correctly parse MAC Address for Power8 VM enlistment.
1503-#1409852 Do not fail when trying to perform an IP Address Reservation.
1504-#1413030 OS and Release no longer populate on Add Node page
1505-#1414036 Trying to add an empty network crashes (AddrFormatError)
1506-
1507+-----
1508+
1509+### Minor feature improvements
1510+
1511+New CentOS Release support.
1512+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.
1513+
1514+Power Monitoring for Seamicro 15000, Cisco UCS and HP Moonshot Chassis
1515+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.
1516+
1517+Node Listing Page and Node Event Log live refresh
1518+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.
1519+
1520+IP Address Reservation
1521+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.
1522+
1523+### Bug fix update
1524+
1525+For full details see <https://launchpad.net/maas/+milestone/1.7.1>
1526+
1527+\#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)
1528
1529 1.7.0
1530-=====
1531-
1532-Important announcements
1533------------------------
1534-
1535-**Re-import your boot images**
1536- You must re-import your boot images, see below for details.
1537-
1538-**Update Curtin preseed files**
1539- Two changes were made to Curtin preseed files that need your attention
1540- if you made any customisations:
1541-
1542- * The OS name must now appear in the filename. The new schema is shown
1543- here, each file pattern is tried in turn until a match is found::
1544-
1545- {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}_{node_name}
1546- {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}
1547- {prefix}_{osystem}_{node_arch}_{node_subarch}
1548- {prefix}_{osystem}_{node_arch}
1549- {prefix}_{osystem}
1550- {prefix}
1551-
1552- * If you are modifying ``/etc/network/interfaces`` in the preseed, it must be
1553- moved so it is processed last in ``late_commands`` since MAAS now writes
1554- to this file itself as part of IPv6 setup. For example::
1555-
1556- late_commands:
1557- bonding_02: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
1558-
1559- must now look like this::
1560-
1561- late_commands:
1562- zz_write_ifaces: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
1563-
1564- The leading ``zz`` ensures the command sorts to the end of the
1565- ``late_commands`` list.
1566-
1567-
1568-Major new features
1569-------------------
1570-
1571-**Improved image downloading and reporting.**
1572- MAAS boot images are now downloaded centrally by the region controller
1573- and disseminated to all registered cluster controllers. This change includes
1574- a new web UI under the `Images` tab that allows the admin to select
1575- which images to import and shows the progress of the ongoing download.
1576- This completely replaces any file-based configuration that used to take
1577- place on cluster controllers. The cluster page now shows whether it has
1578- synchronised all the images from the region controller.
1579-
1580- This process is also completely controllable using the API.
1581-
1582-.. Note::
1583- Unfortunately due to a format change in the way images are stored, it
1584- was not possible to migrate previously downloaded images to the new region
1585- storage. The cluster(s) will still be able to use the existing images,
1586- however the region controller will be unaware of them until an import
1587- is initiated. When the import is finished, the cluster(s) will remove
1588- older image resources.
1589-
1590- This means that the first thing to do after upgrading to 1.7 is go to the
1591- `Images` tab and re-import the images.
1592-
1593-**Increased robustness.**
1594- A large amount of effort has been given to ensuring that MAAS remains
1595- robust in the face of adversity. An updated node state model has been
1596- implemented that takes into account more of the situations in which a
1597- node can be found including any failures at each stage.
1598-
1599- When a node is getting deployed, it is now monitored to check that each
1600- stage is reached in a timely fashion; if it does not then it is marked
1601- as failed.
1602-
1603- The core power driver was updated to check the state of the power on each
1604- node and is reported in the web UI and API. The core driver now also
1605- handles retries when changing the power state of hardware, removing the
1606- requirement that each power template handle it individually.
1607-
1608-**RPC security.**
1609- As a step towards mutually verified TLS connections between MAAS's
1610- components, 1.7 introduces a simple shared-secret mechanism to
1611- authenticate the region with the clusters and vice-versa. For those
1612- clusters that run on the same machine as the region controller (which
1613- will account for most people), everything will continue to work
1614- without intervention. However, if you're running a cluster on a
1615- separate machine, you must install the secret:
1616-
1617- 1. After upgrading the region controller, view /var/lib/maas/secret
1618- (it's text) and copy it.
1619-
1620- 2. On each cluster, run:
1621-
1622- sudo -u maas maas-provision install-shared-secret
1623-
1624- You'll be prompted for the secret; paste it in and press enter. It
1625- is a password prompt, so the secret will not be echoed back to you.
1626-
1627- That's it; the upgraded cluster controller will find the secret
1628- without needing to be told.
1629-
1630-**RPC connections.**
1631- Each cluster maintains a persistent connection to each region
1632- controller process that's running. The ports on which the region is
1633- listening are all high-numbered, and they are allocated randomly by
1634- the OS. In a future release of MAAS we will narrow this down. For now,
1635- each cluster controller needs unfiltered access to each machine in the
1636- region on all high-numbered TCP ports.
1637-
1638-**Node event log.**
1639- For every major event on nodes, it is now logged in a node-specific log.
1640- This includes events such as power changes, deployments and any failures.
1641-
1642-**IPv6.**
1643- It is now possible to deploy Ubuntu nodes that have IPv6 enabled.
1644- See :doc:`ipv6` for more details.
1645-
1646-**Removal of Celery and RabbitMQ.**
1647- While Celery was found to be very reliable it ultimately did not suit
1648- the project's requirements as it is a largely fire-and-forget mechanism.
1649- Additionally it was another moving part that caused some headaches for
1650- users and admins alike, so the decision was taken to remove it and implement
1651- a custom communications mechanism between the region controller and cluster
1652- controllers. The new mechanism is bidirectional and allowed the complex
1653- interactions to take place that are required as part of the robustness
1654- improvements.
1655-
1656- Since a constant connection is maintained, as a side effect the web UI now
1657- shows whether each cluster is connected or not.
1658-
1659-**Support for other OSes.**
1660- Non-Ubuntu OSes are fully supported now. This includes:
1661- - Windows
1662- - Centos
1663- - SuSE
1664-
1665-**Custom Images.**
1666- MAAS now supports the deployment of Custom Images. Custom images can be
1667- uploaded via the API. The usage of custom images allows the deployment of
1668- other Ubuntu Flavors, such as Ubuntu Desktop.
1669-
1670-**maas-proxy.**
1671- MAAS now uses maas-proxy as the default proxy solution instead of
1672- squid-deb-proxy. On a fresh install, MAAS will use maas-proxy by default.
1673- On upgrades from previous releases, MAAS will install maas-proxy instead of
1674- squid-deb-proxy.
1675-
1676-Minor notable changes
1677----------------------
1678-
1679-**Better handling of networks.**
1680- All networks referred to by cluster interfaces are now automatically
1681- registered on the Network page. Any node network interfaces are
1682- automatically linked to the relevant Network.
1683-
1684-.. Note::
1685- Commissioning currently requires an IP address to be available for each
1686- network interface on a network that MAAS manages; this allows MAAS to
1687- auto-populate its networks database. In general you should use a
1688- well-sized network (/16 recommended if you will be using containers and
1689- VMs) and dynamic pool. If this feature risks causing IP exhaustion for
1690- your deployment and you do not need the auto-populate functionality, you
1691- can disable it by running the following command on your region controller::
1692-
1693- sudo maas <profile> maas set-config name=enable_dhcp_discovery_on_unconfigured_interfaces value=False
1694-
1695-**Improved logging.**
1696- A total overhaul of where logging is produced was undertaken, and now
1697- all the main events in MAAS are selectively reported to syslog with the
1698- "maas" prefix from both the region and cluster controllers alike. If MAAS
1699- is installed using the standard Ubuntu packaging, its syslog entries are
1700- redirected to /var/log/maas/maas.log.
1701-
1702- On the clusters, pserv.log is now less chatty and contains only errors.
1703- On the region controller appservers, maas-django.log contains only appserver
1704- errors.
1705-
1706-**Static IP selection.**
1707- The API was extended so that specific IPs can be pre-allocated for network
1708- interfaces on nodes and for user-allocated IPs.
1709-
1710-**Pronounceable random hostnames.**
1711- The old auto-generated 5-letter names were replaced with a pseudo-random
1712- name that is produced from a dictionary giving names of the form
1713- 'adjective-noun'.
1714-
1715-
1716-Known Problems & Workarounds
1717-----------------------------
1718-
1719-**Upgrade issues**
1720- There may be upgrade issues for users currently on MAAS 1.5 and 1.6; while we
1721- have attempted to reproduce and address all the issues reported, some bugs
1722- remain inconclusive. We recommend a full, tested backup of the MAAS servers
1723- before attempting the upgrade to 1.7. If you do encounter issues, please file
1724- these and flag them to the attention of the MAAS team and we will address them
1725- in point-releases. See bugs `1381058`_, `1382266`_, `1379890`_, `1379532`_,
1726- and `1379144`_.
1727-
1728-.. _1381058:
1729- https://launchpad.net/bugs/1381058
1730-.. _1382266:
1731- https://launchpad.net/bugs/1382266
1732-.. _1379890:
1733- https://launchpad.net/bugs/1379890
1734-.. _1379532:
1735- https://launchpad.net/bugs/1379532
1736-.. _1379144:
1737- https://launchpad.net/bugs/1379144
1738-
1739-**Split Region/Cluster set-ups**
1740- If you site your cluster on a separate host to the region, it needs a
1741- security key to be manually installed by running
1742- ``maas-provision install-shared-secret`` on the cluster host.
1743-
1744-**Private boot streams**
1745- If you had private boot image stream information configured in MAAS 1.5 or
1746- 1.6, upgrading to 1.7 will not take that into account and it will need to be
1747- manually entered on the settings page in the MAAS UI (bug `1379890`_)
1748-
1749-.. _1379890:
1750- https://launchpad.net/bugs/1379890
1751-
1752-**Concurrency issues**
1753- Concurrency issues expose us to races when simultaneous operations are
1754- triggered. This is the source of many hard to reproduce issues which will
1755- require us to change the default database isolation level. We intend to address
1756- this in the first point release of 1.7.
1757-
1758-**Destroying a Juju environment**
1759- When attempting to "juju destroy" an environment, nodes must be in the DEPLOYED
1760- state; otherwise, the destroy will fail. You should wait for all in-progress
1761- actions on the MAAS cluster to conclude before issuing the command. (bug
1762- `1381619`_)
1763-
1764-.. _1381619:
1765- https://launchpad.net/bugs/1381619
1766-
1767-**AMT power control**
1768- A few AMT-related issues remain, with workarounds:
1769-
1770- * Commissioning NUC reboots instead of shutting down (bug `1368685`_). There
1771- is `a workaround in the power template`_
1772-
1773- * MAAS (amttool) cannot control AMT version > 8. See `workaround described in
1774- bug 1331214`_
1775-
1776- * AMT NUC stuck at boot prompt instead of powering down (no ACPI support in
1777- syslinux poweroff) (bug `1376716`_). See the `ACPI-only workaround`_
1778-
1779-.. _1368685:
1780- https://bugs.launchpad.net/maas/+bug/1368685
1781-.. _a workaround in the power template:
1782- https://bugs.launchpad.net/maas/+bug/1368685/comments/8
1783-.. _workaround described in bug 1331214:
1784- https://bugs.launchpad.net/maas/+bug/1331214/comments/18
1785-.. _1376716:
1786- https://bugs.launchpad.net/maas/+bug/1376716
1787-.. _ACPI-only workaround:
1788- https://bugs.launchpad.net/maas/+bug/1376716/comments/12
1789-
1790-
1791-**Disk wiping**
1792- If you enable disk wiping, juju destroy-environment may fail for you. The
1793- current workaround is to wait and re-issue the command. This will be fixed in
1794- future versions of MAAS & Juju. (bug `1386327`_)
1795-
1796-.. _1386327:
1797- https://bugs.launchpad.net/maas/+bug/1386327
1798-
1799-**BIND with DNSSEC**
1800- If you are using BIND with a forwarder that uses DNSSEC and have not
1801- configured certificates, you will need to explicitly disable that feature in
1802- your BIND configuration (1384334)
1803-
1804-.. _1384334:
1805- https://bugs.launchpad.net/maas/+bug/1384334
1806-
1807-**Boot source selections on the API**
1808- Use of API to change image selections can leave DB in a bad state
1809- (bug `1376812`_). It can be fixed by issuing direct database updates.
1810-
1811-.. _1376812:
1812- https://bugs.launchpad.net/maas/+bug/1376812
1813-
1814-**Disabling DNS**
1815- Disabling DNS may not work (bug `1383768`_)
1816-
1817-.. _1383768:
1818- https://bugs.launchpad.net/maas/+bug/1383768
1819-
1820-**Stale DNS zone files**
1821- Stale DNS zone files may be left behind if the MAAS domainname is changed
1822- (bug `1383329`_)
1823-
1824-.. _1383329:
1825- https://bugs.launchpad.net/maas/+bug/1383329
1826-
1827-
1828-
1829-Major bugs fixed in this release
1830---------------------------------
1831-
1832-See https://launchpad.net/maas/+milestone/1.7.0 for full details.
1833-
1834-#1081660 If maas-enlist fails to reach a DNS server, the node will be named ";; connection timed out; no servers could be reached"
1835-
1836-#1087183 MaaS cloud-init configuration specifies 'manage_etc_hosts: localhost'
1837-
1838-#1328351 ConstipationError: When the cluster runs the "import boot images" task it blocks other tasks
1839-
1840-#1342117 CLI command to set up node-group-interface fails with /usr/lib/python2.7/dist-packages/maascli/__main__.py: error: u'name'
1841-
1842-#1349254 Duplicate FQDN can be configured on MAAS via CLI or API
1843-
1844-#1352575 BMC password showing in the apache2 logs
1845-
1846-#1355534 UnknownPowerType traceback in appserver log
1847-
1848-#1363850 Auto-enlistment not reporting power parameters
1849-
1850-#1363900 Dev server errors while trying to write to '/var/lib/maas'
1851-
1852-#1363999 Not assigning static IP addresses
1853-
1854-#1364481 http 500 error doesn't contain a stack trace
1855-
1856-#1364993 500 error when trying to acquire a commissioned node (AddrFormatError: failed to detect a valid IP address from None)
1857-
1858-#1365130 django-admin prints spurious messages to stdout, breaking scripts
1859-
1860-#1365850 DHCP scan using cluster interface name as network interface?
1861-
1862-#1366172 NUC does not boot after power off/power on
1863-
1864-#1366212 Large dhcp leases file leads to tftp timeouts
1865-
1866-#1366652 Leaking temporary directories
1867-
1868-#1368269 internal server error when deleting a node
1869-
1870-#1368590 Power actions are not serialized.
1871-
1872-#1370534 Recurrent update of the power state of nodes crashes if the connection to the BMC fails.
1873-
1874-#1370958 excessive pserv logging
1875-
1876-#1372767 Twisted web client does not support IPv6 address
1877-
1878-#1372944 Twisted web client fails looking up IPv6 address hostname
1879-
1880-#1373031 Cannot register cluster
1881-
1882-#1373103 compose_curtin_network_preseed breaks installation of all other operating systems
1883-
1884-#1373368 Conflicting power actions being dropped on the floor can result in leaving a node in an inconsistent state
1885-
1886-#1373699 Cluster Listing Page lacks feedback about the images each cluster has
1887-
1888-#1374102 No retries for AMT power?
1889-
1890-#1375980 Nodes failed to transition out of "New" state on bulk commission
1891-
1892-#1376023 After performing bulk action on maas nodes, Internal Server Error
1893-
1894-#1376888 Nodes can't be deleted if DHCP management is off.
1895-
1896-#1377099 Bulk operation leaves nodes in inconsistent state
1897-
1898-#1379209 When a node has multiple interfaces on a network MAAS manages, MAAS assigns static IP addresses to all of them
1899-
1900-#1379744 Cluster registration is fragile and insecure
1901-
1902-#1380932 MAAS does not cope with changes of the dhcp daemons
1903-
1904-#1381605 Not all the DNS records are being added when deploying multiple nodes
1905-
1906-#1012954 If a power script fails, there is no UI feedback
1907-
1908-#1186196 "Starting a node" has different meanings in the UI and in the API.
1909-
1910-#1237215 maas and curtin do not indicate failure reasonably
1911-
1912-#1273222 MAAS doesn't check return values of power actions
1913-
1914-#1288502 archive and proxy settings not honoured for commissioning
1915-
1916-#1316919 Checks don't exist to confirm a node will actually boot
1917-
1918-#1321885 IPMI detection and automatic setting fail in ubuntu 14.04 maas
1919-
1920-#1325610 node marked "Ready" before poweroff complete
1921-
1922-#1340188 unallocated node started manually, causes AssertionError for purpose poweroff
1923-
1924-#1341118 No feedback when IPMI credentials fail
1925-
1926-#1341121 No feedback to user when cluster is not running
1927-
1928-#1341581 power state is not represented in api and ui
1929-
1930-#1341800 MAAS doesn't support soft power off through the API
1931-
1932-#1344177 hostnames can't be changed while a node is acquired
1933-
1934-#1347518 Confusing error message when API key is wrong
1935-
1936-#1349496 Unable to request a specific static IP on the API
1937-
1938-#1349736 MAAS logging is too verbose and not very useful
1939-
1940-#1349917 guess_server_address() can return IPAddress or hostname
1941-
1942-#1350103 No support for armhf/keystone architecture
1943-
1944-#1350856 Can't constrain acquisition of nodes by not having a tag
1945-
1946-#1356880 MAAS shouldn't allow changing the hostname of a deployed node
1947-
1948-#1357714 Virsh power driver does not seem to work at all
1949-
1950-#1358859 Commissioning output xml is hard to understand, would be nice to have yaml as an output option.
1951-
1952-#1359169 MAAS should handle invalid consumers gracefully
1953-
1954-#1359822 Gateway is missing in network definition
1955-
1956-#1363913 Impossible to remove last MAC from network in UI
1957-
1958-#1364228 Help text for node hostname is wrong
1959-
1960-#1364591 MAAS Archive Mirror does not respect non-default port
1961-
1962-#1365616 Non-admin access to cluster controller config
1963-
1964-#1365619 DNS should be an optional field in the network definition
1965-
1966-#1365776 commissioning results view for a node also shows installation results
1967-
1968-#1366812 Old boot resources are not being removed on clusters
1969-
1970-#1367455 MAC address for node's IPMI is reversed looked up to yield IP address using case sensitive comparison
1971-
1972-#1373580 [SRU] Glen m700 cartridge list as ARM64/generic after enlist
1973-
1974-#1373723 Releasing a node without power parameters ends up in not being able to release a node
1975-
1976-#1233158 no way to get power parameters in api
1977-
1978-#1319854 `maas login` tells you you're logged in successfully when you're not
1979-
1980-#1368480 Need API to gather image metadata across all of MAAS
1981-
1982-#1281406 Disk/memory space on Node edit page have no units
1983-
1984-#1299231 MAAS DHCP/DNS can't manage more than a /16 network
1985-
1986-#1357381 maas-region-admin createadmin shows error if not params given
1987-
1988-#1376393 powerkvm boot loader installs even when not needed
1989-
1990-#1287224 MAAS random generated hostnames are not pronounceable
1991-
1992-#1348364 non-maas managed subnets cannot query maas DNS
1993-
1994+-----
1995+
1996+### Important announcements
1997+
1998+**Re-import your boot images**
1999+You must re-import your boot images, see below for details.
2000+
2001+**Update Curtin preseed files**
2002+Two changes were made to Curtin preseed files that need your attention if you made any customisations:
2003+
2004+- 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:
2005+
2006+ {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}
2007+
2008+- 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:
2009+
2010+ late_commands:
2011+ bonding_02: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
2012+
2013+ must now look like this:
2014+
2015+ late_commands:
2016+ zz_write_ifaces: ["curtin", "in-target", "--", "wget", "-O", "/etc/network/interfaces", "http://[...snip...]"]
2017+
2018+ The leading `zz` ensures the command sorts to the end of the `late_commands` list.
2019+
2020+### Major new features
2021+
2022+**Improved image downloading and reporting.**
2023+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.
2024+
2025+This process is also completely controllable using the API.
2026+
2027+> **note**
2028+
2029+> 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.
2030+>
2031+> This means that the first thing to do after upgrading to 1.7 is go to the Images tab and re-import the images.
2032+
2033+**Increased robustness.**
2034+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.
2035+
2036+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.
2037+
2038+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.
2039+
2040+**RPC security.**
2041+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:
2042+
2043+1. After upgrading the region controller, view /var/lib/maas/secret (it's text) and copy it.
2044+2. On each cluster, run:
2045+
2046+ > sudo -u maas maas-provision install-shared-secret
2047+
2048+ 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.
2049+
2050+That's it; the upgraded cluster controller will find the secret without needing to be told.
2051+
2052+**RPC connections.**
2053+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.
2054+
2055+**Node event log.**
2056+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.
2057+
2058+**IPv6.**
2059+It is now possible to deploy Ubuntu nodes that have IPv6 enabled. See ipv6 for more details.
2060+
2061+**Removal of Celery and RabbitMQ.**
2062+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.
2063+
2064+Since a constant connection is maintained, as a side effect the web UI now shows whether each cluster is connected or not.
2065+
2066+**Support for other OSes.**
2067+Non-Ubuntu OSes are fully supported now. This includes:
2068+- Windows
2069+- Centos
2070+- SuSE
2071+
2072+**Custom Images.**
2073+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.
2074+
2075+**maas-proxy.**
2076+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.
2077+
2078+### Minor notable changes
2079+
2080+**Better handling of networks.**
2081+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.
2082+
2083+> **note**
2084+
2085+> 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:
2086+>
2087+> sudo maas <profile> maas set-config name=enable_dhcp_discovery_on_unconfigured_interfaces value=False
2088+
2089+**Improved logging.**
2090+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.
2091+
2092+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.
2093+
2094+**Static IP selection.**
2095+The API was extended so that specific IPs can be pre-allocated for network interfaces on nodes and for user-allocated IPs.
2096+
2097+**Pronounceable random hostnames.**
2098+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'.
2099+
2100+### Known Problems & Workarounds
2101+
2102+**Upgrade issues**
2103+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).
2104+
2105+**Split Region/Cluster set-ups**
2106+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.
2107+
2108+**Private boot streams**
2109+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))
2110+
2111+**Concurrency issues**
2112+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.
2113+
2114+**Destroying a Juju environment**
2115+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))
2116+
2117+**AMT power control**
2118+A few AMT-related issues remain, with workarounds:
2119+
2120+> - 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)
2121+> - MAAS (amttool) cannot control AMT version \> 8. See [workaround described in bug 1331214](https://bugs.launchpad.net/maas/+bug/1331214/comments/18)
2122+> - 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)
2123+
2124+**Disk wiping**
2125+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))
2126+
2127+**BIND with DNSSEC**
2128+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)
2129+
2130+**Boot source selections on the API**
2131+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.
2132+
2133+**Disabling DNS**
2134+Disabling DNS may not work (bug [1383768](https://bugs.launchpad.net/maas/+bug/1383768))
2135+
2136+**Stale DNS zone files**
2137+Stale DNS zone files may be left behind if the MAAS domainname is changed (bug [1383329](https://bugs.launchpad.net/maas/+bug/1383329))
2138+
2139+### Major bugs fixed in this release
2140+
2141+See <https://launchpad.net/maas/+milestone/1.7.0> for full details.
2142+
2143+\#1081660 If maas-enlist fails to reach a DNS server, the node will be named ";; connection timed out; no servers could be reached"
2144+
2145+\#1087183 MaaS cloud-init configuration specifies 'manage\_etc\_hosts: localhost'
2146+
2147+\#1328351 ConstipationError: When the cluster runs the "import boot images" task it blocks other tasks
2148+
2149+\#1342117 CLI command to set up node-group-interface fails with /usr/lib/python2.7/dist-packages/maascli/\_\_main\_\_.py: error: u'name'
2150+
2151+\#1349254 Duplicate FQDN can be configured on MAAS via CLI or API
2152+
2153+\#1352575 BMC password showing in the apache2 logs
2154+
2155+\#1355534 UnknownPowerType traceback in appserver log
2156+
2157+\#1363850 Auto-enlistment not reporting power parameters
2158+
2159+\#1363900 Dev server errors while trying to write to '/var/lib/maas'
2160+
2161+\#1363999 Not assigning static IP addresses
2162+
2163+\#1364481 http 500 error doesn't contain a stack trace
2164+
2165+\#1364993 500 error when trying to acquire a commissioned node (AddrFormatError: failed to detect a valid IP address from None)
2166+
2167+\#1365130 django-admin prints spurious messages to stdout, breaking scripts
2168+
2169+\#1365850 DHCP scan using cluster interface name as network interface?
2170+
2171+\#1366172 NUC does not boot after power off/power on
2172+
2173+\#1366212 Large dhcp leases file leads to tftp timeouts
2174+
2175+\#1366652 Leaking temporary directories
2176+
2177+\#1368269 internal server error when deleting a node
2178+
2179+\#1368590 Power actions are not serialized.
2180+
2181+\#1370534 Recurrent update of the power state of nodes crashes if the connection to the BMC fails.
2182+
2183+\#1370958 excessive pserv logging
2184+
2185+\#1372767 Twisted web client does not support IPv6 address
2186+
2187+\#1372944 Twisted web client fails looking up IPv6 address hostname
2188+
2189+\#1373031 Cannot register cluster
2190+
2191+\#1373103 compose\_curtin\_network\_preseed breaks installation of all other operating systems
2192+
2193+\#1373368 Conflicting power actions being dropped on the floor can result in leaving a node in an inconsistent state
2194+
2195+\#1373699 Cluster Listing Page lacks feedback about the images each cluster has
2196+
2197+\#1374102 No retries for AMT power?
2198+
2199+\#1375980 Nodes failed to transition out of "New" state on bulk commission
2200+
2201+\#1376023 After performing bulk action on maas nodes, Internal Server Error
2202+
2203+\#1376888 Nodes can't be deleted if DHCP management is off.
2204+
2205+\#1377099 Bulk operation leaves nodes in inconsistent state
2206+
2207+\#1379209 When a node has multiple interfaces on a network MAAS manages, MAAS assigns static IP addresses to all of them
2208+
2209+\#1379744 Cluster registration is fragile and insecure
2210+
2211+\#1380932 MAAS does not cope with changes of the dhcp daemons
2212+
2213+\#1381605 Not all the DNS records are being added when deploying multiple nodes
2214+
2215+\#1012954 If a power script fails, there is no UI feedback
2216+
2217+\#1186196 "Starting a node" has different meanings in the UI and in the API.
2218+
2219+\#1237215 maas and curtin do not indicate failure reasonably
2220+
2221+\#1273222 MAAS doesn't check return values of power actions
2222+
2223+\#1288502 archive and proxy settings not honoured for commissioning
2224+
2225+\#1316919 Checks don't exist to confirm a node will actually boot
2226+
2227+\#1321885 IPMI detection and automatic setting fail in ubuntu 14.04 maas
2228+
2229+\#1325610 node marked "Ready" before poweroff complete
2230+
2231+\#1340188 unallocated node started manually, causes AssertionError for purpose poweroff
2232+
2233+\#1341118 No feedback when IPMI credentials fail
2234+
2235+\#1341121 No feedback to user when cluster is not running
2236+
2237+\#1341581 power state is not represented in api and ui
2238+
2239+\#1341800 MAAS doesn't support soft power off through the API
2240+
2241+\#1344177 hostnames can't be changed while a node is acquired
2242+
2243+\#1347518 Confusing error message when API key is wrong
2244+
2245+\#1349496 Unable to request a specific static IP on the API
2246+
2247+\#1349736 MAAS logging is too verbose and not very useful
2248+
2249+\#1349917 guess\_server\_address() can return IPAddress or hostname
2250+
2251+\#1350103 No support for armhf/keystone architecture
2252+
2253+\#1350856 Can't constrain acquisition of nodes by not having a tag
2254+
2255+\#1356880 MAAS shouldn't allow changing the hostname of a deployed node
2256+
2257+\#1357714 Virsh power driver does not seem to work at all
2258+
2259+\#1358859 Commissioning output xml is hard to understand, would be nice to have yaml as an output option.
2260+
2261+\#1359169 MAAS should handle invalid consumers gracefully
2262+
2263+\#1359822 Gateway is missing in network definition
2264+
2265+\#1363913 Impossible to remove last MAC from network in UI
2266+
2267+\#1364228 Help text for node hostname is wrong
2268+
2269+\#1364591 MAAS Archive Mirror does not respect non-default port
2270+
2271+\#1365616 Non-admin access to cluster controller config
2272+
2273+\#1365619 DNS should be an optional field in the network definition
2274+
2275+\#1365776 commissioning results view for a node also shows installation results
2276+
2277+\#1366812 Old boot resources are not being removed on clusters
2278+
2279+\#1367455 MAC address for node's IPMI is reversed looked up to yield IP address using case sensitive comparison
2280+
2281+\#1373580 [SRU] Glen m700 cartridge list as ARM64/generic after enlist
2282+
2283+\#1373723 Releasing a node without power parameters ends up in not being able to release a node
2284+
2285+\#1233158 no way to get power parameters in api
2286+
2287+\#1319854 maas login tells you you're logged in successfully when you're not
2288+
2289+\#1368480 Need API to gather image metadata across all of MAAS
2290+
2291+\#1281406 Disk/memory space on Node edit page have no units
2292+
2293+\#1299231 MAAS DHCP/DNS can't manage more than a /16 network
2294+
2295+\#1357381 maas-region-admin createadmin shows error if not params given
2296+
2297+\#1376393 powerkvm boot loader installs even when not needed
2298+
2299+\#1287224 MAAS random generated hostnames are not pronounceable
2300+
2301+\#1348364 non-maas managed subnets cannot query maas DNS
2302
2303 1.6.1
2304-=====
2305-
2306-Bug fix update
2307---------------
2308-
2309-- Auto-link node MACs to Networks (LP: #1341619)
2310- MAAS will now auto-create a Network from a cluster interface, and
2311- if an active lease exists for a node's MAC then it will be linked to
2312- that Network.
2313-
2314+-----
2315+
2316+### Bug fix update
2317+
2318+- 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.
2319
2320 1.6.0
2321-=====
2322-
2323-Special notice:
2324- Cluster interfaces now have static IP ranges in order to give nodes stable
2325- IP addresses. You need to set the range in each interface to turn on this
2326- feature. See below for details.
2327-
2328-
2329-Major new features
2330-------------------
2331-
2332-IP addresses overhaul.
2333- This release contains a total reworking of IP address allocation. You can
2334- now define a separate "static" range in each cluster interface configuration
2335- that is separate from the DHCP server's dynamic range. Any node in use by
2336- a user will receive an IP address from the static range that is guaranteed
2337- not to change during its allocated lifetime. Previously, this was at the
2338- whim of the DHCP server despite MAAS placing host maps in its configuration.
2339-
2340- Currently, dynamic IP addresses will continue to receive DNS entries so as
2341- to maintain backward compatibility with installations being upgraded from
2342- 1.5. However, this will be changed in a future release to only give
2343- DNS entries to static IPs.
2344-
2345- You can also use the API to `reserve IP addresses`_ on a per-user basis.
2346-
2347-.. _reserve IP addresses: http://maas.ubuntu.com/docs1.6/api.html#ip-addresses
2348-
2349-Support for additional OSes.
2350- MAAS can now install operating systems other than Ubuntu on nodes.
2351- Preliminary beta support exists for CentOS and SuSE via the `Curtin`_ "fast"
2352- installer. This has not been thoroughly tested yet and has been provided
2353- in case anyone finds this useful and is willing to help find and report bugs.
2354-
2355-
2356-Minor notable changes
2357----------------------
2358-
2359-DNS entries
2360- In 1.5 DNS entries for nodes were a CNAME record. As of 1.6, they are now
2361- all "A" records, which allows for reliable reverse look-ups.
2362-
2363- Only nodes that are allocated to a user and started will receive "A" record
2364- entries. Unallocated nodes no longer have DNS entries.
2365-
2366-Removal of bootresources.yaml
2367- The bootresources.yaml file, which had to be configured separately on each
2368- cluster controller, is no longer in use. Instead, the configuration for
2369- which images to download is now held by the region controller, and defaults
2370- to downloading all images for LTS releases. A `rudimentary API`_ is
2371- available to manipulate this configuration.
2372-
2373-.. _rudimentary API: http://maas.ubuntu.com/docs1.6/api.html#boot-source
2374-
2375-Fast installer is now the default
2376- Prevously, the slower Debian installer was used by default. Any newly-
2377- enlisted nodes will now use the newer `fast installer`_. Existing nodes
2378- will keep the installer setting that they already have.
2379-
2380-.. _fast installer: https://launchpad.net/curtin
2381-
2382-
2383-Bugs fixed in this release
2384---------------------------
2385-#1307779 fallback from specific to generic subarch broken
2386-#1310082 d-i with precise+hwe-s stops at "Architecture not supported"
2387-#1314174 Autodetection of the IPMI IP address fails when the 'power_address'
2388-of the power parameters is empty.
2389-#1314267 MAAS dhcpd will re-issue leases for nodes
2390-#1317675 Exception powering down a virsh machine
2391-#1322256 Import boot resources failing to verify keyring
2392-#1322336 import_boot_images crashes with KeyError on 'keyring'
2393-#1322606 maas-import-pxe-files fails when run from the command line
2394-#1324237 call_and_check does not report error output
2395-#1328659 import_boot_images task fails on utopic
2396-#1332596 AddrFormatError: failed to detect a valid IP address from None executing upload_dhcp_leases task
2397-#1250370 "sudo maas-import-ephemerals" steps on ~/.gnupg/pubring.gpg
2398-#1250435 CNAME record leaks into juju's private-address, breaks host based access control
2399-#1305758 Import fails while writing maas.meta: No such file or directory
2400-#1308292 Unhelpful error when re-enlisting a previously enlisted node
2401-#1309601 maas-enlist prints "successfully enlisted" even when enlistment fail
2402-s.
2403-#1309729 Fast path installer is not the default
2404-#1310844 find_ip_via_arp() results in unpredictable, and in some cases, incorrect IP addresses
2405-#1310846 amt template gives up way too easily
2406-#1312863 MAAS fails to detect SuperMicro-based server's power type
2407-#1314536 Copyright date in web UI is 2012
2408-#1315160 no support for different operating systems
2409-#1316627 API needed to allocate and return an extra IP for a container
2410-#1323291 Can't re-commission a commissioning node
2411-#1324268 maas-cli 'nodes list' or 'node read <system_id>' doesn't display the osystem or distro_series node fields
2412-#1325093 install centos using curtin
2413-#1325927 YUI.Array.each not working as expected
2414-#1328656 MAAS sends multiple stop_dhcp_server tasks even though there's no dhcp server running.
2415-#1331139 IP is inconsistently capitalized on the 'edit a cluster interface' p
2416-age
2417-#1331148 When editing a cluster interface, last 3 fields are unintuitive
2418-#1331165 Please do not hardcode the IP address of Canonical services into MAAS managed DHCP configs
2419-#1338851 Add MAAS arm64/xgene support
2420-#1307693 Enlisting a SeaMicro or Virsh chassis twice will not replace the missing entries
2421-#1311726 No documentation about the supported power types and the related power parameters
2422-#1331982 API documentation for nodegroup op=details missing parameter
2423-#1274085 error when maas can't meet juju constraints is confusing and not helpful
2424-#1330778 MAAS needs support for managing nodes via the Moonshot HP iLO Chassis Manager CLI
2425-#1337683 The API client MAASClient doesn't encode list parameters when doing a GET
2426-#1190986 ERROR Nonce already used
2427-#1342135 Allow domains to be used for NTP server configuration, not just IPs
2428-#1337437 Allow 14.10 Utopic Unicorn as a deployable series
2429-#1350235 Package fails to install when the default route is through an aliased/tagged interface
2430-#1353597 PowerNV: format_bootif should make sure mac address is all lowercase
2431+-----
2432+
2433+Special notice:
2434+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.
2435+
2436+### Major new features
2437+
2438+IP addresses overhaul.
2439+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.
2440+
2441+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.
2442+
2443+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.
2444+
2445+Support for additional OSes.
2446+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.
2447+
2448+### Minor notable changes
2449+
2450+DNS entries
2451+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.
2452+
2453+Only nodes that are allocated to a user and started will receive "A" record entries. Unallocated nodes no longer have DNS entries.
2454+
2455+Removal of bootresources.yaml
2456+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.
2457+
2458+Fast installer is now the default
2459+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.
2460+
2461+### Bugs fixed in this release
2462+
2463+\#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
2464
2465 1.5.3
2466-=====
2467-
2468-Bug fix update
2469---------------
2470-
2471- - Reduce number of celery tasks emitted when updating a cluster controller
2472- (LP: #1324944)
2473- - Fix VirshSSH template which was referencing invalid attributes
2474- (LP: #1324966)
2475- - Fix a start up problem where a database lock was being taken outside of
2476- a transaction (LP: #1325759)
2477- - Reformat badly formatted Architecture error message (LP: #1301465)
2478- - Final changes to support ppc64el (now known as PowerNV) (LP: #1315154)
2479-
2480+-----
2481+
2482+### Bug fix update
2483+
2484+> - Reduce number of celery tasks emitted when updating a cluster controller (LP: \#1324944)
2485+> - Fix VirshSSH template which was referencing invalid attributes (LP: \#1324966)
2486+> - Fix a start up problem where a database lock was being taken outside of a transaction (LP: \#1325759)
2487+> - Reformat badly formatted Architecture error message (LP: \#1301465)
2488+> - Final changes to support ppc64el (now known as PowerNV) (LP: \#1315154)
2489
2490 1.5.2
2491-=====
2492-
2493-Minor feature changes
2494----------------------
2495-
2496-Boot resource download changes.
2497- Further to the work done in the 1.5 (Ubuntu 14.04) release, MAAS no
2498- longer stores the configuration for downloading boot resources in
2499- ``/etc/maas/bootresources.yaml``; this file is now obsolete. The
2500- sources list is now stored on the region controller and passed to the
2501- cluster controller when the job to download boot resources is started.
2502- It is still possible to pass a list of sources to
2503- ``maas-import-pxe-files`` when running the script manually.
2504-
2505+-----
2506+
2507+### Minor feature changes
2508+
2509+Boot resource download changes.
2510+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.
2511
2512 1.5.1
2513-=====
2514-
2515-Bug fix update
2516---------------
2517-
2518-For full details see https://launchpad.net/maas/+milestone/1.5.1
2519-
2520-#1303915 Powering SM15k RESTAPI v2.0 doesn't force PXE boot
2521-#1307780 no armhf commissioning template
2522-#1310076 lost connectivity to a node when using fastpath-installer with precise+hwe-s
2523-#1310082 d-i with precise+hwe-s stops at "Architecture not supported"
2524-#1311151 MAAS imports Trusty's 'rc' images by default.
2525-#1311433 REGRESSION: AttributeError: 'functools.partial' object has no attribute '__module__'
2526-#1313556 API client blocks when deleting a resource
2527-#1314409 parallel juju deployments race on the same maas
2528-#1316396 When stopping a node from the web UI that was started from the API, distro_series is not cleared
2529-#1298784 Vulnerable to user-interface redressing (e.g. clickjacking)
2530-#1308772 maas has no way to specify alternate IP addresses for AMT template
2531-#1300476 Unable to setup BMC/UCS user on Cisco B200 M3
2532+-----
2533+
2534+### Bug fix update
2535+
2536+For full details see <https://launchpad.net/maas/+milestone/1.5.1>
2537+
2538+\#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
2539
2540 1.5
2541-===
2542+---
2543
2544 (released in Ubuntu 14.04)
2545
2546-Major new features
2547-------------------
2548-
2549-Advanced Networking.
2550- MAAS will now support multiple managed network interfaces on a single
2551- cluster. It will track networks (including tagged VLANs) to which each node
2552- is able to connect and provides this information in the API. API clients may
2553- also use networking information in acquisition constraints when asking for a
2554- new node allocation.
2555-
2556- See :ref:`The full Networking documentation <networks>`.
2557-
2558-Zones.
2559- A Zone is an arbitrary grouping of nodes. MAAS now allows admins to define
2560- Zones, and place in them any of the region's nodes. Once defined, API
2561- clients can use the zone name as acquisition constraints for new node
2562- allocations.
2563-
2564- See :doc:`physical-zones` for more detail.
2565-
2566-Hardware Enablement Kernels.
2567- MAAS is now able to fetch and use hardware enablement kernels which allow
2568- kernels for newer Ubuntu releases to be used on older releases.
2569-
2570- See :doc:`hardware-enablement-kernels`
2571-
2572-Minor feature changes
2573----------------------
2574-
2575-Maas-Test.
2576- A new project `maas-test`_ was created to put a piece of hardware through MAAS's
2577- test suite to see if it's suitable for use in MAAS, and optionally report the results
2578- to a bug in Launchpad's maas-test project.
2579-
2580-.. _maas-test: https://launchpad.net/maas-test/
2581-
2582-IPMI improvements.
2583- Many improvements were made to IPMI handling, including better detection
2584- during enlistment. Many IPMI-based systems that previously failed to work
2585- with MAAS will now work correctly.
2586-
2587-Completion of image downloading changes.
2588- Further to the work done in the 1.4 (Ubuntu 13.10) release, MAAS now uses indexed
2589- "simplestreams" data published by Canonical to fetch not only the ephemeral
2590- images, but now also the kernels and ramdisks. The resource download
2591- configuration is now in a new file ``/etc/maas/bootresources.yaml`` on
2592- each cluster controller. All previous configuration files for image
2593- downloads are now obsolete. The new file will be pre-configured based on
2594- images that are already present on the cluster.
2595-
2596- This change also enables end-users to provide their own simplestreams data
2597- and thusly their own custom images.
2598-
2599-Cluster-driven hardware availability.
2600- When adding or editing node hardware in the region controller, MAAS will
2601- contact the relevant cluster controller to validate the node's settings.
2602- As of release, the only validation made is the architecture and the power
2603- settings. Available architectures are based on which images have been
2604- imported on the cluster. In the future, this will enable new cluster
2605- controllers to be added that contain drivers for new hardware without
2606- restarting the region controller.
2607-
2608-Seamicro hardware.
2609- MAAS now supports the Seamicro 15000 hardware for power control and API-based
2610- enlistment.
2611-
2612-AMT.
2613- MAAS now supports power control using `Intel AMT`_.
2614-
2615-.. _Intel AMT: http://www.intel.com/content/www/us/en/architecture-and-technology/intel-active-management-technology.html
2616-
2617-DNS forwarders.
2618- In MAAS's settings it's now possible to configure an upstream DNS, which will
2619- be set in the bind daemon's 'forwarders' option.
2620-
2621-Foreign DHCP servers.
2622- MAAS detects and shows you if any other DHCP servers are active on the
2623- networks that are on the cluster controller.
2624-
2625-Commissioning Results.
2626- A node's commissioning results are now shown in the UI.
2627-
2628-Renamed commands.
2629- ``maas`` is renamed to ``maas-region-admin``. ``maas-cli`` is now just
2630- ``maas``.
2631-
2632-
2633-Bugs fixed in this release
2634---------------------------
2635-For full details see https://launchpad.net/maas/+milestone/14.04
2636-
2637-#1227035 If a template substitution fails, the appserver crashes
2638-
2639-#1255479 MaaS Internal Server Error 500 while parsing tags with namespaces in definition upon commissioning
2640-
2641-#1269648 OAuth unauthorised errors mask the actual error text
2642-
2643-#1270052 Adding an SSH key fails due to a UnicodeDecodeError
2644-
2645-#1274024 kernel parameters are not set up in the installed OS's grub cfg
2646-
2647-#1274190 periodic_probe_dhcp task raises IOError('No such device')
2648-
2649-#1274912 Internal server error when trying to stop a node with no power type
2650-
2651-#1274926 A node's nodegroup is autodetected using the request's IP even when the request is a manual
2652-
2653-#1278895 When any of the commissioning scripts fails, the error reported contains the list of the scripts that *didn't* fail
2654-
2655-#1279107 maas_ipmi_autodetect.py ignores command failures
2656-
2657-#1282828 Almost impossible to provide a valid nodegroup ID when enlisting new node on API
2658-
2659-#1283114 MAAS' DHCP server is not stopped when the number of managed interfaces is zero
2660-
2661-#1285244 Deleting a node sometimes fails with omshell error
2662-
2663-#1285607 maas_ipmi_autodetect mistakes empty slot for taken slot
2664-
2665-#1287274 On OCPv3 Roadrunner, maas_ipmi_autodetect fails because LAN Channel settings can't be changed
2666-
2667-#1287512 OCPv3 roadrunner detects IPMI as 1.5
2668-
2669-#1289456 maas IPMI user creation fails on some DRAC systems
2670-
2671-#1290622 report_boot_images does not remove images that were deleted from the cluster
2672-
2673-#1293676 internal server error when marking nodes as using fast-path installer
2674-
2675-#1300587 Cloud-archive selection widget is obsolete
2676-
2677-#1301809 Report boot images no directory traceback
2678-
2679-#1052339 MAAS only supports one "managed" (DNS/DHCP) interface per cluster controller.
2680-
2681-#1058126 maas dbshell stacktraces in package
2682-
2683-#1064212 If a machine is booted manually when in status "Declared" or "Ready", TFTP server tracebacks
2684-
2685-#1073460 Node-specific kernel and ramdisk is not possible
2686-
2687-#1177932 Unable to select which pxe files to download by both series and architecture.
2688-
2689-#1181334 i386 required to install amd64
2690-
2691-#1184589 When external commands, issued by MAAS, fail, the log output does not give any information about the failure.
2692-
2693-#1187851 Newline added to end of files obtained with maas-cli
2694-
2695-#1190986 ERROR Nonce already used
2696-
2697-#1191735 TFTP server not listening on all interfaces
2698-
2699-#1210393 MAAS ipmi fails on OCPv3 Roadrunner
2700-
2701-#1228205 piston hijacks any TypeError raised by MAAS
2702-
2703-#1234880 HP ilo4 consoles default to autodetect protocol, which doesn't work
2704-
2705-#1237197 No scheduled job for images download
2706-
2707-#1238284 multiple ip address displayed for a node
2708-
2709-#1243917 'maas createsuperuser' errors out if no email address is entered.
2710-
2711-#1246531 dhcpd.conf not updated when user hits "Save cluster controller"
2712-
2713-#1246625 The power parameters used by the virsh power template are inconsistent.
2714-
2715-#1247708 Cluster interface shows up with no interface name
2716-
2717-#1248893 maas-cli listing nodes filtered by hostname doesn't work
2718-
2719-#1249435 kernel options not showing up in WebUI and not being passed at install time to one node
2720-
2721-#1250410 Search box renders incorrectly in Firefox
2722-
2723-#1268795 unable to automatically commission Cisco UCS server due to BMC user permissions
2724-
2725-#1270131 1 CPU when there are multiple cores on Intel NUC
2726-
2727-#1271056 API call for listing nodes filtered by zone
2728-
2729-#1273650 Fastpath installer does not pick up package mirror settings from MAAS
2730-
2731-#1274017 MAAS new user creation requires E-Mail address, throws wrong error when not provided
2732-
2733-#1274465 Network identity shows broadcast address instead of the network's address
2734-
2735-#1274499 dhcp lease rollover causes loss of access to management IP
2736-
2737-#1275643 When both IPMI 1.5 and 2.0 are available, MAAS should use 2.0
2738-
2739-#1279304 Node commissioning results are not displayed in the UI
2740-
2741-#1279728 Storage capacity isn't always detected
2742-
2743-#1287964 MAAS incorrectly detects / sets-up BMC information on Dell PowerEdge servers
2744-
2745-#1292491 pserv traceback when region controller not yet ready
2746-
2747-#1293661 cannot use fast path installer to deploy other than trusty
2748-
2749-#1294302 fast installer fails to PXE boot on armhf/highbank
2750-
2751-#1295035 The UI doesn't display the list of available boot images
2752-
2753-#1297814 MAAS does not advertise its capabilities
2754-
2755-#1298790 Logout page vulnerable to CSRF
2756-
2757-#1271189 support switching image streams in import ephemerals
2758-
2759-#1287310 hard to determine valid values for power parameters
2760-
2761-#1272014 MAAS prompts user to run `maas createadmin`; instead of `maas createsuperuser`
2762-
2763-#1108319 maascli could have a way to tell which cluster controllers don't have the pxe files
2764-
2765+### Major new features
2766+
2767+Advanced Networking.
2768+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.
2769+
2770+See The full Networking documentation \<networks\>.
2771+
2772+Zones.
2773+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.
2774+
2775+See physical-zones for more detail.
2776+
2777+Hardware Enablement Kernels.
2778+MAAS is now able to fetch and use hardware enablement kernels which allow kernels for newer Ubuntu releases to be used on older releases.
2779+
2780+See hardware-enablement-kernels
2781+
2782+### Minor feature changes
2783+
2784+Maas-Test.
2785+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.
2786+
2787+IPMI improvements.
2788+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.
2789+
2790+Completion of image downloading changes.
2791+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.
2792+
2793+This change also enables end-users to provide their own simplestreams data and thusly their own custom images.
2794+
2795+Cluster-driven hardware availability.
2796+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.
2797+
2798+Seamicro hardware.
2799+MAAS now supports the Seamicro 15000 hardware for power control and API-based enlistment.
2800+
2801+AMT.
2802+MAAS now supports power control using [Intel AMT](http://www.intel.com/content/www/us/en/architecture-and-technology/intel-active-management-technology.html).
2803+
2804+DNS forwarders.
2805+In MAAS's settings it's now possible to configure an upstream DNS, which will be set in the bind daemon's 'forwarders' option.
2806+
2807+Foreign DHCP servers.
2808+MAAS detects and shows you if any other DHCP servers are active on the networks that are on the cluster controller.
2809+
2810+Commissioning Results.
2811+A node's commissioning results are now shown in the UI.
2812+
2813+Renamed commands.
2814+`maas` is renamed to `maas-region-admin`. `maas-cli` is now just `maas`.
2815+
2816+### Bugs fixed in this release
2817+
2818+For full details see <https://launchpad.net/maas/+milestone/14.04>
2819+
2820+\#1227035 If a template substitution fails, the appserver crashes
2821+
2822+\#1255479 MaaS Internal Server Error 500 while parsing tags with namespaces in definition upon commissioning
2823+
2824+\#1269648 OAuth unauthorised errors mask the actual error text
2825+
2826+\#1270052 Adding an SSH key fails due to a UnicodeDecodeError
2827+
2828+\#1274024 kernel parameters are not set up in the installed OS's grub cfg
2829+
2830+\#1274190 periodic\_probe\_dhcp task raises IOError('No such device')
2831+
2832+\#1274912 Internal server error when trying to stop a node with no power type
2833+
2834+\#1274926 A node's nodegroup is autodetected using the request's IP even when the request is a manual
2835+
2836+\#1278895 When any of the commissioning scripts fails, the error reported contains the list of the scripts that *didn't* fail
2837+
2838+\#1279107 maas\_ipmi\_autodetect.py ignores command failures
2839+
2840+\#1282828 Almost impossible to provide a valid nodegroup ID when enlisting new node on API
2841+
2842+\#1283114 MAAS' DHCP server is not stopped when the number of managed interfaces is zero
2843+
2844+\#1285244 Deleting a node sometimes fails with omshell error
2845+
2846+\#1285607 maas\_ipmi\_autodetect mistakes empty slot for taken slot
2847+
2848+\#1287274 On OCPv3 Roadrunner, maas\_ipmi\_autodetect fails because LAN Channel settings can't be changed
2849+
2850+\#1287512 OCPv3 roadrunner detects IPMI as 1.5
2851+
2852+\#1289456 maas IPMI user creation fails on some DRAC systems
2853+
2854+\#1290622 report\_boot\_images does not remove images that were deleted from the cluster
2855+
2856+\#1293676 internal server error when marking nodes as using fast-path installer
2857+
2858+\#1300587 Cloud-archive selection widget is obsolete
2859+
2860+\#1301809 Report boot images no directory traceback
2861+
2862+\#1052339 MAAS only supports one "managed" (DNS/DHCP) interface per cluster controller.
2863+
2864+\#1058126 maas dbshell stacktraces in package
2865+
2866+\#1064212 If a machine is booted manually when in status "Declared" or "Ready", TFTP server tracebacks
2867+
2868+\#1073460 Node-specific kernel and ramdisk is not possible
2869+
2870+\#1177932 Unable to select which pxe files to download by both series and architecture.
2871+
2872+\#1181334 i386 required to install amd64
2873+
2874+\#1184589 When external commands, issued by MAAS, fail, the log output does not give any information about the failure.
2875+
2876+\#1187851 Newline added to end of files obtained with maas-cli
2877+
2878+\#1190986 ERROR Nonce already used
2879+
2880+\#1191735 TFTP server not listening on all interfaces
2881+
2882+\#1210393 MAAS ipmi fails on OCPv3 Roadrunner
2883+
2884+\#1228205 piston hijacks any TypeError raised by MAAS
2885+
2886+\#1234880 HP ilo4 consoles default to autodetect protocol, which doesn't work
2887+
2888+\#1237197 No scheduled job for images download
2889+
2890+\#1238284 multiple ip address displayed for a node
2891+
2892+\#1243917 'maas createsuperuser' errors out if no email address is entered.
2893+
2894+\#1246531 dhcpd.conf not updated when user hits "Save cluster controller"
2895+
2896+\#1246625 The power parameters used by the virsh power template are inconsistent.
2897+
2898+\#1247708 Cluster interface shows up with no interface name
2899+
2900+\#1248893 maas-cli listing nodes filtered by hostname doesn't work
2901+
2902+\#1249435 kernel options not showing up in WebUI and not being passed at install time to one node
2903+
2904+\#1250410 Search box renders incorrectly in Firefox
2905+
2906+\#1268795 unable to automatically commission Cisco UCS server due to BMC user permissions
2907+
2908+\#1270131 1 CPU when there are multiple cores on Intel NUC
2909+
2910+\#1271056 API call for listing nodes filtered by zone
2911+
2912+\#1273650 Fastpath installer does not pick up package mirror settings from MAAS
2913+
2914+\#1274017 MAAS new user creation requires E-Mail address, throws wrong error when not provided
2915+
2916+\#1274465 Network identity shows broadcast address instead of the network's address
2917+
2918+\#1274499 dhcp lease rollover causes loss of access to management IP
2919+
2920+\#1275643 When both IPMI 1.5 and 2.0 are available, MAAS should use 2.0
2921+
2922+\#1279304 Node commissioning results are not displayed in the UI
2923+
2924+\#1279728 Storage capacity isn't always detected
2925+
2926+\#1287964 MAAS incorrectly detects / sets-up BMC information on Dell PowerEdge servers
2927+
2928+\#1292491 pserv traceback when region controller not yet ready
2929+
2930+\#1293661 cannot use fast path installer to deploy other than trusty
2931+
2932+\#1294302 fast installer fails to PXE boot on armhf/highbank
2933+
2934+\#1295035 The UI doesn't display the list of available boot images
2935+
2936+\#1297814 MAAS does not advertise its capabilities
2937+
2938+\#1298790 Logout page vulnerable to CSRF
2939+
2940+\#1271189 support switching image streams in import ephemerals
2941+
2942+\#1287310 hard to determine valid values for power parameters
2943+
2944+\#1272014 MAAS prompts user to run maas createadmin; instead of maas createsuperuser
2945+
2946+\#1108319 maascli could have a way to tell which cluster controllers don't have the pxe files
2947
2948 1.4
2949-===
2950+---
2951
2952 (released in Ubuntu 13.10)
2953
2954-Major new features
2955-------------------
2956-
2957-LLDP collection.
2958- MAAS now collects LLDP data on each node during its
2959- commissioning cycle. The router to which the node is connected will have
2960- its MAC address parsed out of the data and made available for using as a
2961- placement constraint (passing connected_to or not_connected_to to the
2962- acquire() API call), or you can define tags using expressions such as
2963- ``//lldp:chassis/lldp:id[@type="mac"]/text() = "20:4e:7f:94:2e:10"``
2964- which would tag nodes with a router using that MAC address.
2965-
2966-New faster installer for nodes.
2967- MAAS will now make use of the new Curtin_ installer which is much quicker
2968- than the old Debian Installer process. Typically an installation now
2969- takes a couple of minutes instead of upwards of 10 minutes. To have a node
2970- use the faster installer, add the ``use-fastpath-installer`` tag to it,
2971- or click the "Use the fast installer" button on the node page.
2972-
2973-.. _Curtin: https://launchpad.net/curtin
2974-
2975-More extensible templates for DHCP, power control, PXE and DNS.
2976- Templates supplied for these activities are now all in their own template
2977- file that is customisable by the user. The files now generally live under
2978- /etc/maas/ rather than embedded in the code tree itself.
2979-
2980-Minor feature changes
2981----------------------
2982-
2983-Reworked ephemeral downloading
2984- While there is no end-user visible change, the ephemeral image download
2985- process is now driven by a data stream published by Canonical at
2986- http://maas.ubuntu.com/images/streams. In the future this will allow end
2987- users to use their own customised images by creating their own stream.
2988- The configuration for this is now also part of ``pserv.yaml``, obsoleting
2989- the maas_import_ephemerals configuration file. The config will be auto-
2990- migrated on the first run of the ``maas-import-ephemerals`` script.
2991-
2992-Improved maas-cli support
2993- Users can now manage their SSH keys and API credentials via the maas-cli
2994- tool.
2995-
2996-Django 1.5
2997- MAAS is updated to work with Django 1.5
2998-
2999-HP Moonshot Systems support.
3000- MAAS can now manage HP Moonshot Systems as any other hardware. However,
3001- in order for MAAS to power manage these systems, it requires the user
3002- to manually specify the iLO credentials before the enlistment process
3003- begins. This can be done in the ``maas_moonshot_autodetect.py``
3004- template under ``/etc/maas/templates/commissioning-user-data/snippets/``.
3005-
3006-Bugs fixed in this release
3007---------------------------
3008-#1039513 maas-import-pxe-files doesn't cryptographically verify what
3009-it downloads
3010-
3011-#1158425 maas-import-pxe-files sources path-relative config
3012-
3013-#1204507 MAAS rejects empty files
3014-
3015-#1208497 netboot flag defaults to 'true' on upgrade, even for allocated
3016-nodes
3017-
3018-#1227644 Releasing a node using the API errors with "TypeError:
3019-00:e0:81:dd:d1:0b is not JSON serializable"
3020-
3021-#1234853 MAAS returns HTTP/500 when adding a second managed interface
3022-to cluster controller
3023-
3024-#971349 With 100% of nodes in 'declared' state, pie chart is white on white
3025-
3026-#974035 Node listing does not support bulk operations
3027-
3028-#1045725 SAY clauses in PXE configs are being evaluated as they're
3029-encountered, not when the label is branched to
3030-
3031-#1054518 distro_series can be None or ""
3032-
3033-#1064777 If a node's IP address is known, it's not shown anywhere
3034-
3035-#1084807 Users are editing the machine-generated dhcpd.conf
3036-
3037-#1155607 Conflict between "DNS zone name" in Cluster controller and
3038-"Default domain for new nodes" in settings
3039-
3040-#1172336 MAAS server reference to AvahiBoot wiki page that does not exist
3041-
3042-#1185160 no way to see what user has a node allocated
3043-
3044-#1202314 Discrepancy between docs and behavior
3045-
3046-#1206222 Documentation Feedback and Site suggestions
3047-
3048-#1209039 Document that MAAS requires 'portfast' on switch ports connected
3049-to nodes
3050-
3051-#1215750 No way of tracing/debugging http traffic content in the appserver.
3052-
3053-#1223157 start_commissioning needlessly sets owner on commissioning nodes
3054-
3055-#1227081 Error in apache's log "No handlers could be found for logger
3056-"maasserver""
3057-
3058-#1233069 maas-import-pxe-files fails when md5 checksums can't be downloaded
3059-
3060-#1117415 maas dhcp responses do not have domain-name or domain-search
3061-
3062-#1136449 maas-cli get-config and set-config documentation
3063-
3064-#1175405 Pie chart says "deployed" which is inconsistent with the node
3065-list's "allocated"
3066-
3067-#1233833 Usability: deleting nodes is too easy
3068-
3069-#1185897 expose ability to re-commission node in api and cli
3070-
3071-#997092 Can't delete allocated node even if owned by self
3072+### Major new features
3073+
3074+LLDP collection.
3075+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.
3076+
3077+New faster installer for nodes.
3078+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.
3079+
3080+More extensible templates for DHCP, power control, PXE and DNS.
3081+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.
3082+
3083+### Minor feature changes
3084+
3085+Reworked ephemeral downloading
3086+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.
3087+
3088+Improved maas-cli support
3089+Users can now manage their SSH keys and API credentials via the maas-cli tool.
3090+
3091+Django 1.5
3092+MAAS is updated to work with Django 1.5
3093+
3094+HP Moonshot Systems support.
3095+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/`.
3096+
3097+### Bugs fixed in this release
3098+
3099+\#1039513 maas-import-pxe-files doesn't cryptographically verify what it downloads
3100+
3101+\#1158425 maas-import-pxe-files sources path-relative config
3102+
3103+\#1204507 MAAS rejects empty files
3104+
3105+\#1208497 netboot flag defaults to 'true' on upgrade, even for allocated nodes
3106+
3107+\#1227644 Releasing a node using the API errors with "TypeError: 00:e0:81:dd:d1:0b is not JSON serializable"
3108+
3109+\#1234853 MAAS returns HTTP/500 when adding a second managed interface to cluster controller
3110+
3111+\#971349 With 100% of nodes in 'declared' state, pie chart is white on white
3112+
3113+\#974035 Node listing does not support bulk operations
3114+
3115+\#1045725 SAY clauses in PXE configs are being evaluated as they're encountered, not when the label is branched to
3116+
3117+\#1054518 distro\_series can be None or ""
3118+
3119+\#1064777 If a node's IP address is known, it's not shown anywhere
3120+
3121+\#1084807 Users are editing the machine-generated dhcpd.conf
3122+
3123+\#1155607 Conflict between "DNS zone name" in Cluster controller and "Default domain for new nodes" in settings
3124+
3125+\#1172336 MAAS server reference to AvahiBoot wiki page that does not exist
3126+
3127+\#1185160 no way to see what user has a node allocated
3128+
3129+\#1202314 Discrepancy between docs and behavior
3130+
3131+\#1206222 Documentation Feedback and Site suggestions
3132+
3133+\#1209039 Document that MAAS requires 'portfast' on switch ports connected to nodes
3134+
3135+\#1215750 No way of tracing/debugging http traffic content in the appserver.
3136+
3137+\#1223157 start\_commissioning needlessly sets owner on commissioning nodes
3138+
3139+\#1227081 Error in apache's log "No handlers could be found for logger "maasserver""
3140+
3141+\#1233069 maas-import-pxe-files fails when md5 checksums can't be downloaded
3142+
3143+\#1117415 maas dhcp responses do not have domain-name or domain-search
3144+
3145+\#1136449 maas-cli get-config and set-config documentation
3146+
3147+\#1175405 Pie chart says "deployed" which is inconsistent with the node list's "allocated"
3148+
3149+\#1233833 Usability: deleting nodes is too easy
3150+
3151+\#1185897 expose ability to re-commission node in api and cli
3152+
3153+\#997092 Can't delete allocated node even if owned by self
3154
3155
3156=== renamed file 'docs/cluster-configuration.rst' => 'docs/cluster-configuration.md'
3157--- docs/cluster-configuration.rst 2014-08-22 00:13:24 +0000
3158+++ docs/cluster-configuration.md 2015-04-17 21:06:27 +0000
3159@@ -1,146 +1,71 @@
3160-.. -*- mode: rst -*-
3161-
3162-.. _cluster-configuration:
3163-
3164 Cluster Configuration
3165 =====================
3166
3167-Before any of MAAS's features can be used for the first time, you must have
3168-a cluster controller and configure it to manage at least one network of
3169-nodes. Each node in the cluster should be attached to one of these networks.
3170-(In addition, a node can be attached to any number of networks that are not
3171-managed by MAAS.)
3172-
3173-Managing a network normally means that MAAS will serve DHCP from the cluster
3174-controller. **Do this only on a network that was set up with this in mind.**
3175-Running your own DHCP server that competes with an existing one that's
3176-already managing the network can cause serious disruption, and it can be hard
3177-for administrators to track the source of the problem. Worse, the problems
3178-may not become immediately noticeable. Make sure you understand the
3179-implications of running a DHCP server before doing this. If MAAS detects any
3180-DHCP servers already running on these networks, it will show them on the
3181-cluster's configuration page.
3182-
3183+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.)
3184+
3185+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.
3186
3187 Network requirements
3188 --------------------
3189
3190-The cluster controller manages a network of nodes through one of its interfaces
3191-as defined in MAAS. Cluster interfaces are discovered automatically, though
3192-this may not happen e.g. if the network interface was down when MAAS was
3193-installed.
3194-
3195-When a cluster controller manages nodes on a network through one of its
3196-interfaces, the nodes must be on the same subnet as the cluster interface.
3197-This is for two reasons:
3198-
3199-1. If the cluster controller is configured to manage DHCP, the nodes must be
3200- able to configure their own network interfaces using MAAS's DHCP server.
3201- This means that either they must be on the same subnet, or that DHCP packets
3202- are being specially routed between the nodes' subnet and MAAS's DHCP server.
3203-2. The cluster controller must be able to find nodes' IP addresses based on
3204- their MAC addresses, by inspecting its ARP cache. This implies that the
3205- nodes and the cluster controller must be on the same physical subnet.
3206-
3207+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.
3208+
3209+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:
3210+
3211+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.
3212+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.
3213
3214 Cluster acceptance
3215 ------------------
3216
3217-If you install your first cluster controller on the same system as the region
3218-controller, as is the case when you install the full "maas" ubuntu package,
3219-it will be automatically accepted by default (but not yet configured, see
3220-below). Any other cluster controllers you set up will show up in the user
3221-interface as "pending," until you manually accept them into the MAAS.
3222-
3223-To accept a cluster controller, visit the "pending clusters" section of the
3224-Clusters page:
3225-
3226-.. image:: media/cluster-accept.png
3227-
3228-You can either click on "Accept all" or click on the edit icon to edit
3229-the cluster. After clicking on the edit icon, you will see this page:
3230-
3231-.. image:: media/cluster-edit.png
3232-
3233-Here you can change the cluster's name as it appears in the UI, its DNS
3234-zone, and its status. Accepting the cluster changes its status from
3235-"pending" to "accepted."
3236-
3237-Now that the cluster controller is accepted, you can configure one or more of
3238-its network interfaces to be managed by MAAS. This will enable the cluster
3239-controller to manage nodes attached to those networks. The next section
3240-explains how to do this and what choices are to be made.
3241-
3242+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.
3243+
3244+To accept a cluster controller, visit the "pending clusters" section of the Clusters page:
3245+
3246+![image](media/cluster-accept.png)
3247+
3248+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:
3249+
3250+![image](media/cluster-edit.png)
3251+
3252+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."
3253+
3254+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.
3255
3256 Cluster interface management
3257 ----------------------------
3258
3259-MAAS automatically recognises the network interfaces on each cluster
3260-controller. Some (though not necessarily all) of these will be connected to
3261-networks where you want to manage nodes. A connection between a cluster
3262-controller and a network is called a `cluster interface`. Each cluster
3263-interface is built on exactly one network interface, though it's possible for
3264-two cluster interfaces to use the same network interface card.
3265-
3266-We recommend letting your cluster controller act as a DHCP server for the
3267-networks it manages, by configuring the corresponding cluster interfaces in
3268-the MAAS user interface.
3269-
3270-As an example, we will configure the cluster controller to manage a network
3271-on interface ``eth0``. Click on the edit icon for the cluster interface on
3272-network interface ``eth0``, which takes us to this page:
3273-
3274-.. image:: media/cluster-interface-edit.png
3275-
3276-Here you can select to what extent you want the cluster controller to manage
3277-the network:
3278-
3279-#. DHCP only - this will run a DHCP server on your cluster
3280-#. DHCP and DNS - this will run a DHCP server on the cluster *and* configure
3281- the DNS server included with the region controller so that it can be used
3282- to look up hosts on this network by name.
3283-
3284-If you set the interface to be managed, you now need to provide all of the
3285-usual DHCP details in the input fields below. Once done, click "Save
3286-interface". The cluster controller will now be able to boot nodes on this
3287-network.
3288-
3289-There is also an option to leave the network unmanaged. Use this for
3290-networks where you don't want to manage any nodes. Or, if you do want to
3291-manage nodes but don't want the cluster controller to serve DHCP, you may be
3292-able to get by without it. This is explained in :ref:`manual-dhcp`.
3293-
3294-.. _static-ip-address:
3295-
3296-Static vs Dynamic IP Addresses
3297-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3298-
3299-On the cluster interface edit page, there are fields to enter both a dynamic
3300-and a static range of IP addresses. It is mandatory to enter the dynamic range
3301-if you are managing DHCP on this interface, but the static range is optional.
3302-
3303-Dynamic addresses are given to both unknown devices booting on this network,
3304-and Nodes that are commissioning. Dynamic addresses are allocated by the
3305-DHCP server and may change at any time.
3306-
3307-Static addresses are given to Nodes when they are allocated to a user and
3308-started up, and returned to the pool only when the Node is de-allocated.
3309-Static addresses are allocated by MAAS, and are guaranteed not to change while
3310-allocated. If you are managing DNS on this network, only static IP addresses
3311-are given DNS entries with the Node's name.
3312-
3313-If you do not configure the static range, then nodes will only get dynamic
3314-IP addresses and will never get a DNS entry.
3315-
3316-IP addresses in the static range are also available for reservation by users
3317-using the :doc:`api`. This prevents MAAS from allocating the reserved
3318-IP to any Nodes or other devices, which allows users to assign it freely
3319-to their own hosts/devices on the same network, such as LXC containers.
3320-
3321+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.
3322+
3323+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.
3324+
3325+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:
3326+
3327+![image](media/cluster-interface-edit.png)
3328+
3329+Here you can select to what extent you want the cluster controller to manage the network:
3330+
3331+1. DHCP only - this will run a DHCP server on your cluster
3332+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.
3333+
3334+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.
3335+
3336+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.
3337+
3338+### Static vs Dynamic IP Addresses
3339+
3340+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.
3341+
3342+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.
3343+
3344+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.
3345+
3346+If you do not configure the static range, then nodes will only get dynamic IP addresses and will never get a DNS entry.
3347+
3348+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.
3349
3350 Multiple networks
3351 -----------------
3352
3353-A single cluster controller can manage more than one network, each from a
3354-different cluster interface. This may help you scale your cluster to larger
3355-numbers of nodes, or it may be a requirement of your network architecture.
3356+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.
3357+
3358
3359=== removed file 'docs/conf.py'
3360--- docs/conf.py 2015-03-25 13:22:48 +0000
3361+++ docs/conf.py 1970-01-01 00:00:00 +0000
3362@@ -1,305 +0,0 @@
3363-# -*- coding: utf-8 -*-
3364-#
3365-# MAAS documentation build configuration file, created by
3366-# sphinx-quickstart on Thu Jan 19 14:48:25 2012.
3367-#
3368-# This file is execfile()d with the current directory set to its containing dir.
3369-#
3370-# Note that not all possible configuration values are present in this
3371-# autogenerated file.
3372-#
3373-# All configuration values have a default; values that are commented out
3374-# serve to show the default.
3375-
3376-# Import maas' settings.
3377-from os import environ
3378-
3379-
3380-environ.setdefault("DJANGO_SETTINGS_MODULE", "maas.settings")
3381-
3382-# If extensions (or modules to document with autodoc) are in another directory,
3383-# add these directories to sys.path here. If the directory is relative to the
3384-# documentation root, use os.path.abspath to make it absolute, like shown here.
3385-
3386-import sys, os
3387-# Include '.' in the path so that our custom extension, 'versions', can
3388-# be found.
3389-sys.path.insert(0, os.path.abspath('.'))
3390-
3391-# -- Multiple documentation options.
3392-
3393-# Add a widget to switch between different versions of the documentation to
3394-# each generated page.
3395-add_version_switcher = False
3396-
3397-# In order for the version widget to be able to redirect correctly to the
3398-# other versions of the documentation, each version of the documentation
3399-# has to be accessible at the following addresses:
3400-# /<doc_prefix>/ -> documentation for trunk.
3401-# /<doc_prefix>1.4/ -> documentation for 1.4.
3402-# etc.
3403-doc_prefix = 'docs'
3404-
3405-# Path of the JSON document, relative to homepage of the documentation for trunk
3406-# (i.e. '/<doc_prefix>/'), with the list of the versions to include in the
3407-# version switcher widget.
3408-versions_path = '_static/versions.js'
3409-
3410-# Versions to include in the version switcher.
3411-# Note that the version switcher fetches the list of the documentation versions
3412-# from the list published by the trunk documentation (i.e. in '/<doc_prefix>/').
3413-# This means the following list is meaningful only for trunk.
3414-# The first item should be the development version.
3415-from collections import OrderedDict
3416-doc_versions = OrderedDict([
3417- ('dev', 'Development trunk'),
3418- ('1.7', 'MAAS 1.7'),
3419- ('1.6', 'MAAS 1.6'),
3420- ('1.5', 'MAAS 1.5'),
3421- ('1.4', 'MAAS 1.4'),
3422- ('1.3', 'MAAS 1.3'),
3423- ('1.2', 'MAAS 1.2'),
3424-])
3425-
3426-# -- General configuration -----------------------------------------------------
3427-
3428-# If your documentation needs a minimal Sphinx version, state it here.
3429-#needs_sphinx = '1.0'
3430-
3431-# Add any Sphinx extension module names here, as strings. They can be extensions
3432-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
3433-extensions = [
3434- 'sphinx.ext.autodoc',
3435- 'sphinx.ext.autosummary',
3436- 'sphinx.ext.doctest',
3437- 'sphinx.ext.intersphinx',
3438- 'sphinx.ext.pngmath',
3439- 'sphinx.ext.viewcode',
3440- 'versions',
3441- ]
3442-
3443-# Add any paths that contain templates here, relative to this directory.
3444-templates_path = ['_templates']
3445-
3446-# The suffix of source filenames.
3447-source_suffix = '.rst'
3448-
3449-# The encoding of source files.
3450-#source_encoding = 'utf-8-sig'
3451-
3452-# The master toctree document.
3453-master_doc = 'index'
3454-
3455-# General information about the project.
3456-project = u'MAAS'
3457-copyright = u'2012-2014, MAAS Developers'
3458-
3459-# The version info for the project you're documenting, acts as replacement for
3460-# |version| and |release|, also used in various other places throughout the
3461-# built documents.
3462-#
3463-# The short X.Y version.
3464-version = doc_versions.items()[0][0]
3465-# The full version, including alpha/beta/rc tags.
3466-release = version
3467-
3468-# The language for content autogenerated by Sphinx. Refer to documentation
3469-# for a list of supported languages.
3470-#language = None
3471-
3472-# There are two options for replacing |today|: either, you set today to some
3473-# non-false value, then it is used:
3474-#today = ''
3475-# Else, today_fmt is used as the format for a strftime call.
3476-#today_fmt = '%B %d, %Y'
3477-
3478-# List of patterns, relative to source directory, that match files and
3479-# directories to ignore when looking for source files.
3480-exclude_patterns = ['_build', '_templates']
3481-
3482-# The reST default role (used for this markup: `text`) to use for all documents.
3483-#default_role = None
3484-
3485-# If true, '()' will be appended to :func: etc. cross-reference text.
3486-#add_function_parentheses = True
3487-
3488-# If true, the current module name will be prepended to all description
3489-# unit titles (such as .. function::).
3490-#add_module_names = True
3491-
3492-# If true, sectionauthor and moduleauthor directives will be shown in the
3493-# output. They are ignored by default.
3494-#show_authors = False
3495-
3496-# The name of the Pygments (syntax highlighting) style to use.
3497-pygments_style = 'sphinx'
3498-
3499-# A list of ignored prefixes for module index sorting.
3500-#modindex_common_prefix = []
3501-
3502-# AutoDoc <http://sphinx.pocoo.org/ext/autodoc.html>
3503-autodoc_default_flags = ['members', 'show-inheritance']
3504-autodoc_member_order = 'bysource'
3505-autodoc_docstring_signature = True
3506-
3507-# AutoSummary <http://sphinx.pocoo.org/ext/autosummary.html>
3508-autosummary_generate = True
3509-
3510-# -- Options for HTML output ---------------------------------------------------
3511-
3512-# The theme to use for HTML and HTML Help pages. See the documentation for
3513-# a list of builtin themes.
3514-html_theme = 'maas'
3515-
3516-# Theme options are theme-specific and customize the look and feel of a theme
3517-# further. For a list of options available for each theme, see the
3518-# documentation.
3519-#html_theme_options = {}
3520-
3521-# Add any paths that contain custom themes here, relative to this directory.
3522-#html_theme_path = []
3523-
3524-html_theme_path = ['_templates']
3525-
3526-# The name for this set of Sphinx documents. If None, it defaults to
3527-# "<project> v<release> documentation".
3528-#html_title = None
3529-
3530-# A shorter title for the navigation bar. Default is the same as html_title.
3531-#html_short_title = None
3532-
3533-# The name of an image file (relative to this directory) to place at the top
3534-# of the sidebar.
3535-html_logo = 'media/maas-logo-200.png'
3536-
3537-# The name of an image file (within the static path) to use as favicon of the
3538-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
3539-# pixels large.
3540-html_favicon = 'media/maas.ico'
3541-
3542-# Add any paths that contain custom static files (such as style sheets) here,
3543-# relative to this directory. They are copied after the builtin static files,
3544-# so a file named "default.css" will overwrite the builtin "default.css".
3545-html_static_path = ['_static']
3546-
3547-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
3548-# using the given strftime format.
3549-html_last_updated_fmt = '%b %d, %Y'
3550-
3551-# If true, SmartyPants will be used to convert quotes and dashes to
3552-# typographically correct entities.
3553-#html_use_smartypants = True
3554-
3555-# Custom sidebar templates, maps document names to template names.
3556-#html_sidebars = {}
3557-
3558-# Additional templates that should be rendered to pages, maps page names to
3559-# template names.
3560-#html_additional_pages = {}
3561-
3562-# If false, no module index is generated.
3563-#html_domain_indices = True
3564-
3565-# If false, no index is generated.
3566-#html_use_index = True
3567-
3568-# If true, the index is split into individual pages for each letter.
3569-#html_split_index = False
3570-
3571-# If true, links to the reST sources are added to the pages.
3572-#html_show_sourcelink = True
3573-
3574-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
3575-html_show_sphinx = True
3576-
3577-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
3578-html_show_copyright = True
3579-
3580-# If true, an OpenSearch description file will be output, and all pages will
3581-# contain a <link> tag referring to it. The value of this option must be the
3582-# base URL from which the finished HTML is served.
3583-#html_use_opensearch = ''
3584-
3585-# This is the file name suffix for HTML files (e.g. ".xhtml").
3586-#html_file_suffix = None
3587-
3588-# Output file base name for HTML help builder.
3589-htmlhelp_basename = 'MAASdoc'
3590-
3591-
3592-# -- Options for LaTeX output --------------------------------------------------
3593-
3594-# The paper size ('letter' or 'a4').
3595-latex_paper_size = 'a4'
3596-
3597-# The font size ('10pt', '11pt' or '12pt').
3598-#latex_font_size = '10pt'
3599-
3600-# Grouping the document tree into LaTeX files. List of tuples
3601-# (source start file, target name, title, author, documentclass [howto/manual]).
3602-latex_documents = [
3603- ('index', 'MAAS.tex', u'MAAS Documentation',
3604- u'MAAS Developers', 'manual'),
3605-]
3606-
3607-# The name of an image file (relative to this directory) to place at the top of
3608-# the title page.
3609-#latex_logo = None
3610-
3611-# For "manual" documents, if this is true, then toplevel headings are parts,
3612-# not chapters.
3613-#latex_use_parts = False
3614-
3615-# If true, show page references after internal links.
3616-#latex_show_pagerefs = False
3617-
3618-# If true, show URL addresses after external links.
3619-#latex_show_urls = False
3620-
3621-# Additional stuff for the LaTeX preamble.
3622-#latex_preamble = ''
3623-
3624-# Documents to append as an appendix to all manuals.
3625-#latex_appendices = []
3626-
3627-# If false, no module index is generated.
3628-#latex_domain_indices = True
3629-
3630-
3631-# -- Options for manual page output --------------------------------------------
3632-
3633-# One entry per manual page. List of tuples
3634-# (source start file, name, description, authors, manual section).
3635-man_pages = [
3636- ('man/maas.8', 'maas', u'MAAS API commandline utility',
3637- [u'Canonical 2013-2014'], 8),
3638- ('man/maas-region-admin.8', 'maas-region-admin', u'MAAS administration tool',
3639- [u'Canonical 2013-2014'], 8)
3640-]
3641-
3642-
3643-# Example configuration for intersphinx: refer to the Python standard library.
3644-intersphinx_mapping = {'http://docs.python.org/': None}
3645-
3646-# Gather information about the branch and the build date.
3647-from subprocess import check_output, CalledProcessError
3648-try:
3649- bzr_last_revision_number = check_output(['bzr', 'revno'])
3650- bzr_last_revision_date = check_output(['bzr', 'version-info', '--template={date}', '--custom'])
3651- bzr_build_date = check_output(['bzr', 'version-info', '--template={build_date}', '--custom'])
3652-except (CalledProcessError):
3653- # not a bzr repository
3654- bzr_last_revision_number = 'unknown'
3655- bzr_last_revision_date = check_output(['date', '-u', '+%Y-%m-%d %H:%M:%S %z'])
3656- bzr_build_date = bzr_last_revision_date
3657-
3658-
3659-# Populate html_context with the variables used in the templates.
3660-html_context = {
3661- 'add_version_switcher': 'true' if add_version_switcher else 'false',
3662- 'versions_json_path': '/'.join(['', doc_prefix, versions_path]),
3663- 'doc_prefix': doc_prefix,
3664- 'bzr_last_revision_date': bzr_last_revision_date,
3665- 'bzr_last_revision_number': bzr_last_revision_number,
3666- 'bzr_build_date': bzr_build_date,
3667-}
3668
3669=== renamed file 'docs/configure.rst' => 'docs/configure.md'
3670--- docs/configure.rst 2015-03-25 13:22:48 +0000
3671+++ docs/configure.md 2015-04-17 21:06:27 +0000
3672@@ -1,268 +1,175 @@
3673 Additional Configuration
3674 ========================
3675
3676-
3677-.. _manual-dhcp:
3678-
3679 Manual DHCP configuration
3680 -------------------------
3681
3682-DHCP is needed in order for MAAS to boot and control nodes. However, there
3683-are some circumstances under which you may not wish a cluster controller to
3684-handle DHCP address assignments for the network. In these instances, the
3685-existing DHCP server for the network will need its configuration altered to
3686-allow MAAS to enlist and control nodes automatically.
3687-
3688-.. note::
3689- If you don't let MAAS manage DHCP, then MAAS will not be able to allocate
3690- its :ref:`static IP addresses <static-ip-address>` to Nodes.
3691+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.
3692+
3693+> **note**
3694+
3695+> 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.
3696
3697 At the very least the "filename" option should be set to "pxelinux.0".
3698
3699-How to configure this depends on what software you use as a DHCP server. If
3700-you are using the ISC DHCP server, for example, the configuration entry might
3701-look something like this::
3702-
3703- subnet 192.168.122.0 netmask 255.255.255.0 {
3704- filename "pxelinux.0";
3705- option subnet-mask 255.255.255.0;
3706- option broadcast-address 192.168.122.255;
3707- option domain-name-servers 192.168.122.136;
3708- range dynamic-bootp 192.168.122.5 192.168.122.135;
3709- }
3710-
3711-When doing this, leave the cluster controller's interface in the "unmanaged"
3712-state.
3713-
3714-If your cluster controller is in charge of nodes on more than one network
3715-through different network interfaces, there is an additional complication.
3716-Without the DHCP server built into the cluster controller, MAAS may not
3717-know which of the cluster controller's IP addresses each node should use
3718-for downloading its installer image. If you want to support this situation,
3719-ensure that all of the nodes can reach all of the cluster controller's
3720-network addresses.
3721-
3722-
3723-.. _ssl:
3724+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:
3725+
3726+ subnet 192.168.122.0 netmask 255.255.255.0 {
3727+ filename "pxelinux.0";
3728+ option subnet-mask 255.255.255.0;
3729+ option broadcast-address 192.168.122.255;
3730+ option domain-name-servers 192.168.122.136;
3731+ range dynamic-bootp 192.168.122.5 192.168.122.135;
3732+ }
3733+
3734+When doing this, leave the cluster controller's interface in the "unmanaged" state.
3735+
3736+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.
3737
3738 SSL Support
3739 -----------
3740
3741-If you want secure access to your MAAS web UI/API, you need to do a few
3742-things. First, turn on SSL support in Apache::
3743-
3744- $ sudo a2enmod ssl
3745-
3746-Ensure that the Apache config file from ``etc/maas/maas-http.conf`` is
3747-included in ``/etc/apache2/conf.d/``, then edit
3748-``/etc/maas/maas_local_settings.py`` and change DEFAULT_MAAS_URL so that it
3749-uses https instead of http.
3750-
3751-Now, restart Apache::
3752-
3753- $ sudo service apache2 restart
3754-
3755-At this point you will be able to access the MAAS web server using https but
3756-the default SSL certificate is insecure. Please generate your own and then
3757-edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the
3758-certificate.
3759-
3760+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:
3761+
3762+ $ sudo a2enmod ssl
3763+
3764+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.
3765+
3766+Now, restart Apache:
3767+
3768+ $ sudo service apache2 restart
3769+
3770+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.
3771
3772 Choosing a series to install
3773 ----------------------------
3774
3775-You may have some specific reason to choose a particular version of Ubuntu
3776-to install on your nodes, perhaps based around package availability,
3777-hardware support or some other reason.
3778-
3779-It is possible to choose a specific series from those available in a
3780-number of ways.
3781-
3782-From the user interface
3783-^^^^^^^^^^^^^^^^^^^^^^^
3784-
3785-The web-based user interface makes it easy to select which Ubuntu series you
3786-wish to install on an individual node. When either adding a node
3787-manually, or on the node page when the node has been automatically
3788-discovered but before it is accepted, there is a drop down menu to select
3789-the version of Ubuntu you wish to install.
3790-
3791-.. image:: media/series.*
3792-
3793-The menu will always list all the currently available series according
3794-to which boot images are available.
3795-
3796-Using the maas command
3797-^^^^^^^^^^^^^^^^^^^^^^
3798-
3799-It is also possible to select a series using the maas command. This
3800-can be done on a per node basis with::
3801-
3802- $ maas <profile> node update <system_id> distro_series="<value>"
3803-
3804-Where the string contains one of the valid, available distro series (e.g.
3805-"trusty") or is empty for the default value.
3806-
3807-
3808-.. _preseed:
3809+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.
3810+
3811+It is possible to choose a specific series from those available in a number of ways.
3812+
3813+### From the user interface
3814+
3815+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.
3816+
3817+![image](media/series.*)
3818+
3819+The menu will always list all the currently available series according to which boot images are available.
3820+
3821+### Using the maas command
3822+
3823+It is also possible to select a series using the maas command. This can be done on a per node basis with:
3824+
3825+ $ maas <profile> node update <system_id> distro_series="<value>"
3826+
3827+Where the string contains one of the valid, available distro series (e.g. "trusty") or is empty for the default value.
3828
3829 Altering the Preseed file
3830 -------------------------
3831
3832-.. warning::
3833- Do not try to alter the preseed files if you don't have a good
3834- understanding of what you are doing. Altering the installed version
3835- of Ubuntu can prevent MAAS from working as intended, and may have
3836- security and stability consequences.
3837-
3838-When MAAS commissions a node it installs a version of Ubuntu. The
3839-installation is performed using a 'preseed' file, which is
3840-effectively a list of answers to the questions you would get were
3841-you to run the installer manually.
3842-The preseed file used by MAAS is carefully made so that the
3843-target node can be brought up and do all the jobs expected of it.
3844-However, in exceptional circumstances, you may wish to alter the
3845-pressed file to work around some issue.
3846-There are actually two preseed files, stored here::
3847-
3848- /etc/maas/preseeds/generic
3849- /etc/maas/preseeds/preseed-master
3850-
3851-The generic file actually references the preseed-master file, and is
3852-used to set conditional parameters based on the type of series and
3853-architecture to install as well as to define the minimum set of install
3854-packages and to tidy up the PXE boot process if that has been used for
3855-the node. Unless you have a specific need to change where install
3856-packages come from, you should not need to edit this file.
3857-
3858-For the more usual sorts of things you may wish to change, you should
3859-edit the preseed-master file. For example, depending on your network
3860-you may wish to change the clock settings::
3861+> **warning**
3862+
3863+> 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.
3864+
3865+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:
3866+
3867+ /etc/maas/preseeds/generic
3868+ /etc/maas/preseeds/preseed-master
3869+
3870+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.
3871+
3872+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:
3873
3874 # Local clock (set to UTC and use ntp)
3875 d-i clock-setup/utc boolean true
3876 d-i clock-setup/ntp boolean true
3877 d-i clock-setup/ntp-server string ntp.ubuntu.com
3878
3879-Having consistent clocks is very important to the working of your MAAS
3880-system overall. If your nodes however cannot freely access the Internet,
3881-the supplied NTP server is not going to be very useful, and you may
3882-find it better to run an ntp service on the MAAS controller and change
3883-the `ntp.ubuntu.com` in the last line for a more appropriate server.
3884-
3885-One thing you may wish to alter in the preseed file is the disk
3886-partitioning. This is a simple recipe that creates a swap partition and
3887-uses the rest of the disk for one large root filesystem::
3888-
3889- partman-auto/text/atomic_scheme ::
3890-
3891- 500 10000 1000000 ext3
3892- $primary{ }
3893- $bootable{ }
3894- method{ format }
3895- format{ }
3896- use_filesystem{ }
3897- filesystem{ ext3 }
3898- mountpoint{ / } .
3899-
3900- 64 512 300% linux-swap
3901- method{ swap }
3902- format{ } .
3903-
3904-
3905-Here the root partition must be at least 500 mb, and has effectively no
3906-maximum size. The swap partition ranges from 64 MB to 3 times the system's
3907-ram.
3908-Adding `$bootable{ }` to make the partition bootable, and $primary{ }
3909-marks it as the primary partition. The other specifiers used are:
3910-
3911-*method{ format }*
3912- Used to make the partition be formatted. For swap partitions,
3913- change it to "swap". To create a new partition but do not
3914- format it, change "format" to "keep" (such a partition can be
3915- used to reserve for future use some disk space).
3916-*format{ }*
3917- Also needed to make the partition be formatted.
3918-*use_filesystem{ }*
3919- Specifies that the partition has a filesystem on it.
3920-*filesystem{ ext3 }*
3921- Specifies the filesystem to put on the partition.
3922-*mountpoint{ / }*
3923- Where to mount the partition.
3924-
3925-For more information on preseed options, you should refer to
3926-`the official Ubuntu documentation
3927-<https://help.ubuntu.com/12.04/installation-guide/i386/preseed-contents.html>`_
3928-
3929-.. note::
3930- Future versions of MAAS are likely to replace this type of automatic
3931- installation with a different installer.
3932-
3933+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.
3934+
3935+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:
3936+
3937+ partman-auto/text/atomic_scheme ::
3938+
3939+ 500 10000 1000000 ext3
3940+ $primary{ }
3941+ $bootable{ }
3942+ method{ format }
3943+ format{ }
3944+ use_filesystem{ }
3945+ filesystem{ ext3 }
3946+ mountpoint{ / } .
3947+
3948+ 64 512 300% linux-swap
3949+ method{ swap }
3950+ format{ } .
3951+
3952+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:
3953+
3954+*method{ format }*
3955+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).
3956+
3957+*format{ }*
3958+Also needed to make the partition be formatted.
3959+
3960+*use\_filesystem{ }*
3961+Specifies that the partition has a filesystem on it.
3962+
3963+*filesystem{ ext3 }*
3964+Specifies the filesystem to put on the partition.
3965+
3966+*mountpoint{ / }*
3967+Where to mount the partition.
3968+
3969+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)
3970+
3971+> **note**
3972+
3973+> Future versions of MAAS are likely to replace this type of automatic installation with a different installer.
3974
3975 Installing additional clusters
3976 ------------------------------
3977
3978-In an environment comprising large numbers of nodes, it is likely that you will
3979-want to organise the nodes on a more distributed basis. The standard install of
3980-the MAAS region controller includes a cluster controller, but it is
3981-possible to add additional cluster controllers to the configuration, as
3982-shown in the diagram below:
3983-
3984-.. image:: media/orientation_architecture-diagram.*
3985-
3986-Each cluster controller will need to run on a separate Ubuntu server.
3987-Installing and configuring the software is straightforward though::
3988-
3989- $ sudo apt-get install maas-cluster-controller
3990-
3991-This meta-package will install all the basic requirements of the system.
3992-However, you may also wish or need to run DHCP and/or DNS services, in
3993-which case you should also specify these::
3994-
3995- $ sudo apt-get install maas-cluster-controller maas-dhcp maas-dns
3996-
3997-
3998-Configuring the cluster controller
3999-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4000-
4001-Once the packages are installed, the cluster controller needs to know
4002-where to look for the region controller. This is achieved using `dpkg` to
4003-configure the software::
4004-
4005- $ dpkg-reconfigure maas-cluster-controller
4006-
4007-.. image:: media/cluster-config.*
4008-
4009-The configuration script should then bring up a screen where you can
4010-enter the IP address of the region controller. Additionally, you will
4011-need to import the distro image files locally for commissioning::
4012-
4013- $ maas maas node-groups import-boot-images
4014+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:
4015+
4016+![image](media/orientation_architecture-diagram.*)
4017+
4018+Each cluster controller will need to run on a separate Ubuntu server. Installing and configuring the software is straightforward though:
4019+
4020+ $ sudo apt-get install maas-cluster-controller
4021+
4022+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:
4023+
4024+ $ sudo apt-get install maas-cluster-controller maas-dhcp maas-dns
4025+
4026+### Configuring the cluster controller
4027+
4028+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:
4029+
4030+ $ dpkg-reconfigure maas-cluster-controller
4031+
4032+![image](media/cluster-config.*)
4033+
4034+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:
4035+
4036+ $ maas maas node-groups import-boot-images
4037
4038 …and optionally set up the DHCP and DNS for the cluster by either:
4039
4040-*Using the web UI*
4041- Follow the instructions at :doc:`cluster-configuration` to
4042- use the web UI to set up your cluster controller.
4043-
4044-*Using the command line client*
4045- First :ref:`logging in to the API <api-key>` and then
4046- :ref:`following this procedure <cli-dhcp>`
4047-
4048+*Using the web UI*
4049+Follow the instructions at cluster-configuration to use the web UI to set up your cluster controller.
4050+
4051+*Using the command line client*
4052+First logging in to the API \<api-key\> and then following this procedure \<cli-dhcp\>
4053
4054 Client-side DNS configuration
4055 -----------------------------
4056
4057-When using a third party tool such as ``juju`` it will need to be able to
4058-resolve the hostnames that the MAAS API returns to it. In order for this to
4059-happen, *client-side DNS* must be configured to point to MAAS's DNS
4060-server. Generally speaking, this is a simple case of adding the following
4061-line to the ``/etc/resolv.conf`` file on your client host::
4062-
4063- nameserver <IP OF MAAS DNS HOST>
4064-
4065-replacing the <IP OF MAAS DNS HOST> with the actual IP address of the host
4066-running the MAAS DNS server.
4067-
4068-However, for hosts using the ``resolvconf`` package, please read its
4069-documentation for more information.
4070+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:
4071+
4072+ nameserver <IP OF MAAS DNS HOST>
4073+
4074+replacing the \<IP OF MAAS DNS HOST\> with the actual IP address of the host running the MAAS DNS server.
4075+
4076+However, for hosts using the `resolvconf` package, please read its documentation for more information.
4077+
4078
4079=== renamed file 'docs/development/building-packages.rst' => 'docs/development/building-packages.md'
4080--- docs/development/building-packages.rst 2014-02-26 16:56:23 +0000
4081+++ docs/development/building-packages.md 2015-04-17 21:06:27 +0000
4082@@ -1,76 +1,61 @@
4083 Building Ubuntu packages of MAAS
4084 ================================
4085
4086-Using a virtual machine from a cloud provider seems to be easier and
4087-less hassle than using a local VM or LXC container, but the same
4088-recipe ought to apply.
4089-
4090-You need to build on the same OS that the package will be targeted to,
4091-so use a Precise instance to make packages for Precise, for example.
4092-
4093-#. Start up an instance, log in, and bring it up to date::
4094-
4095- sudo apt-get update && sudo apt-get upgrade
4096-
4097-#. Get the appropriate packaging branch::
4098-
4099- bzr branch lp:~maas-maintainers/maas/packaging{...}
4100-
4101- The `MAAS Maintainers <https://launchpad.net/~maas-maintainers>`_
4102- own all the `official MAAS branches`_.
4103-
4104-#. Move into the new branch directory.
4105-
4106-#. Check that all the build dependencies are installed. The
4107- dependencies are defined in ``debian/control``::
4108-
4109- fgrep -i build-depends -A 10 debian/control
4110-
4111- This will yield, for example::
4112-
4113- Build-Depends: debhelper (>= 8.1.0~),
4114- dh-apport,
4115- po-debconf,
4116- python (>= 2.7),
4117- python-distribute,
4118- python-django
4119- Standards-Version: 3.9.3
4120- ...
4121-
4122- Install these dependencies::
4123-
4124- sudo apt get install \
4125- debhelper dh-apport po-debconf python \
4126- python-distribute python-django
4127-
4128-#. Edit ``debian/changelog`` so it contains:
4129-
4130- * the right upstream revision number in the version,
4131-
4132- * the series you're building for; if ``UNRELEASED`` appears in the
4133- first entry, ``s/UNRELEASED/trusty/`` (or the series you want),
4134-
4135- * the name and email address that correspond to the PGP key you
4136- want to use to sign the package; these appear near the end of the
4137- topmost entry.
4138-
4139-#. Build::
4140-
4141- bzr bd -S -- -uc -us
4142-
4143- The latter options tell it not to sign the files. You need to do
4144- this because the remote machine will not have your GPG key.
4145-
4146-#. Sign the build on your local machine::
4147-
4148- debsign -r user@host '~/*.changes'
4149-
4150- where ``user@host`` is an SSH string for accessing the remote
4151- instance. This will scp the changes and dsc locally, sign them, and
4152- put them back.
4153-
4154-#. On the remote instance you can optionally upload to a PPA::
4155-
4156- dput -fu ppa:maas-maintainers/name-of-ppa *.changes
4157-
4158-.. _official MAAS branches: https://code.launchpad.net/~maas-maintainers
4159+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.
4160+
4161+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.
4162+
4163+1. Start up an instance, log in, and bring it up to date:
4164+
4165+ sudo apt-get update && sudo apt-get upgrade
4166+
4167+2. Get the appropriate packaging branch:
4168+
4169+ bzr branch lp:~maas-maintainers/maas/packaging{...}
4170+
4171+ The [MAAS Maintainers](https://launchpad.net/~maas-maintainers) own all the [official MAAS branches](https://code.launchpad.net/~maas-maintainers).
4172+
4173+3. Move into the new branch directory.
4174+4. Check that all the build dependencies are installed. The dependencies are defined in `debian/control`:
4175+
4176+ fgrep -i build-depends -A 10 debian/control
4177+
4178+ This will yield, for example:
4179+
4180+ Build-Depends: debhelper (>= 8.1.0~),
4181+ dh-apport,
4182+ po-debconf,
4183+ python (>= 2.7),
4184+ python-distribute,
4185+ python-django
4186+ Standards-Version: 3.9.3
4187+ ...
4188+
4189+ Install these dependencies:
4190+
4191+ sudo apt get install \
4192+ debhelper dh-apport po-debconf python \
4193+ python-distribute python-django
4194+
4195+5. Edit `debian/changelog` so it contains:
4196+ - the right upstream revision number in the version,
4197+ - the series you're building for; if `UNRELEASED` appears in the first entry, `s/UNRELEASED/trusty/` (or the series you want),
4198+ - 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.
4199+
4200+6. Build:
4201+
4202+ bzr bd -S -- -uc -us
4203+
4204+ 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.
4205+
4206+7. Sign the build on your local machine:
4207+
4208+ debsign -r user@host '~/*.changes'
4209+
4210+ 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.
4211+
4212+8. On the remote instance you can optionally upload to a PPA:
4213+
4214+ dput -fu ppa:maas-maintainers/name-of-ppa *.changes
4215+
4216+
4217
4218=== renamed file 'docs/development/cluster-bootstrap.rst' => 'docs/development/cluster-bootstrap.md'
4219--- docs/development/cluster-bootstrap.rst 2015-01-14 16:24:44 +0000
4220+++ docs/development/cluster-bootstrap.md 2015-04-17 21:06:27 +0000
4221@@ -1,81 +1,49 @@
4222 Bootstrapping a cluster
4223 =======================
4224
4225-
4226 Considerations
4227 --------------
4228
4229-A new cluster needs to register itself with the region. At the same
4230-moment that it's accepted by the region, the region starts configuring
4231-it via RPC, so we need an RPC connection open when registering.
4232-
4233-Before a cluster is accepted, we want to restrict the available RPC
4234-calls to a small set, both on the region and the cluster.
4235-
4236-Before a cluster is accepted, we also do not want to start some services
4237-on the cluster, like lease uploads, DHCP scanning, and so forth, because
4238-the region will reject interaction from them.
4239-
4240+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.
4241+
4242+Before a cluster is accepted, we want to restrict the available RPC calls to a small set, both on the region and the cluster.
4243+
4244+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.
4245
4246 Start-up procedure
4247 ------------------
4248
4249-This procedure will be followed by existing clusters and new clusters
4250-alike:
4251-
4252-#. Cluster starts.
4253-
4254-#. If shared secret not available, shutdown, **DONE**.
4255-
4256-#. ``ClusterClientService`` starts.
4257-
4258-#. Services other than ``log`` are **not** started.
4259-
4260-#. Wait for a connection to the region to become available.
4261-
4262-#. Do not allow any RPC calls other than ``Identify`` and ``Authenticate``.
4263-
4264-#. Call ``Identify``.
4265-
4266-#. Call ``Authenticate``.
4267-
4268- - On success, continue.
4269-
4270- - On failure, shutdown, **DONE**.
4271-
4272-#. Permit all other RPC calls.
4273-
4274- - This allows for side-effects from calling ``Register`` next, like DHCP
4275- configuration.
4276-
4277-#. Call ``Register``. Region accepts cluster.
4278-
4279-#. Start all services.
4280-
4281-#. **DONE**.
4282-
4283+This procedure will be followed by existing clusters and new clusters alike:
4284+
4285+1. Cluster starts.
4286+2. If shared secret not available, shutdown, **DONE**.
4287+3. `ClusterClientService` starts.
4288+4. Services other than `log` are **not** started.
4289+5. Wait for a connection to the region to become available.
4290+6. Do not allow any RPC calls other than `Identify` and `Authenticate`.
4291+7. Call `Identify`.
4292+8. Call `Authenticate`.
4293+ - On success, continue.
4294+ - On failure, shutdown, **DONE**.
4295+
4296+9. Permit all other RPC calls.
4297+ - This allows for side-effects from calling `Register` next, like DHCP configuration.
4298+
4299+10. Call `Register`. Region accepts cluster.
4300+11. Start all services.
4301+12. **DONE**.
4302
4303 Work items
4304 ----------
4305
4306-#. **DONE:** Add ``Authenticate`` RPC call.
4307-
4308-#. **DONE:** Add ``Register`` RPC call.
4309-
4310-#. **DONE:** Command-line to install shared-secret.
4311-
4312-#. **DONE:** Check for shared-secret during start-up (packaging change too?).
4313-
4314-#. **DONE:** Perform ``Authenticate`` handshake.
4315-
4316-#. **DONE:** Perform ``Register`` handshake.
4317-
4318-#. **DONE:** Pass MAAS_URL in ``Register`` call. This replicates functionality
4319- found in ``update_nodegroup_maas_url``, which is no longer used.
4320-
4321-#. Display secret to admins in UI, or provide tool to obtain secret
4322- locally on region controller's machine.
4323-
4324-#. Mechanism to limit available RPC calls.
4325-
4326-#. Mechanism to defer start-up of "full" services.
4327+1. **DONE:** Add `Authenticate` RPC call.
4328+2. **DONE:** Add `Register` RPC call.
4329+3. **DONE:** Command-line to install shared-secret.
4330+4. **DONE:** Check for shared-secret during start-up (packaging change too?).
4331+5. **DONE:** Perform `Authenticate` handshake.
4332+6. **DONE:** Perform `Register` handshake.
4333+7. **DONE:** Pass MAAS\_URL in `Register` call. This replicates functionality found in `update_nodegroup_maas_url`, which is no longer used.
4334+8. Display secret to admins in UI, or provide tool to obtain secret locally on region controller's machine.
4335+9. Mechanism to limit available RPC calls.
4336+10. Mechanism to defer start-up of "full" services.
4337+
4338
4339=== renamed file 'docs/development/cluster-registration.rst' => 'docs/development/cluster-registration.md'
4340--- docs/development/cluster-registration.rst 2015-02-19 21:49:54 +0000
4341+++ docs/development/cluster-registration.md 2015-04-17 21:06:27 +0000
4342@@ -1,72 +1,46 @@
4343-======================================
4344 How cluster registration works in MAAS
4345 ======================================
4346
4347-A region controller associates with one or more cluster controllers, each
4348-of which is responsible for contacting the region controller itself and
4349-announcing its presence. An admin must accept or reject each cluster that
4350-registers itself with the region controller, except in the special
4351-circumstance mentioned in :ref:`first-cluster`.
4352-
4353-There is always at least one cluster controller in MAAS (known as a
4354-NodeGroup in the code) which is known as the 'master'. The Nodegroup entry
4355-always exists even if no cluster controllers have contacted the region
4356-controller yet, so that it can be used as a default when adding nodes in the
4357-API or UI before the cluster controller is defined. Once a real cluster
4358-controller connects it will become this master.
4359-
4360-This logic was originally implemented as an easy way to upgrade older
4361-installations that were created before nodegroups were introduced.
4362+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.
4363+
4364+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.
4365+
4366+This logic was originally implemented as an easy way to upgrade older installations that were created before nodegroups were introduced.
4367
4368 Region Controller Location
4369 --------------------------
4370
4371-The cluster obviously needs to know where the region controller is, and this is
4372-configured in a file ``/etc/maas/maas_cluster.conf`` (or
4373-``etc/demo_maas_cluster.conf`` for development environments).
4374+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).
4375
4376 Cluster configuration file
4377 --------------------------
4378
4379-This config file generally contains two items like this::
4380-
4381- MAAS_URL=http://0.0.0.0:5240/
4382- CLUSTER_UUID="adfd3977-f251-4f2c-8d61-745dbd690bf2"
4383-
4384-The values here are the defaults in the development environment. MAAS_URL
4385-tells the cluster controller where to find the region controller.
4386-
4387-``CLUSTER_UUID`` is what the region uses to tell clusters apart when they
4388-connect. Each cluster is free to generate its own UUID but the development
4389-environment fixes it in advance. The Ubuntu packaging generates a new UUID for
4390-a cluster controller each time it is installed.
4391-
4392-.. warning::
4393- The format of this config file is very sensitive due to the code that parses
4394- it. It will not accept quoting, or any kind of comments.
4395-
4396-.. _first-cluster:
4397+This config file generally contains two items like this:
4398+
4399+ MAAS_URL=http://0.0.0.0:5240/
4400+ CLUSTER_UUID="adfd3977-f251-4f2c-8d61-745dbd690bf2"
4401+
4402+The values here are the defaults in the development environment. MAAS\_URL tells the cluster controller where to find the region controller.
4403+
4404+`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.
4405+
4406+> **warning**
4407+
4408+> 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.
4409
4410 First cluster to connect
4411 ------------------------
4412
4413-For the convenience of small setups (and the development environment), the
4414-first cluster controller to connect to the region controller becomes the
4415-'master' nodegroup, and if the cluster connects *from the same host*, it
4416-is automatically accepted.
4417+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.
4418
4419 The logic currently looks like this:
4420
4421-#. If there is one, the oldest nodegroup is the master.
4422-
4423-#. If none exists, the code creates a placeholder master nodegroup on the fly,
4424- pre-accepted but without a UUID.
4425-
4426-#. If the placeholder is the only nodegroup, the first cluster controller to
4427- register becomes the master.
4428-
4429-Sadly, there is some code complexity to clear up here as this logic is not
4430-encapsulated in a single place, but instead in both:
4431-
4432-* ``NodeGroup.objects.ensure_data()`` and
4433-* ``AnonNodeGroupsHandler.register()``.
4434+1. If there is one, the oldest nodegroup is the master.
4435+2. If none exists, the code creates a placeholder master nodegroup on the fly, pre-accepted but without a UUID.
4436+3. If the placeholder is the only nodegroup, the first cluster controller to register becomes the master.
4437+
4438+Sadly, there is some code complexity to clear up here as this logic is not encapsulated in a single place, but instead in both:
4439+
4440+- `NodeGroup.objects.ensure_data()` and
4441+- `AnonNodeGroupsHandler.register()`.
4442+
4443
4444=== renamed file 'docs/development/lease-scanning-and-dns.rst' => 'docs/development/lease-scanning-and-dns.md'
4445--- docs/development/lease-scanning-and-dns.rst 2014-11-14 22:03:20 +0000
4446+++ docs/development/lease-scanning-and-dns.md 2015-04-17 21:06:27 +0000
4447@@ -1,36 +1,24 @@
4448-.. -*- mode: rst -*-
4449-
4450-***************************
4451 DHCP lease scanning and DNS
4452-***************************
4453+===========================
4454
4455 Overview
4456-========
4457-
4458-In a MAAS system, cluster controllers may optionally manage the DHCP, and the
4459-region controller may optionally manage the DNS.
4460-
4461-The region controller periodically tells the cluster controllers to report
4462-their DCHP leases. When a cluster controller reports new leases, the region
4463-controller creates DNS records for them, and instructs the cluster controller
4464-to convert the leases to static host mappings.
4465-
4466+--------
4467+
4468+In a MAAS system, cluster controllers may optionally manage the DHCP, and the region controller may optionally manage the DNS.
4469+
4470+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.
4471
4472 Leases scanning
4473-===============
4474-
4475-MAAS will periodically scan the DHCP leases file using the
4476-``LeaseUploadService()`` pserv service.
4477-
4478-As leases are discovered, it calls the RPC function ``UpdateLeases`` which
4479-stores the active leases in the DHCPLease table.
4480-
4481+---------------
4482+
4483+MAAS will periodically scan the DHCP leases file using the `LeaseUploadService()` pserv service.
4484+
4485+As leases are discovered, it calls the RPC function `UpdateLeases` which stores the active leases in the DHCPLease table.
4486
4487 Updating one or more DNS zone files
4488-===================================
4489-
4490-If a new lease is found then the dns.dns_update_zones() function gets called
4491-which takes two steps::
4492-
4493- #. Write out updated zone files.
4494- #. Ask BIND to reload the zone.
4495+-----------------------------------
4496+
4497+If a new lease is found then the dns.dns\_update\_zones() function gets called which takes two steps:
4498+
4499+ #. Write out updated zone files.
4500+ #. Ask BIND to reload the zone.
4501
4502=== renamed file 'docs/development/metadata.rst' => 'docs/development/metadata.md'
4503--- docs/development/metadata.rst 2014-08-21 20:10:47 +0000
4504+++ docs/development/metadata.md 2015-04-17 21:06:27 +0000
4505@@ -1,127 +1,71 @@
4506 The Metadata API
4507 ================
4508
4509-A MAAS region controller provides a separate API (the metadata API) for the
4510-benefit of the nodes themselves. This is where a node obtains the details of
4511-how it should be set up, such as which SSH keys should be installed in order to
4512-give a particular user remote access to the system.
4513-
4514-As a MAAS user or administrator, you do not need to request this information
4515-yourself. It is normally up to ``cloud-init`` to do this while setting up the
4516-node. You'll find more about how this works in cloud-init's datasources_
4517-documentation.
4518-
4519-.. _datasources: http://cloudinit.readthedocs.org/en/latest/topics/datasources.html
4520-
4521+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.
4522+
4523+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.
4524
4525 Similarity to EC2
4526 -----------------
4527
4528-The metadata API is very similar, and partly identical, to the EC2 metadata
4529-service. It follows a similar directory structure and provides several items
4530-in the same formats. For example, in order to find out its own host name, a
4531-node would perform an http GET request for::
4532-
4533- /2012-03-01/meta-data/local-hostname
4534-
4535-The first item in the path is the API version. The API has been extended since
4536-March 2012, but not changed incompatibly and so that date is still the current
4537-version number.
4538-
4539-The items following that form a directory hierarchy based on that of the EC2
4540-metadata service. The metadata service "knows" which node makes the request,
4541-and so there is no need for the request URL to identify the node whose hostname
4542-should be retrieved. The request automatically returns the hostname for the
4543-node which requested it.
4544-
4545-Just like EC2, the MAAS metadata API will accept GET requests to::
4546-
4547- /
4548- /2012-03-01/
4549- /2012-03-01/meta-data/
4550- /2012-03-01/meta-data/instance-id
4551- /2012-03-01/meta-data/local-hostname
4552- /2012-03-01/meta-data/public-keys
4553- /2012-03-01/user-data
4554-
4555-Hopefully their meanings are fairly obvious. The ``public-keys`` will contain
4556-the user's SSH keys.
4557-
4558-MAAS adds a tarball of scripts that a node should run during its commissioning
4559-phase::
4560-
4561- /2012-03-01/meta-data/maas-commissioning-scripts
4562-
4563-There are other differences. Where EC2 makes the metadata service available at
4564-a fixed IP address, MAAS configures the location of the metadata service on the
4565-node while installing its operating system. It does this through installation
4566-:ref:`preseeds <preseeds>`. These preseeds also include the node's access
4567-credentials.
4568-
4569+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:
4570+
4571+ /2012-03-01/meta-data/local-hostname
4572+
4573+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.
4574+
4575+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.
4576+
4577+Just like EC2, the MAAS metadata API will accept GET requests to:
4578+
4579+ /
4580+ /2012-03-01/
4581+ /2012-03-01/meta-data/
4582+ /2012-03-01/meta-data/instance-id
4583+ /2012-03-01/meta-data/local-hostname
4584+ /2012-03-01/meta-data/public-keys
4585+ /2012-03-01/user-data
4586+
4587+Hopefully their meanings are fairly obvious. The `public-keys` will contain the user's SSH keys.
4588+
4589+MAAS adds a tarball of scripts that a node should run during its commissioning phase:
4590+
4591+ /2012-03-01/meta-data/maas-commissioning-scripts
4592+
4593+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.
4594
4595 Additional Directory Trees
4596 --------------------------
4597
4598-.. _enlistment-tree:
4599-
4600-MAAS adds some entirely new directories as well. An enlisting node
4601-(which does not have access credentials for the metadata API yet) can
4602-anonymously request the same items for itself under ``/enlist/``, e.g.::
4603-
4604- /enlist/2012-03-01/meta-data/local-hostname
4605-
4606-If you set the ``ALLOW_UNSAFE_METADATA_ACCESS`` configuration item, the
4607-metadata service will also provide the information on arbitrary nodes to
4608-authenticated users under a separate sub-tree. For security reasons this is
4609-not recommended, but it may be useful in debugging. With this option enabled,
4610-the information for the node with MAC address 99:99:99:99:99:99 is available
4611-at::
4612-
4613- /2012-03-01/by-mac/99:99:99:99:99:99/meta-data/local-hostname
4614-
4615-And so on for the other information. There is a similar facility keyed by
4616-MAAS system identifiers.
4617-
4618-.. _curtin-tree:
4619-
4620-Finally, a curtin-specific metadata API with largely the same information lives
4621-in the ``/curtin/`` subtree::
4622-
4623- /curtin/2012-03-01/meta-data/local-hostname
4624-
4625-The curtin subtree however differs in the ``user-data`` endpoint. It returns a
4626-curtin-specific form of user data.
4627-
4628+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.:
4629+
4630+ /enlist/2012-03-01/meta-data/local-hostname
4631+
4632+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:
4633+
4634+ /2012-03-01/by-mac/99:99:99:99:99:99/meta-data/local-hostname
4635+
4636+And so on for the other information. There is a similar facility keyed by MAAS system identifiers.
4637+
4638+Finally, a curtin-specific metadata API with largely the same information lives in the `/curtin/` subtree:
4639+
4640+ /curtin/2012-03-01/meta-data/local-hostname
4641+
4642+The curtin subtree however differs in the `user-data` endpoint. It returns a curtin-specific form of user data.
4643
4644 Authentication
4645 --------------
4646
4647-Most metadata requests are authenticated similar to ones to the
4648-region-controller API, through OAuth. Every node in a MAAS has its own OAuth
4649-key. (On the region controller side, these keys collectively belong to a
4650-single special user called ``node-init``. You will not see such special users
4651-listed in the UI, however.) When a node asks for information about itself, the
4652-OAuth key is what tells the metadata service which node that is.
4653-
4654-Not all requests are authenticated in this way. For instance, a node can
4655-access the items under the enlistment subdirectory (see
4656-:ref:`above <enlistment-tree>`) anonymously. The metadata service will
4657-identify the requesting node by its IP address.
4658-
4659+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.
4660+
4661+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.
4662
4663 API Operations
4664 --------------
4665
4666-The MAAS metadata API supports a few non-GET operations. These work just like
4667-the ones on the main :ref:`region-controller API <region-controller-api>`, but they are meant to be invoked by
4668-nodes. The URL for these calls is ``/2013-03-01/``, and the operation name is
4669-passed as a multipart form item called "op". Other parameters are passed in
4670-the same way.
4671-
4672-The ``signal`` call notifies the region controller of the state of a
4673-commissioning node. The node sends running updates, as well as output produced
4674-by the commissioning scripts, and finally completion information through this
4675-call.
4676-
4677-When a node is done installing, it may call POST operations ``netboot_on`` and
4678-``netboot_off`` to instruct MAAS to enable or disable its network boot setting.
4679+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.
4680+
4681+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.
4682+
4683+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.
4684+
4685
4686=== renamed file 'docs/development/philosophy.rst' => 'docs/development/philosophy.md'
4687--- docs/development/philosophy.rst 2013-12-06 15:12:09 +0000
4688+++ docs/development/philosophy.md 2015-04-17 21:06:27 +0000
4689@@ -1,51 +1,25 @@
4690-------------------
4691 Philosophy of MAAS
4692-------------------
4693-
4694-This is a declaration of what we’re aiming for while designing and
4695-developing MAAS. We may fall short in many regards right now, but this
4696-is where we’re heading. Each fix, enhancement, and feature is
4697-conceived and built with these principles in mind.
4698-
4699-It is concise and to the point. If in doubt about including something,
4700-don’t, or talk about it first. Think of it as a reference point for
4701-the core development team, as well as a starting point for external
4702-contributors.
4703-
4704+==================
4705+
4706+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.
4707+
4708+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.
4709
4710 Feedback loops
4711 --------------
4712
4713-When MAAS modifies an external system there should be a feedback loop
4714-so it can know the actual state of the external system, take periodic
4715-or continuous action to converge the external system towards its
4716-notion of truth, and notice when there are problems influencing the
4717-external system.
4718-
4719-For example, when sending out a command to boot a machine from the
4720-network, MAAS should know that (a) the machine has actually powered
4721-on, and (b) that it has obtained boot instructions from the TFTP
4722-server.
4723-
4724+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.
4725+
4726+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.
4727
4728 UI
4729----
4730+--
4731
4732-It should be possible to decompose all operations in the UI down to
4733-API calls.
4734+It should be possible to decompose all operations in the UI down to API calls.
4735
4736 The UI need not have the same granularity as the API.
4737
4738-The UI should never do something that is not possible in the API
4739-unless it is entirely specific to its medium (i.e. HTTP + browser).
4740-
4741-Addendum: though the UI should be decomposable down to API calls, it
4742-does not need to be implemented as such (even though it would be great
4743-if it was).
4744-
4745-
4746-.. TODO
4747- ----
4748- Security
4749- Persistence
4750- Testing
4751+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).
4752+
4753+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).
4754+
4755
4756=== renamed file 'docs/development/preseeds.rst' => 'docs/development/preseeds.md'
4757--- docs/development/preseeds.rst 2015-04-03 11:36:37 +0000
4758+++ docs/development/preseeds.md 2015-04-17 21:06:27 +0000
4759@@ -1,71 +1,55 @@
4760-.. _preseeds:
4761-
4762-=========================
4763 How preseeds work in MAAS
4764 =========================
4765
4766-A preseed is what MAAS sends to the ``cloud-init`` process that starts up
4767-as part of node enlistment, commissioning and installation. It is a
4768-specially formatted chunk of text. MAAS does not care what that formatting
4769-is, it just knows it is text and uses Tempita_ templates to render a final
4770-file based on variables that are required depending on the context.
4771-
4772-.. _Tempita: http://pythonpaste.org/tempita/
4773-
4774+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.
4775
4776 Preseed templates
4777 -----------------
4778
4779-On a live system, the preseed templates live in ``/etc/maas/preseeds/``.
4780+On a live system, the preseed templates live in `/etc/maas/preseeds/`.
4781
4782 Each template uses a prefix that corresponds to a particular "phase":
4783
4784-+---------------+--------------------------+
4785-| Phase | Prefix used |
4786-+===============+==========================+
4787-| Enlistment | enlist |
4788-+---------------+--------------------------+
4789-| Commissioning | commissioning |
4790-+---------------+--------------------------+
4791-| Installation | preseed_master (DI_) or |
4792-| | curtin (Curtin_) |
4793-+---------------+--------------------------+
4794-
4795-.. _DI: https://www.debian.org/devel/debian-installer/
4796-
4797-.. _Curtin: https://launchpad.net/curtin
4798-
4799-Note that the preseed information is in fact composed of two files: the
4800-preseed file per se which usually contains little more than a URL and the
4801-credentials where to get the "user data" which, in turn, contains most of
4802-the logic to be executed.
4803+<table>
4804+<colgroup>
4805+<col width="22%" />
4806+<col width="37%" />
4807+</colgroup>
4808+<thead>
4809+<tr class="header">
4810+<th align="left">Phase</th>
4811+<th align="left">Prefix used</th>
4812+</tr>
4813+</thead>
4814+<tbody>
4815+<tr class="odd">
4816+<td align="left">Enlistment</td>
4817+<td align="left">enlist</td>
4818+</tr>
4819+<tr class="even">
4820+<td align="left">Commissioning</td>
4821+<td align="left">commissioning</td>
4822+</tr>
4823+<tr class="odd">
4824+<td align="left">Installation</td>
4825+<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>
4826+</tr>
4827+</tbody>
4828+</table>
4829+
4830+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.
4831
4832 Installation preseed
4833 --------------------
4834
4835-The installation preseed is broken into the three files because the
4836-requirements are different depending on the installer being used. The
4837-`Debian Installer`_ uses ``preseed_master`` and the newer Curtin_ installer
4838-uses ``curtin_userdata``.
4839-
4840-.. _Debian Installer: https://www.debian.org/devel/debian-installer/
4841-
4842-.. _Curtin: https://launchpad.net/curtin
4843-
4844-The base of both of these is ``generic``, which defines some variables
4845-and then selects the right one depending on the installer being used. Note
4846-that Tempita's inheritance mechanism is a little weird; the ``generic``
4847-template inherits the right file but in effect this is in reverse, the
4848-inherited file becomes the new template and it can then reference the
4849-variables defined in ``generic``.
4850-
4851+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`.
4852+
4853+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`.
4854
4855 User-provided preseeds
4856 ----------------------
4857
4858-In addition to the standard preseed files, the base preseeds can be
4859-overridden on a per-OS, architecture, subarchitecture, OS release and
4860-node name basis. The templates are looked up in the following order::
4861+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:
4862
4863 {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}_{node_name}
4864 {prefix}_{osystem}_{node_arch}_{node_subarch}_{release}
4865@@ -90,60 +74,34 @@
4866 {prefix}
4867 'generic'
4868
4869-``prefix`` is either empty (in which case the following underscore is also
4870-ommitted: e.g. {osystem}_{node_arch}_{node_subarch}_{release}) or one of
4871-``enlist``, ``enlist_userdata``, ``commissioning``, ``curtin``,
4872-``curtin_userdata`` or ``preseed_master``.
4873-
4874-As you can see this mechanism is also used to calculate the base preseeds for
4875-all of installation, enlistment and commissioning. It allows end users to
4876-add, for example, a file named ``curtin_ubuntu_amd64_generic`` that would be
4877-used at installation time.
4878-
4879+`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`.
4880+
4881+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.
4882
4883 Curtin configuration
4884 --------------------
4885
4886-Curtin_ is the tool responsible for performing the OS installation. If you
4887-need to customize the installation, you need to change Curtin's user data
4888-(by either changing the existing ``curtin_userdata`` file or adding a custom
4889-version as described above).
4890-
4891-.. _Curtin: https://launchpad.net/curtin
4892-
4893-There isn't a complete documentation on how to customize Curtin at the time of
4894-this writing but the following instructions and examples should cover most of
4895-the use cases.
4896-
4897-Curtin provides hooks to execute custom code before (`early`) or after (`late`)
4898-the installation takes place. You can override these hooks to execute code,
4899-either code that will run in the ephemeral environment or in the machine being
4900-installed itself (`in-target`). Note that you can execute `in-target` code
4901-only in a `late` command.
4902-
4903-Example: early command
4904-======================
4905-
4906-Here is an example of an early command (i.e. one that will run before the
4907-installation takes place) that runs in the ephemeral environment and
4908-pings an external machine to signal that the installation is about to start.
4909-
4910-.. code:: yaml
4911-
4912- early_commands:
4913- signal: [wget, '--no-proxy', 'http://example.com/', '--post-data', 'system_id={{node.system_id}}&signal=starting_install', '-O', '/dev/null']
4914-
4915-Example: late command
4916-======================
4917-
4918-Here is an example of two late commands (i.e. commands that will run after the
4919-installation has been performed). Both run `in-target` (i.e. in the machine
4920-being installed). The first command adds a PPA to the machine. The second
4921-command create a file containing the node's system_id. (Note that these are
4922-just examples of the things that can be done.)
4923-
4924-.. code:: yaml
4925-
4926- late_commands:
4927- add_repo: ["curtin", "in-target", "--", "add-apt-repository", "-y", "ppa:my/ppa"]
4928- custom: curtin in-target -- sh -c "/bin/echo -en 'Installed {{node.system_id}}' > /tmp/maas_system_id"
4929+[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).
4930+
4931+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.
4932+
4933+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.
4934+
4935+### Example: early command
4936+
4937+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.
4938+
4939+``` {.sourceCode .yaml}
4940+early_commands:
4941+ signal: [wget, '--no-proxy', 'http://example.com/', '--post-data', 'system_id={{node.system_id}}&signal=starting_install', '-O', '/dev/null']
4942+```
4943+
4944+### Example: late command
4945+
4946+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.)
4947+
4948+``` {.sourceCode .yaml}
4949+late_commands:
4950+ add_repo: ["curtin", "in-target", "--", "add-apt-repository", "-y", "ppa:my/ppa"]
4951+ custom: curtin in-target -- sh -c "/bin/echo -en 'Installed {{node.system_id}}' > /tmp/maas_system_id"
4952+```
4953
4954=== renamed file 'docs/development/rpc.rst' => 'docs/development/rpc.md'
4955--- docs/development/rpc.rst 2014-08-21 20:10:47 +0000
4956+++ docs/development/rpc.md 2015-04-17 21:06:27 +0000
4957@@ -1,181 +1,105 @@
4958-.. -*- mode: rst -*-
4959-
4960 RPC HOWTO
4961 =========
4962
4963-MAAS contains an RPC mechanism such that every process in the region is
4964-connected to every process in the cluster (strictly, every pserv
4965-process). It's based on AMP_, specifically `Twisted's implementation`_.
4966-
4967-.. _AMP:
4968- http://amp-protocol.net/
4969-
4970-.. _Twisted's implementation:
4971- http://twistedmatrix.com/documents/current/core/howto/amp.html
4972-
4973+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).
4974
4975 Where do I start?
4976 -----------------
4977
4978-Start in the :py:mod:`provisioningserver.rpc` package. The first two files to
4979-look at are ``cluster.py`` and ``region.py``. This contain the
4980-declarations of what commands are available on clusters and regions
4981-respectively.
4982-
4983-A new command could be declared like so::
4984-
4985- from twisted.protocols import amp
4986-
4987- class EatCheez(amp.Command):
4988- arguments = [
4989- (b"name", amp.Unicode()),
4990- (b"origin", amp.Unicode()),
4991- ]
4992- response = [
4993- (b"rating", amp.Integer()),
4994- ]
4995-
4996-It's also possible to map exceptions across the wire using an ``errors``
4997-attribute; see the docs or code for more information.
4998-
4999-Note that byte-strings are used for parameter names. Twisted gets quite
5000-fussy about this, so remember to do it.
The diff has been truncated for viewing.