Each LAVA instance offers a Local User Account and may also be configured to an alternative authentication method:
OpenID is no longer available for all installations of LAVA. Incompatible changes in the underlying django support made it impossible to support OpenID since the 2015.12 release.
See also
User authentication for more information.
LDAP authentication relies on local configuration and may involve obtaining a privileged access token from the LDAP administrators.
Local accounts remain available for all instances.
Whichever authentication method is used, there is no difference in how users interact with LAVA once logged in.
A local user account may be created by an administrator within LAVA. The administrator may grant different permissions to the user to perform various operations within LAVA. A typical login screen will look something like the following.
To log in with a username and password, enter your credentials in the provided text boxes and click “Sign in with username and password” button.
Local user accounts can be particularly useful for automated users like build systems or continuous integration scripts using the XML-RPC API. The local admin can create the user with a secure password, log in as that user to create a token and then supply the token to the scripts.
Linaro’s central validation lab in Cambridge is accessible via https://validation.linaro.org/ . It is Linaro’s core production instance of LAVA.
This lab is configured to use Linaro LDAP. To log in, enter your details in the LDAP login fields.
Note
If your Linaro email is first.second@linaro.org
then use
first.second
as your username.
A successful authentication will redirect you to https://validation.linaro.org/
If you do not have a Linaro LDAP account, you can Register with Linaro as a Community contributor.
After loggig in, the LAVA scheduler page will look something like the following:
In order to securely access LAVA resources via XML-RPC APIs using lava-tool or XML-RPC clients, users first need to create an authentication token.
Once logged in to a LAVA instance (e.g. https://validation.linaro.org/), click on the “API” link then on the “Authentication Tokens” link from the drop down menu. The following page will appear
Click on the “New” button on the above page which raises a dialog box asking for a “Description” of the token to help you identify and delete tokens - if required at a later stage.
Click on the “Create” button to generate the token. The token will be assigned a token number (which is autogenerated by LAVA).
To display the token that was generated above click on the green “Display this token” button in the Actions column on the above page.
If a token is compromised, it can be removed by clicking on the red “delete this token” button in the Actions column. Anyone using that token will then no longer be able to authenticate as you in the system.
A job defines what software should be deployed on the device under
test
(DUT) and what actions should be performed there. Jobs are
defined in YAML files.
Here’s an example minimal job that you should be able to use right away if you have user access to an appropriately-configured LAVA installation.
# Your first LAVA JOB definition for an x86_64 QEMU
device_type: qemu
job_name: QEMU pipeline, first job
timeouts:
job:
minutes: 15
action:
minutes: 5
connection:
minutes: 2
priority: medium
visibility: public
# context allows specific values to be overridden or included
context:
# tell the qemu template which architecture is being tested
# the template uses that to ensure that qemu-system-x86_64 is executed.
arch: amd64
metadata:
# please change these fields when modifying this job for your own tests.
docs-source: first-job
docs-filename: qemu-pipeline-first-job.yaml
actions:
- deploy:
timeout:
minutes: 5
to: tmpfs
images:
rootfs:
image_arg: -drive format=raw,file={rootfs}
url: https://images.validation.linaro.org/kvm-debian-wheezy.img.gz
compression: gz
os: debian
- boot:
method: qemu
media: tmpfs
prompts: ["root@debian:"]
- test:
timeout:
minutes: 5
definitions:
- repository: git://git.linaro.org/qa/test-definitions.git
from: git
path: ubuntu/smoke-tests-basic.yaml
name: smoke-tests
- repository: https://git.linaro.org/lava-team/lava-functional-tests.git
from: git
path: lava-test-shell/single-node/singlenode03.yaml
name: singlenode-advanced
See also
Jobs may be submitted to LAVA in one of three ways:
lava-tool
program); orNote
lava-tool
is a general-purpose command line interface
for LAVA which can be used directly on the LAVA server
machines and also remotely on any computer running a
Debian-based distribution. See lava-tool for more
information.
For now, lava-tool is the easiest option to demonstrate. Once you have
copied the above job definition to a file, (for example
/tmp/job.yaml), use lava-tool
to submit it as a test job in
Linaro’s main LAVA lab:
$ lava-tool submit-job https://<username>@validation.linaro.org/RPC2/
/tmp/job.yaml
Please enter password for encrypted keyring:
submitted as job id: 82287
Note
Replace username with your username. Enter the password for the encrypted keyring which is the same that was used when adding the authentication token.
Once the job is submitted successfully, the job id is returned; this
may be used in order to check the status of the job via the web UI. In
the above submission the job id returned is 82287. Visit
https://validation.linaro.org/scheduler/job/<job-id>
in order to
see the details of the job run: the test device chosen, the test
results, etc.
It may take some time before the job actually starts, depending on the number of jobs waiting in the queue for a device of this type. Once the job starts, the status information will automatically update and the logs will appear.
Results are populated live and will start to appear during the operation of the deploy action. The plain log can be downloaded and the definition is available for later reference. If you are the submitter of the job, you can also choose to cancel the job.
In order to run a test, a test definition is required. A test definition is expressed in YAML format. A minimal test definition would look something like the following:
metadata:
name: passfail
format: "Lava-Test-Shell Test Definition 1.0"
description: "Pass/Fail test."
version: 1.0
run:
steps:
- "lava-test-case passtest --result pass"
- "lava-test-case failtest --result pass"
The first job mentioned above uses a more complex test definition:
https://git.linaro.org/qa/test-definitions.git/blob/HEAD:/ubuntu/smoke-tests-basic.yaml
The metadata in a test definition is for the maintenance of that test definition and covers details like the maintainer, the kinds of devices which may find this test definition useful and the scope of the test definition. (Scope is arbitrary, often a scope of functional is used to describe a test which is useful to test that the image is functioning correctly.) The run steps of this definition are:
run:
steps:
- lava-test-case linux-linaro-ubuntu-pwd --shell pwd
- lava-test-case linux-linaro-ubuntu-uname --shell uname -a
- lava-test-case linux-linaro-ubuntu-vmstat --shell vmstat
- lava-test-case linux-linaro-ubuntu-ifconfig --shell ifconfig -a
- lava-test-case linux-linaro-ubuntu-lscpu --shell lscpu
- lava-test-case linux-linaro-ubuntu-lsb_release --shell lsb_release -a
This simple test executes a series of commands in the booted image. The exit value of each command is used to determine whether the test case passed or failed. You can try any of these commands on a Ubuntu or Debian system to see what the commands should create as output.
See also
On the job view page, there is a button to access the Results. Results can also be accessed from the Results Overview in the menu. The results for the first job example could look like:
The results include the test definitions submitted within the job as well
as a reserved lava
set of results generated during the operation of
the test job itself. There is also metadata which is generated by the
test job, including details like the URL of the test definitions used
and the type of deploy and boot methods involved in the test job.
LAVA V2 makes the test results available directly from the instance,
without needing to go through lava-tool
. Currently, the results
for any test job can be downloaded as CSV
and YAML format.
For example, the results for test job number 123 are available as CSV using:
https://validation.linaro.org/results/123/csv
The same results for job number 123 are available as YAML using:
https://validation.linaro.org/results/123/yaml
If you know the test definition name, you can download the results for that specific test definition only in the same way:
https://validation.linaro.org/results/123/singlenode-advanced/csv
https://validation.linaro.org/results/123/singlenode-advanced/yaml
Some test jobs can be restricted to particular users or groups of users. The results of these test jobs are restricted in the same way. To download these results, you will need to specify your username and one of your Authentication Tokens - remember to quote the URL if using it on the command line or the & will likely be interpreted by your shell:
'https://validation.linaro.org/results/123/csv?user=user.name&token=yourtokentextgoeshereononeverylongline'
$ curl 'https://validation.linaro.org/results/123/singlenode-advanced/yaml?user=user.name&token=yourtokentextgoeshereononeverylongline'
Use the Username as specified in your Profile - this may differ from the username you use when logging in with LDAP.
Caution
Take care of your tokens - avoid using personal tokens in
scripts and test definitions or other files that end up in public
git repositories. Wherever supported, use https://
when using a
token.
The web UI form does not yet support pipeline (V2) jobs; expect this support to appear soon.
lava-tool is a wrapper around the XML-RPC API with helpers for personal usage. The XML-RPC API itself supports a variety of queries and operations which can assist in creating a frontend to LAVA which can automate the submission of test jobs.
Many languages have XML-RPC support, the API help page on each LAVA
instance provides a python example script, with and without using
tokens. Job submission requires using
an authentication token and should
use https
wherever possible to protect the token.
See also
For help using the XML-RPC API to submit jobs, see the
sections on lava-tool and the Available methods link from
the API menu of the LAVA instance.
For example: http://localhost/api/help
.
lava-tool
is the command-line tool for interacting with the various
services offered by LAVA via XML-RPC APIs. The full list of API calls
is visible on the Available methods link from the API menu:
http://localhost/api/help
lava-tool
is primarily designed to assist users and uses desktop
integration hooks provided by python-keyring
and
gnome-keyring
. If writing or using scripts that need to interact
with LAVA, it is recommended to use XML-RPC API calls directly rather
than calling lava-tool; this will avoid the need to prompt for a
password to access the local user keyring. Scripts used by build
servers and continuous integration tools should ideally use a
dedicated user account, for similar reasons.
The API help page includes an example python script to connect to the local instance. To add token support, use the syntax username:token for the server concerned:
server = xmlrpclib.ServerProxy("https://%s:%s@%s/RPC2" % (username, token, server))
See XML-RPC for more information.
lava-tool
is installed alongside LAVA by default, when the top
level lava
package is installed on a
Debian-based distributions. lava-tool
can also be installed on any
remote machine running a Debian-based distribution, without needing
the rest of LAVA. This allows a remote user to interact with any LAVA
instance on which the user has an account.:
$ sudo apt update
$ sudo apt install lava-tool
(If you are installing on Debian Jessie, you may want to first enable
jessie-backports
to install an updated lava-tool
to use
some superuser operations or for other updates.)
Once the token is created, add it to the keyring for lava-tool. Click on the “Display the token” link on the “Authentication Tokens” page and copy the token. e.g. if your token was created on validation.linaro.org:
$ lava-tool auth-add https://<username>@validation.linaro.org/RPC2/
Paste token for https://<username>@validation.linaro.org/RPC2/:
Please set a password for your new keyring:
Please confirm the password:
Token added successfully for user <username>.
Note
Paste the token copied previously when it is asked above. Replace username with your username. If you don’t already have a keyring, a new one will be created automatically. Set/use a password for keyring access as appropriate here.
LAVA presents much of the data about jobs, devices, results and tasks inside tables. The length of a table can be controlled, the table can be sorted by selected columns and the data itself can be searched. All options can be controlled from the query string in the browser address bar. This allows particular views of a table to be shared as links. See Custom table queries.
For pages which only contain a single table, the number of rows displayed in each page of data is controlled via the length parameter. For convenience, there is a drop down box on the left of each table where the table length can be selected.
Note
Tables are only the base representation of the data available in LAVA and whenever the table search support seems incomplete, the solution is to create a Query which can also be represented as a simple URL.
Unless specified explicitly, all table searches are case-sensitive.
The search box above each table allows arbitrary text strings to be used as filters on the data within the table. Each table has support for matching simple text strings against certain columns within the table and these searches are additive - the data in the row will be included in the results if the text matches any of the search fields.
The fields which support text search are listed above each table.
Some tables also support customised queries on specific fields, typically these will be time based fields like submit_time, end_time and duration. These queries allow a specific function to be called within the filter to match only results where the timestamp occurred within the specified number of minutes, hours or days, relative to the current time on the server.
The queries supported by a table are listed above the table, along with details of whether that query is based on minutes, hours or days.
Note
Time based queries will always take the current time on the server into account, so links containing such queries may not give the same results when viewed at a later time.
Time based queries can take calculations in the query string as well,
e.g. end_time
is based on hours, so ?end_time=4*24
matches
end_time
within the last 4 days (the search summary will still show
the 4*24
.)
Fields used in simple text searches can also be used as exclusive searches by adding the exclusive search field to the querystring. The data in the row will be included in the results only if the text matches all of the search fields:
?device=mx5&length=25&description=ARMMP&status=Incom
This querystring would only show rows where the device hostname contains
mx5
and the description contains ARMMP
and the status of
the job contains Incom
, therefore showing up to 25 results for jobs
on such devices with that description which finished with a status of
Incomplete.
Note
Exclusive searches are not supported via the search box in the table header. Add to the querystring directly. Exclusive text search cannot be combined with simple text search. Replace the search variable in the querystring with the closest discrete query term, e.g. description.
The fields which support exclusive search are listed above each table.
Individual tables may also provide filters via javascript or other support.
The breadcrumb link should take you back to the default table. Alternatively, clear the querystring in the browser address bar manually.