docs: Update RTD content for cloud-init subcommands.

Give a bit more detailed information which others can quickly reference to
discover new CLI subcommand functionality. This section was a bit stale as
we've introduced cloud-init status, clean and analyze content that was a
bit under represented. Since we've had a few request of externals who try
to run cloud-init subcommands on the commandline instead of rebooting,
it's probably worth a bit of content here to describe how those init and
module subcommands work.

4 files changed, 166 insertions, 10 deletions

diff --git a/doc/rtd/topics/boot.rst b/doc/rtd/topics/boot.rst
index 859409a6..f2976fdf 100644
--- a/doc/rtd/topics/boot.rst
+++ b/doc/rtd/topics/boot.rst
@@ -1,3 +1,5 @@
+.. _boot_stages:
+
 ***********
 Boot Stages
 ***********
@@ -74,7 +76,7 @@ Network
  * **systemd service**: ``cloud-init.service``
  * **runs**: After local stage and configured networking is up.
  * **blocks**: As much of remaining boot as possible.
- * **modules**: ``init_modules``
+ * **modules**: ``cloud_init_modules`` in **/etc/cloud/cloud.cfg**
 
 This stage requires all configured networking to be online, as it will fully
 process any user-data that is found.  Here, processing means:
@@ -104,7 +106,7 @@ Config
  * **systemd service**: ``cloud-config.service``
  * **runs**: After network stage.
  * **blocks**: None.
- * **modules**: ``config_modules``
+ * **modules**: ``cloud_config_modules`` in **/etc/cloud/cloud.cfg**
 
 This stage runs config modules only.  Modules that do not really have an
 effect on other stages of boot are run here.
@@ -115,7 +117,7 @@ Final
  * **systemd service**: ``cloud-final.service``
  * **runs**: As final part of boot (traditional "rc.local")
  * **blocks**: None.
- * **modules**: ``final_modules``
+ * **modules**: ``cloud_final_modules`` in **/etc/cloud/cloud.cfg**
 
 This stage runs as late in boot as possible.  Any scripts that a user is
 accustomed to running after logging into a system should run correctly here.
@@ -125,4 +127,9 @@ Things that run here include
  * configuration management plugins (puppet, chef, salt-minion)
  * user-scripts (including ``runcmd``).
 
+For scripts external to cloud-init looking to wait until cloud-init
+finished, the ``cloud-init status`` subcommand can help block external
+scripts until cloud-init is done without having to write your own systemd
+units dependency chains. See :ref:`cli_status` for more info.
+
 .. vi: textwidth=78
diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst
index 31eaba53..ae3a0c74 100644
--- a/doc/rtd/topics/capabilities.rst
+++ b/doc/rtd/topics/capabilities.rst
@@ -1,3 +1,5 @@
+.. _capabilities:
+
 ************
 Capabilities
 ************
@@ -39,17 +41,19 @@ Currently defined feature names include:
    see :ref:`network_config_v2` documentation for examples.
 
 
-CLI Interface :
+CLI Interface
+=============
 
-``cloud-init features`` will print out each feature supported.  If cloud-init
-does not have the features subcommand, it also does not support any features
-described in this document.
+   The command line documentation is accessible on any cloud-init
+installed system:
 
 .. code-block:: bash
 
   % cloud-init --help
-  usage: cloud-init [-h] [--version] [--file FILES] [--debug] [--force]
-                    {init,modules,query,single,dhclient-hook,features} ...
+  usage: cloud-init [-h] [--version] [--file FILES]
+                    [--debug] [--force]
+                    {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
+                    ...
 
   optional arguments:
     -h, --help            show this help message and exit
@@ -61,7 +65,7 @@ described in this document.
                           your own risk)
 
   Subcommands:
