blob: 11bc373b3c766839ad8d613b4c8719c49b510b7d [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
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:
Andrew Geisslerd1e89492021-02-12 15:35:20 -060027https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html
Andrew Geisslerc9f78652020-09-18 14:11:35 -050028
29Command: part or partition
30==========================
31
32Either of these commands creates a partition on the system and uses the
Andrew Geisslerc926e172021-05-07 16:11:35 -050033following syntax::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050034
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050035 part [mntpoint]
Andrew Geisslerc9f78652020-09-18 14:11:35 -050036 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
Andrew Geissler595f6302022-01-24 19:11:47 +000057 ``--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.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050060
61Here is an example that uses "/" as the mountpoint. The command uses
Andrew Geisslerc926e172021-05-07 16:11:35 -050062``--ondisk`` to force the partition onto the ``sdb`` disk::
Andrew Geissler4c19ea12020-10-27 13:52:24 -050063
64 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
Andrew Geisslerc9f78652020-09-18 14:11:35 -050065
66Here is a list that describes other supported options you can use with
67the ``part`` and ``partition`` commands:
68
Patrick Williams0ca19cc2021-08-16 14:03:13 -050069- ``--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``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050073
Patrick Williams0ca19cc2021-08-16 14:03:13 -050074- ``--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``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050080
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,
Andrew Geissler09209ee2020-12-13 08:44:15 -060085 see the ":ref:`dev-manual/common-tasks:using the wic plugin interface`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086 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
Andrew Geissler595f6302022-01-24 19:11:47 +000090 to by the ``-r`` command-line option or the equivalent root filesystem derived
Andrew Geisslerc9f78652020-09-18 14:11:35 -050091 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
Andrew Geissler595f6302022-01-24 19:11:47 +000099 the ``-r`` command-line option or the equivalent root filesystem derived from
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500100 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
Andrew Geissler09036742021-06-25 14:25:14 -0500114 - ``btrfs``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115
Andrew Geissler09036742021-06-25 14:25:14 -0500116 - ``erofs``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117
118 - ``ext2``
119
Andrew Geissler09036742021-06-25 14:25:14 -0500120 - ``ext3``
121
122 - ``ext4``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500123
124 - ``squashfs``
125
126 - ``swap``
127
Patrick Williams45852732022-04-02 08:58:32 -0500128 - ``vfat``
129
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500130- ``--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
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500144- ``--offset``: This option is a Wic-specific option that
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500145 says to place a partition at exactly the specified offset. If the
146 partition cannot be placed at the specified offset, the image build
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500147 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".
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500151
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500152- ``--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``
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500164 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".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168
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
Patrick Williams7784c422022-11-17 07:29:11 -0600180 :wikipedia:`GUID_Partition_Table#Partition_type_GUIDs`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181
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
Patrick Williams2390b1b2022-11-03 13:47:49 -0500214 various source plugins that implement bootloader functionality. The bootloader
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500215 command essentially provides a means of modifying bootloader
216 configuration.
217
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500218- ``--append``: Specifies kernel parameters. These parameters will be
Andrew Geissler5f350902021-07-23 13:09:54 -0400219 added to the syslinux :term:`APPEND` or ``grub`` kernel command line.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220
221- ``--configfile``: Specifies a user-defined configuration file for
222 the bootloader. You can provide a full pathname for the file or a
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700223 file located in the ``canned-wks`` folder. This option overrides
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500224 all other bootloader options.
Patrick Williams2390b1b2022-11-03 13:47:49 -0500225
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