1BKR(1) Beaker BKR(1)
2
6 bkr - Beaker client
7
9 bkr <subcommand> [options] ...
10
12 Provides a scriptable command-line interface to the Beaker server.
13 The following subcommands are supported. Each subcommand is documented
15 in its own man page. This man page is reserved for common options and
16 features.
17 orphan
19 Subcommands
21 • bkr-distro-trees-list(1) -- List Beaker distro trees
22 • bkr-distro-trees-verify(1) -- Check Beaker distro trees for problems
24 • bkr-distros-edit-version(1) -- Edit the version of Beaker distros
26 • bkr-distros-list(1) -- List Beaker distros
28 • bkr-distros-tag(1) -- Tag Beaker distros
30 • bkr-distros-untag(1) -- Untag Beaker distros
32 • bkr-group-create(1) -- Create a group
34 • bkr-group-list(1) -- List groups
36 • bkr-group-members(1) -- List members of a group
38 • bkr-group-modify(1) -- Modify a group
40 • bkr-harness-test(1) -- Generate Beaker job to test harness installa‐
42 tion
43 • bkr-job-cancel(1) -- Cancel running Beaker jobs
45 • bkr-job-clone(1) -- Clone existing Beaker jobs
47 • bkr-job-comment(1) -- Add a comment to a job
49 • bkr-job-delete(1) -- Delete Beaker jobs
51 • bkr-job-list(1) -- List Beaker jobs
53 • bkr-job-logs(1) -- Print URLs of Beaker recipe log files
55 • bkr-job-modify(1) -- Modify Beaker jobs
57 • bkr-job-results(1) -- Export Beaker job results as XML
59 • bkr-job-submit(1) -- Submit job XML to Beaker
61 • bkr-job-watch(1) -- Watch the progress of a Beaker job
63 • bkr-labcontroller-create(1) -- Create a new lab controller
65 • bkr-labcontroller-list(1) -- List Beaker lab controllers
67 • bkr-labcontroller-modify(1) -- Modify a lab controller
69 • bkr-list-labcontrollers(1) --
71 • bkr-list-systems(1) --
73 • bkr-loan-grant(1) -- Grant a loan for a Beaker system
75 • bkr-loan-return(1) -- Return a current Beaker system loan
77 • bkr-machine-test(1) -- Generate Beaker job to test a system
79 • bkr-policy-grant(1) -- Grant permissions in an access policy
81 • bkr-policy-list(1) -- Lists access policy rules for a system
83 • bkr-policy-revoke(1) -- Revoke permissions in an access policy
85 • bkr-pool-add(1) -- Add systems to a system pool
87 • bkr-pool-create(1) -- Create a system pool
89 • bkr-pool-delete(1) -- Delete a system pool
91 • bkr-pool-list(1) -- List system pools
93 • bkr-pool-modify(1) -- Modify a system pool
95 • bkr-pool-remove(1) -- Remove systems from a pool
97 • bkr-pool-systems(1) -- List systems in a pool
99 • bkr-remove-account(1) -- Remove user accounts
101 • bkr-system-create(1) -- Create a system
103 • bkr-system-delete(1) -- Delete a Beaker system permanently
105 • bkr-system-details(1) -- Export RDF/XML description of a Beaker sys‐
107 tem
108 • bkr-system-history-list(1) -- Export history of activity for the
110 given system
111 • bkr-system-list(1) -- List Beaker systems
113 • bkr-system-modify(1) -- Modify system attributes
115 • bkr-system-power(1) -- Control power for a Beaker system
117 • bkr-system-provision(1) -- Provision a Beaker system
119 • bkr-system-release(1) -- Release a reserved Beaker system
121 • bkr-system-reserve(1) -- Manually reserve a Beaker system
123 • bkr-system-status(1) -- Return the current status of a system
125 • bkr-task-add(1) -- Upload tasks to Beaker's task library
127 • bkr-task-delete(1) -- Delete tasks to Beaker's task library
129 • bkr-task-details(1) -- Export details of a Beaker task
131 • bkr-task-list(1) -- List tasks in Beaker's task library
133 • bkr-update-inventory(1) -- Submits a inventory job for the system
135 • bkr-update-openstack-trust(1) -- Update OpenStack Keystone trust
137 • bkr-update-prefs(1) -- Update user preferences
139 • bkr-user-modify(1) -- Modify Beaker users
141 • bkr-watchdog-extend(1) -- Extend Beaker watchdog time
143 • bkr-watchdog-show(1) -- Show time remaining on Beaker watchdogs
145 • bkr-watchdogs-extend(1) -- Extend Beaker watchdogs time
147 • bkr-whoami(1) -- Show your Beaker username
149 • bkr-workflow-installer-test(1) -- DEPRECATED workflow to generate a
151 kickstart for testing Anaconda
152 • bkr-workflow-simple(1) -- Simple workflow to generate Beaker jobs
154 Specifying tasks
156 Some bkr subcommands accept one or more <taskspec> arguments. This al‐
157 lows the user to identify a job, or any subcomponent of a job, by its
158 id. The format is <type>:<id> where <type> is one of the following ab‐
159 breviations, in descending hierarchical order:
160 J job
162 RS recipe set
164 R recipe
166 T recipe-task
168 TR task-result
170 For example, J:123 might contain RS:456, which might contain R:789,
172 which might contain T:1234 and T:5678.
173 This format is also used in the Beaker web UI to identify jobs and
175 their subcomponents.
176
178 Common options
179 These options are applicable to all bkr subcommands.
180 --hub <url>
182 Connect to the Beaker server at the given URL. This overrides
183 the HUB_URL setting from the configuration file. The URL should
184 not include a trailing slash.
185 --insecure
187 Skip all SSL certificate validity checks. This allows the client
188 to connect to a Beaker server with an invalid, expired, or un‐
189 trusted SSL certificate.
190 --username <username>
192 Authenticate using password authentication, with <username>. If
193 a password is not given using --password, the user is prompted
194 for the password on stdin.
195 This option overrides the authentication type specified in the
197 configuration file, forcing password authentication to be used.
198 --password <password>
200 Authenticate using <password>. This option is only applicable
201 when --username is also passed.
202 --proxy-user <username>
204 Impersonate <username> in order to perform actions on their be‐
205 half.
206 This option can only be used when the authenticating user is a
208 member of a group which has been granted 'proxy_user' permission
209 by the Beaker administrator. Typically this permission is
210 granted to service accounts so that a trusted script can perform
211 actions on behalf of any other Beaker user.
212 --help Show a brief summary of the command and its available options
214 then exit.
215 Workflow options
217 These options are applicable to bkr workflow subcommands, such as bkr
218 workflow-simple.
219 --dry-run, --dryrun
221 Don't submit the job(s) to Beaker.
222 --debug
224 Print the generated job XML before submitting it to Beaker.
225 --pretty-xml, --prettyxml
227 Pretty-print the generated job XML in a human-readable form
228 (with indentation and line breaks).
229 --wait Watch the newly submitted job(s) for state changes and print
231 them to stdout. The command will not exit until all submitted
232 jobs have finished. See bkr-job-watch(1).
233 --no-wait, --nowait
235 Do not wait on job completion [default].
236 --quiet
238 Be quiet, don't print warnings.
239 Options for selecting distro tree(s):
241 --family <family>
243 Run the job with the latest distro in <family> (for example:
244 RedHatEnterpriseLinux6).
245 --tag <tag>
247 Run the job with the latest distro tagged with <tag>. Combine
248 this with --family. By default the STABLE tag is used.
249 --distro <name>
251 Run the job with distro named <name>. If the given name includes
252 a % character, it is interpreted as a SQL LIKE pattern (the %
253 character matches any substring).
254 --variant <variant>
256 Run the job with distro variant <variant>, for example Server.
257 Combine this with --family.
258 --arch <arch>
260 Use only <arch> in job. By default, a recipe set is generated
261 for each arch supported by the selected distro. This option may
262 be specified multiple times.
263 Options for selecting system(s):
265 --machine <fqdn>
267 Run the job on system with <fqdn>. This option will always se‐
268 lect a single system, and so does not make sense combined with
269 any other system options.
270 --ignore-system-status
272 Always use the system given by --machine, regardless of its sta‐
273 tus.
274 --systype <type>
276 Run the job on system(s) of type <type>. This defaults to Ma‐
277 chine which is almost always what you want. Other supported val‐
278 ues are Laptop, Prototype and Resource. Laptop type would be
279 used to select a system from the available laptop computers.
280 Similarly, Resource and Prototype would be used in cases where
281 you would want to schedule your job against a system whose type
282 has been set as such.
283 --hostrequire "<tag> <operator> <value>"
285 Additional <hostRequires/> for the job. For example, labcon‐
286 troller=lab.example.com would become <labcontroller op="="
287 value="lab.example.com"/> in the job XML.
288 For more advanced filtering (for example using <device/>) you
290 can also pass raw XML directly to this option. Any value start‐
291 ing with < is parsed as XML and inserted directly into <hostRe‐
292 quires/>.
293 See Job XML for more information about the <hostRequires/> ele‐
295 ment.
296 --host-filter <name>
298 Look up the pre-defined host filter with the given name,and add
299 the corresponding XML snippet to <hostRequires/>.
300 You can use pre-defined host filters as a short-hand for compli‐
302 cated or difficult to remember XML snippets. Beaker includes
303 many pre-defined filters for different types of hardware. For
304 example, pass --host-filter=INTEL__FAM15_CELERON to filter for
305 hosts with an Intel Celeron CPU.
306 Filter definitions are read from the following configuration
308 files:
309 • /usr/lib/python2.x/site-packages/bkr/client/host-fil‐
311 ters/*.conf
312 • /etc/beaker/host-filters/*.conf
314 • ~/.beaker_client/host-filter
316 Files within each directory are processed in lexicographical or‐
318 der. The files contain one filter definition per line, consist‐
319 ing of the filter name and the associated XML snippet separated
320 by whitespace. If the same filter name appears in multiple
321 files, the last definition overrides earlier definitions.
322 --keyvalue "<name> <operator> <value>"
324 Run the job on system(s) which have the key <name> set to
325 <value> (for example: NETWORK=e1000).
326 --random
328 Select a system at random. The systems owned by the user are
329 first checked for availability, followed by the systems owned by
330 the user's group and finally all other systems.
331 Options for selecting tasks:
333 --task <task>
335 Include <task> in the job. This option may be specified multiple
336 times.
337 --taskfile <filename>
339 Include tasks listed in <filename>, each line contains one task
340 name. Lines not starting with '/' are ignored.
341 --package <package>
343 Include tests for <package> in the job. This option may be spec‐
344 ified multiple times.
345 --task-type <type>
347 Include tasks of type <type> in the job. This option may be
348 specified multiple times.
349 --install <package>
351 Install additional package <package> after provisioning. This
352 uses the /distribution/pkginstall task. This option may be spec‐
353 ified multiple times.
354 --kdump
356 Enable kdump using using /kernel/networking/kdump.
357 --ndump
359 Enable ndnc using using /kernel/networking/ndnc.
360 --suppress-install-task
362 Omit the installation checking task.
363 By default, the first task in the recipe will be /distribu‐
365 tion/check-install. The purpose of this task is to check that
366 the operating system was installed successfully and report back
367 on any potential problems, and to collect information about the
368 installed system for debugging.
369 Pass this option if you do not want this task to be implicitly
371 inserted at the start of the recipe.
372 Options for job configuration:
374 --job-owner <username>
376 Submit the job on behalf of <username>. The job will be owned by
377 <username> rather than the submitting user.
378 The submitting user must be a submission delegate of <username>.
380 Users can add other users as submission delegates on their Pref‐
381 erences page in Beaker's web UI.
382 --job-group <group>
384 Associate the job with <group>. This will allow other group mem‐
385 bers to modify the job.
386 --whiteboard <whiteboard>
388 Set the job's whiteboard to <whiteboard>.
389 --taskparam <name>=<value>
391 Sets parameter <name> to <value> for all tasks in the job.
392 New in version 0.14.3.
394 --ignore-panic
397 Disable kernel panic detection and install failure detection for
398 the recipe. By default if a kernel panic appears on the serial
399 console, or a fatal installer error appears during installation,
400 the recipe is aborted. When this option is given, the messages
401 are ignored and the recipe is not aborted.
402 --reserve
404 Reserve the system at the end of the recipe, for further testing
405 or examination. The system will be reserved when all tasks have
406 completed executing, or if the recipe ends abnormally. Refer to
407 Using the <reservesys/> element.
408 --reserve-duration <seconds>
410 When --reserve is used, this option controls the duration for
411 the reservation. The default duration is 86400 seconds (24
412 hours).
413 --cc <email>
415 Add <email> to the cc list for the job(s). The cc list will re‐
416 ceive the job completion notification. This option may be speci‐
417 fied multiple times.
418 --priority <priority>
420 Set job priority to <priority>. Can be Low, Medium, Normal,
421 High, or Urgent. The default is Normal.
422 --retention-tag <tag>
424 Specify data retention policy for this job [default: Scratch]
425 --product <product>
427 Associate job with <product> for data retention purposes.
428 Options for installation:
430 --method <method>
432 Installation source method (nfs, http, ftp) [default: nfs].
433 --kernel-options <opts>
435 Pass additional kernel options for during installation. The op‐
436 tions string is applied on top of any install-time kernel op‐
437 tions which are set by default for the chosen system and distro.
438 --kernel-options-post <opts>
440 Pass additional kernel options for after installation. The op‐
441 tions string is applied on top of any post-install kernel op‐
442 tions which are set by default for the chosen system and distro.
443 --ks-append <commands>
445 Specify additional kickstart commands to add to the base kick‐
446 start file.
447 --ks-meta <options>
449 Pass kickstart metadata <options> when generating kickstart.
450 --repo <url>
452 Make the yum repository at <url> available during initial in‐
453 stallation of the system and afterwards. This option may be
454 specified multiple times. The installation may fail if the repo
455 is not actually available.
456 --repo-post <url>
458 Make the yum repository at <url> available AFTER the installa‐
459 tion. This option may be specified multiple times. The repo con‐
460 fig will be appended to the kickstart's %post section. Whether
461 or not the installation succeeds is not affected by the avail‐
462 ability of the repo.
463 --kickstart <filename>
465 Use this kickstart template for installation. Templates are ren‐
466 dered on the server. Refer to the Custom kickstart templates
467 section in Beaker's documentation for details about the templat‐
468 ing language and available variables. You can also pass raw
469 kickstarts in - if you don't use any Jinja2 variable substitu‐
470 tion syntax, the rendering process will reproduce the template
471 verbatim.
472 If the template provides the following line:
474 ## kernel_options: <options>
476 the specified kernel options will be appended to existing ones
478 defined with --kernel-options.
479 Options for multi-host testing:
481 --clients <number>
483 Use <number> clients in the job.
484 --servers <number>
486 Use <number> servers in the job.
487
489 On startup bkr searches the following locations in order for its con‐
490 fig:
491 ~/.beaker_client/config
492 /etc/beaker/client.conf
494
496 The following environment variables affect the operation of bkr.
497 BEAKER_CLIENT_CONF
499 If set to a non-empty value, this overrides the usual configura‐
500 tion search paths. This must be the full path to the configura‐
501 tion file.
502
504 The Beaker team <beaker-devel@lists.fedorahosted.org>
505
507 2013-2023 Red Hat, Inc.
50828.3 Nov 17, 2023 BKR(1)