LAVA-TOOL(1)

General Commands Manual

LAVA-TOOL(1)

" "LAVA Tool"

NAME¶

lava-tool - LAVA Tool Command Line Support

SUMMARY¶

lava-tool is a command-line tool to interact with LAVA.

USAGE¶

lava-tool [-h] <subcommand> [args]

OPTIONAL ARGUMENTS¶

-h, --help: show this help message and exit

SUBCOMMANDS¶

Type lava-tool <subcommand> -h for help on a specific subcommand.

AVAILABLE SUBCOMMANDS¶

data-views: Show data views defined on the server DEPRECATED

Usage:: lava-tool data-views [-h] --dashboard-url URL [--verbose-xml-rpc] [--experimental-notice]

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

Experimental commands:

--experimental-notice: Explain the nature of experimental commands

job-output: Get job output from the scheduler

Usage:: lava-tool job-output [-h] [--overwrite] [--output OUTPUT] SERVER JOB_ID

Positional arguments:

SERVER: Host to download job output from

JOB_ID: Job ID to download output file

Optional arguments:

-h, --help: show this help message and exit

--overwrite: Overwrite files on the local disk

--output OUTPUT, -o OUTPUT: Alternate name of the output file

devices-list

Get list of devices from the scheduler.

Usage:: lava-tool devices-list [-h] SERVER

Positional arguments:

SERVER: Host to query for the list of devices

Optional arguments:

-h, --help: show this help message and exit

help: Show a summary of all available commands

deserialize: Deserialize a bundle on the server DEPRECATED

Usage:: lava-tool deserialize [-h] --dashboard-url URL [--verbose-xml-rpc] SHA1

Positional arguments:

SHA1: SHA1 of the bundle to deserialize

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

get: Download a bundle from the server DEPRECATED

Usage:: lava-tool get [-h] --dashboard-url URL [--verbose-xml-rpc] [--overwrite] [--output OUTPUT] SHA1

Positional arguments:

SHA1: SHA1 of the bundle to download

Optional arguments:

-h, --help: show this help message and exit

--overwrite: Overwrite files on the local disk

--output OUTPUT, -o OUTPUT: Alternate name of the output file

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

auth-add: Add an authentication token

Usage:: lava-tool auth-add [-h] [--token-file TOKEN_FILE] [--no-check] HOST

Positional arguments:

HOST: Endpoint to add token for, in the form scheme://username@host. The username will default to the currently logged in user.

Optional arguments:

-h, --help: show this help message and exit

--token-file TOKEN_FILE: Read the secret from here rather than prompting for it.

--no-check: By default, a call to the remote server is made to check that the added token works before remembering it. Passing this option prevents this check.

--user-shortcut USER_SHORTCUT: Shortcut name for the user.

--endpoint-shortcut ENDPOINT_SHORTCUT: Shortcut name for the endpoint.

--default-user: Set this user as default user for the endpoint

auth-config

Usage: lava-tool auth-config [-h] [--user-shortcut USER_SHORTCUT]: [--endpoint-shortcut ENDPOINT_SHORTCUT] [--default-user] HOST

Positional arguments:

HOST: Endpoint to add token for, in the form scheme://username@host.

Optional arguments:

-h, --help: show this help message and exit

--user-shortcut USER_SHORTCUT: Shortcut name for the user.

--endpoint-shortcut ENDPOINT_SHORTCUT: Shortcut name for the endpoint.

--default-user: Set this user as default user for the endpoint.

put: Upload a bundle on the server DEPRECATED

Usage:: lava-tool put [-h] --dashboard-url URL [--verbose-xml-rpc] LOCAL [REMOTE]

Positional arguments:

LOCAL: pathname on the local file system

REMOTE: pathname on the server

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

bundles: Show bundles in the specified stream DEPRECATED

Usage:: lava-tool bundles [-h] --dashboard-url URL [--verbose-xml-rpc] [PATHNAME]

Positional arguments:

PATHNAME: pathname on the server (defaults to /anonymous/)

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

server-version: Display dashboard server version DEPRECATED

Usage:: lava-tool server-version [-h] --dashboard-url URL [--verbose-xml-rpc]

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

cancel-job: Cancel job

Usage:: lava-tool cancel-job [-h] SERVER JOB_ID

Positional arguments:

SERVER: Host to cancel job on

