aboutsummaryrefslogtreecommitdiffstats
path: root/userdata/conf/lava/lava-boot/README
diff options
context:
space:
mode:
Diffstat (limited to 'userdata/conf/lava/lava-boot/README')
-rw-r--r--userdata/conf/lava/lava-boot/README203
1 files changed, 203 insertions, 0 deletions
diff --git a/userdata/conf/lava/lava-boot/README b/userdata/conf/lava/lava-boot/README
new file mode 100644
index 0000000..7484a9e
--- /dev/null
+++ b/userdata/conf/lava/lava-boot/README
@@ -0,0 +1,203 @@
+Lava-boot
+=========
+
+Lava-boot is a synchronous alternative to the official lava-tool command line
+tool. Lava-boot will submit a job and exit when the job finishes.
+
+The key use case is quick turnaround testing of locally built kernel in LAVA.
+
+Lava-boot features include variable substitution in job/test definition files,
+running scripts on target devices (with exit code return) and even
+integrated hacking session support.
+
+Quick start
+===========
+
+Go to your lava web interface and get your API key from api->tokens
+
+Create the minimal ~/.lava.yaml configuration file:
+
+-~/lava.yaml-
+server: lava-server
+user: username
+token: lava token string
+https: true
+-~/lava.yaml-
+
+The simplest invocation with just an existing json file:
+
+$ lava-boot -j test.json
+[12:32:46] LAVA Job 10, URL: http://lava-server/scheduler/job/10
+
+[12:32:46] LAVA Job 10, status: Submitted .
+[12:33:47] LAVA Job 10, status: Running ...................
+[12:43:56] LAVA Job 10 finished, status: Complete
+...output of lava job...
+
+Booting a local built kernel
+============================
+
+To boot a kernel in lava, the kernel needs to be placed somewhere where lava
+can fetch it from. lava-boot launches a HTTP server and uploads kernel and
+other artifacts there. The server is configured with the "proxy-ssh" and
+"proxy-hostname" variables below:
+
+-~/lava.yaml-
+server: lava-server
+user: username
+token: output of lava token
+https: true
+
+proxy-ssh: username@jumphost
+proxy-hostname: jumphost
+-~/lava.yaml-
+
+proxy-ssh is the username@host combo for the ssh to host which can be reached
+from the lava dispatcher and lava target machines. proxy-hostname is the
+hostname as seen from dispatcher.
+
+In case your PC and lava dispatcher are in the same network, you don't need
+proxy-ssh setting - just set proxy-hostname t the hostname or IP of the PC
+where you are running lava-boot from.
+
+You will now need a lava job definition with a few variable expansions. You
+can take an existing .json file and set the dtb to ${PROXY}/${DTB} and kernel
+to ${PROXY}/${KERNEL}, or you can use the minimal yaml file below as beginning
+point. lava-boot will convert the yaml file to json file on the fly.
+
+-test.yaml-
+actions:
+ - command: deploy_linaro_kernel
+ parameters:
+ dtb: '${PROXY}/${DTB}'
+ kernel: '${PROXY}/${KERNEL}'
+ nfsrootfs: ${ROOTFS}
+ - command: boot_linaro_image
+device_type: '${DEVICE_TYPE}'
+job_name: '${JOB_NAME}'
+timeout: 1800
+-test-yaml-
+
+Now say, you have a kernel for apm mustang compiled under build/ directory,
+you can now boot with:
+
+lava-boot -k build/ -d arndale -j test.yaml
+[16:00:26] Proxy started at: user@jumphost, URL: http://jumphost:29871
+[16:00:28] Uploading kernel build/arch/arm/boot/zImage
+[16:00:34] Uploading dtb build/arch/arm/boot/dts/exynos5250-arndale.dtb for arndale
+[16:00:35] LAVA Job 11, URL: http://lava-server/scheduler/job/11
+
+[16:00:35] LAVA Job 11, status: Submitted
+[16:01:06] LAVA Job 11, status: Running .
+
+
+Running a script on device and fetch it's exit code
+===================================================
+
+The original motivation for this script was to run arbitrary scripts against
+the locally built kernel and get the results back. For example, to bisect a
+regression on where the rtc device vanished, you might want a script like
+
+--has-rtc.sh--
+#!/bin/sh -e
+test -c /dev/rtc
+--has-rtc.sh--
+
+$ lava-boot --quiet -k build/ -d arndale -r has-rtc.sh
+[16:00:26] Proxy started at: user@jumphost, URL: http://jumphost:29871
+[16:00:28] Uploading kernel build/arch/arm/boot/zImage
+[16:00:34] Uploading dtb build/arch/arm/boot/dts/exynos5250-arndale.dtb for arndale
+[16:00:34] Uploading test-rtc
+[16:00:35] Uploading test_definition.yaml
+[16:00:35] LAVA Job 11, URL: http://lava-server/scheduler/job/11
+
+[16:00:35] LAVA Job 11, status: Submitted
+[16:01:06] LAVA Job 11, status: Running ......
+[16:04:38] LAVA Job 11, script finished: fail
+$
+
+The target of this feature is to help bisecting.
+
+Automatic hacking sessions
+==========================
+
+One advanced hack in this script has is automatic hack sessions: Add your ssh
+key settings to config. sshfile is optional if you only have one private ssh
+key. sshkey variable is the contents of your public ssh key, usually in file
+~/.ssh/id_rsa.pub.
+
+-~/lava.yaml-
+sshfile: "~/.ssh/private_file"
+sshkey: "ssh-rsa AAAAB3i...."
+-~/lava.yaml-
+
+Add the --hack option:
+
+$ lava-boot -k build -d arndale --hack
+[14:27:19] Proxy started at: user@jumphost, URL: http://jumphost:36766
+[14:27:21] Uploading kernel build/arch/arm/boot/zImage
+[14:27:27] Uploading dtb build/arch/arm/boot/dts/exynos5250-arndale.dtb for arndale
+[14:27:27] LAVA Job 243722, URL: http://lava-server/scheduler/job/243722
+
+[14:27:27] LAVA Job 243722, status: Submitted
+[14:27:58] LAVA Job 243722, status: Running ........
+[14:32:31] LAVA Job 243722, hacking session: 10.1.1.1
+[14:32:32] session started with: ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o 'ProxyCommand=ssh user@jumphost netcat %h %p' root@10.1.1.1
+Warning: Permanently added '10.1.1.1' (ECDSA) to the list of known hosts.
+Welcome to Ubuntu 14.10 (GNU/Linux 3.19.0-rc5 armv7l)
+
+ * Documentation: http://www.linaro.org
+Last login: Sat Jan 1 00:00:13 2000
+root@linaro-nano:~#
+lava-boot -k build/ -d mustang --hack
+
+
+Variable substitution
+=====================
+
+Automatic Variables defined by lava-boot:
+
+GIT_COMMIT = git commit id of kernel
+TESTCASE = lava_test_shell test case passed from command line
+KERNEL = kernel filename
+DTB = device tree file used
+DEVICE_TYPE = lava device type
+
+PROXY = proxy HTTP URL
+RESULT_URL = URL to poll back for results
+JOB_NAME = generated name for job
+
+ROOTFS = rootfs URL
+ lava-boot fill this with rootfs_arm for 32bit target and
+ rootfs_arm64 for 64bit targets. these variables can be set
+ in ~/.lava.yaml
+
+All variables from ~/.lava.yaml are expanded too. You can add arbitrary
+key/value pairs to the configuration file, and lava-boot will used them
+in substitution phase.
+
+Multi-server configuration
+==========================
+
+The configuration file supports defining several servers, using yaml list
+format:
+
+- server: lavaserver.net
+ user: ss
+ token: ...
+- server: staging.lavaserver.net
+ user: xx
+ token: ...
+
+In this format by default lava-boot will pick up first server defined. other
+servers can be selected using "-s staging.lavaserver.net" in command line
+
+TODO
+====
+
+* test suite!
+* printing output from LAVA line-by-line
+* instead of passing success/fail via proxy, support reading lava-test-shell
+ results from result bundle
+* make is possible to upload the job artifacts directly to LAVA so proxy can
+ be eliminated.