-    {init,modules,single,dhclient-hook,features,analyze,devel}
+    {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
       init                initializes cloud-init and performs initial modules
       modules             activates modules using a given configuration key
       single              run a single module
@@ -69,11 +73,153 @@ described in this document.
       features            list defined features
       analyze             Devel tool: Analyze cloud-init logs and data
       devel               Run development tools
+      collect-logs        Collect and tar all cloud-init debug info
+      clean               Remove logs and artifacts so cloud-init can re-run.
+      status              Report cloud-init status or wait on completion.
+
+CLI Subcommand details
+======================
+
+.. _cli_features:
+
+cloud-init features
+-------------------
+Print out each feature supported.  If cloud-init does not have the
+features subcommand, it also does not support any features described in
+this document.
+
+.. code-block:: bash
 
   % cloud-init features
   NETWORK_CONFIG_V1
   NETWORK_CONFIG_V2
 
+.. _cli_status:
+
+cloud-init status
+-----------------
+Report whether cloud-init is running, done, disabled or errored. Exits
+non-zero if an error is detected in cloud-init.
+ * **--long**: Detailed status information.
+ * **--wait**: Block until cloud-init completes.
+
+.. code-block:: bash
+
+  % cloud-init status --long
+  status: done
+  time: Wed, 17 Jan 2018 20:41:59 +0000
+  detail:
+  DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net]
+
+  # Cloud-init running still short versus long options
+  % cloud-init status
+  status: running
+  % cloud-init status --long
+  status: running
+  time: Fri, 26 Jan 2018 21:39:43 +0000
+  detail:
+  Running in stage: init-local
+
+.. _cli_collect_logs:
+
+cloud-init collect-logs
+-----------------------
+Collect and tar cloud-init generated logs, data files and system
+information for triage. This subcommand is integrated with apport. 
+
+**Note**: Ubuntu users can file bugs with `ubuntu-bug cloud-init` to
+automaticaly attach these logs to a bug report.
+
+Logs collected are:
+
+ * /var/log/cloud-init*log
+ * /run/cloud-init
+ * cloud-init package version
+ * dmesg output
+ * journalctl output
+ * /var/lib/cloud/instance/user-data.txt
+
+.. _cli_analyze:
+
+cloud-init analyze
+------------------
+Get detailed reports of where cloud-init spends most of its time. See
+:ref:`boot_time_analysis` for more info.
+
+ * **blame** Report ordered by most costly operations.
+ * **dump** Machine-readable JSON dump of all cloud-init tracked events.
+ * **show** show time-ordered report of the cost of operations during each
+   boot stage.
+
+.. _cli_devel:
+
+cloud-init devel
+----------------
+Collection of development tools under active development. These tools will
+likely be promoted to top-level subcommands when stable.
+
+ * ``cloud-init devel schema``: A **#cloud-config** format and schema
+   validator. It accepts a cloud-config yaml file and annotates potential
+   schema errors locally without the need for deployment. Schema
+   validation is work in progress and supports a subset of cloud-config
+   modules.
+
+.. _cli_clean:
+
+cloud-init clean
+----------------
+Remove cloud-init artifacts from /var/lib/cloud and optionally reboot the
+machine to so cloud-init re-runs all stages as it did on first boot.
+
+ * **--logs**: Optionally remove /var/log/cloud-init*log files.
+ * **--reboot**: Reboot the system after removing artifacts.
+
+.. _cli_init:
+
+cloud-init init
+---------------
+Generally run by OS init systems to execute cloud-init's stages
+*init* and *init-local*. See :ref:`boot_stages` for more info.
+Can be run on the commandline, but is generally gated to run only once
+due to semaphores in **/var/lib/cloud/instance/sem/** and
+**/var/lib/cloud/sem**.
+
+ * **--local**: Run *init-local* stage instead of *init*.
+
+.. _cli_modules:
+
+cloud-init modules
+------------------
+Generally run by OS init systems to execute *modules:config* and
+*modules:final* boot stages. This executes cloud config :ref:`modules`
+configured to run in the init, config and final stages. The modules are
+declared to run in various boot stages in the file
+**/etc/cloud/cloud.cfg** under keys **cloud_init_modules**,
+**cloud_init_modules** and **cloud_init_modules**. Can be run on the
+commandline, but each module is gated to run only once due to semaphores
+in ``/var/lib/cloud/``.
+
+ * **--mode (init|config|final)**: Run *modules:init*, *modules:config* or
+   *modules:final* cloud-init stages. See :ref:`boot_stages` for more info.
+
+.. _cli_single:
+
+cloud-init single
+-----------------
+Attempt to run a single named cloud config module.  The following example
+re-runs the cc_set_hostname module ignoring the module default frequency
+of once-per-instance:
+
+ * **--name**: The cloud-config module name to run
+ * **--frequency**: Optionally override the declared module frequency
+   with one of (always|once-per-instance|once)
+
+.. code-block:: bash
+
+  % cloud-init single --name set_hostname --frequency always
+
+**Note**: Mileage may vary trying to re-run each cloud-config module, as
+some are not idempotent.
 
 .. _Cloud-init: https://launchpad.net/cloud-init
 .. vi: textwidth=78
diff --git a/doc/rtd/topics/debugging.rst b/doc/rtd/topics/debugging.rst
index 4e43dd57..c2b47edc 100644
--- a/doc/rtd/topics/debugging.rst
+++ b/doc/rtd/topics/debugging.rst
@@ -7,6 +7,7 @@ Overview
 This topic will discuss general approaches for test and debug of cloud-init on
 deployed instances.
 
+.. _boot_time_analysis:
 
 Boot Time Analysis - cloud-init analyze
 ======================================
diff --git a/doc/rtd/topics/modules.rst b/doc/rtd/topics/modules.rst
index cdb0f419..7b146751 100644
--- a/doc/rtd/topics/modules.rst
+++ b/doc/rtd/topics/modules.rst
@@ -1,3 +1,5 @@
+.. _modules:
+
 *******
 Modules
 *******