launchpad-reviewers team mailing list archive

[Nick Veitch <nick.veitch@xxxxxxxxxxxxx>]

Nick Veitch has proposed merging lp:~evilnick/maas/new_docs into lp:maas.

Commit message:
Restructure of docs. Adds new install and configure sections as well as brief overview 

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~evilnick/maas/new_docs/+merge/127873

Adds the bare minimum of documentation!
-- 
https://code.launchpad.net/~evilnick/maas/new_docs/+merge/127873
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~evilnick/maas/new_docs into lp:maas.

=== modified file 'INSTALL.txt'
--- INSTALL.txt	2012-09-25 23:49:01 +0000
+++ INSTALL.txt	2012-10-03 20:43:22 +0000
@@ -1,72 +1,139 @@
 .. -*- mode: rst -*-
 
-***************
+ 
 Installing MAAS
-***************
-
-There are two main ways to install MAAS:
-
- * as part of a fresh Ubuntu install using the Ubuntu Server installer
- * or from Ubuntu's archive on an existing Ubuntu install.
-
-This is a guide to installing MAAS from the Ubuntu archive.
-
-It assumes that you're working with:
-
- * a fresh Ubuntu 12.04 LTS install
- * a machine dedicated to running MAAS
- * control of the network your machine is connected to
- * internet access or a local mirror of the Ubuntu archive.
-
+===============
+
+There are two main ways to install MAAS
+
+ * :ref:`From Ubuntu's package archive on an existing Ubuntu install. <pkg-install>`
+ * :ref:`As a fresh install from Ubuntu Server install media. <disc-install>`
+ 
+
+If you are interested in testing the latest development version you can also check out the very latest source and build MAAS yourself. 
+
+
+.. _pkg-install:
 
 Installing MAAS from the archive
