Beaker

XML-RPC methods

These XML-RPC methods form part of the public API exposed by Beaker. The bkr command-line client (distributed with Beaker) uses these methods to interact with the Beaker server. Users may also invoke them directly. The Python standard library includes an XML-RPC client library (xmlrpclib); the Kobo utility library may also be of interest.

The XML-RPC endpoint URL is /RPC2 (relative to the base URL of the Beaker server).

Beaker uses XML-RPC internally for communication between the lab controller and the server. The internal API is not documented here.

Authentication

XML-RPC methods in the auth namespace allow the caller to begin or end an authenticated session with Beaker.

Beaker uses HTTP cookies to track sessions across XML-RPC calls. When calling the auth.login_*() methods below, the response will include an HTTP cookie identifying the session. The caller must use this cookie in subsequent requests which belong with this session.

auth.login_krbV(krb_request, proxy_user=None)

Authenticates the current session using Kerberos. The caller may act as a proxy on behalf of another user by passing the proxy_user argument. This requires that the caller has ‘proxy_auth’ permission. :param krb_request: KRB_AP_REQ message containing client credentials, as produced by krb5_mk_req() :type krb_request: base64-encoded string :param proxy_user: username on whose behalf the caller is proxying :type proxy_user: string or None This method is also available under the alias auth.login_krbv(), for compatibility with Kobo.

auth.login_password(username, password, proxy_user=None)

Authenticates the current session using the given username and password. The caller may act as a proxy on behalf of another user by passing the proxy_user argument. This requires that the caller has ‘proxy_auth’ permission. :param proxy_user: username on whose behalf the caller is proxying :type proxy_user: string or None

auth.logout()

Invalidates the current session.

auth.who_am_i()

Returns an XML-RPC structure (dict) with information about the currently logged in user. Provided for testing purposes.

New in version 0.6.0.

Changed in version 0.6.1: Formerly returned only the username.

Changed in version 1.0: Also return the email address of user.

User Preferences

prefs.update(email_address=None, tg_errors=None)

Update user preferences

Parameters:email_address (string) – email address

User Accounts

users.remove_account(username, newowner=None)

Removes a Beaker user account. When the account is removed:

  • it is removed from all groups and access policies
  • any running jobs owned by the account are cancelled
  • any systems reserved by or loaned to the account are returned
  • any systems and system pools owned by the account are transferred to the admin running this command, or some other user if specified using the newowner parameter
  • the account is disabled for further login
Parameters:
  • username (string) – An existing username
  • newowner – An optional username to assign all systems to.

Groups

These XML-RPC methods allow the caller to query and manipulate groups in Beaker.

groups.create(kw)

Creates a new group.

The kw argument must be an XML-RPC structure (dict) specifying the following keys:

‘group_name’
Group name (maximum 16 characters)
‘display_name’
Group display name
‘description’
Group description
‘ldap’
Populate users from LDAP (True/False)

Returns a message whether the group was successfully created or raises an exception on failure.

groups.modify(group_name, kw)

Modifies an existing group. You must be an owner of a group to modify any details.

Parameters:group_name (string) – An existing group name

The kw argument must be an XML-RPC structure (dict) specifying the following keys:

‘group_name’
New group name (maximum 16 characters)
‘display_name’
New group display name
‘add_member’
Add user (username) to the group
‘remove_member’
Remove an existing user (username) from the group
‘root_password’
Change the root password of this group.

Returns a message whether the group was successfully modified or raises an exception on failure.

groups.grant_ownership(group, kw)

Grant group ownership to an existing group member

Parameters:group (string) – An existing group name

The kw argument must be an XML-RPC structure (dict) specifying the following keys:

‘member_name’
Group member’s username to grant ownership
groups.revoke_ownership(group, kw)

Revoke group ownership from an existing group member

Parameters:group (string) – An existing group name

The kw argument must be an XML-RPC structure (dict) specifying the following keys:

‘member_name’
Group member’s username to revoke ownership
groups.members(group_name)

List the members of an existing group.

Parameters:group_name (string) – An existing group name

Returns a list of the members (a dictionary containing each member’s username, email, and whether the member is an owner or not).

Systems

These XML-RPC methods allow the caller to query and manipulate systems in Beaker’s inventory.

systems.reserve(fqdn)

“Reserves” (a.k.a. “takes”) the system with the given fully-qualified domain name. The caller then becomes the user of the system, and can provision it at will.

A system may only be reserved when: its condition is ‘Manual’, it is not currently in use, and the caller has permission to use the system.

