blob: 1128bd50d08c8c696b0ce8cb10517c69b900e9c6 [file] [log] [blame]
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-kickstart'>
6<title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title>
7
8 <section id='openembedded-kickstart-wks-reference'>
9 <title>Introduction</title>
10
11 <para>
12 The current Wic implementation supports only the basic kickstart
13 partitioning commands:
14 <filename>partition</filename> (or <filename>part</filename>
15 for short) and <filename>bootloader</filename>.
16 <note>
17 Future updates will implement more commands and options.
18 If you use anything that is not specifically supported, results
19 can be unpredictable.
20 </note>
21 </para>
22
23 <para>
24 This chapter provides a reference on the available kickstart
25 commands.
26 The information lists the commands, their syntax, and meanings.
27 Kickstart commands are based on the Fedora kickstart versions but
28 with modifications to reflect Wic capabilities.
29 You can see the original documentation for those commands at the
Brad Bishop316dfdd2018-06-25 12:45:53 -040030 following link:
31 <literallayout class='monospaced'>
32 <ulink url='http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html'>http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html</ulink>
33 </literallayout>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050034 </para>
35 </section>
36
37 <section id='command-part-or-partition'>
38 <title>Command: part or partition</title>
39
40 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040041 Either of these commands creates a partition on the system and uses
Brad Bishopd7bf8c12018-02-25 22:55:05 -050042 the following syntax:
43 <literallayout class='monospaced'>
44 part [<replaceable>mntpoint</replaceable>]
45 partition [<replaceable>mntpoint</replaceable>]
46 </literallayout>
47 If you do not provide <replaceable>mntpoint</replaceable>, Wic
48 creates a partition but does not mount it.
49 </para>
50
51 <para>
52 The <filename><replaceable>mntpoint</replaceable></filename> is
Brad Bishop316dfdd2018-06-25 12:45:53 -040053 where the partition is mounted and must be in one of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050054 following forms:
55 <itemizedlist>
56 <listitem><para>
57 <filename>/<replaceable>path</replaceable></filename>:
58 For example, "/", "/usr", or "/home"
59 </para></listitem>
60 <listitem><para>
61 <filename>swap</filename>:
Brad Bishop316dfdd2018-06-25 12:45:53 -040062 The created partition is used as swap space
Brad Bishopd7bf8c12018-02-25 22:55:05 -050063 </para></listitem>
64 </itemizedlist>
65 </para>
66
67 <para>
68 Specifying a <replaceable>mntpoint</replaceable> causes the
69 partition to automatically be mounted.
70 Wic achieves this by adding entries to the filesystem table (fstab)
71 during image generation.
Brad Bishop316dfdd2018-06-25 12:45:53 -040072 In order for Wic to generate a valid fstab, you must also provide
Brad Bishopd7bf8c12018-02-25 22:55:05 -050073 one of the <filename>--ondrive</filename>,
74 <filename>--ondisk</filename>, or
75 <filename>--use-uuid</filename> partition options as part of the
76 command.
Brad Bishop316dfdd2018-06-25 12:45:53 -040077 <note>
78 The mount program must understand the PARTUUID syntax you use
79 with <filename>--use-uuid</filename> and non-root
80 <replaceable>mountpoint</replaceable>, including swap.
81 The busybox versions of these application are currently
82 excluded.
83 </note>
84 Here is an example that uses "/" as the
85 <replaceable>mountpoint</replaceable>.
86 The command uses <filename>--ondisk</filename> to force the
87 partition onto the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050088 <filename>sdb</filename> disk:
89 <literallayout class='monospaced'>
90 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
91 </literallayout>
92 </para>
93
94 <para>
95 Here is a list that describes other supported options you can use
96 with the <filename>part</filename> and
97 <filename>partition</filename> commands:
98 <itemizedlist>
99 <listitem><para>
100 <emphasis><filename>--size</filename>:</emphasis>
101 The minimum partition size in MBytes.
102 Specify an integer value such as 500.
103 Do not append the number with "MB".
104 You do not need this option if you use
105 <filename>--source</filename>.
106 </para></listitem>
107 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400108 <emphasis><filename>--fixed-size</filename>:</emphasis>
109 The exact partition size in MBytes.
110 You cannot specify with <filename>--size</filename>.
111 An error occurs when assembling the disk image if the
112 partition data is larger than
113 <filename>--fixed-size</filename>.
114 </para></listitem>
115 <listitem><para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500116 <emphasis><filename>--source</filename>:</emphasis>
117 This option is a Wic-specific option that names the source
118 of the data that populates the partition.
119 The most common value for this option is "rootfs", but you
Brad Bishopc342db32019-05-15 21:57:59 -0400120 can use any value that maps to a valid source plugin.
121 For information on the source plugins, see the
122 "<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plugin-interface'>Using the Wic Plugins Interface</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400123 section in the Yocto Project Development Tasks Manual.
124 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500125
126 <para>If you use <filename>--source rootfs</filename>, Wic
Brad Bishop316dfdd2018-06-25 12:45:53 -0400127 creates a partition as large as needed and fills it with
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500128 the contents of the root filesystem pointed to by the
129 <filename>-r</filename> command-line option or the
130 equivalent rootfs derived from the <filename>-e</filename>
131 command-line option.
132 The filesystem type used to create the partition is driven
133 by the value of the <filename>--fstype</filename> option
134 specified for the partition.
135 See the entry on <filename>--fstype</filename> that follows
136 for more information.</para>
137
138 <para>If you use
139 <filename>--source <replaceable>plugin-name</replaceable></filename>,
140 Wic creates a partition as large as needed and fills it
141 with the contents of the partition that is generated by the
Brad Bishopc342db32019-05-15 21:57:59 -0400142 specified plugin name using the data pointed to by the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500143 <filename>-r</filename> command-line option or the
144 equivalent rootfs derived from the <filename>-e</filename>
145 command-line option.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400146 Exactly what those contents are and filesystem type used are
Brad Bishopc342db32019-05-15 21:57:59 -0400147 dependent on the given plugin implementation.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500148 </para>
149
150 <para>If you do not use the <filename>--source</filename>
151 option, the <filename>wic</filename> command creates an
152 empty partition.
153 Consequently, you must use the <filename>--size</filename>
154 option to specify the size of the empty partition.
155 </para></listitem>
156 <listitem><para>
157 <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
158 Forces the partition to be created on a particular disk.
159 </para></listitem>
160 <listitem><para>
161 <emphasis><filename>--fstype</filename>:</emphasis>
162 Sets the file system type for the partition.
163 Valid values are:
164 <itemizedlist>
165 <listitem><para>
166 <filename>ext4</filename>
167 </para></listitem>
168 <listitem><para>
169 <filename>ext3</filename>
170 </para></listitem>
171 <listitem><para>
172 <filename>ext2</filename>
173 </para></listitem>
174 <listitem><para>
175 <filename>btrfs</filename>
176 </para></listitem>
177 <listitem><para>
178 <filename>squashfs</filename>
179 </para></listitem>
180 <listitem><para>
181 <filename>swap</filename>
182 </para></listitem>
183 </itemizedlist>
184 </para></listitem>
185 <listitem><para>
186 <emphasis><filename>--fsoptions</filename>:</emphasis>
187 Specifies a free-form string of options to be used when
188 mounting the filesystem.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400189 This string is copied into the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500190 <filename>/etc/fstab</filename> file of the installed
191 system and should be enclosed in quotes.
192 If not specified, the default string is "defaults".
193 </para></listitem>
194 <listitem><para>
195 <emphasis><filename>--label label</filename>:</emphasis>
196 Specifies the label to give to the filesystem to be made on
197 the partition.
198 If the given label is already in use by another filesystem,
199 a new label is created for the partition.
200 </para></listitem>
201 <listitem><para>
202 <emphasis><filename>--active</filename>:</emphasis>
203 Marks the partition as active.
204 </para></listitem>
205 <listitem><para>
206 <emphasis><filename>--align (in KBytes)</filename>:</emphasis>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400207 This option is a Wic-specific option that says to start
208 partitions on boundaries given
209 <replaceable>x</replaceable> KBytes.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500210 </para></listitem>
211 <listitem><para>
212 <emphasis><filename>--no-table</filename>:</emphasis>
213 This option is a Wic-specific option.
214 Using the option reserves space for the partition and
215 causes it to become populated.
216 However, the partition is not added to the partition table.
217 </para></listitem>
218 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400219 <emphasis><filename>--exclude-path</filename>:</emphasis>
220 This option is a Wic-specific option that excludes the given
221 relative path from the resulting image.
222 This option is only effective with the rootfs source
Brad Bishopc342db32019-05-15 21:57:59 -0400223 plugin.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400224 </para></listitem>
225 <listitem><para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500226 <emphasis><filename>--extra-space</filename>:</emphasis>
227 This option is a Wic-specific option that adds extra space
228 after the space filled by the content of the partition.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400229 The final size can exceed the size specified by the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500230 <filename>--size</filename> option.
231 The default value is 10 Mbytes.
232 </para></listitem>
233 <listitem><para>
234 <emphasis><filename>--overhead-factor</filename>:</emphasis>
235 This option is a Wic-specific option that multiplies the
236 size of the partition by the option's value.
237 You must supply a value greater than or equal to "1".
238 The default value is "1.3".
239 </para></listitem>
240 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400241 <emphasis><filename>--part-name</filename>:</emphasis>
242 This option is a Wic-specific option that specifies a name
243 for GPT partitions.
244 </para></listitem>
245 <listitem><para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500246 <emphasis><filename>--part-type</filename>:</emphasis>
247 This option is a Wic-specific option that specifies the
248 partition type globally unique identifier (GUID) for GPT
249 partitions.
250 You can find the list of partition type GUIDs at
251 <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
252 </para></listitem>
253 <listitem><para>
254 <emphasis><filename>--use-uuid</filename>:</emphasis>
255 This option is a Wic-specific option that causes Wic to
256 generate a random GUID for the partition.
257 The generated identifier is used in the bootloader
258 configuration to specify the root partition.
259 </para></listitem>
260 <listitem><para>
261 <emphasis><filename>--uuid</filename>:</emphasis>
262 This option is a Wic-specific option that specifies the
263 partition UUID.
264 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400265 <listitem><para>
266 <emphasis><filename>--fsuuid</filename>:</emphasis>
267 This option is a Wic-specific option that specifies the
268 filesystem UUID.
269 You can generate or modify
270 <link linkend='var-WKS_FILE'><filename>WKS_FILE</filename></link>
271 with this option if a preconfigured filesystem UUID is
272 added to the kernel command line in the bootloader
273 configuration before you run Wic.
274 </para></listitem>
275 <listitem><para>
276 <emphasis><filename>--system-id</filename>:</emphasis>
277 This option is a Wic-specific option that specifies the
278 partition system ID, which is a one byte long, hexadecimal
279 parameter with or without the 0x prefix.
280 </para></listitem>
281 <listitem><para>
282 <emphasis><filename>--mkfs-extraopts</filename>:</emphasis>
283 This option specifies additional options to pass to the
284 <filename>mkfs</filename> utility.
285 Some default options for certain filesystems do not take
286 effect.
287 See Wic's help on kickstart
288 (i.e. <filename>wic help kickstart</filename>).
289 </para></listitem>
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500290 </itemizedlist>
291 </para>
292 </section>
293
294 <section id='command-bootloader'>
295 <title>Command: bootloader</title>
296
297 <para>
298 This command specifies how the bootloader should be configured and
299 supports the following options:
300 <note>
301 Bootloader functionality and boot partitions are implemented by
Brad Bishopc342db32019-05-15 21:57:59 -0400302 the various <filename>--source</filename> plugins that
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500303 implement bootloader functionality.
304 The bootloader command essentially provides a means of
305 modifying bootloader configuration.
306 </note>
307 <itemizedlist>
308 <listitem><para>
309 <emphasis><filename>--timeout</filename>:</emphasis>
310 Specifies the number of seconds before the bootloader times
311 out and boots the default option.
312 </para></listitem>
313 <listitem><para>
314 <emphasis><filename>--append</filename>:</emphasis>
315 Specifies kernel parameters.
316 These parameters will be added to the syslinux
317 <filename>APPEND</filename> or <filename>grub</filename>
318 kernel command line.
319 </para></listitem>
320 <listitem><para>
321 <emphasis><filename>--configfile</filename>:</emphasis>
322 Specifies a user-defined configuration file for the
323 bootloader.
324 You can provide a full pathname for the file or a file that
325 exists in the <filename>canned-wks</filename> folder.
326 This option overrides all other bootloader options.
327 </para></listitem>
328 </itemizedlist>
329 </para>
330 </section>
331</chapter>
332<!--
333vim: expandtab tw=80 ts=4
334-->