From e33807033b6d3a42b3ff9f9d6ddd394cd8306af9 Mon Sep 17 00:00:00 2001 From: Neil Williams Date: Fri, 1 May 2015 09:47:12 +0100 Subject: Update documentation on hacking sessions LAVA-1987 - set out the changes after HKG15 for inactivity timeouts and logout termination. Change-Id: I0b305359c893d02eb65113d962c7620221757191 --- README.rst | 135 +++++++++++++++++++++++++++++++++++++++++++------------------ 1 file 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 `_ + +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. -- cgit v1.2.3