bkr: Beaker client¶

Subcommands¶

• bkr-distro-trees-list(1) – List Beaker distro trees
• bkr-distro-trees-verify(1) – Check Beaker distro trees for problems
• bkr-distros-edit-version(1) – Edit the version of Beaker distros
• bkr-distros-list(1) – List Beaker distros
• bkr-distros-tag(1) – Tag Beaker distros
• bkr-distros-untag(1) – Untag Beaker distros
• bkr-group-create(1) – Create a group
• bkr-group-list(1) – List groups
• bkr-group-members(1) – List members of a group
• bkr-group-modify(1) – Modify a group
• bkr-harness-test(1) – Generate Beaker job to test harness installation
• bkr-job-cancel(1) – Cancel running Beaker jobs
• bkr-job-clone(1) – Clone existing Beaker jobs
• bkr-job-comment(1) – Add a comment to a job
• bkr-job-delete(1) – Delete Beaker jobs
• bkr-job-list(1) – List Beaker jobs
• bkr-job-logs(1) – Print URLs of Beaker recipe log files
• bkr-job-modify(1) – Modify Beaker jobs
• bkr-job-results(1) – Export Beaker job results as XML
• bkr-job-submit(1) – Submit job XML to Beaker
• bkr-job-watch(1) – Watch the progress of a Beaker job
• bkr-labcontroller-create(1) – Create a new lab controller
• bkr-labcontroller-list(1) – List Beaker lab controllers
• bkr-labcontroller-modify(1) – Modify a lab controller
• bkr-list-labcontrollers(1) –
• bkr-list-systems(1) –
• bkr-loan-grant(1) – Grant a loan for a Beaker system
• bkr-loan-return(1) – Return a current Beaker system loan
• bkr-machine-test(1) – Generate Beaker job to test a system
• bkr-policy-grant(1) – Grant permissions in an access policy
• bkr-policy-list(1) – Lists access policy rules for a system
• bkr-policy-revoke(1) – Revoke permissions in an access policy
• bkr-pool-add(1) – Add systems to a system pool
• bkr-pool-create(1) – Create a system pool
• bkr-pool-delete(1) – Delete a system pool
• bkr-pool-list(1) – List system pools
• bkr-pool-modify(1) – Modify a system pool
• bkr-pool-remove(1) – Remove systems from a pool
• bkr-pool-systems(1) – List systems in a pool
• bkr-remove-account(1) – Remove user accounts
• bkr-system-create(1) – Create a system
• bkr-system-delete(1) – Delete a Beaker system permanently
• bkr-system-details(1) – Export RDF/XML description of a Beaker system
• bkr-system-history-list(1) – Export history of activity for the given system
• bkr-system-list(1) – List Beaker systems
• bkr-system-modify(1) – Modify system attributes
• bkr-system-power(1) – Control power for a Beaker system
• bkr-system-provision(1) – Provision a Beaker system
• bkr-system-release(1) – Release a reserved Beaker system
• bkr-system-reserve(1) – Manually reserve a Beaker system
• bkr-system-status(1) – Return the current status of a system
• bkr-task-add(1) – Upload tasks to Beaker’s task library
• bkr-task-delete(1) – Delete tasks to Beaker’s task library
• bkr-task-details(1) – Export details of a Beaker task
• bkr-task-list(1) – List tasks in Beaker’s task library
• bkr-update-inventory(1) – Submits a inventory job for the system
• bkr-update-openstack-trust(1) – Update OpenStack Keystone trust
• bkr-update-prefs(1) – Update user preferences
• bkr-user-modify(1) – Modify Beaker users
• bkr-watchdog-extend(1) – Extend Beaker watchdog time
• bkr-watchdog-show(1) – Show time remaining on Beaker watchdogs
• bkr-watchdogs-extend(1) – Extend Beaker watchdogs time
• bkr-whoami(1) – Show your Beaker username
• bkr-workflow-installer-test(1) – DEPRECATED workflow to generate a kickstart for testing Anaconda
• bkr-workflow-simple(1) – Simple workflow to generate Beaker jobs

Specifying tasks¶

Some bkr subcommands accept one or more <taskspec> arguments. This allows the user to identify a job, or any subcomponent of a job, by its id. The format is <type>:<id> where <type> is one of the following abbreviations, in descending hierarchical order:

J

job

RS