JOB_ID: Job ID to cancel

Optional arguments:

-h, --help: show this help message and exit

resubmit-job: Resubmit job

Usage:: lava-tool resubmit-job [-h] SERVER JOB_ID

Positional arguments:

SERVER: Host to resubmit job on

JOB_ID: Job ID to resubmit

Optional arguments:

-h, --help: show this help message and exit

version: Show dashboard client version

Usage:: lava-tool version [-h]

Optional arguments:

-h, --help: show this help message and exit

query-data-view: Invoke a specified data view DEPRECATED

Usage:: lava-tool restore [-h] --dashboard-url URL [--verbose-xml-rpc] [--experimental-notice] QUERY

Positional arguments:

QUERY: Data view name and any optional and required arguments

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

Experimental commands:

--experimental-notice: Explain the nature of experimental commands

submit-job: Submit a job to lava-scheduler

Usage:: lava-tool submit-job [-h] [--block] SERVER JSON_FILE

Positional arguments:

SERVER: Host to resubmit job on

JSON_FILE: JSON file with test defenition to submit

Optional arguments:

-h, --help: show this help message and exit

--block: Blocks until the job gets executed. Deprecated. This option adds unnecessary load on the server. Please use wait-job-events command instead.

Experimental commands:

--experimental-notice: Explain the nature of experimental commands

wait-job-events: Wait for a job events from lava-publisher. Can also submit a job and wait for that particular one.

Usage:: lava-tool wait-job-events [-h] (--job-definition JOB_DEFINITION | --job-id JOB_ID) [--port PORT] [--timeout TIMEOUT] [--quiet] SERVER

Positional arguments:

SERVER: Host to submit job on and/or listen to job events from.

Optional arguments:

-h, --help: show this help message and exit

--job-definition JOB_DEFINITION: Definition file path of the job that will be submitted.

--job-id JOB_ID: ID of the job to wait for. If this argument is provided, this command will not submit new job.

--port PORT, -p PORT: Alternative publisher port to use

--timeout TIMEOUT: Time to wait until the job is finished. Default will wait until manually canceled.

--quiet, -q: Do not print out interim messages (when job becomes Submitted or Running) but only when the job is finished.

validate-pipeline-devices: Validate pipeline devices on the specified server. Print output in the form of "device_hostname: {'Valid': null} | {'Invalid': message}"

Usage:: lava-tool validate-pipeline-devices [-h] [--name NAME] SERVER

Positional arguments:: SERVER

Optional arguments:

-h, --help: show this help message and exit

--name NAME: Hostname of the device or device_type name.

streams: Show streams you have access to DEPRECATED

Usage:: lava-tool streams [-h] --dashboard-url URL [--verbose-xml-rpc]

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

make-stream: Create a bundle stream on the server DEPRECATED

Usage:: lava-tool make-stream [-h] --dashboard-url URL [--verbose-xml-rpc] [--name NAME] pathname

Positional arguments:

pathname: Pathname of the bundle stream to create

Optional arguments:

-h, --help: show this help message and exit

--name NAME: Name of the bundle stream (description)

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

compare-device-conf: Compare device configurations and output a diff.

Usage:: lava-tool compare-device-conf [-h] [--wdiff] [--use-stored USE_STORED] [--dispatcher-config-dir DISPATCHER_CONFIG_DIR] [CONFIGS [CONFIGS ...]]

Positional arguments:

CONFIGS: List of device config paths, at least one, max two.

Optional arguments:

-h, --help: show this help message and exit

--wdiff, -w: Use wdiff for parsing output

--use-stored USE_STORED, -u USE_STORED: Use stored device config with specified device

--dispatcher-config-dir DISPATCHER_CONFIG_DIR: Where to find the device_type templates.

pull: Copy bundles and bundle streams from one dashboard to another DEPRECATED

Usage:: lava-tool pull [-h] --dashboard-url URL [--verbose-xml-rpc] [--experimental-notice] FROM [STREAM [STREAM ...]]

Positional arguments:

FROM: URL of the remote validation dashboard

Optional arguments:

-h, --help: show this help message and exit

Dashboard specific arguments:

--dashboard-url URL: URL of your validation dashboard

STREAM: Streams to pull from (all by default)

Debugging arguments:

--verbose-xml-rpc: Show XML-RPC data

