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.
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.
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.
Parameters: |
|
---|
This method is also available under the alias auth.login_krbv(), for compatibility with Kobo.
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.
Parameters: |
|
---|
Invalidates the current session.
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.
These XML-RPC methods allow the caller to query and manipulate systems in Beaker’s inventory.
“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.
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.
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: |
|
---|
New in version 0.6.
Changed in version 0.6.14: No longer waits for completion of Cobbler power task.
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: |
|
---|
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().
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.
The following XML-RPC methods allow the caller to fetch and manipulate distros and distro trees recorded in Beaker.
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.
- ‘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.
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.
- ‘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.
Returns a list of all distro families. If tags is given, limits to distros with at least one of the given tags.
Updates the version for all distros with the given name.
Parameters: |
|
---|
Applies the given tag to all matching distros.
Parameters: |
|
---|---|
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.
Like distros.tag() but the opposite.
These XML-RPC methods fetch and manipulate tasks in the Beaker task library.
Returns an XML-RPC structure (dict) with details about the given task.
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
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.
Uploads a new task RPM.
Parameters: |
|
---|
Queues a new job.
Parameters: |
|
---|
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.
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
At present, only non admins can call this feature. Admin functionality will be added to when we are using a message bus.
Return an array of logs for the given recipe.
Parameters: |
|
---|
Extends the watchdog for a running task.
Parameters: |
|
---|
Returns number of seconds left on the watchdog for the given task, or False if it doesn’t exist.
Parameters: |
|
---|
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:
Returns an XML representation of the given job component, including its current state.
Parameters: |
|
---|
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: |
|
---|