-================================
-
-Installing MAAS is straightforward. At the command-line, type::
-
-  $ sudo apt-get install maas
-
-From a fresh Ubuntu 12.04 LTS install, MAAS will pull down around 200
-MB of packages.
-
-
-Creating a superuser account
-----------------------------
-
-Once MAAS is installed, you'll need to create your first administrator
+--------------------------------
+
+Installing MAAS from packages is thankfully straightforward. There are actually several packages that go into making up a working MAAS install, but for convenience, many of these have been gathered into a virtual package called 'maas' which will install the necessary components.
+There are two suggested additional packages 'maas-dhcp' and 'maas-dns'. These set up MAAS-controlled DHCP and DNS services which greatly simplify deployment if you are running a typical setup where the MAAS controller can run the network. If you need to integrate your MAAS setup under an existing DHCP setup, see :ref:
+ 
+
+Install packages
+^^^^^^^^^^^^^^^^
+
+At the command-line, type::
+
+  $ sudo apt-get install maas maas-dhcp maas-dns
+
+You will see a list of packages and a confirmation message to proceed. The exact list will obviously depend on what you already have installed on your server, but expect to add about 200Mb of files.
+
+The configuration for the MAAS controller will automatically run and pop up this config screen:
+
+.. image:: media/install_cluster-config.*
+
+Here you will need to enter the hostname for where the region controller can be contacted. In many scenarios, you may be running the region controller (i.e. the web and API interface) from a different network address, for example where a server has several network interfaces. 
+
+Once the configuration scripts have run you should see this message telling you that the system is ready to use:
+
+.. image:: media/install_controller-config.*
+
+The web server is started last, so you have to accept this message before the service is run and you can access the Web interface. Then there are just a few more setup steps :ref:`post_install`
+
+.. _disc-install:
+
+Installing MAAS from Ubuntu Server boot media
+---------------------------------------------
+
+If you are installing MAAS as part of a fresh install it is easiest to choose the "Multiple Server install with MAAS" option from the installer and have pretty much everything set up for you.
+Boot from the Ubuntu Server media and you will be greeted with the usual language selection screen:
+
+.. image:: media/install_01.*
+
+On the next screen, you will see there is an entry in the menu called "Multiple server install with MAAS". Use the cursor keys to select this and then press Enter.
+
+.. image:: media/install_02.*
+
+The installer then runs through the usual language and keyboard options. Make your selections using Tab/Cursor keys/Enter to proceed through the install.
+The installer will then load various drivers, which may take a moment or two.
+
+.. image:: media/install_03.*
+
+The next screen asks for the hostname for this server. Choose something appropriate for your network.
+
+
+.. image:: media/install_04.*
+
+Finally we get to the MAAS part! Here there are just two options. We want to "Create a new MAAS on this server" so go ahead and choose that one.
+
+.. image:: media/install_05.*
+
+The install now continues as usual. Next you will be prompted to enter a username. This will be the admin user for the actual server that MAAS will be running on (not the same as the MAAS admin user!)
+
+.. image:: media/install_06.*
+
+As usual you will have the chance to encrypt your home directory. Continue to make selections based on whatever settings suit your usage.
+
+.. image:: media/install_07.*
+
+After making selections and partitioning storage, the system software will start to be installed. This part should only take a few minutes.
+
+.. image:: media/install_09.*
+
+Various packages will now be configured, including the package manager and update manager. It is important to set these up appropriately so you will receive timely updates of the MAAS server software, as well as other essential services that may run on this server.
+
+.. image:: media/install_10.*
+
+The configuration for MAAS will ask you to configure the host address of the server. This should be the IP address you will use to connect to the server (you may have additional interfaces e.g. to run node subnets)
+
+.. image:: media/install_cluster-config.*
+
+The next screen will confirm the web address that will be used to the web interface.
+
+.. image:: media/install_controller-config.*
+
+After configuring any other packages the installer will finally come to and end. At this point you should eject the boot media.
+
+.. image:: media/install_14.*
+
+After restarting, you should be able to login to the new server with the information you supplied during the install. The MAAS software will run automatically.
+
+
+.. image:: media/install_15.*
+
+
+**NOTE:** The mmas-dhcp and maas-dns packages are not installed by default. If you want to have MAAS run DHCP and DNS services, you should install these packages::
+
+ $ sudo apt-get install maas-dhcp maas-dns
+
+And then proceed to the post-intsall setup below.
+
+.. _post_install:
+
+Post-Install tasks
+==================
+If you now use a web browser to connect to the region controller, you should see that MAAS is running, but there will also be some errors on the screen:
+
+.. image:: media/install_web-init.*
+
+The on screen messages will tell you that there are no boot images present, and that you can't login because there is no admin user. 
+
+Create a superuser account
+--------------------------
+
+Once MAAS is installed, you'll need to create an administrator
 account::
 
-  $ maas createsuperuser
-
-Follow the prompts and MAAS will create an admin account that you can
-later use to log in.
-
-
-Configuring a DHCP server
-=========================
-
-MAAS requires a properly configured DHCP server so it can boot machines using
-PXE.  MAAS works with the ISC DHCP server; install it if it's not already
-installed::
-
-    $ sudo apt-get install isc-dhcp-server
-
-There is a tool to generate a configuration for it that will work with MAAS::
-
-    $ maas-provision generate-dhcp-config [options]
-
-Run ``maas-provision generate-dhcp-config -h`` to see the options.  You will
-need to provide various IP details such as the range of IP addresses to assign
-to clients.  You can use the generated output to configure your system's ISC
-DHCP server, by putting the configuration in the ``/etc/dhcp/dhcpd.conf`` file.
-
-Now restart dhcpd::
-
-  $ sudo /etc/init.d/isc-dhcp-server restart
-
-
-Import the Ubuntu images
-========================
+  $ sudo maas createsuperuser
+
+Follow the prompts to create the account which you will need to login to the web interface. Unless you have a special need, it is best to accept the default login name of `root`, as it is rather annoying if you forget the username (although you can simply run this command again to create a new superuser).
+
+
+Import the boot images
+----------------------
 
 MAAS will check for and download new Ubuntu images once a week.
 However, you'll need to download them manually the first time::
