LAVACLI(1)

" "lavacli"

NAME
lavacli - lavacli Documentation

lavacli is a command line tool to interact with one or many LAVA instances using XML-RPC.

FEATURES

lavacli allows you to interact with all LAVA objects:

    •   aliases

    •   device-types

    •   devices

    •   events

    •   jobs

    •   results

    •   tags

    •   workers

TABLE OF CONTENTS

  Installation

  Debian

A Debian package <https://packages.debian.org/unstable/lavacli> is available for Debian unstable and could be installed with:

            apt install lavacli

  PyPi

lavacli is also available on Pypi <https://pypi.org/project/lavacli/> and can be installed with:

            pip install lavacli

  Development versions

It's also possible to use lavacli directly from the sources:

            git clone https://gitlab.com/lava/lavacli.git
            cd lavacli
            virtualenv -p python3 venv
            source venv/bin/activate
            pip install -r requirements.txt
            python3 -m lavacli

  Configuration

lavacli can be used with or without a configuration file. Having a configuration file will help when using more than one lava instance.

  Without a configuration file

When using lavacli without any configuration file, the uri should be passed as a command line argument:

            lavacli --uri https://validation.linaro.org/RPC2 devices list

The authentication can also be passed in the uri:

            lavacli --uri https://admin:my_secret_token@validation.linaro.org/RPC2 devices list

Keep in mind, that any user on the same machine will then see the username and token in the process list.

  With a configuration file

lavacli configuration file is stored in ~/.config/lavacli.yaml. This is a YAML dictionary where each key is an identity.

            default:
              uri: https://validation.linaro.org/RPC2
            validation:
              uri: https://validation.linaro.org/RPC2
            admin@validation:
              uri: https://validation.linaro.org/RPC2
              username: admin
              token: my_secret_token
            staging:
              uri: https://staging.validation.linaro.org/RPC2
              events:
                uri: tcp://staging.validation.linaro.org:5500

When using lavacli, the identity can be used with -i or --identity:

            lavacli -i admin@validation devices list
            lavacli -i staging events listen

By default, the default identity will be used. Hence both commands are identitical:

            lavacli devices list
            lavacli -i validation devices list

  Available options

For each identity, you have to set:

    •   uri: the uri of the RPC endpoint.

You can also set:

    •   username: the api username

    •   token: the api token

    •   version: the api version to use when talking to this instance

    •   timeout: the http timeout (defaults to 20 seconds)

    •   proxy: the uri to the proxy

    •   verify_ssl_cert: set it to false to ignore SSL certificates errors (defaults to true)

    •   events: zmq event configuration

The events key is a dictionary where you can specify:

    •   uri: the uri of the events stream. If not specified, lavacli will ask the server.

    •   socks_proxy: uri to the socks proxy, if needed

  Usage

Here is the list of available commands and sub-commands.

  Aliases

LAVA aliases can be managed by:

            lavacli aliases add <name>
            lavacli aliases delete <name>
            lavacli aliases list
            lavacli aliases show <name>

  Device types

LAVA device types can be managed by:

            lavacli device-types add [...]
            lavacli device-types aliases add <name> <alias>
            lavacli device-types aliases delete <name> <alias>
            lavacli device-types aliases list
            lavacli device-types health-check get <name>
            lavacli device-types health-check set <name> <health-check.yaml>
            lavacli device-types list
            lavacli device-types show <name>
            lavacli device-types template get <name>
            lavacli device-types template set <name> <template.jinja2>
            lavacli device-types update [...]

  Devices

LAVA devices can be managed by:

            lavacli devices add [...]
            lavacli devices control <hostname> (on|off|reset|connect) [--dry-run]
            lavacli devices dict get <hostname>
            lavacli devices dict set <hostname>
            lavacli devices list
            lavacli devices maintenance <hostname> [--force] [--no-wait] [--reason <text>]
            lavacli devices show <hostname>
            lavacli devices tags add <hostname> <name>
            lavacli devices tags delete <hostname> <name>
            lavacli devices tags list
            lavacli devices update [...]

