BKR(1)

📦
version 29.2 · 3 versions
, in epel 9

💅 BKR(1) — the Beaker client, bestie edition 🎀

okay so this is bkr, the Beaker client — and in the classic manpage style it lives under the name BKR(1) in section 1 (Beaker). Think of this page as your group-chat pinned message for the stuff every subcommand shares. The individual subcommands each get their own man page, so don't come for me about missing flags — they're literally in their own docs, iykyk. ✨

🌸 NAME 🌸

bkr — the Beaker client. that's it, that's the name, she's iconic 💅

🦋 SYNOPSIS 🦋

bkr <subcommand> [options] ...

💖 DESCRIPTION 💖

so basically bkr gives you a scriptable command-line interface to the Beaker server. no cap, it's the whole point. 🫶

Here's the tea: the following subcommands are supported. Each subcommand is documented in its own man page. This man page is reserved for common options and features. periodt.

orphan

⭐ Subcommands ⭐

🧚 Specifying tasks 🧚

okay this part is lowkey the most useful thing on the whole page. Some bkr subcommands accept one or more <taskspec> arguments. This lets you identify a job, or literally any subcomponent of a job, by its id. The format is:

<type>:<id>

...where <type> is one of these abbreviations, in descending hierarchical order:

  • J — job
  • RS — recipe set
  • R — recipe
  • T — recipe-task
  • TR — task-result

So for example, J:123 might contain RS:456, which might contain R:789, which might contain T:1234 and T:5678. it's giving nesting dolls but make it CI 🪆

This format is also used in the Beaker web UI to identify jobs and their subcomponents. so you'll see it everywhere, bestie — learn it once, slay forever 💅

✨ OPTIONS ✨

🎀 Common options 🎀

These options are applicable to all bkr subcommands. universal queen behavior 👑

  • --hub <url> — Connect to the Beaker server at the given URL. This overrides the HUB_URL setting from the configuration file. Heads up though: the URL should not include a trailing slash. don't do it. I'm begging 🙈
  • --insecure — Skip all SSL certificate validity checks. This lets the client connect to a Beaker server with an invalid, expired, or untrusted SSL certificate. yes this is exactly as spicy as it sounds 🔥
  • --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. she does not care what your config said 💀

  • --password <password> — Authenticate using <password>. This option is only applicable when --username is also passed. solo password is a no, they're a package deal 🫶
  • --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. it's giving main character energy on someone else's behalf, but like, officially sanctioned ✨

  • --help — Show a brief summary of the command and its available options then exit. the "help I'm lost" button, but make it fashionable 🧭

🌈 Workflow options 🌈

These options are applicable to bkr workflow subcommands, such as bkr workflow-simple. (yes, they get their own little club 🌸)

  • --dry-run, --dryrun — Don't submit the job(s) to Beaker. look but don't touch, iconique 👀
  • --debug — Print the generated job XML before submitting it to Beaker. for when you gotta see the receipts 🧾
  • --pretty-xml, --prettyxml — Pretty-print the generated job XML in a human-readable form (with indentation and line breaks). because raw XML is a jumpscare 😭
  • --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). she commits to the bit and stays till the end ⌛
  • --no-wait, --nowait — Do not wait on job completion [default]. submit and dip 🏃‍♀️
  • --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). wildcard slay ✨
  • --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. stack 'em up 🧱