@@ -80,33 +147,18 @@
   $ sudo http_proxy=$http_proxy maas-import-pxe-files
 
 
-SSL Support
-===========
-
-If you want secure access to your MAAS web UI/API, you need to do a few
-things. First, turn on SSL support in Apache::
-
-  $ sudo a2enmod ssl
-
-Ensure that the Apache config file from ``etc/maas/maas-http.conf`` is
-included in ``/etc/apache2/conf.d/``, then edit
-``/etc/maas/maas_local_settings.py`` and change DEFAULT_MAAS_URL so that it
-uses https instead of http.
-
-Now, restart Apache::
-
-  $ sudo service apache2 restart
-
-At this point you will be able to access the MAAS web server using https but
-the default SSL certificate is insecure.  Please generate your own and then
-edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the
-certificate.
-
-
-Next steps
-==========
-
-Your MAAS is now ready for use. Visit the MAAS web interface in your
-browser at http://localhost/MAAS.
-
-Now, :doc:`let's prepare your Juju environment <juju-quick-start>`.
+Login to the server
+-------------------
+
+To check that everything is working properly, you should try and login to the server now. Both the error messages should have gone (it can take a few minutes for the boot image files to register) and you can see that there are currently 0 nodes attached to this controller.
+
+.. image:: media/install-login.*
+
+
+Configure DHCP
+--------------
+
+If you are using MAAS to control DHCP, you need to set this via the web interface.
+However, if you are manually configuring a DHCP server, you should take a look at :ref:`manual-dhcp`
+
+Once everything is set up and running, you are ready to :doc:`start enlisting nodes <nodes>`

=== added file 'docs/about.rst'
--- docs/about.rst	1970-01-01 00:00:00 +0000
+++ docs/about.rst	2012-10-03 20:43:22 +0000
@@ -0,0 +1,19 @@
+About this documentation
+========================
+
+This is the documentation for Canonical's MAAS software. If you aren't sure what that is, you should probably skip everything else and head straight to the :ref:`orientation` section where it is explained.
+Like any software though, it can be frustrating if you don't know how bits of it work, how to achieve certain goals or what to do when things go wrong. Amongst its various sections, this manual aims to answer all those questions and plenty more you haven't even thought of yet. 
+
+Getting it
+----------
+
+In a cunning move, the current documentation always lives, and is built from, the main MAAS source code. That means that whatever MAAS package you have installed, or even if you are really living life on the edge and have checked out a development version from Launchpad, this documentation should be the latest and most appropriate version for the software you are running.
+However, it is also possible that there have been further sections or more helpful, or clearer bits added since the package you are using was made. For this reason you can always find the latest documentation online here: http://maas.ubuntu.com
+
+Contributing
+------------
+
+If you have some extra information to add, or think you have spotted an error or something out of date, we really want to hear about it. File a bug report or contact us via the MAAS homepage at http://maas.ubuntu.com
+
+
+

=== modified file 'docs/conf.py'
--- docs/conf.py	2012-06-25 14:04:32 +0000
+++ docs/conf.py	2012-10-03 20:43:22 +0000
@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '12.10'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '12.10b'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -126,12 +126,12 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = 'media/maas-logo-64.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = 'media/maas.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -140,7 +140,7 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -186,7 +186,7 @@
 # -- Options for LaTeX output --------------------------------------------------
 
 # The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
+latex_paper_size = 'a4'
 
 # The font size ('10pt', '11pt' or '12pt').
 #latex_font_size = '10pt'

