Beaker provides a number of ways to customize the distro installation which happens at the start of each recipe.
In Beaker, install options are a set of three related argument strings in the form foo=bar baz=qux. Kernel options are passed on the kernel command line when the installer is booted. Post-install kernel options (labelled Kernel Options Post in the web UI) are set in the boot loader configuration, to be passed on the kernel command line after installation. Kickstart metadata variables are passed to the kickstart template engine, and can be used to control the content of the kickstart in various ways.
All three options can be set:
Beaker combines all the install options in the order listed above to determine the effective install options for each recipe. To unset an option of a previous setting, place ! before the option. For example, the following will remove the beaker default kernel option setting of ksdevice=bootif from a user’s job:
<recipe ... kernel_options="!ksdevice" ...>
Most kernel options are passed as-is on the kernel command line when the installer is booted. Refer to the distro documentation for details about kernel options supported by the installer.
The following kernel options are treated specially by Beaker:
This option is passed as-is on the kernel command line. It specifies the kickstart file for Anaconda.
Beaker performs no extra processing on this kernel option, however if it is present Beaker skips all of the normal mechanisms for kickstart generation using templates and variables (described below). The kickstart used for provisioning will be the one given in this option.
Extra initrd/initramfs image to load, in addition to the initrd image for the distro installer. Use this to apply updates to the installer image, or to supply additional drivers for installation.
If the boot loader supports multiple initrd images, Beaker extracts the initrd= option from the kernel command line and appends it to the boot loader configuration.
Alternate device tree binary to load. Use this to supply a different device tree binary than the one built into the kernel.
If the boot loader supports passing a device tree to the kernel (currently only GRUB for AArch64), Beaker extracts the devicetree= option from the kernel command line and appends it to the boot loader configuration.
Netboot loader image to use. Beaker creates a symlink so the TFTP path bootloader/fqdn/image serves the specified image.
Set this option if you want to boot an alternative image. For example, if the administrator has made an older version of PXELINUX available in the TFTP root as pxelinux-311.0, you can boot it using netbootloader=pxelinux-311.0.
By default Beaker uses the most suitable boot loader for the chosen distro and architecture:
For ppc64 and ppc64le, for Fedora, RHEL 7.1 and later:
and for RHEL 7.0 and earlier:
Note that this option will have no effect if the system has a hard-coded boot loader filename in the DHCP configuration. For configurable netboot loader support the DHCP configuration must specify the filename as bootloader/fqdn/image. See DHCP and DNS.
The following variables are supported and can be selected by placing them in the ks_meta attribute in the recipe element. In many cases, these variables correspond to the similarly-named kickstart option.
For example in the job XML:
...
<recipe kernel_options="" kernel_options_post="" ks_meta="harness=restraint hwclock_is_utc" role="None" whiteboard="Lab Controller">
...
Configure additional network devices to start on boot with DHCP activation. The device should be given as a kernel device name (for example, em1) or MAC address.
Note that the network device used for installation is always set to start on boot with DHCP activation.
If specified, runs the test harness and hence the tasks in a Docker container. The test harness to be run defaults to “restraint”. A different test harness can be specified using the harness variable. Also see contained_harness_entrypoint below.
The host distro and architecture must support Docker for this to be possible.
Specify how the harness should be started. This defaults to “/usr/sbin/init” and expects “systemd” to be the process manager. Alternatively, another binary can be specified. The entry point must be in one of the forms understood by Docker’s CMD instruction.
This is only required if the test harness is run in a Docker container. See contained_harness above.
Specify the host volumes to be mounted as read-only inside the container. The default volumes mounted as read-only are /var/log/messages, /etc/localtime and /etc/timezone.
For example, contained_harness_ro_host_volumes='/var/run,/etc' will then mount /var/run and /etc as read-only volumes.
Specify the host volumes to be mounted with write permissions inside the container. The default volumes with write permissions are /mnt and /root.
For example, harness_rw_host_volumes='/myvolume' will then only mount the /myvolume with write permissions.
Specify the test harness to use instead of the default test harness, “beah”. With the contained_harness variable specified, this defaults to “restraint”.
To learn more, see the Alternative Harness Guide.
If specified, uses this docker image to build the Docker container that the test runs in. The <image> is expected to be in a form usable in a Dockerfile’s FROM instruction. If contained_harness_entrypoint is not specified, the distro should use “systemd” as the process manager.
If not specified, Beaker will attempt to build the container by fetching the same image as that of the host distro from the Docker public registry. Thus, if Fedora 20 is used on the host machine, the image used will be: “registry.hub.docker.com/fedora:20”.
Options to be passed directly to the ignoredisk kickstart command. The complete option string must be given, including -- and =.
Use this to skip certain disks during the installation, for example ignoredisk=--drives=sdb,sdc, or to use only certain disks for the installation, for example ignoredisk=--only-use=sda,sdb.
If defined, Beaker will include the packages required by every task in the recipe. The packages will be populated in the kickstart %packages section, causing Anaconda to install them.
For Fedora 29 and RHEL8 and later versions, this variable is not defined by default. The default harness, Restraint, will install task requirements before executing each task.
This variable is defined by default for older distros, where the default harness is Beah. Beah does not install task requirements, instead it relies on the requirements being populated in %packages and installed by Anaconda.
Colon-separated list of package names to be installed during provisioning. If this variable is set, it replaces any packages defined by default in the kickstart templates. It also replaces any packages requested by the recipe, including task requirements.
In a recipe, considering using the <package/> element instead. This augments the package list instead of replacing it completely.
Configure one or more network devices to start on boot with static IPv4 addresses. The device should be given as a kernel device name (for example, em1) or MAC address. The IPv4 address should be given with its netmask in CIDR notation (for example, 192.168.99.1/24).
Note that the network device used for installation is always set to start on boot with DHCP activation.
Extra command-line options which will be passed to all invocations of yum install which Beaker produces in the generated kickstart.
On RHEL3 and RHEL4 this variable defaults to “-d 1” which inhibits Yum’s progress bar made up of hashes which can take a long time to print. On newer releases, where Yum’s progress bar produces less output, this variable is undefined.
The following kickstart metadata variables are used to test for installer or distro features. Beaker populates these variables automatically by inspecting the distro name and version. They can be overridden if necessary for custom distros.
Indicates that the installer is capable of formatting disks using GPT on x86 systems with BIOS firmware.
This support is needed for disks larger than 2TB and it requires an extra “BIOS boot” partition to be defined.
If specified, Beaker assumes that the specified distribution is rpm-ostree based (an Atomic host, for example). The test harness is run inside a Docker container and the tests are run inside it instead of the host system. The OSTree location and ref must be specified using ostree_repo_url and ostree_ref respectively.
Also, see harness_docker_base_image and contained_harness_entrypoint above.
In your job XML you can specify extra content to be appended to the generated kickstart, using the <ks_appends/> element. For example:
<recipe>
...
<ks_appends>
<ks_append><![CDATA[
%post
echo "This is my extra %post script"
%end
]]></ks_append>
</ks_appends>
</recipe>
You can also specify a complete kickstart template in your job XML, using the <kickstart/> element. Note that if a custom template is supplied, the other customization mechanisms described above (ksmeta= and <ks_appends/>) will have no effect, unless the custom template also obeys those customizations.
Beaker’s kickstart templates are written in the Jinja2 templating language. Refer to the Jinja2 documentation for details of the template syntax and built-in constructs which are available to all templates.
All kickstart metadata variables are available to the kickstart template. That includes variables set on the recipe, the system, the distro, the OS major, and system-wide in the Beaker configuration. It also includes distro feature variables (see Distro features above) which are particularly useful in kickstart templates for handling differences between distros and versions.
A number of additional Beaker-specific Jinja filters, tests, and variables are defined in the template environment. They are described below.
Returns a dict based on a sequence of key-value pairs encoded in a string, like this:
type:mdraid,part:swap,size:256
Parses a URL using urlparse.urlparse().
Quotes a string using pipes.quote(), suitable for interpolation as an argument into a shell command.
Splits on whitespace, or the given delimiter. See string.split().
Resolves a relative URL against a base URL. For example:
{{ 'http://example.com/distros/'|urljoin('RHEL-6.2/') }}
will evaluate to http://example.com/distros/RHEL-6.2/ in the kickstart.
Tests whether a distro tree’s arch matches any of the given arches. For example:
{% if distro_tree is arch('i386', 'x86_64') %}
Tests whether a distro matches any of the given OS major names. For example:
{% if distro is osmajor('CentOS6', 'RedHatEnterpriseLinux6') %}
In most cases it is preferable to use a distro feature variable rather than hard-coding all possible OS major names.
Tests whether a distro matches any of the given OS versions. For example:
{% if distro is osversion('CentOS6.0', 'RedHatEnterpriseLinux6.0') %}
A function which returns the absolute URL to the given path within the Beaker application. kwargs are converted to query parameters.
The distro which is being provisioned. This object has the following attributes:
The distro tree which is being provisioned. This object has the following attributes:
Repository used to download harness RPMs from. For example:
{% if harnessrepo %}
{% set repo_name, repo_url = harnessrepo.split(',', 1) %}
repo --name={{ repo_name }} --baseurl={{ repo_url }}
{% endif %}
The value of the job whiteboard.
Post-install kernel options from the install options.
List of string containing extra kickstart content supplied by the job submitter in the <ks_appends/> element.
The lab controller where the system is being provisioned.
The recipe to be run on the provisioned system. This object has the following attributes:
The value of the recipe whiteboard.
A function which evaluates the named snippet and returns the result. If no template is found for the snippet, returns a comment to that effect.
This is also available as a Jinja statement, for example:
{% snippet 'network' %}
Repository used to download tasks RPMs from. This is independent for each job. For example:
{% if taskrepo %}
{% set repo_name, repo_url = taskrepo.split(',', 1) %}
repo --name={{ repo_name }} --baseurl={{ repo_url }}
{% endif %}
A function which returns the value of the template variable with the given name.