recipe set

R

recipe

T

recipe-task

TR

task-result

For example, J:123 might contain RS:456, which might contain R:789, which might contain T:1234 and T:5678.

This format is also used in the Beaker web UI to identify jobs and their subcomponents.

Common options¶

These options are applicable to all bkr subcommands.

--hub <url>¶

Connect to the Beaker server at the given URL. This overrides the HUB_URL setting from the configuration file. The URL should not include a trailing slash.

--insecure¶

Skip all SSL certificate validity checks. This allows the client to connect to a Beaker server with an invalid, expired, or untrusted SSL certificate.

--username <username>¶

Authenticate using password authentication, with <username>. If a password is not given using --password, the user is prompted for the password on stdin.

This option overrides the authentication type specified in the configuration file, forcing password authentication to be used.

--password <password>¶

Authenticate using <password>. This option is only applicable when --username is also passed.

--proxy-user <username>¶

Impersonate <username> in order to perform actions on their behalf.

This option can only be used when the authenticating user is a member of a group which has been granted ‘proxy_user’ permission by the Beaker administrator. Typically this permission is granted to service accounts so that a trusted script can perform actions on behalf of any other Beaker user.

--help¶

Show a brief summary of the command and its available options then exit.

Workflow options¶

These options are applicable to bkr workflow subcommands, such as bkr workflow-simple.

--dry-run, --dryrun¶

Don’t submit the job(s) to Beaker.

--debug¶

Print the generated job XML before submitting it to Beaker.

--pretty-xml, --prettyxml¶

Pretty-print the generated job XML in a human-readable form (with indentation and line breaks).

--wait¶

Watch the newly submitted job(s) for state changes and print them to stdout. The command will not exit until all submitted jobs have finished. See bkr-job-watch(1).

--no-wait, --nowait¶

Do not wait on job completion [default].

--quiet¶

Be quiet, don’t print warnings.

Options for selecting distro tree(s):

--family <family>¶

Run the job with the latest distro in <family> (for example: RedHatEnterpriseLinux6).

--tag <tag>¶

Run the job with the latest distro tagged with <tag>. Combine this with --family. By default the STABLE tag is used.

--distro <name>¶

Run the job with distro named <name>. If the given name includes a % character, it is interpreted as a SQL LIKE pattern (the % character matches any substring).

--variant <variant>¶

Run the job with distro variant <variant>, for example Server. Combine this with --family.

--arch <arch>¶

Use only <arch> in job. By default, a recipe set is generated for each arch supported by the selected distro. This option may be specified multiple times.

Options for selecting system(s):

--machine <fqdn>¶

Run the job on system with <fqdn>. This option will always select a single system, and so does not make sense combined with any other system options.

--ignore-system-status¶

Always use the system given by –machine, regardless of its status.

--systype <type>¶

Run the job on system(s) of type <type>. This defaults to Machine which is almost always what you want. Other supported values are Laptop, Prototype and Resource. Laptop type would be used to select a system from the available laptop computers. Similarly, Resource and Prototype would be used in cases where you would want to schedule your job against a system whose type has been set as such.

--hostrequire "<tag> <operator> <value>"¶

Additional <hostRequires/> for the job. For example, labcontroller=lab.example.com would become <labcontroller op="=" value="lab.example.com"/> in the job XML.

For more advanced filtering (for example using <device/>) you can also pass raw XML directly to this option. Any value starting with < is parsed as XML and inserted directly into <hostRequires/>.

See Job XML for more information about the <hostRequires/> element.

--host-filter <name>¶

Look up the pre-defined host filter with the given name,and add the corresponding XML snippet to <hostRequires/>.

You can use pre-defined host filters as a short-hand for complicated or difficult to remember XML snippets. Beaker includes many pre-defined filters for different types of hardware. For example, pass --host-filter=INTEL__FAM15_CELERON to filter for hosts with an Intel Celeron CPU.

Filter definitions are read from the following configuration files:

