blob: 8308ffff5b72659ac13ec2577d2a17f322c8a042 [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 Geissler3b8a17c2021-04-15 15:55:55 -050057 ``--use-uuid`` and non-root *mountpoint*, including swap. The BusyBox
Andrew Geissler4c19ea12020-10-27 13:52:24 -050058 versions of these application are currently excluded.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059
60Here is an example that uses "/" as the mountpoint. The command uses
Andrew Geisslerc926e172021-05-07 16:11:35 -050061``--ondisk`` to force the partition onto the ``sdb`` disk::
Andrew Geissler4c19ea12020-10-27 13:52:24 -050062
63 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
Andrew Geisslerc9f78652020-09-18 14:11:35 -050064
65Here is a list that describes other supported options you can use with
66the ``part`` and ``partition`` commands:
67
68- ``--size``: The minimum partition size in MBytes. Specify an
69 integer value such as 500. Do not append the number with "MB". You do
70 not need this option if you use ``--source``.
71
72- ``--fixed-size``: The exact partition size in MBytes. You cannot
73 specify with ``--size``. An error occurs when assembling the disk
74 image if the partition data is larger than ``--fixed-size``.
75
76- ``--source``: This option is a Wic-specific option that names the
77 source of the data that populates the partition. The most common
78 value for this option is "rootfs", but you can use any value that
79 maps to a valid source plugin. For information on the source plugins,
Andrew Geissler09209ee2020-12-13 08:44:15 -060080 see the ":ref:`dev-manual/common-tasks:using the wic plugin interface`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050081 section in the Yocto Project Development Tasks Manual.
82
83 If you use ``--source rootfs``, Wic creates a partition as large as
84 needed and fills it with the contents of the root filesystem pointed
85 to by the ``-r`` command-line option or the equivalent rootfs derived
86 from the ``-e`` command-line option. The filesystem type used to
87 create the partition is driven by the value of the ``--fstype``
88 option specified for the partition. See the entry on ``--fstype``
89 that follows for more information.
90
91 If you use ``--source plugin-name``, Wic creates a partition as large
92 as needed and fills it with the contents of the partition that is
93 generated by the specified plugin name using the data pointed to by
94 the ``-r`` command-line option or the equivalent rootfs derived from
95 the ``-e`` command-line option. Exactly what those contents are and
96 filesystem type used are dependent on the given plugin
97 implementation.
98
99 If you do not use the ``--source`` option, the ``wic`` command
100 creates an empty partition. Consequently, you must use the ``--size``
101 option to specify the size of the empty partition.
102
103- ``--ondisk`` or ``--ondrive``: Forces the partition to be created
104 on a particular disk.
105
106- ``--fstype``: Sets the file system type for the partition. Valid
107 values are:
108
109 - ``ext4``
110
111 - ``ext3``
112
113 - ``ext2``
114
115 - ``btrfs``
116
117 - ``squashfs``
118
119 - ``swap``
120
121- ``--fsoptions``: Specifies a free-form string of options to be used
122 when mounting the filesystem. This string is copied into the
123 ``/etc/fstab`` file of the installed system and should be enclosed in
124 quotes. If not specified, the default string is "defaults".
125
126- ``--label label``: Specifies the label to give to the filesystem to
127 be made on the partition. If the given label is already in use by
128 another filesystem, a new label is created for the partition.
129
130- ``--active``: Marks the partition as active.
131
132- ``--align (in KBytes)``: This option is a Wic-specific option that
133 says to start partitions on boundaries given x KBytes.
134
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500135- ``--offset (in KBytes)``: This option is a Wic-specific option that
136 says to place a partition at exactly the specified offset. If the
137 partition cannot be placed at the specified offset, the image build
138 will fail.
139
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500140- ``--no-table``: This option is a Wic-specific option. Using the
141 option reserves space for the partition and causes it to become
142 populated. However, the partition is not added to the partition
143 table.
144
145- ``--exclude-path``: This option is a Wic-specific option that
146 excludes the given relative path from the resulting image. This
147 option is only effective with the rootfs source plugin.
148
149- ``--extra-space``: This option is a Wic-specific option that adds
150 extra space after the space filled by the content of the partition.
151 The final size can exceed the size specified by the ``--size``
152 option. The default value is 10 Mbytes.
153
154- ``--overhead-factor``: This option is a Wic-specific option that
155 multiplies the size of the partition by the option's value. You must
156 supply a value greater than or equal to "1". The default value is
157 "1.3".
158
159- ``--part-name``: This option is a Wic-specific option that
160 specifies a name for GPT partitions.
161
162- ``--part-type``: This option is a Wic-specific option that
163 specifies the partition type globally unique identifier (GUID) for
164 GPT partitions. You can find the list of partition type GUIDs at
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600165 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500166
167- ``--use-uuid``: This option is a Wic-specific option that causes
168 Wic to generate a random GUID for the partition. The generated
169 identifier is used in the bootloader configuration to specify the
170 root partition.
171
172- ``--uuid``: This option is a Wic-specific option that specifies the
173 partition UUID.
174
175- ``--fsuuid``: This option is a Wic-specific option that specifies
176 the filesystem UUID. You can generate or modify
177 :term:`WKS_FILE` with this option if a preconfigured
178 filesystem UUID is added to the kernel command line in the bootloader
179 configuration before you run Wic.
180
181- ``--system-id``: This option is a Wic-specific option that
182 specifies the partition system ID, which is a one byte long,
183 hexadecimal parameter with or without the 0x prefix.
184
185- ``--mkfs-extraopts``: This option specifies additional options to
186 pass to the ``mkfs`` utility. Some default options for certain
187 filesystems do not take effect. See Wic's help on kickstart (i.e.
188 ``wic help kickstart``).
189
190Command: bootloader
191===================
192
193This command specifies how the bootloader should be configured and
194supports the following options:
195
196.. note::
197
198 Bootloader functionality and boot partitions are implemented by the
199 various
200 --source
201 plugins that implement bootloader functionality. The bootloader
202 command essentially provides a means of modifying bootloader
203 configuration.
204
205- ``--timeout``: Specifies the number of seconds before the
206 bootloader times out and boots the default option.
207
208- ``--append``: Specifies kernel parameters. These parameters will be
209 added to the syslinux ``APPEND`` or ``grub`` kernel command line.
210
211- ``--configfile``: Specifies a user-defined configuration file for
212 the bootloader. You can provide a full pathname for the file or a
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700213 file located in the ``canned-wks`` folder. This option overrides
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500214 all other bootloader options.