New in version 0.6.

systems.release(fqdn)

Releases a reservation on the system with the given fully-qualified domain name.

The caller must be the current user of a system (i.e. must have successfully reserved it previously).

New in version 0.6.

systems.power(action, fqdn, clear_netboot=False, force=False, delay=0)

Controls power for the system with the given fully-qualified domain name.

If the clear_netboot argument is True, the Cobbler netboot configuration for the system will be cleared before power controlling.

Controlling power for a system is not normally permitted when the system is in use by someone else, because it is likely to interfere with their usage. Callers may pass True for the force argument to override this safety check.

This method does not wait for Cobbler to report whether the power control was succesful.

Parameters:
  • action (string) – ‘on’, ‘off’, or ‘reboot’
  • fqdn (string) – fully-qualified domain name of the system to be power controlled
  • clear_netboot (boolean) – whether to clear netboot configuration before powering
  • force (boolean) – whether to power the system even if it is in use
  • delay (int or float) – number of seconds to delay before performing the action (default none)

New in version 0.6.

Changed in version 0.6.14: No longer waits for completion of Cobbler power task.

systems.provision(fqdn, distro_tree_id, ks_meta=None, kernel_options=None, kernel_options_post=None, kickstart=None, reboot=True)

Provisions a system with the given distro tree and options.

The ks_meta, kernel_options, and kernel_options_post arguments override the default values configured for the system. For example, if the default kernel options for the system/distro are ‘console=ttyS0 ksdevice=eth0’, and the caller passes ‘ksdevice=eth1’ for kernel_options, the kernel options used will be ‘console=ttyS0 ksdevice=eth1’.

Parameters:
  • distro_tree_id (int) – numeric id of distro tree to be provisioned
  • ks_meta (str) – kickstart options
  • kernel_options (str) – kernel options for installation
  • kernel_options_post (str) – kernel options for after installation
  • kickstart (str) – complete kickstart
  • reboot (bool) – whether to reboot the system after applying Cobbler changes

New in version 0.6.

Changed in version 0.6.10: System-specific kickstart/kernel options are now obeyed.

Changed in version 0.9: distro_install_name parameter is replaced with distro_tree_id. See distrotrees.filter().

systems.history(fqdn, since=None)

Returns the history for the given system. If the since argument is given, all history entries between that timestamp and the present are returned. By default, history entries from the past 24 hours are returned.

History entries are returned as a list of structures (dicts), each of which has the following keys:

‘created’
Timestamp of the activity
‘user’
Username of the user who performed the action
‘service’
Service by which the action was performed (e.g. ‘XMLRPC’)
‘action’
Action which was performed (e.g. ‘Changed’)
‘field_name’
Name of the field which was acted upon
‘old_value’
Value of the field before the action (if any)
‘new_value’
Value of the field after the action (if any)

Note that field names and actions are recorded in human-readable form, which might not be ideal for machine parsing.

All timestamps are expressed in UTC.

New in version 0.6.6.

systems.get_osmajor_arches(fqdn, tags=None)

Returns a dict of all distro families with a list of arches that apply for system. If tags is given, limits to distros with at least one of the given tags.

{“RedHatEnterpriseLinux3”: [“i386”, “x86_64”],}

New in version 0.11.0.

Distros and distro trees

The following XML-RPC methods allow the caller to fetch and manipulate distros and distro trees recorded in Beaker.

distrotrees.filter(filter)

Returns a list of details for distro trees filtered by the given criteria.

The filter argument must be an XML-RPC structure (dict) specifying filter criteria. The following keys are recognised:

‘name’
Distro name. May include % SQL wildcards, for example '%20101121.nightly'.
‘family’
Distro family name, for example 'RedHatEnterpriseLinuxServer5'. Matches are exact.
‘tags’
List of distro tags, for example ['STABLE', 'RELEASED']. All given tags must be present on the distro for it to match.
‘arch’
Architecture name, for example 'x86_64'.
‘treepath’
Tree path (on any lab controller). May include % SQL wildcards, for example 'nfs://nfs.example.com:%'.
‘labcontroller’
FQDN of lab controller. Limit to distro trees which are available on this lab controller. May include % SQL wildcards.
‘distro_id’
Distro id. Matches are exact.
‘distro_tree_id’
Distro Tree id. Matches are exact.
‘xml’
XML filter criteria in the same format allowed inside <distroRequires/> in a job, for example <or><distro_tag value="RELEASED"/><distro_tag value="STABLE"/></or>.
‘limit’
Integer limit to number of distro trees returned.

