Merge lp:~julian-edwards/maas/more-docs into lp:~maas-committers/maas/trunk

[Julian Edwards]

Documentation update for kernel options and client-side DNS configuration.

[Jeroen T. Vermeulen (jtv)]

Thanks. Good to see some attention being paid to documentation.

“When using third party tools such as ``juju`` it will need to be able to resolve the hostnames” hobbles a bit — tools, plural, are suddenly an “it.” How about just “Third-party tools such as ``juju`` may need the ability to resolve the hostnames”?

I suppose that note at the very end means that even if you could give a node multiple kernel-options tags, only an arbitrary one of them would actually be applied. Or are per-node kernel options combined? Worth a mention perhaps.

review: Approve

[Julian Edwards (julian-edwards)]

On Friday 11 Oct 2013 06:21:25 you wrote:
> Review: Approve
>
> Thanks. Good to see some attention being paid to documentation.
>
> “When using third party tools such as ``juju`` it will need to be able to
> resolve the hostnames” hobbles a bit — tools, plural, are suddenly an “it.”
> How about just “Third-party tools such as ``juju`` may need the ability to
> resolve the hostnames”?

Good spot.

> I suppose that note at the very end means that even if you could give a node
> multiple kernel-options tags, only an arbitrary one of them would actually
> be applied. Or are per-node kernel options combined? Worth a mention
> perhaps.

I think you are missing something here. It's talking about overriding the
global options, not multiple options per node. It remains clear even re-
reading it 2 hours after I wrote it.

[Julian Edwards (julian-edwards)]

Thanks for reviewing!

[Jeroen T. Vermeulen (jtv)]

Yes, I am missing something — that's the point. I know the note is about overriding the global options, but it raises the question of whether kernel options from tags override or extend kernel options from other tags.

[Julian Edwards (julian-edwards)]

I understand now, fixed, thanks.

=== modified file 'docs/configure.rst'
--- docs/configure.rst	2013-09-19 03:25:49 +0000
+++ docs/configure.rst	2013-10-11 06:39:26 +0000
@@ -233,3 +233,19 @@
   :ref:`following this procedure <cli-dhcp>` 
 
 
+Client-side DNS configuration
+-----------------------------
+
+When using a third party tool such as ``juju`` it will need to be able to
+resolve the hostnames that the MAAS API returns to it.  In order for this to
+happen, *client-side DNS* must be configured to point to MAAS's DNS
+server.  Generally speaking, this is a simple case of adding the following
+line to the ``/etc/resolv.conf`` file on your client host::
+
+  nameserver <IP OF MAAS DNS HOST>
+
+replacing the <IP OF MAAS DNS HOST> with the actual IP address of the host
+running the MAAS DNS server.
+
+However, for hosts using the ``resolvconf`` package, please read its
+documentation for more information.
 
=== modified file 'docs/index.rst'
--- docs/index.rst	2013-10-09 09:18:10 +0000
+++ docs/index.rst	2013-10-11 06:39:26 +0000
@@ -30,6 +30,7 @@
    configure
    cluster-configuration
    nodes
+   kernel-options
 
 
 ******************
 
=== added file 'docs/kernel-options.rst'
--- docs/kernel-options.rst	1970-01-01 00:00:00 +0000
+++ docs/kernel-options.rst	2013-10-11 06:39:26 +0000
@@ -0,0 +1,38 @@
+===========================
+Setting kernel boot options
+===========================
+
+MAAS is able to send specific kernel options to booting nodes on both
+a global basis and a per-node basis.
+
+Global kernel options
+---------------------
+
+As an admin, click on the gear icon at the top right and scroll down to
+the Global Kernel Parameters section, as shown here:
+
+.. image:: media/global_kernel_opts.png
+
+Whatever you set here is sent as-is to all booting nodes.
+
+Per-node kernel options
+-----------------------
+
+Per-node kernel options are set using tags.  The easiest way of doing this
+is to use the ``maas-cli`` command.  You will need to :ref:`be
+logged in to the API first <api-key>` and then you can add a tag which has its
+``kernel_opts`` value set, like this::
+
+  $ maas-cli maas tags new name='nomodeset' \
+    comment='nomodeset kernel option' kernel_opts='nomodeset vga'
+
+Once the tag is defined, you can add it to a node or nodes::
+
+  $ maas-cli maas tag update-nodes nomodeset add=<system_id_1> \
+    add=<system_id_2>
+
+.. note::
+
+  Any per-node kernel options set will completely override the global options.
+  If multiple tags attached to a node have the kernel_opts defined, the first
+  one ordered by name is used.
 
=== added file 'docs/media/global_kernel_opts.png'
 Binary files docs/media/global_kernel_opts.png	1970-01-01 00:00:00 +0000 and docs/media/global_kernel_opts.png	2013-10-11 06:39:26 +0000 differ