🌸 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. monogamous machine selection 💍
  • --ignore-system-status — Always use the system given by --machine, regardless of its status. no vibe check, we ride 🏇
  • --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. pick your fighter 🥊
  • --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/>. (yes that comma-squish is canon, don't @ me 😌)

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. last one wins, no takebacks 🏆

  • --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. chaotic neutral system selection 🎲

💜 Options for selecting tasks: 💜

  • --task <task> — Include <task> in the job. This option may be specified multiple times.
  • --taskfile <filename> — pull in tasks from filename, one task name per line. Lines that don't start with / are literally ignored, so don't come for me when they get skipped 🫶
  • --package <package> — include the tests for package in the job. You can pass this as many times as you want, stack 'em up ✨
  • --task-type <type> — include tasks of type type in the job. Also repeatable, also stackable, go off 👑
  • --install <package> — install an extra package after provisioning. This one rides on the /distribution/pkginstall task. Repeatable too.
  • --kdump — turn on kdump, using /kernel/networking/kdump.
  • --ndump — turn on ndnc, using /kernel/networking/ndnc.
  • --suppress-install-task — skip the installation-checking task entirely.

Okay so by default the very first task in the recipe is /distribution/check-install. Its whole job is to confirm the OS actually installed okay, report back on anything sus, and hoover up info about the installed system for debugging purposes.

Pass this flag only if you genuinely don't want that task quietly inserted at the top of your recipe, bestie.

🌸 Options for job configuration 🌸

  • --job-owner <username> — submit the job on behalf of username. So the job belongs to username and not to you, the submitting user. Iconic delegation move.

Heads up though: the submitting user must be a submission delegate of username. People add other users as submission delegates on their Preferences page in Beaker's web UI. No delegate status, no submitting for them, fr fr.

  • --job-group <group> — attach the job to group, which lets other members of that group modify it. Sharing is caring 💜
  • --whiteboard <whiteboard> — set the job's whiteboard to whiteboard.
  • --taskparam <name>=<value> — set the parameter name to value for every task in the job.
New in version 0.14.3. 🎀
  • --ignore-panic — disable kernel panic detection and install failure detection for the recipe. Normally, if a kernel panic shows up on the serial console, or a fatal installer error pops up during installation, the recipe gets aborted. Give this option and those messages just get ignored — no abort. 💀
  • --reserve — reserve the system at the end of the recipe so you can keep testing or poking at it. It gets reserved once all tasks finish running, or if the recipe ends abnormally. See reservesys for the deets.
  • --reserve-duration <seconds> — when --reserve is on, this controls how long the reservation lasts. Default is 86400 seconds, aka 24 hours. That's a whole day, bestie 😭
  • --cc <email> — add email to the cc list for the job(s). Everyone on the cc list gets the job completion notification. Repeatable, obviously.
  • --priority <priority> — set the job priority to priority. Valid values: Low, Medium, Normal, High, or Urgent. Default is Normal.
  • --retention-tag <tag> — set the data retention policy for this job [default: Scratch].
  • --product <product> — associate the job with product, for data retention purposes.

🧚 Options for installation 🧚

  • --method <method> — installation source method: nfs, http, or ftp [default: nfs].
  • --kernel-options <opts> — pass extra kernel options for during installation. The options string gets applied on top of any install-time kernel options that are set by default for the chosen system and distro. Stack it like a filter, not like a replacement ✨
  • --kernel-options-post <opts> — same deal but for after installation. Applied on top of any post-install kernel options set by default for the chosen system and distro.
  • --ks-append <commands> — add extra kickstart commands onto the base kickstart file.
  • --ks-meta <options> — pass kickstart metadata options along when generating the kickstart.
  • --repo <url> — make the yum repo at url available during the initial installation and afterwards. Repeatable! But lowkey mind this: the installation may fail if the repo isn't actually available. So like, double check the URL first 🫶
  • --repo-post <url> — make the yum repo at url available AFTER the installation. Repeatable. The repo config gets appended to the kickstart's %post section. And here's the nice part: whether or not the installation succeeds is not affected by whether this repo is available. Chill repo, no pressure 🦋
  • --kickstart <filename> — use this kickstart template for installation. Templates are rendered on the server, so check the custom-kickstarts section in Beaker's docs for the templating language and the available variables. You can also pass raw kickstarts — if you don't use any Jinja2 variable substitution syntax, the rendering process just reproduces your template verbatim. Wild but true.

And if your template contains this line:

## kernel_options: <options>

then those specified kernel options get appended to the ones you already defined with --kernel-options. Sneaky, love it 💅

🎀 Options for multi-host testing 🎀

  • --clients <number> — use number clients in the job.
  • --servers <number> — use number servers in the job.

📁 FILES 📁

On startup, bkr searches these locations, in this order, for its config:

~/.beaker_client/config

/etc/beaker/client.conf

🌈 ENVIRONMENT 🌈

These environment variables affect how bkr operates:

BEAKER_CLIENT_CONF

If set to a non-empty value, this overrides the usual configuration search paths. It has to be the full path to the configuration file — no shortcuts, no relative paths, full path only bestie 💖

👑 AUTHOR 👑

The Beaker team <beaker-devel@lists.fedorahosted.org>

2013-2025 Red Hat, Inc.

And that's the whole page, bestie! 🫶 This one's version 29.2, dated May 26, 2025 — go forth and submit jobs with main character energy 💅✨

📦 where this page comes from