Help

Event notifications

Event notifications are handled by the lava-publisher service on the master. You can subscribe to these events through lava-publisher service and receive events such as:

To subscribe to these events, you can get the lava-publisher protocol and port via XML-RPC call from the server [ scheduler.get_publisher_event_socket ].

For more information, visit lava-publisher docs.

About XML-RPC API

LAVA Server offers API services as an XML-RPC server. You can interact with it using any XML-RPC client. For example, in python3 you can do this:

import xmlrpc.client
server = xmlrpc.client.ServerProxy("https://federation.lavasoftware.org/lava/RPC2", allow_none=True)
print(server.system.listMethods())

The following python3 code shows how to authenticate using an XML-RPC client, when a method requires authentication.

WARNING: https:// scheme is recommended when using authentication.

  import xmlrpc.client
  username = "USERNAME"
  token = "TOKEN_STRING"
  hostname = "HOSTNAME"  # federation.lavasoftware.org
  server = xmlrpc.client.ServerProxy("https://%s:%s@%s/lava/RPC2" % (username, token, hostname), allow_none=True)
  print(server.system.listMethods())

NOTE: USERNAME is a valid username in the specified LAVA instance. TOKEN_STRING is a valid token associated with the above username in the same LAVA instance. HOSTNAME is the fully qualified domain name or IP address of the same LAVA instance.

In the above code snippet the ServerProxy string is constructed from different components, with separators, which are clearly illustrated as follows:
USERNAME:TOKEN_STRING@HOSTNAME/HANDLER

allow_none=True allows your client to match the server behaviour of handling an empty value as a null (None in Python, undef in Perl etc.) instead of as string like 'None'.

Available functions

Scheduler

scheduler

scheduler.all_device_types ][ scheduler.all_devices ][ scheduler.all_jobs ][ scheduler.cancel_job ][ scheduler.export_device_dictionary ][ scheduler.get_device_config ][ scheduler.get_device_status ][ scheduler.get_device_type_by_alias ][ scheduler.get_pipeline_device_config ][ scheduler.get_publisher_event_socket ][ scheduler.get_recent_jobs_for_device ][ scheduler.get_recent_jobs_for_device_type ][ scheduler.import_device_dictionary ][ scheduler.job_details ][ scheduler.job_health ][ scheduler.job_list_status ][ scheduler.job_output ][ scheduler.job_state ][ scheduler.job_status ][ scheduler.pending_jobs_by_device_type ][ scheduler.put_into_maintenance_mode ][ scheduler.put_into_online_mode ][ scheduler.resubmit_job ][ scheduler.submit_job ][ scheduler.validate_pipeline_devices ][ scheduler.validate_yaml ]

scheduler.aliases

scheduler.aliases.add ][ scheduler.aliases.delete ][ scheduler.aliases.list ][ scheduler.aliases.show ]

scheduler.device_types

scheduler.device_types.add ][ scheduler.device_types.get_health_check ][ scheduler.device_types.get_template ][ scheduler.device_types.list ][ scheduler.device_types.set_health_check ][ scheduler.device_types.set_template ][ scheduler.device_types.show ][ scheduler.device_types.update ]

scheduler.device_types.aliases

scheduler.device_types.aliases.add ][ scheduler.device_types.aliases.delete ][ scheduler.device_types.aliases.list ]

scheduler.devices

scheduler.devices.add ][ scheduler.devices.get_dictionary ][ scheduler.devices.list ][ scheduler.devices.set_dictionary ][ scheduler.devices.show ][ scheduler.devices.update ]

scheduler.devices.tags

scheduler.devices.tags.add ][ scheduler.devices.tags.delete ][ scheduler.devices.tags.list ]

scheduler.jobs

scheduler.jobs.cancel ][ scheduler.jobs.configuration ][ scheduler.jobs.definition ][ scheduler.jobs.list ][ scheduler.jobs.logs ][ scheduler.jobs.queue ][ scheduler.jobs.resubmit ][ scheduler.jobs.show ][ scheduler.jobs.submit ][ scheduler.jobs.validate ]

scheduler.tags

scheduler.tags.add ][ scheduler.tags.delete ][ scheduler.tags.list ][ scheduler.tags.show ]

scheduler.workers

scheduler.workers.add ][ scheduler.workers.get_config ][ scheduler.workers.get_env ][ scheduler.workers.list ][ scheduler.workers.set_config ][ scheduler.workers.set_env ][ scheduler.workers.show ][ scheduler.workers.update ]

Results

results.get_testcase_results_csv ] [ results.get_testcase_results_yaml ] [ results.get_testjob_metadata ] [ results.get_testjob_results_csv ] [ results.get_testjob_results_yaml ] [ results.get_testjob_suites_list_csv ] [ results.get_testjob_suites_list_yaml ] [ results.get_testsuite_results_count ] [ results.get_testsuite_results_csv ] [ results.get_testsuite_results_yaml ] [ results.make_custom_query ] [ results.refresh_all_queries ] [ results.refresh_query ] [ results.run_query ]

System and Authentication

system.api_version ] [ system.assign_perm_device ] [ system.assign_perm_device_type ] [ system.getCapabilities ] [ system.listMethods ] [ system.master_config ] [ system.methodHelp ] [ system.methodSignature ] [ system.multicall ] [ system.pipeline_network_map ] [ system.revoke_perm_device ] [ system.revoke_perm_device_type ] [ system.user_can_submit_to_types ] [ system.user_can_view_bundles ] [ system.user_can_view_devices ] [ system.user_can_view_jobs ] [ system.version ] [ system.whoami ]

scheduler.aliases.add

Name
----
`scheduler.aliases.add` (`name`)

Description
-----------
Create a device-type alias
Permission: lava_scheduler_app.add_alias

Arguments
---------
`name`: string
  Name of the alias
'device_type_name': string
  Name of the device type to alias

Return value
------------
None
Available functions

scheduler.aliases.delete

Name
----
`scheduler.aliases.delete` (`name`)

Description
-----------
Remove a device-type alias
Permission: lava_scheduler_app.delete_alias

Arguments
---------
`name`: string
  Name of the alias

Return value
------------
None
Available functions

scheduler.aliases.list

Name
----
`scheduler.aliases.list` ()

Description
-----------
List available device-type aliases

Arguments
---------
None

Return value
------------
This function returns an XML-RPC array of aliases
Available functions

scheduler.aliases.show

Name
----
`scheduler.aliases.show` (`name`)

Description
-----------
Show alias details.

Arguments
---------
`name`: string
  Alias name

Return value
------------
This function returns an XML-RPC dictionary with alias details.
Available functions

scheduler.all_device_types

Name
----
`all_device_types` ()

Description
-----------
Get all the available device types with their state and count
information.

Arguments
---------
None

Return value
------------
This function returns an XML-RPC array in which each item is a dict
which contains name (device type), idle, busy, offline counts.
For example:

[{'idle': 1, 'busy': 0, 'name': 'panda', 'offline': 0},
{'idle': 1, 'busy': 0, 'name': 'qemu', 'offline': 0}]
Available functions

scheduler.all_devices

Name
----
`all_devices` ()

Description
-----------
Get all the available devices with their state and type information.

