10 OpenEmbedded Kickstart (.wks) Reference

10.1 Introduction

This chapter provides a reference on the available kickstart commands and variable expansion in kickstart files (.wks and .wks.in files). The information lists the commands, their syntax, and meanings. Kickstart commands are based on the Fedora kickstart versions but with modifications to reflect Wic capabilities. You can see the original documentation for those commands at the following link: https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html

10.2 Kickstart Files Location

Within a layer, a kickstart file should always be placed in the files/wic directory. For example, as of writing, the OpenEmbedded-Core (OE-Core) layer has the following files:

meta/files/wic
├── common.wks.inc
├── directdisk-bootloader-config.cfg
├── directdisk-bootloader-config.wks
├── directdisk-gpt.wks
├── directdisk-multi-rootfs.wks
├── directdisk.wks
├── efi-bootdisk.wks.in
├── efi-uki-bootdisk.wks.in
├── mkefidisk.wks
├── mkhybridiso.wks
├── qemuloongarch.wks
├── qemuriscv.wks
├── qemux86-directdisk.wks
├── sdimage-bootpart.wks
└── systemd-bootdisk.wks

Kickstart files within this directory can end with .wks and .wks.in (see the Kickstart Variable Expansion section for more details on the differences). Files ending with .inc are files included in kickstart files (see the Directive: include section), and the .cfg is a configuration file used by the bootloader command.

10.3 Kickstart Commands And Directives

10.3.1 Command: part

This command creates a partition on the system and uses the following syntax:

part [mntpoint]

If you do not provide mntpoint, Wic creates a partition but does not mount it.

The mntpoint is where the partition is mounted and must be in one of the following forms:

• /path: For example, “/”, “/usr”, or “/home”

• swap: The created partition is used as swap space

Specifying a mntpoint causes the partition to automatically be mounted. Wic achieves this by adding entries to the filesystem table (fstab) during image generation. In order for Wic to generate a valid fstab, you must also provide one of the --ondrive, --ondisk, or --use-uuid partition options as part of the command.

Note

The mount program must understand the PARTUUID syntax you use with --use-uuid and non-root mountpoint, including swap. The default configuration of BusyBox in OpenEmbedded supports this, but this may be disabled in custom configurations.

Here is an example that uses “/” as the mountpoint. The command uses --ondisk to force the partition onto the sdb disk:

part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024

Here is a list that describes other supported options you can use with the part command:

• --size: The minimum partition size. Specify as an integer value optionally followed by one of the units “k” / “K” for kibibyte, “M” for mebibyte and “G” for gibibyte. The default unit if none is given is “M”. You do not need this option if you use --source.

• --fixed-size: The exact partition size. Specify as an integer value optionally followed by one of the units “k” / “K” for kibibyte, “M” for mebibyte and “G” for gibibyte. The default unit if none is given is “M”. Cannot be specify together with --size. An error occurs when assembling the disk image if the partition data is larger than --fixed-size.

• --source: This option is a Wic-specific option that names the source of the data that populates the partition. The most common value for this option is “rootfs”, but you can use any value that maps to a valid source plugin. For information on the source plugins, see the “Using the Wic Plugin Interface” section in the Yocto Project Development Tasks Manual.

  If you use --source rootfs, Wic creates a partition as large as needed and fills it with the contents of the root filesystem pointed to by the -r command-line option or the equivalent root filesystem derived from the -e command-line option. The filesystem type used to create the partition is driven by the value of the --fstype option specified for the partition. See the entry on --fstype that follows for more information.

  If you use --source plugin-name, Wic creates a partition as large as needed and fills it with the contents of the partition that is generated by the specified plugin name using the data pointed to by the -r command-line option or the equivalent root filesystem derived from the -e command-line option. Exactly what those contents are and filesystem type used are dependent on the given plugin implementation.

  If you do not use the --source option, the wic command creates an empty partition. Consequently, you must use the --size option to specify the size of the empty partition.

• --ondisk or --ondrive: Forces the partition to be created on a particular disk.

• --fstype: Sets the file system type for the partition. Valid values are:

  • btrfs

  • erofs

  • ext2

  • ext3

  • ext4

  • squashfs

  • swap

  • vfat

• --fsoptions: Specifies a free-form string of options to be used when mounting the filesystem. This string is copied into the /etc/fstab file of the installed system and should be enclosed in quotes. If not specified, the default string is “defaults”.

• --label label: Specifies the label to give to the filesystem to be made on the partition. If the given label is already in use by another filesystem, a new label is created for the partition.

• --active: Marks the partition as active.

• --align (in KBytes): This option is a Wic-specific option that says to start partitions on boundaries given x KBytes.

• --offset: This option is a Wic-specific option that says to place a partition at exactly the specified offset. If the partition cannot be placed at the specified offset, the image build will fail. Specify as an integer value optionally followed by one of the units “s” / “S” for 512 byte sector, “k” / “K” for kibibyte, “M” for mebibyte and “G” for gibibyte. The default unit if none is given is “k”.

• --no-table: This option is a Wic-specific option. Using the option reserves space for the partition and causes it to become populated. However, the partition is not added to the partition table.

• --exclude-path: This option is a Wic-specific option that excludes the given relative path from the resulting image. This option is only effective with the rootfs source plugin.

