Update documentation on hacking sessions

LAVA-1987 - set out the changes after HKG15 for
inactivity timeouts and logout termination.

Change-Id: I0b305359c893d02eb65113d962c7620221757191

1 files changed, 96 insertions, 39 deletions

diff --git a/README.rst b/README.rst
index 222d112..615b6fc 100644
--- a/README.rst
+++ b/README.rst
@@ -1,34 +1,51 @@
 LAVA Hacking Sessions
 *********************
-A LAVA hacking session is a lava-test-shell test that provides remote ssh access to a LAVA device.
+A LAVA hacking session is a lava-test-shell test that provides remote
+ssh access to a LAVA device.
 
 Assumptions
 ===========
  * The user has TCP/IP access to the device
+ * The test job deployment raises a usable networking interface.
 
 Parameters
 ==========
- * GATEWAY - The gateway for the network the target device is on 
-   (check with your LAVA admins)
- * PUB_KEY - A plain-text string containing the ssh public key(s) you wish to use to connect to the device over ssh
- * IRC_NICK - An IRC nickname to notify when ready (Debian only)
- * IRC_SERVER - The IRC server to use (Debian only)
- * NOTIFY_URL - Url to notify when ready
+ * ``PUB_KEY`` - A plain-text string containing the ssh public key(s) you
+   wish to use to connect to the device over ssh
+ * ``IRC_USER`` - your IRC nick - the user will be alerted when the hacking
+   session is ready for a connection with a private IRC message containing
+   the details of how to connect to the session. (Debian hacking sessions
+   only.)
  * testdef - The test definition (distrbution specific)
 
-  * **hacking-session-debian.yaml** - run the hacking session on a Debian
-    or Ubuntu filesystem, *openssh-server will be installed using the
-    package manager*
-    GATEWAY can be left empty for Debian hacking sessions to let the
-    device identify the default gateway.
-    IRC_SERVER defaults to irc.freenode.net
-  * **hacking-session-oe.yaml** - run the hacking session on an Open
-    Embedded filesystem *openssh-server must be installed in the image*
+  * `hacking-session-debian.yaml`_ - run the hacking session on a
+    Debian or Ubuntu filesystem, **openssh-server will be installed
+    using the package manager** if not already installed. The test
+    image **must** raise a network interface automatically (this can be
+    done with ``lava_command_run``, see `example`_).
+  * `hacking-session-oe.yaml`_ - run the hacking session on an Open
+    Embedded filesystem. **openssh-server must be installed in
+    the test image**
   * **hacking-session-android.yaml** - run the hacking session on an
-    Android filesystem *openssh-server must be installed in the image*
+    Android filesystem **openssh-server must be installed in the
+    test image**. (The YAML for this session is still in review).
+
+Options
+=======
+ * ``GATEWAY`` - The gateway for the network the target device is on -
+   only needs to be set if the test is unable to determine the gateway
+   correctly. (check with your LAVA admins)
+ * ``IRC_SERVER`` - defaults to ``irc.freenode.net``
+
+.. _hacking-session-debian.yaml: https://git.linaro.org/lava-team/hacking-session.git/blob_plain/HEAD:/hacking-session-debian.yaml
+
+.. _hacking-session-oe.yaml: https://git.linaro.org/lava-team/hacking-session.git/blob_plain/HEAD:/hacking-session-oe.yaml
+
+.. _example: https://staging.validation.linaro.org/scheduler/job/125107/definition
 
 Starting a Hacking Session
 ==========================
+
 * Create a LAVA job file with your desired target and image
 * Add a lava-test-shell action to your LAVA json job file where you want hacking access
 
@@ -42,7 +59,7 @@ Starting a Hacking Session
                     "git-repo": "http://git.linaro.org/lava-team/hacking-session.git",
                     "testdef": "hacking-session-debian.yaml",
                     "parameters": {
-                        "GATEWAY": "10.0.0.1",
+                        "IRC_USER": "TYPE YOUR IRC NICK HERE",
                         "PUB_KEY": "PASTE_PUBKEY(S) HERE"
                     }
                 }
@@ -51,8 +68,12 @@ Starting a Hacking Session
         }
     }
 
+See :ref:`inactivity_termination` for clarification of the timeout
+support.
+
 Connecting to a Hacking Session
 ===============================
