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.
LAVA Server offers API services as an XML-RPC server. You can interact with it using any XML-RPC client. For example, in python you can do this:
import xmlrpclib
server = xmlrpclib.ServerProxy("https://validation.linaro.org/RPC2")
print(server.system.listMethods())
The following python code shows how to authenticate using an XML-RPC client, when a method requires authentication.
WARNING: https:// scheme
is recommended when using authentication.
import xmlrpclib
username = "USERNAME"
token = "TOKEN_STRING"
hostname = "HOSTNAME" # validation.linaro.org
server = xmlrpclib.ServerProxy("https://%s:%s@%s/RPC2" % (username, token, hostname))
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
Name ---- `scheduler.aliases.add` (`name`) Description ----------- [superuser only] Create a device-type alias Arguments --------- `name`: string Name of the alias Return value ------------ None
Name ---- `scheduler.aliases.delete` (`name`) Description ----------- [superuser only] Remove a device-type alias Arguments --------- `name`: string Name of the alias Return value ------------ None
Name ---- `scheduler.aliases.list` () Description ----------- List available device-type aliases Arguments --------- None Return value ------------ This function returns an XML-RPC array of aliases
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.
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}]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', 164, False], ['qemu01', 'qemu', 'idle', None, True]]
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, None, 'kvm', '72.1'], [72, 'multinode-job', 'submitted', None, None, 'kvm', '72.0'], [71, 'test-job', 'running', 'kvm01', None, None, None]]
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.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
Is the device-type only available to owners?
`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
------------
NoneName ---- `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
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
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
Name ---- `scheduler.device_types.get_template` (`name`) Description ----------- Return the device-type configuration Arguments --------- `name`: string Name of the device-type Return value ------------ The device-type configuration
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
Name ---- `scheduler.device_types.set_config` (`name`, `config`) Description ----------- [superuser only] Set the device-type configuration Arguments --------- `name`: string name of the device-type `config`: string The device-type configuration as a jinja2 template Return value ------------ None
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
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
Hide this device type for all users except owners of devices of this type.
`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
------------
NoneName
----
`scheduler.devices.add` (`hostname`, `type_name`, `worker_hostname`,
`user_name=None`, `group_name=None`,
`public=True`, `status=None`,
`health_status=None`, `description=None`)
Description
-----------
[superuser only]
Add a new device to the database, to support V1 and V2.
Each device will also need a device dictionary which may include a
setting making the device exclusive to V2.
Arguments
---------
`hostname`: string
Hostname of the device
`type_name`: string
Type of the new device
`worker_hostname`: string
Worker hostname
`user_name`: string
Device owner, None by default
`group_name`: string
Device group owner, None by default
`public`: boolean
Is the device public?
`status`: string
Device status, among ["OFFLINE", "IDLE", "RUNNING", "OFFLINING",
"RETIRED", "RESERVED"]
`health_status`: string
Device health, among ["UNKNOWN", "PASS", "FAIL", "LOOPING"]
`description`: string
Device description
Return value
------------
NoneName ---- `scheduler.devices.force_health_check` (`hostname`) Description ----------- [admin only] Force health check on the specified device Arguments --------- `hostname`: string Hostname of the device Return value ------------ The id of the health check job.
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
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
Name ---- `scheduler.devices.set_dictionary` (`hostname`, `dictionary`) Description ----------- [superuser 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.
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
Name
----
`scheduler.devices.update` (`hostname`, `worker_hostname=None`,
`user_name=None`, `group_name=None`,
`public=True`, `status=None`,
`health_status=None`, `description=None`)
Description
-----------
[superuser 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
Device owner
`group_name`: string
Device group owner
`public`: boolean
Is the device public?
`status`: string
Device status, among ["OFFLINE", "IDLE", "RUNNING", "OFFLINING",
"RETIRED", "RESERVED"]
`health_status`: string
Device health, among ["UNKNOWN", "PASS", "FAIL", "LOOPING"]
`description`: string
Device description
Return value
------------
NoneName
----
`export_device_dictionary` (`device_hostname`)
Description
-----------
[superuser 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.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.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.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']}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.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.
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'
}
]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'
}
]Name
----
`import_device_dictionary` (`device_hostname`, `jinja_string`)
Description
-----------
[superuser 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.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:
_results_link, _state, submitter_id, submit_token_id, is_pipeline,
id, failure_comment, multinode_definition, user_id,
priority, _actual_device_cache, original_definition,
status, health_check, description, admin_notifications, start_time,
target_group, visibility, requested_device_id, pipeline_compatibility,
submit_time, is_public, _old_status, actual_device_id, definition,
sub_id, requested_device_type_id, end_time,
group_id, absolute_url, submitter_usernameName
----
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.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.Name
----
`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)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.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.Name ---- `scheduler.jobs.list` (`start=0`, `limit=25`) Description ----------- List the last jobs, within the specified range, in descending order of job ID. Arguments --------- `start`: int Skip the first job 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
Name ---- `scheduler.jobs.logs` (`job_id`, `line=0`) Description ----------- Return the logs for the given job Arguments --------- `job_id`: str Job id `line`: int Show only after the given 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.
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.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.
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.Name ---- `notify_incomplete_job` (`job_id`) Description ----------- Internal call to notify the master scheduler that a job on a remote worker ended in the Incomplete state. This allows the master to send the notification emails, if any. The status of the TestJob is not altered. Arguments --------- The TestJob.id which ended in status Incomplete. Return value ------------ None. The user should be authenticated with a username and token.
Name
----
`pending_jobs_by_device_type` ()
Description
-----------
Get number of pending jobs in each device type.
Arguments
---------
None
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}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.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.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.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.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}
`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.
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
Name ---- `scheduler.workers.get_config` (`hostname`) Description ----------- Return the worker configuration Arguments --------- `hostname`: string Hostname of the worker Return value ------------ This function returns the worker configuration
Name ---- `scheduler.workers.list` () Description ----------- List workers Arguments --------- None Return value ------------ This function returns an XML-RPC array of workers
Name ---- `scheduler.workers.set_config` (`hostname`, `config`) Description ----------- [superuser only] 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.
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
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
------------
NoneName
----
`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.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.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'}
]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.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.Name
----
`get_testsuite_results_csv` (`job_id`, `suite_name`)
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.
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.Name
----
`get_testsuite_results_yaml` (`job_id`, `suite_name`)
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.
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.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__status__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 }, ...]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.
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.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.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 integerName
----
`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).Name ---- `listMethods` () Description ----------- List all available methods in this XML-RPC server. Arguments --------- None Return value ------------ Returns a list of available methods.
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.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.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.
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: bbb1Name
----
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'
)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.
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': False,
'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'
)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}Name ---- `system.version` () Description ----------- Return the lava-server version string Arguments --------- None Return value ------------ lava-server version string
Name ---- `whoami` () Description ----------- Find the authenticated user, if any, or None. Arguments --------- None Return value ------------ Name of the authenticated user, if any, or None.