The return value is an array with one element per distro (up to the maximum number of distros given by ‘limit’). Each element is an XML-RPC structure (dict) describing a distro tree.

New in version 0.9.

distros.filter(filter)

See also

distrotrees.filter()

Returns a list of details for distros filtered by the given criteria.

The filter argument must be an XML-RPC structure (dict) specifying filter criteria. The following keys are recognised:

‘name’
Distro name. May include % SQL wildcards, for example '%20101121.nightly'.
‘family’
Distro family name, for example 'RedHatEnterpriseLinuxServer5'. Matches are exact.
‘distroid’
Distro id. Matches are exact.
‘tags’
List of distro tags, for example ['STABLE', 'RELEASED']. All given tags must be present on the distro for it to match.
‘limit’
Integer limit to number of distros returned.

The return value is an array with one element per distro (up to the maximum number of distros given by ‘limit’). Each element is an XML-RPC structure (dict) describing a distro.

Changed in version 0.9: Some return columns were removed, because they no longer apply to distros in Beaker. Use the new distrotrees.filter() method to fetch details of distro trees.

distros.get_osmajors(tags=None)

Returns a list of all distro families. If tags is given, limits to distros with at least one of the given tags.

distros.edit_version(name, version)

Updates the version for all distros with the given name.

Parameters:
  • name (string) – name of distros to be updated, for example ‘RHEL5.6-Server-20101110.0’
  • version (string) – new version to be applied, for example ‘RedHatEnterpriseLinuxServer5.6’ or ‘Fedora14’
distros.tag(name, tag)

Applies the given tag to all matching distros.

Parameters:
  • name (string or nil) – distro name to filter by (may include SQL wildcards)
  • tag (string) – tag to be applied
Returns:

list of distro names which have been modified

Changed in version 0.9: Removed arch parameter. Tags apply to distros and not distro trees.

distros.untag(name, tag)

Like distros.tag() but the opposite.

Task library

These XML-RPC methods fetch and manipulate tasks in the Beaker task library.

tasks.to_dict(name, valid=None)

Returns an XML-RPC structure (dict) with details about the given task.

tasks.filter(filter)

Returns a list of tasks filtered by the given criteria.

The filter argument must be an XML-RPC structure (dict), with any of the following keys:

‘distro_name’
Distro name. Include only tasks which are compatible with this distro.
‘osmajor’
OSVersion OSMajor, like RedHatEnterpriseLinux6. Include only tasks which are compatible with this OSMajor.
‘names’
Task name. Include only tasks that are named. Useful when combined with ‘osmajor’ or ‘distro_name’.
‘packages’
List of package names. Include only tasks which have a Run-For entry matching any of these packages.
‘types’
List of task types. Include only tasks which have one or more of these types.
‘valid’
bool 0 or 1. Include only tasks which are valid or not.
‘destructive’
bool 0 or 1. Set to 0 for only non-destructive tasks. Set to 1 for only destructive tasks.

The return value is an array of dicts, which are name and arches. name is the name of the matching tasks. arches is an array of arches which this task does not apply for. Call tasks.to_dict() to fetch metadata for a particular task.

Changed in version 0.9: Changed ‘install_name’ to ‘distro_name’ in the filter argument.

tasks.upload(task_rpm_name, task_rpm_data)

Uploads a new task RPM.

Parameters:
  • task_rpm_name (string) – filename of the task RPM, for example 'beaker-distribution-install-1.10-11.noarch.rpm'
  • task_rpm_data (XML-RPC binary) – contents of the task RPM

Running jobs

jobs.upload(jobxml, ignore_missing_tasks=False)

Queues a new job.

Parameters:
  • jobxml (string) – XML description of job to be queued
  • ignore_missing_tasks (bool) – pass True for this parameter to cause unknown tasks to be silently discarded (default is False)
jobs.list(tags, days_complete_for, family, product, **kw)

Lists Jobs, filtered by the given criteria. :param tags: limit to recipe sets which have one of these retention tags :type tags: string or array of strings :param days_complete_for: limit to recipe sets which completed at least this many days ago :type days_complete_for: integer :param family: limit to recipe sets which used distros with this family name :type family: string

Returns a two-element array. The first element is an array of JobIDs of the form 'J:123', suitable to be passed to the jobs.delete_jobs() method. The second element is a human-readable count of the number of Jobs matched. Does not return deleted jobs.