Experimental commands:

--experimental-notice: Explain the nature of experimental commands

This command checks for two environment varialbes: The value of DASHBOARD_URL is used as a replacement for --dashbard-url. The value of REMOTE_DASHBOARD_URL as a replacement for FROM. Their presence automatically makes the corresponding argument optional.

get-pipeline-device-config: Get pipeline device configuration to a local file or stdout.

Usage:: lava-tool get-pipeline-device-config [-h] [--overwrite] [--output OUTPUT] [--output-to-stdout] SERVER DEVICE_HOSTNAME

Positional arguments:

SERVER: Host to download pipeline device configuration from

DEVICE_HOSTNAME: HOSTNAME of the pipeline device for which configuration is required

Optional arguments:

-h, --help: show this help message and exit

--overwrite: Overwrite files on the local disk

--output OUTPUT, -o OUTPUT: Alternate name of the output file

--stdout: Write output to stdout

device-dictionary: Update or export device dictionary data as jinja2 data. [Superusers only.] Either [--update | -u] or [--export | -e] must be used. Wraps the import-device-dictionary and export-device-dictionary XMLRPC API calls on the specified server.

Usage: lava-tool device-dictionary [-h] [--update UPDATE] [--export]: SERVER DEVICE_HOSTNAME

Positional arguments:: SERVER Host to query or update the device dictionary on DEVICE_HOSTNAME DEVICE_HOSTNAME to query or update

Optional arguments:

-h, --help: show this help message and exit

--update UPDATE, -u UPDATE: Load a jinja2 file to update the device dictionary

--export, -e: Export the device dictionary for this device as jinja2

LAVA TEST DEFINITIONS¶

A LAVA Test Definition comprises of two parts:

•: the data to setup the test, expressed as a JSON file.

•: the instructions to run inside the test, expressed as a YAML file.

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.

CONTENTS OF THE JSON FILE¶

The JSON file is submitted to the LAVA server and contains:

•: Demarcation as a health check or a user test.

•: The default timeout of each action within the test.

•: The logging level for the test, DEBUG or INFO.

•: The name of the test, shown in the list of jobs.

•: The location of all support files.

•: All parameters necessary to use the support files.

•: The declaration of which device(s) to use for the test.

•: The location to which the results should be uploaded.

•: The JSON determines how the test is deployed onto the device and where to find the tests to be run.

BASIC JSON FILE¶

Your first LAVA test should use the DEBUG logging level so that it is easier to see what is happening.

A suitable timeout for your first tests is 900 seconds.

Make the job_name descriptive and explanatory, you will want to be able to tell which job is which when reviewing the results.

Make sure the device_type matches exactly with one of the suitable device types listed on the server to which you want to submit this job.

Change the stream to one to which you are allowed to upload results, on your chosen server.

{
  "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/"
          }
      }
  ]
}

NOTE¶

Always check your JSON syntax. A useful site for this is http://jsonlint.com. YAML syntax can be checked at http://yaml-online-parser.appspot.com/?yaml=

BUGS AND ISSUES¶

General hints and tips on lava-tool and LAVA are available on the Linaro wiki: https://wiki.linaro.org/Platform/LAVA/LAVA_Tips. (Login is not required to read this page, only to edit.)

NOTE:

lava-tool is intended for user command line interaction. For all scripting requirements use XMLRPC support directly. Help on using XMLRPC with python is in the API | Available Methods section of the LAVA instance. e.g. https://validation.linaro.org/api/help/ Other languages also have XMLRPC support.

TESTING CHANGES TO LAVA-TOOL¶

Adding new commands to lava-tool requires changes to the entrypoints.ini file and these changes need to be picked up by setuptools. The local test directory can use any name - just remember to remove the directory before committing your local changes for review.

python setup.py install --root=./_dev/lava-tool/ --install-layout=deb
PYTHONPATH=. python ./_dev/lava-tool/usr/bin/lava-tool --help
rm -rf ./_dev/

AUTHOR¶

Linaro Validation Team

COPYRIGHT¶

2010-2015, Linaro Limited

January 3, 2017

0.19

Source file:	lava-tool.1.en.gz (from lava-tool 0.19-1~bpo8+1)
Source last updated:	2017-01-03T12:53:57Z
Converted to HTML:	2018-08-09T23:21:44Z