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
157 allows 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
159 abbreviations, 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
189 untrusted 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
205 behalf.
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
268 select 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
277 Machine which is almost always what you want. Other supported
278 values 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
318 order. The files contain one filter definition per line, con‐
319 sisting of the filter name and the associated XML snippet sepa‐
320 rated by whitespace. If the same filter name appears in multi‐
321 ple 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 (or the previous implementation /distribu‐
366 tion/install on RHEL7 and older). The purpose of this task is to
367 check that the operating system was installed successfully and
368 report back on any potential problems, and to collect informa‐
369 tion about the installed system for debugging.
370 Pass this option if you do not want this task to be implicitly
372 inserted at the start of the recipe.
373 Options for job configuration:
375 --job-owner <username>
377 Submit the job on behalf of <username>. The job will be owned by
378 <username> rather than the submitting user.
379 The submitting user must be a submission delegate of <username>.
381 Users can add other users as submission delegates on their Pref‐
382 erences page in Beaker's web UI.
383 --job-group <group>
385 Associate the job with <group>. This will allow other group mem‐
386 bers to modify the job.
387 --whiteboard <whiteboard>
389 Set the job's whiteboard to <whiteboard>.
390 --taskparam <name>=<value>
392 Sets parameter <name> to <value> for all tasks in the job.
393 New in version 0.14.3.
395 --ignore-panic
398 Disable kernel panic detection and install failure detection for
399 the recipe. By default if a kernel panic appears on the serial
400 console, or a fatal installer error appears during installation,
401 the recipe is aborted. When this option is given, the messages
402 are ignored and the recipe is not aborted.
403 --reserve
405 Reserve the system at the end of the recipe, for further testing
406 or examination. The system will be reserved when all tasks have
407 completed executing, or if the recipe ends abnormally. Refer to
408 reservesys.
409 --reserve-duration <seconds>
411 When --reserve is used, this option controls the duration for
412 the reservation. The default duration is 86400 seconds (24
413 hours).
414 --cc <email>
416 Add <email> to the cc list for the job(s). The cc list will
417 receive the job completion notification. This option may be
418 specified multiple times.
419 --priority <priority>
421 Set job priority to <priority>. Can be Low, Medium, Normal,
422 High, or Urgent. The default is Normal.
423 --retention-tag <tag>
425 Specify data retention policy for this job [default: Scratch]
426 --product <product>
428 Associate job with <product> for data retention purposes.
429 Options for installation:
431 --method <method>
433 Installation source method (nfs, http, ftp) [default: nfs].
434 --kernel-options <opts>
436 Pass additional kernel options for during installation. The
437 options string is applied on top of any install-time kernel
438 options which are set by default for the chosen system and dis‐
439 tro.
440 --kernel-options-post <opts>
442 Pass additional kernel options for after installation. The
443 options string is applied on top of any post-install kernel
444 options which are set by default for the chosen system and dis‐
445 tro.
446 --ks-append <commands>
448 Specify additional kickstart commands to add to the base kick‐
449 start file.
450 --ks-meta <options>
452 Pass kickstart metadata <options> when generating kickstart.
453 --repo <url>
455 Make the yum repository at <url> available during initial
456 installation of the system and afterwards. This option may be
457 specified multiple times. The installation may fail if the repo
458 is not actually available.
459 --repo-post <url>
461 Make the yum repository at <url> available AFTER the installa‐
462 tion. This option may be specified multiple times. The repo con‐
463 fig will be appended to the kickstart's %post section. Whether
464 or not the installation succeeds is not affected by the avail‐
465 ability of the repo.
466 --kickstart <filename>
468 Use this kickstart template for installation. Templates are ren‐
469 dered on the server. Refer to the custom-kickstarts section in
470 Beaker's documentation for details about the templating language
471 and available variables. You can also pass raw kickstarts in -
472 if you don't use any Jinja2 variable substitution syntax, the
473 rendering process will reproduce the template verbatim.
474 If the template provides the following line:
476 ## kernel_options: <options>
478 the specified kernel options will be appended to existing ones
480 defined with --kernel-options.
481 Options for multi-host testing:
483 --clients <number>
485 Use <number> clients in the job.
486 --servers <number>
488 Use <number> servers in the job.
489
491 On startup bkr searches the following locations in order for its con‐
492 fig:
493 ~/.beaker_client/config
494 /etc/beaker/client.conf
496
498 The following environment variables affect the operation of bkr.
499 BEAKER_CLIENT_CONF
501 If set to a non-empty value, this overrides the usual configura‐
502 tion search paths. This must be the full path to the configura‐
503 tion file.
504
506 The Beaker team <beaker-devel@lists.fedorahosted.org>
507
509 2013-2020 Red Hat, Inc.
51027.4 Mar 30, 2020 BKR(1)