=== added file 'docs/configure.rst'
--- docs/configure.rst	1970-01-01 00:00:00 +0000
+++ docs/configure.rst	2012-10-03 20:43:22 +0000
@@ -0,0 +1,46 @@
+Additional Configuration
+========================
+
+.. _manual-dhcp:
+
+Manual DHCP configuration
+-------------------------
+
+There are some circumstances under which you may not wish the master MAAS worker to handle DHCP for the network. In these instances, the existing DHCP server for the network will need its configuration altered to allow MAAS to enlist and control nodes automatically.
+
+At the very least the next-server should point to the MAAS controller host address and the filename should be set to pxelinux.0
+
+The configuration entry may look something like this::
+
+   subnet 192.168.122.0 netmask 255.255.255.0 {
+       next-server 192.168.122.136;
+       filename "pxelinux.0";
+       option subnet-mask 255.255.255.0;
+       option broadcast-address 192.168.122.255;
+       option domain-name-servers 192.168.122.136;
+       range dynamic-bootp 192.168.122.5 192.168.122.135;
+   }
+
+.. _ssl:
+SSL Support
+-----------
+
+If you want secure access to your MAAS web UI/API, you need to do a few
+things. First, turn on SSL support in Apache::
+
+  $ sudo a2enmod ssl
+
+Ensure that the Apache config file from ``etc/maas/maas-http.conf`` is
+included in ``/etc/apache2/conf.d/``, then edit
+``/etc/maas/maas_local_settings.py`` and change DEFAULT_MAAS_URL so that it
+uses https instead of http.
+
+Now, restart Apache::
+
+  $ sudo service apache2 restart
+
+At this point you will be able to access the MAAS web server using https but
+the default SSL certificate is insecure.  Please generate your own and then
+edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the
+certificate.
+

=== modified file 'docs/index.rst'
--- docs/index.rst	2012-09-18 16:51:54 +0000
+++ docs/index.rst	2012-10-03 20:43:22 +0000
@@ -1,46 +1,62 @@
-.. MAAS documentation master file, created by
-   sphinx-quickstart on Thu Jan 19 14:48:25 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-=============================
-MAAS developer documentation!
-=============================
-
-Welcome to the MAAS developer documentation.
-This documentation is for people who want to hack on MAAS or create a service
-that communicates with a MAAS server using the API.
-
-Overview
-========
-
-.. toctree::
-   :maxdepth: 1
-
-   readme
-   hacking
+.. MAAS documentation master file
+
+########################
+Metal As A Service: MAAS
+########################
+
+
+This is the documentation for the MAAS project http://maas.ubuntu.com
+
+************
+Introduction
+************   
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   orientation
+
+***************
+Getting started
+***************
+
+.. toctree::
+   :maxdepth: 2
+
    install
+   configure
+   nodes
+   
+
+******************
+Deploying services
+******************
+
+.. toctree::
+   :maxdepth: 2
+
    juju-quick-start
+
+**************
+Using maas-cli
+**************
+
+.. toctree::
+   :maxdepth: 2
+
+   maascli
+
+**********
+Appendices
+**********
+
+.. toctree::
+   :maxdepth: 2
+
    troubleshooting
+   hacking 
    api
-
-MAAS API
-========
-
-Other services interact with a MAAS server using its :doc:`api`.
-
-
-MAAS from the command-line
-==========================
-
-MAAS comes with a few command-line tools, including `maascli`, which
-exposes the entire :doc:`api` to command-line users.
-
-
-Code
-====
-
-.. toctree::
    models
    enum
 

