Add documentation for rescue mode

This adds documentation for rescue mode, including the finalize_rescue
command as well as upstream support in agent images.

Change-Id: Id0834941ee4dacf2e7c0feaa65126d63e8a97c39
Partial-Bug: 1526449

4 files changed, 94 insertions, 0 deletions

diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index b4545ed8..dbe5cdd0 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -17,6 +17,7 @@ Index
 
 .. toctree::
     how_it_works
+    rescue
     troubleshooting
 
 Indices and tables
diff --git a/doc/source/admin/rescue.rst b/doc/source/admin/rescue.rst
new file mode 100644
index 00000000..0e33c6c8
--- /dev/null
+++ b/doc/source/admin/rescue.rst
@@ -0,0 +1,53 @@
+.. _admin_rescue:
+
+===========
+Rescue mode
+===========
+
+Overview
+========
+
+Rescue mode is a feature that can be used to boot a ramdisk for a tenant in
+case the machine is otherwise inaccessible. For example, if there's a disk
+failure that prevents access to another operating system, rescue mode can be
+used to diagnose and fix the problem.
+
+Support in ironic-python-agent images
+=====================================
+
+Rescue is initiated when ironic-conductor sends the ``finalize_rescue``
+command to ironic-python-agent. A user `rescue` is created with a password
+provided as an argument to this command. DHCP is then configured to
+facilitate network connectivity, thus enabling a user to login to the machine
+in rescue mode.
+
+.. warning:: Rescue mode exposes the contents of the ramdisk to the tenant.
+             Ensure that any rescue image you build does not contain secrets
+             (e.g. sensitive clean steps, proprietary firmware blobs).
+
+The below has information about supported images that may be built to use
+rescue mode.
+
+CoreOS
+------
+
+The CoreOS image supports rescue mode when used with DHCP tenant networks. You
+may follow the normal process for `building a CoreOS ironic-python-agent
+image`_ to create an image that supports rescue mode.
+
+After the ``finalize_rescue`` command completes, DHCP will be configured on all
+network interfaces, and a `rescue` user will be created with the specified
+``rescue_password``.
+
+TinyIPA
+-------
+
+The TinyIPA image supports rescue mode when used with DHCP tenant networks.
+No special action is required to `build a TinyIPA image`_ with this support.
+
+After the ``finalize_rescue`` command completes, DHCP will be configured on all
+network interfaces, and a `rescue` user will be created with the specified
+``rescue_password``.
+
+.. _`building a CoreOS ironic-python-agent image`: https://github.com/openstack/ironic-python-agent/tree/master/imagebuild/coreos/README.rst
+.. _`build a TinyIPA image`: https://github.com/openstack/ironic-python-agent/tree/master/imagebuild/tinyipa/README.rst
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index f1f4ae7f..4f421637 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -19,6 +19,7 @@ Index
 
     hardware_managers
     metrics
+    rescue
 
 Generated Developer Documentation
 =================================
diff --git a/doc/source/contributor/rescue.rst b/doc/source/contributor/rescue.rst
new file mode 100644
index 00000000..16b185f4
--- /dev/null
+++ b/doc/source/contributor/rescue.rst
@@ -0,0 +1,39 @@
+.. rescue:
+
+===========
+Rescue Mode
+===========
+
+Ironic supports putting nodes in rescue mode using hardware types that
+support rescue interfaces. A rescue operation can be used to boot nodes
+into a rescue ramdisk so that the ``rescue`` user can access the node.
+This provides the ability to access the node when normal access is not
+possible. For example, if there is a need to perform manual password
+reset or data recovery in the event of some failure, a rescue operation
+can be used. IPA rescue extension exposes a command ``finalize_rescue``
+(that is used by Ironic) to set the password for the ``rescue`` user
+when the rescue ramdisk is booted.
+
+finalize_rescue command
+=======================
+
+The rescue extension exposes the command ``finalize_rescue``; when
+invoked, it triggers rescue mode::
+
+    POST /v1/commands
+
+    {"name": "rescue.finalize_rescue",
+     "params": {
+        "rescue_password": "p455w0rd"}
+    }
+
+``rescue_password`` is a required parameter for this command.
+
+If successful, this synchronous command will:
+
+1. Write the salted and crypted ``rescue_password`` to
+   ``/etc/ipa-rescue-config/ipa-rescue-password`` in the chroot or filesystem
+   that ironic-python-agent is running in.
+
+2. Stop the ironic-python-agent process after completing these actions and
+   returning the response to the API request.