The control command allows controlling the device power and serial connection directly from the workstation, using the commands defined in the device dictionary:

    •   on: turn the device on (commands.power_on)

    •   off: turn the device off (commands.power_off)

    •   reset: hard reset the device (commands.hard_reset)

    •   connect: connect to the device primary serial port (commands.connections.<primary>.connect)

Use --dry-run (or -n) to print the command that would be run without executing it.

  Events

LAVA events can be used by:

            lavacli events listen
            lavacli events wait device [...]
            lavacli events wait job [...]
            lavacli events wait worker [...]

  Groups

LAVA groups can be managed by:

            lavacli add [...]
            lavacli delete <group>
            lavacli list
            lavacli perms add [...]
            lavacli perms list
            lavacli perms delete [...]
            lavacli show <group>

  Identities

lavacli identities can be managed by:

            lavacli identities add [...]
            lavacli identities delete <id>
            lavacli identities list
            lavacli identities show <id>

  Jobs

LAVA jobs can be managed by:

            lavacli jobs cancel <job_id>
            lavacli jobs config <job_i>
            lavacli jobs definition <job_id>
            lavacli jobs list
            lavacli jobs logs <job_id>
            lavacli jobs queue <device-type>
            lavacli jobs resubmit <job_id>
            lavacli jobs run <definition.yaml>
            lavacli jobs show <job_id>
            lavacli jobs submit <definition.yaml>
            lavacli jobs validate <definition.yaml>
            lavacli jobs wait <job_id>
            lavacli jobs find-errors

  Lab

LAVA lab can be managed by:

            lavacli lab apply <config>
            lavacli lab import <config>

  Results

LAVA results can be managed by:

            lavacli results <job_id>
            lavacli results <job_id> <suite>
            lavacli results <job_id> <suite> <case>

  System

LAVA instance can be managed by:

            lavacli system active
            lavacli system api
            lavacli system maintenance
            lavacli system methods list
            lavacli system methods help <method>
            lavacli system methods signature <method>
            lavacli system version
            lavacli system whoami

In order to put a full instance into maintenance, an admin could call system maintenance. This function will:

    •   set all workers health to MAINTENANCE

    •   wait for all jobs to finish

If the instance should be put into into maintenance immediately, addind --force will:

    •   set all workers health to MAINTENANCE

    •   cancel all running jobs

    •   wait for all jobs to finish

It also possible to exclude some workers with --exclude.

When the maintenance is finished, calling system active will move every worker into MAINTENANCE to ACTIVE.

  Tags

LAVA tag can be managed by:

            lavacli tags add [...]
            lavacli tags delete <tag>
            lavacli tags list
            lavacli tags show <tag>

  Tokens

Manage user remote artifact tokens:

            lavacli add [...]
            lavacli delete <token>
            lavacli list
            lavacli show <token>

  Users

Manage LAVA users with:

            lavacli add [...]
            lavacli delete <user>
            lavacli groups add <user> [...]
            lavacli groups list
            lavacli groups delete [...]
            lavacli perms add <user> [...]
            lavacli perms list
            lavacli perms delete [...]
            lavacli list
            lavacli show <user>
            lavacli update <user> [...]

  Utils

Some utilities are available with:

            lavacli utils logs print <output.yaml>
            lavacli utils templates render <output.yaml>

  Printing logs

When working with raw logs, lavacli might help by coloring the logs by levels.

It's also possible to filter the logs by level. To only print the serial output and the commands sent by LAVA to the board, use:

            lavacli utils logs print --filter target,input

Available log levels are: exception, error, warning, info, debug, target, input, feedback, results.

  Workers

LAVA workers can be managed by:

            lavacli workers add [...]
            lavacli workers config get <hostname>
            lavacli workers config set <hostname> <config.yaml>
            lavacli workers env get <hostname>
            lavacli workers env set <hostname> <env.yaml>
            lavacli workers list
            lavacli workers maintenance <hostname>
            lavacli workers update [...]
            lavacli workers show <hostname>

Author
Rémi Duraffort

Copyright
2018, Rémi Duraffort