=== added file 'docs/maascli.rst'
=== added directory 'docs/media'
=== added file 'docs/media/install_01.png'
Binary files docs/media/install_01.png	1970-01-01 00:00:00 +0000 and docs/media/install_01.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_02.png'
Binary files docs/media/install_02.png	1970-01-01 00:00:00 +0000 and docs/media/install_02.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_03.png'
Binary files docs/media/install_03.png	1970-01-01 00:00:00 +0000 and docs/media/install_03.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_04.png'
Binary files docs/media/install_04.png	1970-01-01 00:00:00 +0000 and docs/media/install_04.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_05.png'
Binary files docs/media/install_05.png	1970-01-01 00:00:00 +0000 and docs/media/install_05.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_06.png'
Binary files docs/media/install_06.png	1970-01-01 00:00:00 +0000 and docs/media/install_06.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_07.png'
Binary files docs/media/install_07.png	1970-01-01 00:00:00 +0000 and docs/media/install_07.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_08.png'
Binary files docs/media/install_08.png	1970-01-01 00:00:00 +0000 and docs/media/install_08.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_09.png'
Binary files docs/media/install_09.png	1970-01-01 00:00:00 +0000 and docs/media/install_09.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_10.png'
Binary files docs/media/install_10.png	1970-01-01 00:00:00 +0000 and docs/media/install_10.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_11.png'
Binary files docs/media/install_11.png	1970-01-01 00:00:00 +0000 and docs/media/install_11.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_12.png'
Binary files docs/media/install_12.png	1970-01-01 00:00:00 +0000 and docs/media/install_12.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_13.png'
Binary files docs/media/install_13.png	1970-01-01 00:00:00 +0000 and docs/media/install_13.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_14.png'
Binary files docs/media/install_14.png	1970-01-01 00:00:00 +0000 and docs/media/install_14.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_15.png'
Binary files docs/media/install_15.png	1970-01-01 00:00:00 +0000 and docs/media/install_15.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_cluster-config.png'
Binary files docs/media/install_cluster-config.png	1970-01-01 00:00:00 +0000 and docs/media/install_cluster-config.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_controller-config.png'
Binary files docs/media/install_controller-config.png	1970-01-01 00:00:00 +0000 and docs/media/install_controller-config.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/install_web-init.png'
Binary files docs/media/install_web-init.png	1970-01-01 00:00:00 +0000 and docs/media/install_web-init.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/maas-logo-64.png'
Binary files docs/media/maas-logo-64.png	1970-01-01 00:00:00 +0000 and docs/media/maas-logo-64.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/maas.ico'
Binary files docs/media/maas.ico	1970-01-01 00:00:00 +0000 and docs/media/maas.ico	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/media/orientation_architecture-diagram.png'
Binary files docs/media/orientation_architecture-diagram.png	1970-01-01 00:00:00 +0000 and docs/media/orientation_architecture-diagram.png	2012-10-03 20:43:22 +0000 differ
=== added file 'docs/nodes.rst'
--- docs/nodes.rst	1970-01-01 00:00:00 +0000
+++ docs/nodes.rst	2012-10-03 20:43:22 +0000
@@ -0,0 +1,37 @@
+
+
+Adding nodes to the system
+==========================
+
+Now that the MAAS controller is running, we need to make the nodes aware of MAAS and vice-versa. If you have set up DHCP correctly, and your nodes can boot via PXE then things really couldn't be much easier and you can use :ref:`the automatic discovery procedure <auto-enlist>`
+
+
+
+.. _auto-enlist:
+
+Automatic Discovery
+-------------------
+
+With nodes set to boot from a PXE image, they will start, look for a DHCP server, receive the PXE boot details, boot the image, contact the MAAS server and shut down.
+
+During this process, the MAAS server will be passed information about the node, including the architecture, MAC address and other details which will be stored in the database of nodes. You can accept and comission the nodes via the web interface.
+When the nodes have been accepted the selected series of Ubuntu will be installed.
+
+To save time, you can accept and commission all nodes from the commandline::
+
+   $ maas-cli api maas nodes accept-all
+
+
+
+Enlist nodes via boot media
+---------------------------
+
+Using Boot media such as an AVAHI boot image or the Ubuntu Server install disk, it is possible to perform the discovery and enlistment process without using DHCP/PXE.
+
+Boot from the media and follow the instructions.
+
+
+Manually add nodes
+------------------
+
+If you know the MAC address of a node, you can manually enter details about the node through the web interface.

