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