1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3*******************************************
4OpenEmbedded Kickstart (``.wks``) Reference
5*******************************************
6
7.. _openembedded-kickstart-wks-reference:
8
9Introduction
10============
11
12The current Wic implementation supports only the basic kickstart
13partitioning commands: ``partition`` (or ``part`` for short) and
14``bootloader``.
15
16.. note::
17
18   Future updates will implement more commands and options. If you use
19   anything that is not specifically supported, results can be
20   unpredictable.
21
22This chapter provides a reference on the available kickstart commands.
23The information lists the commands, their syntax, and meanings.
24Kickstart commands are based on the Fedora kickstart versions but with
25modifications to reflect Wic capabilities. You can see the original
26documentation for those commands at the following link:
27https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html
28
29Command: part or partition
30==========================
31
32Either of these commands creates a partition on the system and uses the
33following syntax::
34
35   part [mntpoint]
36   partition [mntpoint]
37
38If you do not
39provide mntpoint, Wic creates a partition but does not mount it.
40
41The ``mntpoint`` is where the partition is mounted and must be in one of
42the following forms:
43
44-  ``/path``: For example, "/", "/usr", or "/home"
45
46-  ``swap``: The created partition is used as swap space
47
48Specifying a mntpoint causes the partition to automatically be mounted.
49Wic achieves this by adding entries to the filesystem table (fstab)
50during image generation. In order for Wic to generate a valid fstab, you
51must also provide one of the ``--ondrive``, ``--ondisk``, or
52``--use-uuid`` partition options as part of the command.
53
54.. note::
55
56   The mount program must understand the PARTUUID syntax you use with
57   ``--use-uuid`` and non-root *mountpoint*, including swap. The default
58   configuration of BusyBox in OpenEmbedded supports this, but this may
59   be disabled in custom configurations.
60
61Here is an example that uses "/" as the mountpoint. The command uses
62``--ondisk`` to force the partition onto the ``sdb`` disk::
63
64      part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
65
66Here is a list that describes other supported options you can use with
67the ``part`` and ``partition`` commands:
68
69-  ``--size``: The minimum partition size. Specify as an integer value
70   optionally followed by one of the units "k" / "K" for kibibyte,
71   "M" for mebibyte and "G" for gibibyte. The default unit if none is
72   given is "M". You do not need this option if you use ``--source``.
73
74-  ``--fixed-size``: The exact partition size. Specify as an integer
75   value optionally followed by one of the units "k" / "K" for kibibyte,
76   "M" for mebibyte and "G" for gibibyte. The default unit if none is
77   given is "M".  Cannot be specify together with ``--size``. An error
78   occurs when assembling the disk image if the partition data is larger
79   than ``--fixed-size``.
80
81-  ``--source``: This option is a Wic-specific option that names the
82   source of the data that populates the partition. The most common
83   value for this option is "rootfs", but you can use any value that
84   maps to a valid source plugin. For information on the source plugins,
85   see the ":ref:`dev-manual/wic:using the wic plugin interface`"
86   section in the Yocto Project Development Tasks Manual.
87
88   If you use ``--source rootfs``, Wic creates a partition as large as
89   needed and fills it with the contents of the root filesystem pointed
90   to by the ``-r`` command-line option or the equivalent root filesystem derived
91   from the ``-e`` command-line option. The filesystem type used to
92   create the partition is driven by the value of the ``--fstype``
93   option specified for the partition. See the entry on ``--fstype``
94   that follows for more information.
95
96   If you use ``--source plugin-name``, Wic creates a partition as large
97   as needed and fills it with the contents of the partition that is
98   generated by the specified plugin name using the data pointed to by
99   the ``-r`` command-line option or the equivalent root filesystem derived from
100   the ``-e`` command-line option. Exactly what those contents are and
101   filesystem type used are dependent on the given plugin
102   implementation.
103
104   If you do not use the ``--source`` option, the ``wic`` command
105   creates an empty partition. Consequently, you must use the ``--size``
106   option to specify the size of the empty partition.
107
108-  ``--ondisk`` or ``--ondrive``: Forces the partition to be created
109   on a particular disk.
110
111-  ``--fstype``: Sets the file system type for the partition. Valid
112   values are:
113
114   -  ``btrfs``
115
116   -  ``erofs``
117
118   -  ``ext2``
119
120   -  ``ext3``
121
122   -  ``ext4``
123
124   -  ``squashfs``
125
126   -  ``swap``
127
128   -  ``vfat``
129
130-  ``--fsoptions``: Specifies a free-form string of options to be used
131   when mounting the filesystem. This string is copied into the
132   ``/etc/fstab`` file of the installed system and should be enclosed in
133   quotes. If not specified, the default string is "defaults".
134
135-  ``--label label``: Specifies the label to give to the filesystem to
136   be made on the partition. If the given label is already in use by
137   another filesystem, a new label is created for the partition.
138
139-  ``--active``: Marks the partition as active.
140
141-  ``--align (in KBytes)``: This option is a Wic-specific option that
142   says to start partitions on boundaries given x KBytes.
143
144-  ``--offset``: This option is a Wic-specific option that
145   says to place a partition at exactly the specified offset. If the
146   partition cannot be placed at the specified offset, the image build
147   will fail. Specify as an integer value optionally followed by one of
148   the units "s" / "S" for 512 byte sector, "k" / "K" for kibibyte, "M"
149   for mebibyte and "G" for gibibyte. The default unit if none is given
150   is "k".
151
152-  ``--no-table``: This option is a Wic-specific option. Using the
153   option reserves space for the partition and causes it to become
154   populated. However, the partition is not added to the partition
155   table.
156
157-  ``--exclude-path``: This option is a Wic-specific option that
158   excludes the given relative path from the resulting image. This
159   option is only effective with the rootfs source plugin.
160
161-  ``--extra-space``: This option is a Wic-specific option that adds
162   extra space after the space filled by the content of the partition.
163   The final size can exceed the size specified by the ``--size``
164   option. The default value is 10M. Specify as an integer value
165   optionally followed by one of the units "k" / "K" for kibibyte, "M"
166   for mebibyte and "G" for gibibyte. The default unit if none is given
167   is "M".
168
169-  ``--overhead-factor``: This option is a Wic-specific option that
170   multiplies the size of the partition by the option's value. You must
171   supply a value greater than or equal to "1". The default value is
172   "1.3".
173
174-  ``--part-name``: This option is a Wic-specific option that
175   specifies a name for GPT partitions.
176
177-  ``--part-type``: This option is a Wic-specific option that
178   specifies the partition type globally unique identifier (GUID) for
179   GPT partitions. You can find the list of partition type GUIDs at
180   :wikipedia:`GUID_Partition_Table#Partition_type_GUIDs`.
181
182-  ``--use-uuid``: This option is a Wic-specific option that causes
183   Wic to generate a random GUID for the partition. The generated
184   identifier is used in the bootloader configuration to specify the
185   root partition.
186
187-  ``--uuid``: This option is a Wic-specific option that specifies the
188   partition UUID.
189
190-  ``--fsuuid``: This option is a Wic-specific option that specifies
191   the filesystem UUID. You can generate or modify
192   :term:`WKS_FILE` with this option if a preconfigured
193   filesystem UUID is added to the kernel command line in the bootloader
194   configuration before you run Wic.
195
196-  ``--system-id``: This option is a Wic-specific option that
197   specifies the partition system ID, which is a one byte long,
198   hexadecimal parameter with or without the 0x prefix.
199
200-  ``--mkfs-extraopts``: This option specifies additional options to
201   pass to the ``mkfs`` utility. Some default options for certain
202   filesystems do not take effect. See Wic's help on kickstart (i.e.
203   ``wic help kickstart``).
204
205Command: bootloader
206===================
207
208This command specifies how the bootloader should be configured and
209supports the following options:
210
211.. note::
212
213   Bootloader functionality and boot partitions are implemented by the
214   various source plugins that implement bootloader functionality. The bootloader
215   command essentially provides a means of modifying bootloader
216   configuration.
217
218-  ``--append``: Specifies kernel parameters. These parameters will be
219   added to the syslinux :term:`APPEND` or ``grub`` kernel command line.
220
221-  ``--configfile``: Specifies a user-defined configuration file for
222   the bootloader. You can provide a full pathname for the file or a
223   file located in the ``canned-wks`` folder. This option overrides
224   all other bootloader options.
225
226-  ``--ptable``: Specifies the partition table format. Valid values are:
227
228   -  ``msdos``
229
230   -  ``gpt``
231
232-  ``--timeout``: Specifies the number of seconds before the
233   bootloader times out and boots the default option.
234
235