Arguments
---------
None

Return value
------------
This function returns an XML-RPC array in which each item is a list of
device hostname, device type, device state, current running job id and
if device is pipeline. For example:

[['panda01', 'panda', 'running', 'good', 164, False], ['qemu01', 'qemu', 'idle', 'unknwon', None, True]]
Available functions

scheduler.all_jobs

Name
----
`all_jobs` ()

Description
-----------
Get submitted or running jobs.

Arguments
---------
None

Return value
------------
This function returns a XML-RPC array of submitted and running jobs with their status and
actual device for running jobs and requested device or device type for submitted jobs and
job sub_id for multinode jobs.
For example:

[[73, 'multinode-job', 'submitted', None, 'kvm', '72.1'],
[72, 'multinode-job', 'submitted', None, 'kvm', '72.0'],
[71, 'test-job', 'running', 'kvm01', None, None]]
Available functions

scheduler.cancel_job

Name
----
`cancel_job` (`job_id`)

Description
-----------
Cancel the given job reffered by its id.

Arguments
---------
`job_id`: string
    Job id which should be canceled.

Return value
------------
None. The user should be authenticated with an username and token.
Available functions

scheduler.device_types.add

Name
----
`scheduler.device_types.add` (`name`, `description`, `display`, `owners_only`, `health_frequency`, health_denominator`)

Description
-----------
[superuser only]
Add a new device-type to the database. Devices will need a suitable
template to use the new device-type.

Arguments
---------
`name`: string
  Name of the device-type
`description`: string
  Device-type description
`display`: bool
  Is the device-type displayed in the GUI?
`owners_only`: bool
  DEPRECATED: this field is not used any more
`health_frequency`: int
  How often to run health checks
`health_denominator`: string ("hours" or "jobs")
  Initiate health checks by hours or by jobs

Return value
------------
None
Available functions

scheduler.device_types.aliases.add

Name
----
`scheduler.device_types.aliases.add` (`name`, `alias`)

Description
-----------
[superuser only]
Add an alias to the device-type

Arguments
---------
`name`: string
  Device-type name
`alias`: string
  Alias name to add

Return value
------------
None
Available functions

scheduler.device_types.aliases.delete

Name
----
`scheduler.device_types.aliases.delete` (`name`, `alias`)

Description
-----------
[superuser only]
Remove an alias from a device-type

Arguments
---------
`hostname`: string
  Device hostname
`name`: string
  Alias to remove
Return value
------------
None
Available functions

scheduler.device_types.aliases.list

Name
----
`scheduler.device_types.aliases.list` (`name`)

Description
-----------
List device-type aliases

Arguments
---------
`name`: string
  Device-type name

Return value
------------
This function returns an XML-RPC array of aliases
Available functions

scheduler.device_types.get_health_check

Name
----
`scheduler.device_types.get_health_check` (`name`)

Description
-----------
Return the health-check definition for the requested device-type or
filename.

Note: not all device-types have a health check filename that matches
the device-type name in the database.

Arguments
---------
`name`: string
  Filename

The .yaml suffix will be added if not specified.

Return value
------------
The health-check
Available functions

scheduler.device_types.get_template

Name
----
`scheduler.device_types.get_template` (`name`)

Description
-----------
Return the device-type configuration for the requested device-type or
filename.

Note: not all device-types have a health check filename that matches
the device-type name in the database.

Arguments
---------
`name`: string
  Name of the device-type

The .jinja2 suffix will be added if not specified.

Return value
------------
The device-type configuration
Available functions

scheduler.device_types.list

Name
----
`scheduler.device_types.list` (`show_all=False`)

Description
-----------
List available device-types. Some device-types are only visible to
devices owners.

Arguments
---------
`show_all`: bool
  Show all available device-types

Return value
------------
This function returns an XML-RPC array of device-types
Available functions

scheduler.device_types.set_health_check

Name
----
`scheduler.device_types.set_health_check` (`name`, `config`)

Description
-----------
[superuser only]
Set the health-check definition for the requested device-type or
filename.

Note: not all device-types have a health check filename that matches
the device-type name in the database.

Arguments
---------
`name`: string
  name of the device-type
`config`: string
  The health-check as a yaml file

The .yaml suffix will be added if not specified.

Return value
------------
None
Available functions

scheduler.device_types.set_template

Name
----
`scheduler.device_types.set_template` (`name`, `config`)

Description
-----------
[superuser only]
Set the device-type configuration for the requested device-type or
filename.

Note: not all device-types have a health check filename that matches
the device-type name in the database.

Arguments
---------
`name`: string
  name of the device-type
`config`: string
  The device-type configuration as a jinja2 template

The .jinja2 suffix will be added if not specified.

Return value
------------
None
Available functions

scheduler.device_types.show

Name
----
`scheduler.device_types.show` (`name`)

Description
-----------
Show some details about the given device type.

Arguments
---------
`name`: string
  Name of the device-type

Return value
------------
This function returns an XML-RPC dictionary with device-type details
Available functions

scheduler.device_types.update

Name
----
`scheduler.device_types.update` (`name`, `description=None`,
                                 `display=None`,
                                 `owners_only=None`,
                                 `health_frequency=None`,
                                 `health_denominator=None`,
                                 `health_disabled=None`)

Description
-----------
[superuser only]
Update the metadata information for this device-type.

Arguments
---------
`name`: string
  Name of the device-type
`description`: string
  Device-type description
`display`: bool
  Is the device-type displayed in the GUI?
`owners_only`: bool
  DEPRECATED: this field is not used any more
`health_frequency`: int
  How often to run health checks
`health_denominator`: string ("hours" or "jobs")
  Initiate health checks by hours or by jobs
`health_disabled`: bool
  Disable health checks for this device-type

Return value
------------
None
Available functions

scheduler.devices.add

Name
----
`scheduler.devices.add` (`hostname`, `type_name`, `worker_hostname`,
                         `user_name=None`, `group_name=None`,
                         `public=True`, `health=None`,
                         `description=None`)

Description
-----------
[superuser only]
Add a new device to the database, to support V2.

Each device will also need a device dictionary.

Arguments
---------
`hostname`: string
  Hostname of the device
`type_name`: string
  Type of the new device
`worker_hostname`: string
  Worker hostname
`user_name`: string
  DEPRECATED: This field is not used any more
`group_name`: string
  DEPRECATED: This field is not used any more
`public`: boolean
  DEPRECATED: This field is not used any more
`health`: string
  Device health, among ["GOOD", "UNKNOWN", "LOOPING", "BAD", "MAINTENANCE", "RETIRED"]
`description`: string
  Device description

Return value
------------
None
Available functions

scheduler.devices.get_dictionary

Name
----
`scheduler.devices.get_dictionary` (`hostname`, `render=False`, `context=None`)

Support for the context argument is new in api_version 2
see system.api_version().

Description
-----------
Return the device configuration

Arguments
---------
`hostname`: string
  Hostname of the device
`render`: bool
  Render the device configuration. By default, return the dictionary
`context`: string
  Some device templates need a context specific when processing the
  device-type template. This can be specified as a YAML string.
  New in api_version 2 - see system.api_version()

Return value
------------
The device dictionary
Available functions

scheduler.devices.list

Name
----
`scheduler.devices.list` (`show_all=False`, `offline_info=False`)

Description
-----------
List available devices with their state and type information.

Arguments
---------
`show_all`: boolean
  Show all devices, including retired
`offline_info`: boolean
  Add date from which each of the returned devices is offline (if the
  device is offline) and the user who put the device offline (if the
  device is offline) to the returned dictionary.

Return value
------------
This function returns an XML-RPC array in which each item is a
dictionary with device information
Available functions

scheduler.devices.set_dictionary

Name
----
`scheduler.devices.set_dictionary` (`hostname`, `dictionary`)

Description
-----------
[user with admin permission only]
Set the device dictionary

Arguments
---------
`hostname`: string
  Hostname of the device
`dictionary`: string
  The device dictionary as a jinja2 template

Return value
------------
True if the dictionary was saved to file, False otherwise.
Available functions

scheduler.devices.show

Name
----
`scheduler.devices.show` (`hostname`)

Description
-----------
Show some details about the given device.

Arguments
---------
`hostname`: string
  Hostname of the device

Return value
------------
This function returns an XML-RPC dictionary with device details
Available functions

scheduler.devices.tags.add

Name
----
`scheduler.devices.tags.add` (`hostname`, `name`)

Description
-----------
[user with admin device and add tag permissions only]
Add a device tag to the specific device

Arguments
---------
`hostname`: string
  Device hostname
`name`: string
  Tag name to add

Return value
------------
None
Available functions

scheduler.devices.tags.delete

Name
----
`scheduler.devices.tags.delete` (`hostname`, `name`)

Description
-----------
[user with admin permission only]
Remove a device tag from the device

Arguments
---------
`hostname`: string
  Device hostname
`name`: string
  Tag name to remove
Return value
------------
None
Available functions

scheduler.devices.tags.list

Name
----
`scheduler.devices.tags.list` (`hostname`)

Description
-----------
List device tags

Arguments
---------
`hostname`: string
  Device hostname

Return value
------------
This function returns an XML-RPC array of tag names
Available functions

scheduler.devices.update

Name
----
`scheduler.devices.update` (`hostname`, `worker_hostname=None`,
                            `user_name=None`, `group_name=None`,
                            `public=True`,  `health=None`,
                            `description=None`)

Description
-----------
[user with admin permission only]
Update device parameters. Only the non-None values will be updated.
Owner and group are always updated at the same time.

Arguments
---------
`hostname`: string
  Hostname of the device
`worker_hostname`: string
  Worker hostname
`user_name`: string
  DEPRECATED: This field is not used any more
`group_name`: string
  DEPRECATED: This field is not used any more
`public`: boolean
  DEPRECATED: This field is not used any more
`health`: string
  Device health, among ["GOOD", "UNKNOWN", "LOOPING", "BAD", "MAINTENANCE", "RETIRED"]
`description`: string
  Device description

Return value
------------
None
Available functions

scheduler.export_device_dictionary

Name
----
`export_device_dictionary` (`device_hostname`)

Description
-----------
[user with admin permission only]
Export the device dictionary key value store for a
pipeline device.

See also get_pipeline_device_config

Arguments
---------
`device_hostname`: string
    Device hostname to update.

Return value
------------
This function returns an XML-RPC binary data of output file.
Available functions

scheduler.get_device_config

New in api_version 2 - see system.api_version()

Name
----
`get_device_config` (`device_hostname`, context=None)

Description
-----------
Get the device configuration for given device hostname.

Arguments
---------
`device_hostname`: string
    Device hostname for which the configuration is required.

Some device templates need a context specified when processing the
device-type template. This can be specified as a YAML string:

`get_device_config` `('qemu01', '{arch: amd64}')`

Return value
------------
This function returns an XML-RPC binary data of output file.
Available functions

scheduler.get_device_status

Name
----
`get_device_status` (`hostname`)

Description
-----------
Get status, running job, date from which it is offline of the given
device and the user who put it offline.

Arguments
---------
`hostname`: string
    Name of the device for which the status is asked.

Return value
------------
This function returns an XML-RPC dictionary which contains hostname,
status, date from which the device is offline if the device is offline,
the user who put the device offline if the device is offline and the
job id of the running job.
The device has to be visible to the user who requested device's status.

Note that offline_since and offline_by can be empty strings if the device
status is manually changed by an administrator in the database or from
the admin site of LAVA even if device's status is offline.
Available functions

scheduler.get_device_type_by_alias

Name
----

`get_device_type_by_alias` (`alias`)

Description
-----------
Get the matching device-type(s) for the specified alias. It is
possible that more than one device-type can be returned, depending
on local admin configuration. An alias can be used to provide the
link between the device-type name and the Device Tree name.
It is possible for multiple device-types to have the same alias
(to assist in transitions and migrations).
The specified alias string can be a partial match, returning all
device-types which have an alias name containing the requested
string.

Arguments
---------
`alias`: string
    Name of the alias to lookup

Return value
------------
This function returns a dictionary containing the alias as the key
and a list of device-types which use that alias as the value. If the
specified alias does not match any device-type, the dictionary contains
an empty list for the alias key.

{'apq8016-sbc': ['dragonboard410c']}
{'ompa4-panda': ['panda', 'panda-es']}
Available functions

scheduler.get_pipeline_device_config

Name
----
DEPRECATED - use `get_device_config` instead.

`get_pipeline_device_config` (`device_hostname`)

Description
-----------
Get the pipeline device configuration for given device hostname.

Arguments
---------
`device_hostname`: string
    Device hostname for which the configuration is required.

Return value
------------
This function returns an XML-RPC binary data of output file.
Available functions

scheduler.get_publisher_event_socket

Name
----
`get_publisher_event_socket`

Return value
------------
This function exposes the EVENT_SOCKET from the settings file which is
used for the lava-publisher daemon.
Available functions

scheduler.get_recent_jobs_for_device

Name
----

`get_recent_jobs_for_device` (`device`, `count=1`, `restrict_to_user=False`)

Description
-----------
Get details of recently finished jobs for a given device. Limits the list
to test jobs submitted by the user making the query if restrict_to_user is set to
True. Get only the most recent job by default, but count can be set higher to
get for example the last 10 jobs.

Arguments
---------
`device`: string
    Name of the device for which you want the jobs
`count`: integer (Optional, default=1)
    Number of last jobs you want
`restrict_to_user`: boolean (Optional, default=False)
    Fetch only the jobs submitted by the user making the query if set to True

Return value
------------
This function returns a list of dictionaries, which correspond to the
list of recently finished jobs informations (Complete or Incomplete)
for this device, ordered from youngest to oldest.

[
    {
        'description': 'mainline--armada-370-db--multi_v7_defconfig--network',
        'id': 359828,
        'status': 'Complete'
    },
    {
        'description': 'mainline--armada-370-db--multi_v7_defconfig--sata',
        'id': 359827
        'status': 'Incomplete'
    }
]
Available functions

scheduler.get_recent_jobs_for_device_type

Name
----

`get_recent_jobs_for_device_type` (`device_type`, `count=1`, `restrict_to_user=False`)

Description
-----------
Get details of recently finished jobs for a given device_type. Limits the list
to test jobs submitted by the user making the query if restrict_to_user is set to
True. Get only the most recent job by default, but count can be set higher to
get for example the last 10 jobs.

Arguments
---------
`device_type`: string
    Name of the device_type for which you want the jobs
`count`: integer (Optional, default=1)
    Number of last jobs you want
`restrict_to_user`: boolean (Optional, default=False)
    Fetch only the jobs submitted by the user making the query if set to True

Return value
------------
This function returns a list of dictionaries, which correspond to the
list of recently finished jobs informations (Complete or Incomplete)
for this device, ordered from youngest to oldest.

[
    {
        'description': 'ramdisk health check',
        'id': 359828,
        'status': 'Complete',
        'device': 'black01'
    },
    {
        'description': 'standard ARMMP NFS',
        'id': 359827
        'status': 'Incomplete',
        'device': 'black02'
    }
]
Available functions

scheduler.import_device_dictionary

Name
----
`import_device_dictionary` (`device_hostname`, `jinja_string`)

Description
-----------
[user with admin_device permission only]
Import or update the device dictionary key value store for a
pipeline device.

Arguments
---------
`device_hostname`: string
    Device hostname to update.
`jinja_str`: string
    Device configuration as Jinja2

Return value
------------
This function returns an XML-RPC binary data of output file.
Available functions

scheduler.job_details

Name
----
`job_details` (`job_id`)

Description
-----------
Get the details of given job id.

Arguments
---------
`job_id`: string
    Job id for which the output is required.

Return value
------------
This function returns an XML-RPC structures of job details, provided
the user is authenticated with an username and token.

The elements available in XML-RPC structure include:
_state, submitter_id, is_pipeline, id, failure_comment,
multinode_definition, priority, _actual_device_cache,
original_definition, status, health_check, description,
start_time, target_group, pipeline_compatibility, submit_time,
is_public, _old_status, actual_device_id, definition, sub_id,
requested_device_type_id, end_time, absolute_url, submitter_username
Available functions

scheduler.job_health

Name
----
`job_health` (`job_id`)

Description
-----------
Get the health of given job id.

Arguments
---------
`job_id`: string
    Job id for which the output is required.

Return value
------------
This function returns an XML-RPC structures of job health with the
following fields.
The user is authenticated with an username and token.

`job_health`: string
['Unknown'|'Complete'|'Incomplete'|'Canceled']
Available functions

scheduler.job_list_status

Name
----
DEPRECATED - use `job_health` or `job_state` instead.

job_list_status ([job_id, job_id, job_id])

Description
-----------
Get the status of a list of job ids.

Arguments
---------
`job_id_list`: list
    List of job ids for which the output is required.
    For multinode jobs specify the job sub_id as a float
    in the XML-RPC call:
    job_list_status([1, 2, 3,1, 5])

Return value
------------
The user needs to be authenticated with an username and token.

This function returns an XML-RPC structure of job status with the
following content.

`job_status`: string
{ID: ['Submitted'|'Running'|'Complete'|'Incomplete'|'Canceled'|'Canceling']}

If the user is not able to view one of the specified jobs, that entry
will be omitted.
Available functions

scheduler.job_output

Name
----
`job_output` (`job_id`, `offset=0`)

Description
-----------
Get the output of given job id.

Arguments
---------
`job_id`: string
    Job id for which the output is required.
`offset`: integer
    Offset from which to start reading the output file specified in bytes.
    It defaults to 0.

Return value
------------
This function returns an XML-RPC binary data of output file, provided
the user is authenticated with an username and token.
Available functions

scheduler.job_state

Name
----
`job_state` (`job_id`)

Description
-----------
Get the state of given job id.

Arguments
---------
`job_id`: string
    Job id for which the output is required.

Return value
------------
This function returns an XML-RPC structures of job state with the
following fields.
The user is authenticated with an username and token.

`job_state`: string
['Submitted'|'Scheduling'|'Scheduled'|'Running'|'Canceling'|'Finished']
Available functions

scheduler.job_status

Name
----
DEPRECATED - use `job_health` or `job_state` instead.

`job_status` (`job_id`)

Description
-----------
Get the status of given job id.

Arguments
---------
`job_id`: string
    Job id for which the output is required.

Return value
------------
This function returns an XML-RPC structures of job status with the
following fields.
The user is authenticated with an username and token.

`job_status`: string
['Submitted'|'Running'|'Complete'|'Incomplete'|'Canceled'|'Canceling']

`bundle_sha1`: string
The sha1 hash code of the bundle, if it existed. Otherwise it will be
an empty string. (LAVA V1 only)
Available functions

scheduler.jobs.cancel

Name
----
`scheduler.jobs.cancel` (`job_id`)

Description
-----------
Cancel the given job referred by its id.

Arguments
---------
`job_id`: string
    Job id which should be canceled.

Return value
------------
None. The user should be authenticated with an username and token.
Available functions

scheduler.jobs.configuration

Name
----
`scheduler.jobs.configuration` (`job_id`)

Description
-----------
Return the full job configuration

Arguments
---------
`job_id`: string
    Job id

Return value
------------
Return an array with [job, device, dispatcher, env, env-dut] config.
Any of theses values might be None if the corresponding file hasn't
been used by the job.
If the job hasn't started yet, a 404 error will be returned.
Available functions

scheduler.jobs.definition

Name
----
`scheduler.jobs.definition` (`job_id`)

Description
-----------
Return the job definition

Arguments
---------
`job_id`: string
    Job id

Return value
------------
The job definition or and error.

Note: for MultiNode jobs, the original MultiNode definition
is returned.
Available functions

scheduler.jobs.list

Name
----
`scheduler.jobs.list` (
    `state=None`, `health=None`, `start=0`, `limit=25`,
    `since=None`, `verbose=False`
)

Description
-----------
List the last jobs, within the specified range, in descending order of
job ID. Jobs can be filtered by `state` and `health` (if provided).

Arguments
---------
`state`: str
  Filter by state, None by default (no filtering).
  Values: [SUBMITTED, SCHEDULING, SCHEDULED, RUNNING, CANCELING, FINISHED]
`health`: str
  Filter by health, None by default (no filtering).
  Values: [UNKNOWN, COMPLETE, INCOMPLETE, CANCELED]
`start`: int
  Skip the first N job(s) in the list
`limit`: int
  Max number of jobs to return.
  This value will be clamped to 100
`since`: int (minutes)
  Filter by jobs which completed in the last N minutes.
`verbose`: bool
  Add extra data including actual_device, start_time, end_time,
  error_msg and error_type.
  Note: error_msg can contain nested quotes and other escape
  characters, parse with care.

Return value
------------
This function returns an array of jobs with keys:
    "id", "description", "device_type", "health",
    "state", "submitter"
If verbose is True, these keys are added:
    "actual_device", "start_time", "end_time",
    "error_msg", "error_type"
Available functions

scheduler.jobs.logs

Name
----
`scheduler.jobs.logs` (`job_id`, `start=0`, `end=None`)

Description
-----------
Return the logs for the given job

Arguments
---------
`job_id`: str
  Job id
`start`: int
  Show only after the given line
`end`: int
  Do not return after the fiven line

Return value
------------
This function returns a tuple made of (job_finished, data).
job_finished is True if and only if the job is finished.
Available functions

scheduler.jobs.queue

Name
----
`scheduler.jobs.queue` (`device_types=None`, `start=0`, `limit=25`)

Description
-----------
List the queued jobs (state.SUBMITTED), within the specified range,
in descending order of job ID.
Jobs can be filtered by `requested_device_type` (if provided).

Arguments
---------
`device_types`: Array of str
  If provided, list jobs whose requested_device_type match any of the
  provided device-types. None by default (no filtering).
`start`: int
  Skip the first N job(s) in the list
`limit`: int
  Max number of jobs to return.
  This value will be clamped to 100

Return value
------------
This function returns an array of jobs with keys:
    "id", "description", "requested_device_type", "submitter"

If no queued test jobs exist to match the criteria, an empty array
is returned.
Available functions

scheduler.jobs.resubmit

Name
----
`scheduler.jobs.resubmit` (`job_id`)

Description
-----------
Resubmit the given job referred by its id.

Arguments
---------
`job_id`: string
    The job's id which should be re-submitted.

Return value
------------
This function returns an XML-RPC integer which is the newly created
job's id, provided the user is authenticated with an username and token.
Available functions

scheduler.jobs.show

Name
----
`scheduler.jobs.show` (`job_id`)

Description
-----------
Show job details

Arguments
---------
`job_id`: string
  Job id

Return value
------------
This function returns a dictionary of details abou the specified test job.
Available functions

scheduler.jobs.submit

Name
----
`scheduler.jobs.submit` (`definition`)

Description
-----------
Submit the given job data which is in LAVA job JSON or YAML format as a
new job to LAVA scheduler.

Arguments
---------
`definition`: string
    Job JSON or YAML string.

Return value
------------
This function returns an XML-RPC integer which is the newly created
job's id, provided the user is authenticated with an username and token.
If the job is a multinode job, this function returns the list of created
job IDs.
Available functions

scheduler.jobs.validate

Name
----
`scheduler.jobs.validate` (`definition`, `strict=False`)

Description
-----------
Validate the given job definition against the schema validator.

Arguments
---------
`definition`: string
    Job YAML string.
`strict`: boolean
    If set to True, the validator will reject any extra keys that are
    present in the job definition but not defined in the schema.

Return value
------------
This function returns None if the job definition is valid. Returns a
dictionary in case of error with the key and msg.
Available functions

scheduler.pending_jobs_by_device_type

Name
----
`pending_jobs_by_device_type` ()

Description
-----------
Get number of pending jobs in each device type.
Private test jobs and hidden device types are
excluded, except for authenticated superusers.

Arguments
---------
`all`: boolean - include retired devices and undisplayed device-types in the listing.

Return value
------------
This function returns a dict where the key is the device type and
the value is the number of jobs pending in that device type.
For example:

{'qemu': 0, 'panda': 3}
Available functions

scheduler.put_into_maintenance_mode

Name
----
`put_into_maintenance_mode` (`hostname`, `reason`, `notify`)

Description
-----------
Put the given device in maintenance mode with the given reason and optionally
notify the given mail address when the job has finished.

Arguments
---------
`hostname`: string
    Name of the device to put into maintenance mode.
`reason`: string
    The reason given to justify putting the device into maintenance mode.
`notify`: string
    Email address of the user to notify when the job has finished. Can be
    omitted.

Return value
------------
None. The user should be authenticated with a username and token and has
sufficient permission.
Available functions

scheduler.put_into_online_mode

Name
----
`put_into_online_mode` (`hostname`, `reason`, `skip_health_check`)

Description
-----------
Put the given device into online mode with the given reason ans skip health
check if asked.

Arguments
---------
`hostname`: string
    Name of the device to put into online mode.
`reason`: string
    The reason given to justify putting the device into online mode.
`skip_health_check`: boolean
    Skip health check when putting the board into online mode. If
    omitted, health check is not skipped by default.

Return value
------------
None. The user should be authenticated with a username and token and has
sufficient permission.
Available functions

scheduler.resubmit_job

Name
----
`resubmit_job` (`job_id`)

Description
-----------
Resubmit the given job reffered by its id.

Arguments
---------
`job_id`: string
    The job's id which should be re-submitted.

Return value
------------
This function returns an XML-RPC integer which is the newly created
job's id,  provided the user is authenticated with an username and
token.
Available functions

scheduler.submit_job

Name
----
`submit_job` (`job_data`)

Description
-----------
Submit the given job data which is in LAVA job JSON or YAML format as a
new job to LAVA scheduler.

Arguments
---------
`job_data`: string
    Job JSON or YAML string.

Return value
------------
This function returns an XML-RPC integer which is the newly created
job's id, provided the user is authenticated with an username and token.
If the job is a multinode job, this function returns the list of created
job IDs.
Available functions

scheduler.tags.add

Name
----
`scheduler.tags.add` (`name`, `description=None`)

Description
-----------
[superuser only]
Create a device tag

Arguments
---------
`name`: string
  Name of the tag
`description`: string
  Tag description

Return value
------------
None
Available functions

scheduler.tags.delete

Name
----
`scheduler.tags.delete` (`name`)

Description
-----------
[superuser only]
Remove a device tag

Arguments
---------
`name`: string
  Name of the tag

Return value
------------
None
Available functions

scheduler.tags.list

Name
----
`scheduler.tags.list` ()

Description
-----------
List available device tags

Arguments
---------
None

Return value
------------
This function returns an XML-RPC array of tag dictionaries
Available functions

scheduler.tags.show

Name
----
`scheduler.tags.show` (`name`)

Description
-----------
Show some details about the given device tag.

Arguments
---------
`name`: string
  Name of the device tag

Return value
------------
This function returns an XML-RPC dictionary with device tag details
Available functions

scheduler.validate_pipeline_devices

Name
----
`validate_pipeline_device` [`name`]

Description
-----------
Validate that the device dictionary and device-type template
together create a valid YAML file which matches the pipeline
device schema.
Retired devices are ignored.

See also get_pipeline_device_config

Arguments
---------
`name`: string
    Can be device hostname or device type name.
If name is specified, method will search for either a matching device
hostname or matching device type name in which case it will only
validate that(those) device(s).
If not specified, this method will validate all non-retired devices
in the system.

Return value
------------
This function returns an XML-RPC structure of results with the
following fields.

`device_hostname`: {'Valid': null}
or
`device_hostname`: {'Invalid': message}
`
Available functions

scheduler.validate_yaml

Name
----
validate_yaml (yaml_job_data)

Description
-----------
Validate the supplied pipeline YAML against the submission schema.

Note: this does not validate the job itself, just the YAML against the
submission schema. A job which validates against the schema can still be
an invalid job for the dispatcher and such jobs will be accepted as Submitted,
scheduled and then marked as Incomplete with a failure comment. Full validation
only happens after a device has been assigned to the Submitted job.

Arguments
---------
'yaml_job_data': string

Return value
------------
Raises an Exception if the yaml_job_data is invalid.
Available functions

scheduler.workers.add

Name
----
`scheduler.workers.add` (`hostname`, `description=None`, `disabled=False`)

Description
-----------
[superuser only]
Add a new worker entry to the database.

Arguments
---------
`hostname`: string
  The name of the worker
`description`: string
  Description of the worker
`disabled`: bool
  Is the worker disabled?

Return value
------------
None
Available functions

scheduler.workers.get_config

Name
----
`scheduler.workers.get_config` (`hostname`)

Description
-----------
Return the worker configuration
The server will first try
/etc/lava-server/dispatcher.d/<hostname>/dispatcher.yaml and fallback to
/etc/lava-server/dispatcher.d/<hostname>.yaml

Arguments
---------
`hostname`: string
  Hostname of the worker

Return value
------------
This function returns the worker configuration
Available functions

scheduler.workers.get_env

Name
----
`scheduler.workers.get_env` (`hostname`)

Description
-----------
Return the worker environment
The server will first try
/etc/lava-server/dispatcher.d/<hostname>/env.yaml and fallback to
/etc/lava-server/env.yaml

Arguments
---------
`hostname`: string
  Hostname of the worker

Return value
------------
This function returns the worker environment
Available functions

scheduler.workers.list

Name
----
`scheduler.workers.list` ()

Description
-----------
List workers

Arguments
---------
None

Return value
------------
This function returns an XML-RPC array of workers
Available functions

scheduler.workers.set_config

Name
----
`scheduler.workers.set_config` (`hostname`, `config`)

Description
-----------
Set the worker configuration

Arguments
---------
`hostname`: string
  Hostname of the worker
`config`: string
  The worker configuration as a yaml file

Return value
------------
True if the configuration was saved to file, False otherwise.
Available functions

scheduler.workers.set_env

Name
----
`scheduler.workers.set_env` (`hostname`, `env`)

Description
-----------
Set the worker environment

Arguments
---------
`hostname`: string
  Hostname of the worker
`env`: string
  The worker environment as a yaml file

Return value
------------
True if the environment was saved to file, False otherwise.
Available functions

scheduler.workers.show

Name
----
`scheduler.workers.show` (`hostname`)

Description
-----------
Show some details about the given worker.

Arguments
---------
`hostname`: string
  Hostname of the worker

Return value
------------
This function returns an XML-RPC dictionary with worker details
Available functions

scheduler.workers.update

Name
----
`scheduler.workers.update` (`hostname`, `description=None`, `health=None`)

Description
-----------
[superuser only]
Update worker parameters

Arguments
---------
`hostname`: string
  Hostname of the worker
`description`: string
  Description of the worker
`health`: string
  Set worker health ("ACTIVE", "MAINTENANCE" or "RETIRED")

Return value
------------
None
Available functions

results.get_testcase_results_csv

Name
----
`get_testcase_results_csv` (`job_id`, `suite_name`, `case_name`)

Description
-----------
Get the test case results of given job id, suite and test case name
in CSV format.

Arguments
---------
`job_id`: string
    Job id for which the results are required.
`suite_name`: string
    Name of the suite for which the results are required.
`case_name`: string
    Name of the test case for which the results are required.

Return value
------------
This function returns an XML-RPC structures of test case results in
CSV format, provided the user is authenticated with an username and
token.
Available functions

results.get_testcase_results_yaml

Name
----
`get_testcase_results_yaml` (`job_id`, `suite_name`, `case_name`)

Description
-----------
Get the test case results of given job id, suite and test case name
in YAML format.

Arguments
---------
`job_id`: string
    Job id for which the results are required.
`suite_name`: string
    Name of the suite for which the results are required.
`case_name`: string
    Name of the test case for which the results are required.

Return value
------------
This function returns an XML-RPC structures of test case results in
YAML format, provided the user is authenticated with an username and
token.
Available functions

results.get_testjob_metadata

Name
----
`get_testjob_metadata` (`job_id`)

Description
-----------
Get the job level metadata which includes entries created by
LAVA as well as submitted in the test job definition

Arguments
---------
`job_id`: string
    Job id for which the results are required.

Return value
------------
This function returns an XML-RPC structures of job results as
a list of dictionaries, provided the user is authenticated with
a username and token.

[
    {name: value},
    {name: value},
]

For example:
[
    {'boot.0.hikey-oe.commands': 'fastboot'},
    {'source': 'https://git.linaro.org/lava-team/refactoring.git'},
    {'test.0.tlxc.definition.path': 'ubuntu/smoke-tests-basic.yaml'}
]
Available functions

results.get_testjob_results_csv

Name
----
`get_testjob_results_csv` (`job_id`)

Description
-----------
Get the job results of given job id in CSV format.

Arguments
---------
`job_id`: string
    Job id for which the results are required.

Return value
------------
This function returns an XML-RPC structures of job results in CSV
format, provided the user is authenticated with an username and token.
Available functions

results.get_testjob_results_yaml

Name
----
`get_testjob_results_yaml` (`job_id`)

Description
-----------
Get the job results of given job id in the YAML format.

Arguments
---------
`job_id`: string
    Job id for which the results are required.

Return value
------------
This function returns an XML-RPC structures of job results in YAML
format, provided the user is authenticated with an username and token.
Available functions

results.get_testjob_suites_list_csv

Name
----
`get_testjob_suites_list_csv` (`job_id`)

Description
-----------
Get the test suites list from job results of given job id in CSV format.

Arguments
---------
`job_id`: string
    Job id for which the test suites are required.

Return value
------------
This function returns an XML-RPC structures of test suites list from
job results in CSV format, provided the user is authenticated with an
username and token.
Available functions

results.get_testjob_suites_list_yaml

Name
----
`get_testjob_suites_list_yaml` (`job_id`)

Description
-----------
Get the test suites list from job results of given job id in YAML format.

Arguments
---------
`job_id`: string
    Job id for which the test suites are required.

Return value
------------
This function returns an XML-RPC structures of test suites list from
job results in YAML format, provided the user is authenticated with an
username and token.
Available functions

results.get_testsuite_results_count

Name
----
`get_testsuite_results_count` (`job_id`, `suite_name`)

Description
-----------
Get the count of test cases in test suite.

Arguments
---------
`job_id`: string
    Job id for which the results are required.
`suite_name`: string
    Name of the suite for which the test case count is required.

Return value
------------
This function returns a count of test cases in particular test suite,
provided the user is authenticated with an username and token.
Available functions

results.get_testsuite_results_csv

Name
----
`get_testsuite_results_csv` (`job_id`, `suite_name`, `limit=None`, `offset=None`)

Description
-----------
Get the suite results of given job id and suite name in CSV format.

Arguments
---------
`job_id`: string
    Job id for which the results are required.
`suite_name`: string
    Name of the suite for which the results are required.
`limit`: int
    Limit the number of test cases fetched.
`offset`: int
    Start fetching test cases from a specific point.

Return value
------------
This function returns an XML-RPC structures of suite results in CSV
format, provided the user is authenticated with an username and token.
Available functions

results.get_testsuite_results_yaml

Name
----
`get_testsuite_results_yaml` (`job_id`, `suite_name`, `limit=None`, `offset=None`)

Description
-----------
Get the suite results of given job id and suite name in YAML format.

Arguments
---------
`job_id`: string
    Job id for which the results are required.
`suite_name`: string
    Name of the suite for which the results are required.
`limit`: int
    Limit the number of test cases fetched.
`offset`: int
    Start fetching test cases from a specific point.

Return value
------------
This function returns an XML-RPC structures of suite results in YAML
format, provided the user is authenticated with an username and token.
Available functions

results.make_custom_query

Name
----
`make_custom_query` (`entity`, `conditions`, `limit`)

Description
-----------
Construct and run a custom query and return the results.

Arguments
---------
`entity`: string
    The entity you want to query
`conditions`: string
    The conditions of the query
`limit`: integer
    Add a limit to the number of results returned.
    Defaults to 200.

Return value
------------
A list of dictionaries containing the query results.

The user should be authenticated with a username and token.

Example
-------

# Get all test jobs submitted by the user 'kernel-ci', and which ended
# as 'Incomplete':
server.results.make_custom_query("testjob",
    "testjob__submitter__exact__kernel-ci,"
    "testjob__health__exact__Incomplete")
[{ jobXX }, { jobXY }, ...]

# Get all test cases in a test suite named 'custom-tests', that failed,
# and for whom the job ended after '2017-04-26 00:00:00'.
server.results.make_custom_query("testcase",
    "testsuite__name__exact__1_custom-tests,"
    "testcase__result__exact__Test failed,"
    "testjob__end_time__gt__2017-04-26 00:00:00")
[{ testcaseXX }, { testcaseXY }, ...]
Available functions

results.refresh_all_queries

Name
----
`refresh_all_queries`

Description
-----------
Refreshes all queries in the system. Available only for superusers.

Arguments
---------
None.

Return value
------------
None. The user should be authenticated with a username and token.
Available functions

results.refresh_query

Name
----
`refresh_query` (`query_name`, `username`)

Description
-----------
Refreshes the query with the given name owned by specific user.

Arguments
---------
`query_name`: string
    Query name string.
`username`: string
    Username of the user which is owner of/created the query you would
    like to update. Defaults to None, in which case the method will
    consider the authenticated user to be the owner.
    Either way, the authenticated user needs to have special access to
    this query (being an owner or belonging to the group which has
    admin access to the query).

Return value
------------
None. The user should be authenticated with a username and token.
Available functions

results.run_query

Name
----
`run_query` (`query_name`, `limit=200`, `username=None`)

Description
-----------
Run the specified query and return the results of the query.

Arguments
---------
`query_name`: string
    Query name string.
`limit`: integer
    Add a limit to the number of results returned.
    Defaults to 200.
`username`: string
    Username of the user which is owner of the query you would like the
    results.
    Defaults to None, in which case the method will consider the
    authenticated user to be the owner.
    Either way, the authenticated user needs to have special access to
    this query (being an owner or belonging to the group which has
    admin access to the query).

Return value
------------
A list of dictionaries containing the query results.

The user should be authenticated with a username and token.
Available functions

system.api_version

Name
----
`system.api_version` ()

Description
-----------
Return the lava-server XML-RPC API version string.
Clients can check this string to know whether to
use particular arguments to available functions.

Note: For older instances which do not support this
call in the first place, check for this call in the
output of system.listMethods()

if 'system.api_version' in connection.system.listMethods():
    api_version = int(connection.system.api_version())
        if api_version >= 2:
            # safe to run the new API here.
else:
    # use the old API

Arguments
---------
None

Return value
------------
lava-server XML-RPC API version integer
Available functions

system.assign_perm_device

Name
----
assign_perm_device(`perm`, `device`, `group`):

Description
-----------

Grant a permission to a specific group over a device.

This function requires ``admin_device`` permission.

Arguments
---------
perm: string
    Permission codename string. Currently supported permissions for
    Devices are 'view_device', 'submit_to_device' and
    'admin_device'.
device: string
    device hostname to assign permission for. Device with the specific
    hostname must exist in LAVA.
group: string
    group name to which the permission will be granted

Return value
------------
No return value.
Available functions

system.assign_perm_device_type

Name
----
assign_perm_device_type(`perm`, `device_type`, `group`):

Description
-----------

Grant a permission to a specific group over a device type.

This function requires ``admin_devicetype`` permission.

Arguments
---------
perm: string
    Permission codename string. Currently supported permissions for
    Device_Types are 'view_devicetype', 'submit_to_devicetype' and
    'admin_devicetype'.
device_type: string
    name of device type to assign permission for. Device type with
    specified name must exist in LAVA.
group: string
    group name to which the permission will be granted

Return value
------------
No return value.
Available functions

system.getCapabilities

Name
----
`getCapabilities` ()

Description
-----------
XML-RPC Server capabilities.

Arguments
---------
None

Return value
------------
Returns the XML-RPC Server capabilities which has the following format:

{
  auth_token: {
    'specUrl': 'xxxxxx',
    'specVersion': xxxxxx
  },
  'introspect': {
    'specUrl': 'xxxxxx',
    'specVersion': x
  },
  'faults_interop': {
    'specUrl': 'xxxxxx',
    'specVersion': xxxxxx
  }
}

Reference
---------
* See: http://groups.yahoo.com/group/xml-rpc/message/2897

* http://xmlrpc-c.sourceforge.net/xmlrpc-c/introspection.html is dead,
the actual URL that works is:
http://xmlrpc-c.sourceforge.net/introspection.html This is, however,
what the spec mandates (visit the URL above to cross-reference the
relevant fragment).
Available functions

system.listMethods

Name
----
`listMethods` ()

Description
-----------
List all available methods in this XML-RPC server.

Arguments
---------
None

Return value
------------
Returns a list of available methods.
Available functions

system.master_config

Name
----
`master_config` ()

Description
-----------
Return a dictionary containing the master and logger ZMQ
socket addresses for this instance.

Arguments
---------
None

Return value
------------
Returns a dictionary containing the following keys:
{
  "MASTER_URL": "tcp://<lava-master-dns>:5556",
  "LOGGING_URL": "tcp://<lava-master-dns>:5555",
  "ENCRYPT": False,
  "IPv6": False,
  "EVENT_SOCKET": "tcp://*:5500",
  "EVENT_TOPIC": "org.linaro.validation",
  "EVENT_NOTIFICATION": True,
  "LOG_SIZE_LIMIT": 10,
}

If ENCRYPT is True, clients MUST already have a usable
client certificate installed on the master AND the current
master certificate installed on the client, before a
connection can be made.
Available functions

system.methodHelp

Name
----
`methodHelp` (`method_name`)

Description
-----------
Provide documentation for specified method.

Arguments
---------
`method_name`: string
    Name of the method whose documentation is required.

Return value
------------
Returns the documentation for specified method.
Available functions

system.methodSignature

Name
----
`methodSignature` (`method_name`)

Description
-----------
Provide signature for the specified method.

Arguments
---------
`method_name`: string
    Name of the method whose signature is required.

Return value
------------
Returns the signature for specified method or undef if the signature is
unknown.
Available functions

system.multicall

Call multiple methods with one request.

See: http://web.archive.org/web/20060824100531/http://www.xmlrpc.com/discuss/msgReader$1208

The calls are specified by an XML-RPC array of XML-RPC structures.
Each structure must have exactly two arguments: 'methodName' and
'params'. Method name must be a string matching existing method.
Params must be an XML-RPC array of arguments for that method.

All methods will be executed in order, failure of any method does not
prevent other methods from executing.

The return value is an XML-RPC array of the same length as the lenght
of the subcalls array. Each element of the result array holds either an
XML-RPC Fault when the subcall has failed or a list with one element
that is the return value of the subcall.
Available functions

system.pipeline_network_map

Name
----
pipeline_network_map(switch=None):

Description
-----------

Collate all the vland information from pipeline devices to create a complete map,
then return YAML data for all switches or a specified switch.

This function requires authentication with a username and token.

Arguments
---------
switch: string
    hostname or IP of the switch to map. If None, data is returned for all switches.

Return value
------------
Returns a YAML file of the form:

switches:
  '192.168.0.2':
  - port: 5
    device:
      interface: eth0
      sysfs: "/sys/devices/pci0000:00/0000:00:19.0/net/eth0"
      mac: "f0:de:f1:46:8c:21"
      hostname: bbb1
Available functions

system.revoke_perm_device

Name
----
revoke_perm_device(`perm`, `device`, `group`):

Description
-----------

Revoke a permission from a specific group over a device.

This function requires ``admin_device`` permission.

Arguments
---------
perm: string
    Permission codename string. Currently supported permissions for
    Devices are 'view_device', 'submit_to_device' and
    'admin_device'.
device: string
    device hostname to revoke permission for. Device with the specific
    hostname must exist in LAVA.
group: string
    group name to which the permission will be revoked

Return value
------------
No return value.
Available functions

system.revoke_perm_device_type

Name
----
revoke_perm_device_type(`perm`, `device_type`, `group`):

Description
-----------

Revoke a permission from a specific group over a device type.

This function requires ``admin_devicetype`` permission.

Arguments
---------
perm: string
    Permission codename string. Currently supported permissions for
    Device_Types are 'view_devicetype', 'submit_to_devicetype' and
    'admin_devicetype'.
device_type: string
    name of device type to revoke permission for. Device type with
    specified name must exist in LAVA.
group: string
    group name to which the permission will be revoked

Return value
------------
No return value.
Available functions

system.user_can_submit_to_types

Name
----
user_can_submit_to_types (`type_list`)

Administrators only:
user_can_submit_to_types (`type_list`, `username`)

Description
-----------
Check the access permissions on a list of device types.
Admins can specify a username as the second argument to run
the query on behalf of that user.

Arguments
---------
type_list: list
    list of device types to query
username: string
    username of the user to query (admins only)

Return value
------------
Returns a dictionary where the key is a string of the device_type from
the type_list, if it exists in the queried instance. The value is a boolean
for whether the user can submit to any devices of the specified type.
{
  'panda': True,
  'mustang': False
}
If the device type number does not exist, that type will be omitted from the
returned dictionary.
This function requires authentication with a username and token.

Example
-------
server.system.user_can_submit_to_types(
    ['mustang', 'panda', 'qemu', 'kvm', 'cubie2']
)
{'cubie2': True, 'mustang': False, 'kvm': True, 'qemu': True, 'panda': True}

# if using the username and token of an admin, a different user can be queried:
server.system.user_can_submit_to_types(
    ['mustang', 'panda', 'qemu', 'kvm', 'cubie2'],
    'firstname.lastname'
)
Available functions

system.user_can_view_bundles

Name
----
user_can_view_bundles (`bundle_list`)

Removal of V1 support
--------------------
This function has been disabled. It is retained as a stub for older
versions of clients. Please update your tool to use LAVA V2.
Available functions

system.user_can_view_devices

Name
----
user_can_view_devices (`device_list`)

Administrators only:
user_can_view_devices (`device_list`, `username`)

Description
-----------
Check the access permissions on a list of devices.
Admins can specify a username as the second argument to run
the query on behalf of that user.

Arguments
---------
device_list: list
    list of device hostnames to query
username: string
    username of the user to query (admins only)

Return value
------------
Returns a nested dictionary where the top level key is the device type, the value is
a list of dictionaries. The key of the second dictionary is a hostname from the device_list
which exists in the queried instance. The value is a boolean
for whether the user can access that device.
If the device is visible, also includes a boolean denoting whether the specified
device is a pipeline device which can run jobs designed in the dispatcher refactoring.
If a pipeline device, also includes a boolean denoting whether the specified pipeline
device exclusively accepts YAML submissions - JSON submissions are rejected if this
device is marked as exclusive.
{
    'mustang': [
        {
            'mustang01': {
                'visible': True
                }
        }
    ],
    'panda': [
        {
            'panda05': {
                'visible': True
                }
            }
    ]
}

If the device type is hidden, that type and the nested dictionary for that type
will be omitted.
Retired devices will be omitted.
If the device does not exist, that device will be omitted from the
returned dictionary.
This function requires authentication with a username and token.

Example
-------

server.system.user_can_view_devices(['kvm014', 'kvm02'])
{'qemu':
    [
        {'kvm014': {
            'exclusive': True,
            'visible': True,
            'is_pipeline': True
            }
        },
        {'kvm02': {
            'exclusive': True,
            'visible': True,
            'is_pipeline': True}
        }
    ]
}

# if using the username and token of an admin, a different user can be queried:
server.system.user_can_view_devices(
    ['mustang01', 'wandboard07', 'imx53-01', 'cubietruck02', 'black01'],
    'firstname.lastname'
)
Available functions

system.user_can_view_jobs

Name
----
user_can_view_jobs (`job_list`)

Administrators only:
user_can_view_jobs (`job_list`, `username`)

Description
-----------
Check the access permissions on a list of jobs.
Admins can specify a username as the second argument to run
the query on behalf of that user.

Arguments
---------
job_list: list
    list of job ids to query
username: string
    username of the user to query (admins only)

Return value
------------
Returns a dictionary where the key is a string of the job_id from
the job_list, if it exists in the queried instance. The value is a boolean
for whether the user can access that job.
{
  '1234': True,
  '1543': False
}
If the job number does not exist, that job will be omitted from the
returned dictionary.
This function requires authentication with a username and token.

Example
-------
server.system.user_can_view_jobs([1, 2, 3, 4, 99999, 4000])
{'1': True, '4000': True, '3': True, '2': True, '4': True}

# if using the username and token of an admin, a different user can be queried:
server.system.user_can_view_jobs([1, 2, 3, 4, 99999, 4000], 'firstname.lastname')
{'1': True, '4000': False, '3': True, '2': True, '4': False}
Available functions

system.version

Name
----
`system.version` ()

Description
-----------
Return the lava-server version string

Arguments
---------
None

Return value
------------
lava-server version string
Available functions

system.whoami

Name
----
`whoami` ()

Description
-----------
Find the authenticated user, if any, or None.

Arguments
---------
None

Return value
------------
Name of the authenticated user, if any, or None.
Available functions