← Back to branch summary

~ubuntu-branches/debian/jessie/lava-server/jessie

« back to all changes in this revision

Viewing changes to doc/hacking-session.rst

  • Committer: Package Import Robot
  • Author(s): Neil Williams
  • Date: 2014-06-29 19:29:34 UTC
  • Revision ID: package-import@ubuntu.com-20140629192934-ue8hrzzpye9isevt
Tags: upstream-2014.05.30.09
Import upstream version 2014.05.30.09

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/hacking-session.rst
 
1
LAVA Hacking Sessions
 
2
*********************
 
3
A LAVA hacking session is a lava-test-shell test that provides remote
 
4
ssh access to a LAVA device.
 
5
 
 
6
Assumptions
 
7
===========
 
8
 * The user has TCP/IP access to the device
 
9
 
 
10
Parameters
 
11
==========
 
12
 * ``GATEWAY`` - The gateway for the network the target device is on
 
13
   (check with your LAVA admins)
 
14
 * ``PUB_KEY`` - A plain-text string containing the ssh public key(s) you
 
15
   wish to use to connect to the device over ssh
 
16
 * testdef - The test definition (distrbution specific)
 
17
 
 
18
  * `hacking-session-debian.yaml`_ - run the hacking session on a
 
19
    Debian or Ubuntu filesystem, **openssh-server will be installed
 
20
    using the package manager** if not already installed. The test
 
21
    image **must** raise a network interface automatically.
 
22
  * `hacking-session-oe.yaml`_ - run the hacking session on an Open
 
23
    Embedded filesystem. **openssh-server must be installed in
 
24
    the test image**
 
25
  * **hacking-session-android.yaml** - run the hacking session on an
 
26
    Android filesystem **openssh-server must be installed in the
 
27
    test image**. (The YAML for this session is still in review).
 
28
 
 
29
.. _hacking-session-debian.yaml: https://git.linaro.org/lava-team/hacking-session.git/blob_plain/HEAD:/hacking-session-debian.yaml
 
30
 
 
31
.. _hacking-session-oe.yaml: https://git.linaro.org/lava-team/hacking-session.git/blob_plain/HEAD:/hacking-session-oe.yaml
 
32
 
 
33
Starting a Hacking Session
 
34
==========================
 
35
 
 
36
* Create a LAVA job file with your desired target and image
 
37
* Add a lava-test-shell action to your LAVA json job file where you want hacking access
 
38
 
 
39
::
 
40
 
 
41
    {
 
42
        "command": "lava_test_shell",
 
43
        "parameters": {
 
44
            "testdef_repos": [
 
45
                {
 
46
                    "git-repo": "http://git.linaro.org/lava-team/hacking-session.git",
 
47
                    "testdef": "hacking-session-debian.yaml",
 
48
                    "parameters": {
 
49
                        "GATEWAY": "10.0.0.1",
 
50
                        "PUB_KEY": "PASTE_PUBKEY(S) HERE"
 
51
                    }
 
52
                }
 
53
            ],
 
54
            "timeout": 3600
 
55
        }
 
56
    }
 
57
 
 
58
.. note:: The session **will not end** simply because you log out. Always
 
59
          use the commands for :ref:`stop_hacking` so that the device is
 
60
          returned to the pool for other users to use as soon as you
 
61
          have finished with your hacking session.
 
62
 
 
63
Connecting to a Hacking Session
 
64
===============================
 
65
 
 
66
The hacking session test definition will report the commands to ssh within the
 
67
LAVA log file.  To access the log file, you can use a web browser; navigate to
 
68
your hacking session and scroll to the end of the job to see instructions
 
69
 
 
70
 * This hack session was executed on Linaro's LAVA system, job ID: 116632
 
71
 
 
72
  * https://validation.linaro.org/scheduler/job/116632/log_file#L_5_7
 
73
 
 
74
SSH tunneling
 
75
-------------
 
76
 
 
77
If your target device is located on a remote server, as is the case when
 
78
accessing the Linaro LAVA lab, you'll want to tunnel onto the Linaro network
 
79
to the device under test
 
80
 
 
81
#. verify your SSH key is setup and configured to connect::
 
82
 
 
83
    ~# ssh -T username@example.com
 
84
 
 
85
#. Modify your SSH config to allow agent forwarding::
 
86
 
 
87
    Host example.com
 
88
       ForwardAgent yes
 
89
 
 
90
lava-test-shell helper functions in a hack session
 
91
--------------------------------------------------
 
92
 
 
93
lava-test-shell helper functions can be found within target in the
 
94
directory ``/lava/bin``
 
95
 
 
96
Record text to the LAVA log
 
97
---------------------------
 
98
 
 
99
During a hacking session, LAVA is listening to ``/dev/ttyS0`` for the
 
100
duration of the hacking session.  From within the target any text you
 
101
echo to ``/dev/ttyS0`` will be recorded within LAVA.
 
102
 
 
103
 * From within the Test session::
 
104
 
 
105
    root@kvm01:~# echo "This is a test statement" > /dev/ttyS0
 
106
 
 
107
 * Viewing the output in the LAVA log
 
108
 
 
109
   https://validation.linaro.org/scheduler/job/116632/log_file#L_5_12
 
110
 
 
111
.. _stop_hacking:
 
112
 
 
113
Stopping a Hacking Session
 
114
==========================
 
115
 
 
116
During a hacking session, the target your are connected to can't be used for
 
117
other tasks, to complete your session
 
118
 
 
119
 * Cancel the job in the LAVA using the link in the job detail or
 
120
   job log pages.
 
121
 * Use the helper function ``stop_hacking`` from the command-line
 
122
   within the hacking session