• --extra-filesystem-space: This option is a Wic-specific option that adds extra space after the space filled by the content of the partition. The final size can exceed the size specified by the --size option. The default value is 10M. Specify as an integer value optionally followed by one of the units “k” / “K” for kibibyte, “M” for mebibyte and “G” for gibibyte. The default unit if none is given is “M”.

• --extra-partition-space: This option is a Wic-specific option that adds extra empty space after the space filled by the filesystem. With --fixed-size option, the extra partition space is removed from the filesystem size. Otherwise (with or without --size flag), the extra partition space is added to the final partition size. The default value is 0M. Specify as an integer value optionally followed by one of the units “k” / “K” for kibibyte, “M” for mebibyte and “G” for gibibyte. The default unit if none is given is “M”.

• --overhead-factor: This option is a Wic-specific option that multiplies the size of the partition by the option’s value. You must supply a value greater than or equal to “1”. The default value is “1.3”.

• --part-name: This option is a Wic-specific option that specifies a name for GPT partitions.

• --part-type: This option is a Wic-specific option that specifies the partition type globally unique identifier (GUID) for GPT partitions. You can find the list of partition type GUIDs at https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs.

• --use-uuid: This option is a Wic-specific option that causes Wic to generate a random GUID for the partition. The generated identifier is used in the bootloader configuration to specify the root partition.

• --uuid: This option is a Wic-specific option that specifies the partition UUID.

• --fsuuid: This option is a Wic-specific option that specifies the filesystem UUID. You can generate or modify WKS_FILE with this option if a preconfigured filesystem UUID is added to the kernel command line in the bootloader configuration before you run Wic.

• --system-id: This option is a Wic-specific option that specifies the partition system ID, which is a one byte long, hexadecimal parameter with or without the 0x prefix.

• --mkfs-extraopts: This option specifies additional options to pass to the mkfs utility. Some default options for certain filesystems do not take effect. See Wic’s help on kickstart (i.e. wic help kickstart).

10.3.2 Command: bootloader

This command specifies how the bootloader should be configured and supports the following options:

Note

Bootloader functionality and boot partitions are implemented by the various source plugins that implement bootloader functionality. The bootloader command essentially provides a means of modifying bootloader configuration.

• --append: Specifies kernel parameters. These parameters will be added to the syslinux APPEND or grub kernel command line.

• --configfile: Specifies a user-defined configuration file for the bootloader. You can provide a full pathname for the file or a file located in the files/wic folder. This option overrides all other bootloader options.

• --ptable: Specifies the partition table format. Valid values are:

  • msdos

  • gpt

• --timeout: Specifies the number of seconds before the bootloader times out and boots the default option.

10.3.3 Directive: include

The include directive can be used to include a WKS file into another. The only argument to this command is the path to the file to include, relative to the current file. For example:

include common.wks.inc

bootloader --configfile="directdisk-bootloader-config.cfg"

Warning

File inclusion is only supported for .wks files, not .wks.in. See the Kickstart Variable Expansion section below for more details on the differences between the two files.

10.4 Kickstart Variable Expansion

Kickstart files support two different file extensions and each has a different variable expansion mechanism:

• .wks: in this file format, only the variables listed in the WICVARS variable are expanded. These variables are expanded by the wic command-line utility, not BitBake. However, the syntax to reference these variables is the same. For example:

  Snippet from mkefidisk.wks

  bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=${KERNEL_CONSOLE} console=tty0"
  

  Here, the KERNEL_CONSOLE variable will be expanded, because it is in WICVARS.

  For any referenced variable that is not listed in WICVARS, a warning is emitted (by the wic command-line tool, not BitBake), and the ${...} string is left as-is.

  Note

  The wic command-line utility is a separate project (see https://git.yoctoproject.org/wic). It is for this reason that the wic tool supports expanding variables without BitBake, using its own mechanism.

• .wks.in: in this file format, variables are expanded by BitBake. This means that the WICVARS list has no effect anymore: those variables are expanded by BitBake directly. For example:

  Snippet from efi-uki-bootdisk.wks.in

  part /boot --source bootimg_efi --sourceparams="loader=${EFI_PROVIDER}" --label boot --active ...
  

  Here, the EFI_PROVIDER variable is expanded by BitBake.

  This also means that .wks.in files can contain inline Python expressions. Here is a made up example:

  part / --source rootfs --fstype=ext4 --label root --align ${@4 * 1024} --size 5G
  

  Here, since the ${@4 * 1024} expression is evaluated by BitBake, it will be expanded to 4096.

  For any referenced variable that is not defined in the environment, an empty string replaces the reference.

Here is a table that summarizes expansion results between .wks and .wks.in:

Reference	In WICVARS?	.wks (Wic expansion)	.wks.in (BitBake expansion)
${IMAGE_ROOTFS}	yes	/path/to/rootfs	/path/to/rootfs
${TMPDIR}	no	${TMPDIR}	/path/to/build/tmp
${@1024*2}	n/a	${@1024*2}	2048
${NOWHERE_DEFINED}	no	${NOWHERE_DEFINED}	(empty)

10.4.1 Expansion in Included Files

For files that are included with the include directive presented above, variable expansion is always done by wic’s own parser, using the WICVARS variable.