xenial (1) lava-tool.1.gz

Provided by: lava-tool_0.14-2_all bug

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

                 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

                 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

                 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.

       put    Upload a bundle on the server

                 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

                 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

                 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

                 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] 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

                 Experimental commands:

                        --experimental-notice
                               Explain the nature of experimental commands

       streams
              Show streams you have access to

                 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

                 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

                 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.

       lava-tool uses python-keyring for the authentication and this can cause some issues. When a desktop UI is
       installed,  python-keyring  attempts  to communicate with the desktop keyring support, e.g. gnome-keyring
       for a clean desktop interface.  If the particular desktop lacks such support, there can be  issues  using
       lava-tool.

       There  are several steps which can be useful in this situation (which results from a design choice within
       the python-keyring package and is beyond the control of lava-tool itself):

       https://wiki.linaro.org/Platform/LAVA/LAVA_Tips#gnomekeyring.IOError

       These suggestions are in no particular order and users need to choose  whichever  method  has  the  least
       impact  on  the  rest  of  the  workflow.  If  any  of  these steps allow successful authentication using
       lava-tool, the original problem is not a bug in lava-tool itself.

       • Use a server version of Ubuntu (or a remove the Gnome Keyring) [1]

       • unset the DISPLAY environment variable in your shell (this will make the keyring library  not  use  the
         GNOME keyring)

       • Setup and use a file-based key ring:

            mkdir ~/.cache/keyring
            echo '
            [backend]
            default-keyring=keyring.backend.CryptedFileKeyring
            keyring-path=~/.cache/keyring/
            ' > ~/keyringrc.cfg

       • Use a remote xmlrpclib call:

            import xmlrpclib
            import json

            config = json.dumps({ ... })
            server=xmlrpclib.ServerProxy("http://username:API-Key@localhost/RPC2/")
            jobid=server.scheduler.submit_job(config)

       • Disable DBUS links to the keyring backend [2]:

            $ unset DBUS_SESSION_BUS_ADDRESS

       [1]  removing gnome-keyring may have unwanted consequences and may still generate DBUS issues, see [2]

       [2]  the  DBUS change can be required even if gnome-keyring is not installed but a desktop UI is present.
            Depending on the use case, this can be unset locally, in a wrapper script or in the entire  session,
            e.g. in ~/.bashrc.

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.

       The locally changed lava-tool will still use the same keyring support.

          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

       2010-2015, Linaro Limited