=== added file 'docs/orientation.rst'
--- docs/orientation.rst	1970-01-01 00:00:00 +0000
+++ docs/orientation.rst	2012-10-03 20:43:22 +0000
@@ -0,0 +1,51 @@
+.. _orientation:
+ 
+Orientation
+===========
+
+MAAS in Brief
+-------------
+
+Canonical’s MAAS brings the dynamism of cloud computing to the world of physical provisioning and Ubuntu. Connect, commission and deploy physical servers in record time, re-allocate nodes between services dynamically, and keep them up to date and in due course, retire them from use.
+
+MAAS is a new way of thinking about physical infrastructure. Compute, storage and network are commodities in the virtual world, and for large-scale deployments the same is true of the metal. “Metal as a service” lets you treat farms of servers as a malleable resource for allocation to specific problems, and re-allocation on a dynamic basis.
+
+In conjunction with the Juju service orchestration software (see https://juju.ubuntu.com/docs/), MAAS will enable you to get the most out of your physical hardware and dynamically deploy complex services with ease and confidence.
+
+Do I Need MAAS?
+---------------
+
+MAAS certainly isn't for everyone, but why not ask yourself these questions? 
+
+You probably *SHOULD* use MAAS if any or all of the following statements are true:
+
+    * You are trying to manage many physical servers.
+    * You want to deploy services with the minimum fuss.
+    * You need to get the most from your resources.
+    * You want things to work, repeatably and reliably.
+
+You probably don't need MAAS if any or all of these statements are true:
+
+    * You don't need to manage physical hardware
+    * You relish time spent in the server room
+    * You like trying to set up complicated, critical services without any help
+
+
+
+A Typical MAAS setup
+--------------------
+
+MAAS is designed to work with your physical hardware, whether your setup includes thousands of server boxes or only a few. The key components of the MAAS software are:
+
+  * Region controller
+  * Cluster controller(s)
+  * Nodes
+
+For small (in terms of number of nodes) setups, you will probably just install the Region controller and a cluster controller on the same server - it is only worth having multiple region controllers if you need to organise your nodes into different subnets (e.g. if you have a lot of nodes). 
+
+.. image:: media/orientation_architecture-diagram.*
+
+
+
+
+

=== modified file 'docs/troubleshooting.rst'
--- docs/troubleshooting.rst	2012-09-11 14:58:22 +0000
+++ docs/troubleshooting.rst	2012-10-03 20:43:22 +0000
@@ -1,6 +1,6 @@
-************************
+********************
 MAAS Troubleshooting
-************************
+********************
 Some parts of MAAS may still be a little confusing, and sometimes you might be trying to do things that are just plain impossible. This section covers some of the most commonly encountered problems and tries its best to make them gone.
 
 .. contents:: Contents
@@ -9,16 +9,16 @@
 
 
 **Nodes hang on "Commissioning"**
-====================
+=================================
 
 Possible Cause: Timing issues
----------------
+-----------------------------
 Various parts of MAAS rely on OAuth to negotiate a connection to nodes. If the current time reported by the hardware clock on your node differs significantly from that on the MAAS server, the connection will not be made.
 
 **SOLUTION:** Check that the hardware clocks are consistent, and if necessary, adjust them. This can usually be done from within the system BIOS, without needing to install an OS
 
 Possible Cause: Network drivers
----------------
+-------------------------------
 
 Sometimes the hardware can boot from PXE, but fail to load correct drivers when booting the received image. This is sometimes the case when no open source drivers are available for the network hardware.
 
@@ -55,7 +55,7 @@
 There is also an option in the MAAS web interface to add new ssh keys to the nodes (via Preferences in the drop down menu which appears when clicking your username in the top-right of the page).
 
 **Forgot MAAS superuser password**
-====================
+==================================
 
 As long as you have sudo privileges, this is not a disaster. You can use the ``maas`` command to change the password for the MAAS superuser on the MAAS server:
 
@@ -63,14 +63,14 @@
 
 
 **Need to reconfigure server IP address**
-====================
+=========================================
 If you made a mistake during setup or you just need to reconfigure your MAAS server, you can simply run the setup again:
 
     ``sudo dpkg-reconfigure maas``
 
 
 **Can't find MAAS webpage**
-====================
+===========================
 
 The default webpage is located at ``http://<hostname>/maas``. If you can't access it, there are a few things to try: