.\" Man page generated from reStructuredText.
.
.TH "LAVA-DISPATCH" "1" "October 20, 2014" "lava-dispatcher-2014.09.1
" "LAVA Dispatcher"
.SH NAME
lava-dispatch \- dispatch jobs to LAVA devices
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SUMMARY
.sp
\fBlava\-dispatch\fP runs a LAVA test job on the reserved device, as
scheduled by the \fBlava\-server\fP and publish the test result back to
the server. Jobs are scheduled by the server but can also be run by
calling \fBlava\-dispatch\fP directly.
.sp
You can see an up\-to\-date list of supported target devices by looking
at the device types on the relevant server.
.SH USAGE
.sp
lava dispatch [\-h] [\-\-config\-dir CONFIG_DIR] [\-\-oob\-fd OOB_FD]
[\-\-output\-dir OUTPUT_DIR] [\-\-validate] [\-\-job\-id JOB_ID]
[\-\-target TARGET]
JOB
.SH OPTIONS
.INDENT 0.0
.TP
.B positional arguments:
JOB                   Test scenario JSON file
.TP
.B optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-config\-dir \ CONFIG_DIR
Configuration directory override
.TP
.BI \-\-oob\-fd \ OOB_FD
Used internally by LAVA scheduler.
.TP
.BI \-\-output\-dir \ OUTPUT_DIR
Directory to put structured output in.
.TP
.B \-\-validate
Just validate the job file, do not execute any steps.
.TP
.BI \-\-job\-id \ JOB_ID
Set the scheduler job identifier. This alters process
name for easier debugging
.TP
.BI \-\-target \ TARGET
Run the job on a specific target device
.UNINDENT
.UNINDENT
.SH LAVA TEST DEFINITIONS
.sp
A LAVA Test Definition comprises of two parts:
.INDENT 0.0
.IP \(bu 2
the data to setup the test, expressed as a JSON file.
.IP \(bu 2
the instructions to run inside the test, expressed as a YAML file.
.UNINDENT
.sp
This allows the same tests to be easily migrated to a range of different
devices, environments and purposes by using the same YAML files in
multiple JSON files. It also allows tests to be built from a range of
components by aggregating YAML files inside a single JSON file.
.SH CONTENTS OF THE JSON FILE
.sp
The JSON file is submitted to the LAVA server and contains:
.INDENT 0.0
.IP \(bu 2
Demarcation as a health check or a user test.
.IP \(bu 2
The default timeout of each action within the test.
.IP \(bu 2
The logging level for the test, DEBUG or INFO.
.IP \(bu 2
The name of the test, shown in the list of jobs.
.IP \(bu 2
The location of all support files.
.IP \(bu 2
All parameters necessary to use the support files.
.IP \(bu 2
The declaration of which device(s) to use for the test.
.IP \(bu 2
The location to which the results should be uploaded.
.IP \(bu 2
The JSON determines how the test is deployed onto the device and
where to find the tests to be run.
.UNINDENT
.SH BASIC JSON FILE
.sp
Your first LAVA test should use the \fBDEBUG\fP logging level so that it
is easier to see what is happening.
.sp
A suitable \fBtimeout\fP for your first tests is 900 seconds.
.sp
Make the \fBjob_name\fP descriptive and explanatory, you will want to be
able to tell which job is which when reviewing the results.
.sp
Make sure the \fBdevice_type\fP matches exactly with one of the suitable
device types listed on the server to which you want to submit this job.
.sp
Change the stream to one to which you are allowed to upload results, on
your chosen server.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
  "health_check": false,
  "logging_level": "DEBUG",
  "timeout": 900,
  "job_name": "kvm\-basic\-test",
  "device_type": "kvm",
  "actions": [
      {
          "command": "deploy_linaro_image",
          "parameters": {
              "image": "http://images.validation.linaro.org/kvm\-debian\-wheezy.img.gz"
          }
      },
      {
          "command": "lava_test_shell",
          "parameters": {
              "testdef_repos": [
                  {
                      "git\-repo": "git://git.linaro.org/qa/test\-definitions.git",
                      "testdef": "ubuntu/smoke\-tests\-basic.yaml"
                  }
              ],
              "timeout": 900
          }
      },
      {
          "command": "submit_results_on_host",
          "parameters": {
              "stream": "/anonymous/example/",
              "server": "http://localhost/RPC2/"
          }
      }
  ]
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH NOTE
.sp
Always check your JSON syntax. A useful site for this is \fI\%http://jsonlint.com\fP\&.
.SH USEFUL LINKS
.sp
\fI\%http://validation.linaro.org/static/docs/writing\-tests.html\fP
.sp
\fI\%http://validation.linaro.org/\fP
.sp
\fI\%http://validation.linaro.org/static/docs/overview.html\fP
.sp
\fI\%http://www.linaro.org/engineering/validation\fP
.SH AUTHOR
Linaro Validation Team
.SH COPYRIGHT
2011-2013, Linaro Validation Team
.\" Generated by docutils manpage writer.
.