• /usr/lib/python2.x/site-packages/bkr/client/host-filters/*.conf
• /etc/beaker/host-filters/*.conf
• ~/.beaker_client/host-filter

Files within each directory are processed in lexicographical order. The files contain one filter definition per line, consisting of the filter name and the associated XML snippet separated by whitespace. If the same filter name appears in multiple files, the last definition overrides earlier definitions.

--keyvalue "<name> <operator> <value>"¶

Run the job on system(s) which have the key <name> set to <value> (for example: NETWORK=e1000).

--random¶

Select a system at random. The systems owned by the user are first checked for availability, followed by the systems owned by the user’s group and finally all other systems.

Options for selecting tasks:

--task <task>¶

Include <task> in the job. This option may be specified multiple times.

--taskfile <filename>¶

Include tasks listed in <filename>, each line contains one task name. Lines not starting with ‘/’ are ignored.

--package <package>¶

Include tests for <package> in the job. This option may be specified multiple times.

--task-type <type>¶

Include tasks of type <type> in the job. This option may be specified multiple times.

--install <package>¶

Install additional package <package> after provisioning. This uses the /distribution/pkginstall task. This option may be specified multiple times.

--kdump¶

Enable kdump using using /kernel/networking/kdump.

--ndump¶

Enable ndnc using using /kernel/networking/ndnc.

--suppress-install-task¶

Omit the installation checking task.

By default, the first task in the recipe will be /distribution/check-install. The purpose of this task is to check that the operating system was installed successfully and report back on any potential problems, and to collect information about the installed system for debugging.

Pass this option if you do not want this task to be implicitly inserted at the start of the recipe.

Options for job configuration:

--job-owner <username>¶

Submit the job on behalf of <username>. The job will be owned by <username> rather than the submitting user.

The submitting user must be a submission delegate of <username>. Users can add other users as submission delegates on their Preferences page in Beaker’s web UI.

--job-group <group>¶

Associate the job with <group>. This will allow other group members to modify the job.

--whiteboard <whiteboard>¶

Set the job’s whiteboard to <whiteboard>.

--taskparam <name>=<value>¶

Sets parameter <name> to <value> for all tasks in the job.

New in version 0.14.3.

--ignore-panic¶

Disable kernel panic detection and install failure detection for the recipe. By default if a kernel panic appears on the serial console, or a fatal installer error appears during installation, the recipe is aborted. When this option is given, the messages are ignored and the recipe is not aborted.

--reserve¶

Reserve the system at the end of the recipe, for further testing or examination. The system will be reserved when all tasks have completed executing, or if the recipe ends abnormally. Refer to Using the <reservesys/> element.

--reserve-duration <seconds>¶

When --reserve is used, this option controls the duration for the reservation. The default duration is 86400 seconds (24 hours).

--cc <email>¶

Add <email> to the cc list for the job(s). The cc list will receive the job completion notification. This option may be specified multiple times.

--priority <priority>¶

Set job priority to <priority>. Can be Low, Medium, Normal, High, or Urgent. The default is Normal.

--retention-tag <tag>¶

Specify data retention policy for this job [default: Scratch]

--product <product>¶

Associate job with <product> for data retention purposes.

Options for installation:

--method <method>¶

Installation source method (nfs, http, ftp) [default: nfs].

--kernel-options <opts>¶

Pass additional kernel options for during installation. The options string is applied on top of any install-time kernel options which are set by default for the chosen system and distro.

--kernel-options-post <opts>¶

Pass additional kernel options for after installation. The options string is applied on top of any post-install kernel options which are set by default for the chosen system and distro.

--ks-append <commands>¶

Specify additional kickstart commands to add to the base kickstart file.

--ks-meta <options>¶

Pass kickstart metadata <options> when generating kickstart.

--repo <url>¶

Make the yum repository at <url> available during initial installation of the system and afterwards. This option may be specified multiple times. The installation may fail if the repo is not actually available.

--repo-post <url>¶

Make the yum repository at <url> available AFTER the installation. This option may be specified multiple times. The repo config will be appended to the kickstart’s %post section. Whether or not the installation succeeds is not affected by the availability of the repo.

--kickstart <filename>¶

Use this kickstart template for installation. Templates are rendered on the server. Refer to the Custom kickstart templates section in Beaker’s documentation for details about the templating language and available variables. You can also pass raw kickstarts in - if you don’t use any Jinja2 variable substitution syntax, the rendering process will reproduce the template verbatim.

If the template provides the following line:

## kernel_options: <options>

the specified kernel options will be appended to existing ones defined with --kernel-options.

Options for multi-host testing:

--clients <number>¶

Use <number> clients in the job.

--servers <number>¶

Use <number> servers in the job.