First Steps Using LAVA V2

Logging In

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.

Local User Account

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.

_images/local-user-login.png

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 lab users

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.

_images/ldap-user-login.png

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:

_images/lava-scheduler-page.png

Authentication Tokens

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

_images/authentication-tokens-page.png

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.

_images/create-new-authentication-token.png

Click on the “Create” button to generate the token. The token will be assigned a token number (which is autogenerated by LAVA).

_images/sample-token-page.png

To display the token that was generated above click on the green “Display this token” button in the Actions column on the above page.

_images/token-display-page.png

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.

Submitting your first job

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.

Job Definition

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

Job Submission

Jobs may be submitted to LAVA in one of three ways:

  • the command line (using the lava-tool program); or
  • the XML-RPC API

Note

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.

_images/first-job-submitted.png

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.

Test Definitions

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.

Viewing test results

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:

_images/first-results.png

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.

Downloading test results

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.

Web Based Job Submission

The web UI form does not yet support pipeline (V2) jobs; expect this support to appear soon.

XML-RPC Job Submission

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

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.

Installing lava-tool

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.)

Using lava-tool

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.

Using tables in LAVA

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.

Table search support

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.

Custom table queries

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.)

Exclusive table searches

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.

Other filters

Individual tables may also provide filters via javascript or other support.

Resetting a table

The breadcrumb link should take you back to the default table. Alternatively, clear the querystring in the browser address bar manually.

Unavailable entries

Certain tables may contain data relating to a hidden device type which would show as Unavailable if the user viewing the table does not own a device of this type. It is not possible to search these tables for details of the hidden type and the Unavailable label itself does not match as a search term.