Deprecated since version 0.9.4: Use jobs.filter() instead.

jobs.filter(filters)

Returns a list of details for jobs filtered by the given criteria.

The filter argument must be a an XML-RPC structure (dict) specifying filter criteria. The following keys are recognised:

‘tags’
List of job tags.
‘daysComplete’
Number of days elapsed since the jobs completion.
‘family’
Job distro family, for example 'RedHatEnterpriseLinuxServer5'.
‘product’
Job product name
‘owner’
Job owner username
‘mine’
Inclusion is equivalent to including own username in ‘owner’
‘group’
Job group name
‘my-group’
Jobs for any of the given user’s groups.
‘whiteboard’
Job whiteboard (substring match)
‘limit’
Integer limit to number of jobs returned.
‘minid’
Min JobID of the jobs to search
‘maxid’
Maximum Job ID of the jobs to search
‘is_finished’
If True, limit to jobs which are finished(completed, aborted, cancelled) If False, limit to jobs which are not finished.

Returns an array of JobIDs of the form 'J:123', suitable to be passed to the jobs.delete_jobs() method. Does not return deleted jobs.

jobs.delete_jobs(jobs=None, tag=None, complete_days=None, family=None, dryrun=False, product=None)

delete_jobs will mark the job to be deleted

To select jobs by id, pass an array for the jobs argument. Elements of the array must be strings of the form 'J:123'. Alternatively, pass some combination of the tag, complete_days, or family arguments to select jobs for deletion. These arguments behave as per the jobs.list() method.

If dryrun is True, deletions will be reported but nothing will be modified.

Admins are not be able to delete jobs which are not owned by themselves by using the tag, complete_days etc kwargs, instead, they should do that via the jobs argument.

recipes.files(recipe_id)

Return an array of logs for the given recipe.

Parameters:recipe_id (integer) – id of recipe

Deprecated since version 0.9.4: Use taskactions.files() instead.

recipes.tasks.extend(task_id, kill_time)

Extends the watchdog for a running task.

Parameters:
  • task_id (integer) – id of task to be extended
  • kill_time (integer) – number of seconds by which to extend the watchdog
recipes.tasks.watchdog()

Returns number of seconds left on the watchdog for the given task, or False if it doesn’t exist.

Parameters:task_id (integer) – id of task

XML-RPC methods in the taskactions namespace can be applied to a running job or any of its constituent parts (recipe sets, recipes, tasks, and task results). For methods related to Beaker’s task library, see the Task library section.

These methods accept a taskid argument, which must be a string of the form type:id, for example 'RS:4321'. The server recognises the following values for type:

  • J: Job
  • RS: Recipe set
  • R: Recipe
  • T: Task within a recipe
  • TR: Result within a task
taskactions.task_info(taskid)

Returns an XML-RPC structure (dict) describing the current state of the given job component.

Parameters:taskid (string) – see above
taskactions.to_xml(taskid, clone=False, exclude_enclosing_job=True, include_logs=True)

Returns an XML representation of the given job component, including its current state.

Parameters:
  • taskid (string) – see above
  • clone (bool) – If True, returns XML suitable for submitting back to Beaker. Otherwise, the XML includes results.
  • exclude_enclosing_job (bool) – If False, returns <job> as the root element even when requesting a recipe set or recipe. This is useful when cloning, in order to always produce a complete job definition.
  • include_logs (bool) – If True (the default), the results XML includes links to all logs. This can make the results XML substantially larger.
taskactions.files(taskid)

Returns an array of XML-RPC structures (dicts) describing each of the result files for the given job component and its descendants.

Parameters:taskid (string) – see above
taskactions.stop(taskid, stop_type, msg)

Cancels the given job. Note that when cancelling some part of a job (for example, by passing taskid starting with R: to indicate a particular recipe within a job) the entire job is cancelled.

Parameters:
  • taskid (string) – see above
  • stop_type (string) – must be 'cancel' (other values are reserved for Beaker’s internal use)
  • msg (string) – reason for cancelling
jobs.set_response(taskid, response)

Updates the response (ack/nak) for a recipe set, or for all recipe sets in a job.

Deprecated: setting ‘nak’ is a backwards compatibility alias for waiving a recipe set. Use the JSON API to set {waived: true} instead.

Parameters:
  • taskid (string) – see above
  • response (string) – new response, either 'ack' or 'nak'

General Beaker information

lab_controllers()

Returns an array containing the fully-qualified domain name of each lab controller attached to the Beaker server.