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