+
 The hacking session test definition will report the commands to ssh within the
 LAVA log file.  To access the log file, you can use a web browser; navigate to
 your hacking session and scroll to the end of the job to see instructions
@@ -63,53 +84,89 @@ your hacking session and scroll to the end of the job to see instructions
 
 SSH tunneling
 -------------
+
 If your target device is located on a remote server, as is the case when
 accessing the Linaro LAVA lab, you'll want to tunnel onto the Linaro network
 to the device under test
 
-# verify your SSH key is setup and configured to connect
+#. verify your SSH key is setup and configured to connect::
 
- # ssh -T username@example.com
+    ~# ssh -T username@example.com
 
-# Modify your SSH config to allow agent forwarding
-
-::
+#. Modify your SSH config to allow agent forwarding::
 
     Host example.com
        ForwardAgent yes
 
 lava-test-shell helper functions in a hack session
 --------------------------------------------------
-lava-test-shell helper functions can be found within target in the directory /lava/bin
+
+lava-test-shell helper functions can be found within target in the
+directory ``/lava/bin``
 
 Record text to the LAVA log
 ---------------------------
-During a hacking session, LAVA is listening to /dev/ttyS0 for the duration of
-the hacking session.  From within the target any text you echo to /dev/ttyS0
-will be recorded within LAVA
 
- * From within the Test session
+During a hacking session, LAVA is listening to ``/dev/ttyS0`` for the
+duration of the hacking session.  From within the target any text you
+echo to ``/dev/ttyS0`` will be recorded within LAVA.
 
-  * root@kvm01:~# echo "This is a test statement" > /dev/ttyS0
+ * From within the Test session::
+
+    root@kvm01:~# echo "This is a test statement" > /dev/ttyS0
 
  * Viewing the output in the LAVA log
 
-  * https://validation.linaro.org/scheduler/job/116632/log_file#L_5_12
+   https://validation.linaro.org/scheduler/job/116632/log_file#L_5_12
+
+.. _stop_hacking:
 
 Stopping a Hacking Session
 ==========================
+
 During a hacking session, the target your are connected to can't be used for
-other tasks, to complete your session
+other tasks, so this holds up other users who may want to run tests using
+the device. Your session is monitored for :ref:`inactivity_termination`,
+or you can complete your session immediately:
+
+ * **logout** of your session (you can avoid closing the session on logout
+   using the :ref:`continue_hacking` support).
+ * **Cancel** the job in the LAVA using the link in the job detail or
+   job log pages.
+ * **Stop** - Use the helper function ``stop_hacking`` from the command-line
+   within the hacking session
+
+.. note:: Cancel will end the job immediately, there will not be any time
+   to process the :term:`result bundle`. Use ``stop_hacking`` to close the
+   session and complete normal job processing.
+
+.. _inactivity_termination:
+
+Hacking Session timeouts
+========================
+
+.. note:: This behaviour changed after a session at
+   `Connect HKG15 <http://www.slideshare.net/linaroorg/hkg15402-orphan-hacking-sessions>`_
+
+All hacking sessions will **timeout after 1 hour** if a login has not
+been detected. If an ``IRC_USER`` is specified with a Debian hacking
+session, that user will get another IRC private message explaining
+the termination.
+
+The timer is running for the lifetime of the hacking session, so if you
+use :ref:`continue_hacking` and logout, you will still need to log back
+in within one hour.
 
- * Cancel the job in the LAVA dashboard
+The session will timeout, regardless of activity, when the timeout
+specified in the job is reached.
 
- * Use the helper function 'stop_hacking' from the command-line within the hacking session
+.. _continue_hacking:
 
-About
-*****
-Linaro Automated Validation Architecture (LAVA)
+Continuing a Hacking Session
+============================
 
-* Code: https://git.linaro.org/lava-team/hacking-session.git
-* Hosted website: https://validation.linaro.org
-* Documentation: https://validation.linaro.org/static/docs
-* Mailing list: linaro-validation@lists.linaro.org
+If you want to be able to logout of a hacking session and log back in
+within the inactivity timeout, call the ``continue_hacking`` script from
+the command line within the hacking session. The hacking session is still
+monitored for :ref:`inactivity_termination`, so do remember to log back
+in.