blob: 1dd36b242c9449fd28347e7c1b96e1a5b3721df6 [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
30 following links:
31 <itemizedlist>
32 <listitem><para>
33 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
34 </para></listitem>
35 <listitem><para>
36 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
37 </para></listitem>
38 </itemizedlist>
39 </para>
40 </section>
41
42 <section id='command-part-or-partition'>
43 <title>Command: part or partition</title>
44
45 <para>
46 Either of these commands create a partition on the system and use
47 the following syntax:
48 <literallayout class='monospaced'>
49 part [<replaceable>mntpoint</replaceable>]
50 partition [<replaceable>mntpoint</replaceable>]
51 </literallayout>
52 If you do not provide <replaceable>mntpoint</replaceable>, Wic
53 creates a partition but does not mount it.
54 </para>
55
56 <para>
57 The <filename><replaceable>mntpoint</replaceable></filename> is
58 where the partition will be mounted and must be of one of the
59 following forms:
60 <itemizedlist>
61 <listitem><para>
62 <filename>/<replaceable>path</replaceable></filename>:
63 For example, "/", "/usr", or "/home"
64 </para></listitem>
65 <listitem><para>
66 <filename>swap</filename>:
67 The created partition is used as swap space.
68 </para></listitem>
69 </itemizedlist>
70 </para>
71
72 <para>
73 Specifying a <replaceable>mntpoint</replaceable> causes the
74 partition to automatically be mounted.
75 Wic achieves this by adding entries to the filesystem table (fstab)
76 during image generation.
77 In order for wic to generate a valid fstab, you must also provide
78 one of the <filename>--ondrive</filename>,
79 <filename>--ondisk</filename>, or
80 <filename>--use-uuid</filename> partition options as part of the
81 command.
82 Here is an example using "/" as the mountpoint.
83 The command uses "--ondisk" to force the partition onto the
84 <filename>sdb</filename> disk:
85 <literallayout class='monospaced'>
86 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
87 </literallayout>
88 </para>
89
90 <para>
91 Here is a list that describes other supported options you can use
92 with the <filename>part</filename> and
93 <filename>partition</filename> commands:
94 <itemizedlist>
95 <listitem><para>
96 <emphasis><filename>--size</filename>:</emphasis>
97 The minimum partition size in MBytes.
98 Specify an integer value such as 500.
99 Do not append the number with "MB".
100 You do not need this option if you use
101 <filename>--source</filename>.
102 </para></listitem>
103 <listitem><para>
104 <emphasis><filename>--source</filename>:</emphasis>
105 This option is a Wic-specific option that names the source
106 of the data that populates the partition.
107 The most common value for this option is "rootfs", but you
108 can use any value that maps to a valid source plug-in.
109 For information on the source plug-ins, see the
110 "<link linkend='wic-plug-ins-interface'>Wic Plug-Ins Interface</link>"
111 section.</para>
112
113 <para>If you use <filename>--source rootfs</filename>, Wic
114 creates a partition as large as needed and to fill it with
115 the contents of the root filesystem pointed to by the
116 <filename>-r</filename> command-line option or the
117 equivalent rootfs derived from the <filename>-e</filename>
118 command-line option.
119 The filesystem type used to create the partition is driven
120 by the value of the <filename>--fstype</filename> option
121 specified for the partition.
122 See the entry on <filename>--fstype</filename> that follows
123 for more information.</para>
124
125 <para>If you use
126 <filename>--source <replaceable>plugin-name</replaceable></filename>,
127 Wic creates a partition as large as needed and fills it
128 with the contents of the partition that is generated by the
129 specified plug-in name using the data pointed to by the
130 <filename>-r</filename> command-line option or the
131 equivalent rootfs derived from the <filename>-e</filename>
132 command-line option.
133 Exactly what those contents and filesystem type end up
134 being are dependent on the given plug-in implementation.
135 </para>
136
137 <para>If you do not use the <filename>--source</filename>
138 option, the <filename>wic</filename> command creates an
139 empty partition.
140 Consequently, you must use the <filename>--size</filename>
141 option to specify the size of the empty partition.
142 </para></listitem>
143 <listitem><para>
144 <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
145 Forces the partition to be created on a particular disk.
146 </para></listitem>
147 <listitem><para>
148 <emphasis><filename>--fstype</filename>:</emphasis>
149 Sets the file system type for the partition.
150 Valid values are:
151 <itemizedlist>
152 <listitem><para>
153 <filename>ext4</filename>
154 </para></listitem>
155 <listitem><para>
156 <filename>ext3</filename>
157 </para></listitem>
158 <listitem><para>
159 <filename>ext2</filename>
160 </para></listitem>
161 <listitem><para>
162 <filename>btrfs</filename>
163 </para></listitem>
164 <listitem><para>
165 <filename>squashfs</filename>
166 </para></listitem>
167 <listitem><para>
168 <filename>swap</filename>
169 </para></listitem>
170 </itemizedlist>
171 </para></listitem>
172 <listitem><para>
173 <emphasis><filename>--fsoptions</filename>:</emphasis>
174 Specifies a free-form string of options to be used when
175 mounting the filesystem.
176 This string will be copied into the
177 <filename>/etc/fstab</filename> file of the installed
178 system and should be enclosed in quotes.
179 If not specified, the default string is "defaults".
180 </para></listitem>
181 <listitem><para>
182 <emphasis><filename>--label label</filename>:</emphasis>
183 Specifies the label to give to the filesystem to be made on
184 the partition.
185 If the given label is already in use by another filesystem,
186 a new label is created for the partition.
187 </para></listitem>
188 <listitem><para>
189 <emphasis><filename>--active</filename>:</emphasis>
190 Marks the partition as active.
191 </para></listitem>
192 <listitem><para>
193 <emphasis><filename>--align (in KBytes)</filename>:</emphasis>
194 This option is a Wic-specific option that says to start a
195 partition on an <replaceable>x</replaceable> KBytes
196 boundary.
197 </para></listitem>
198 <listitem><para>
199 <emphasis><filename>--no-table</filename>:</emphasis>
200 This option is a Wic-specific option.
201 Using the option reserves space for the partition and
202 causes it to become populated.
203 However, the partition is not added to the partition table.
204 </para></listitem>
205 <listitem><para>
206 <emphasis><filename>--extra-space</filename>:</emphasis>
207 This option is a Wic-specific option that adds extra space
208 after the space filled by the content of the partition.
209 The final size can go beyond the size specified by the
210 <filename>--size</filename> option.
211 The default value is 10 Mbytes.
212 </para></listitem>
213 <listitem><para>
214 <emphasis><filename>--overhead-factor</filename>:</emphasis>
215 This option is a Wic-specific option that multiplies the
216 size of the partition by the option's value.
217 You must supply a value greater than or equal to "1".
218 The default value is "1.3".
219 </para></listitem>
220 <listitem><para>
221 <emphasis><filename>--part-type</filename>:</emphasis>
222 This option is a Wic-specific option that specifies the
223 partition type globally unique identifier (GUID) for GPT
224 partitions.
225 You can find the list of partition type GUIDs at
226 <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
227 </para></listitem>
228 <listitem><para>
229 <emphasis><filename>--use-uuid</filename>:</emphasis>
230 This option is a Wic-specific option that causes Wic to
231 generate a random GUID for the partition.
232 The generated identifier is used in the bootloader
233 configuration to specify the root partition.
234 </para></listitem>
235 <listitem><para>
236 <emphasis><filename>--uuid</filename>:</emphasis>
237 This option is a Wic-specific option that specifies the
238 partition UUID.
239 </para></listitem>
240 </itemizedlist>
241 </para>
242 </section>
243
244 <section id='command-bootloader'>
245 <title>Command: bootloader</title>
246
247 <para>
248 This command specifies how the bootloader should be configured and
249 supports the following options:
250 <note>
251 Bootloader functionality and boot partitions are implemented by
252 the various <filename>--source</filename> plug-ins that
253 implement bootloader functionality.
254 The bootloader command essentially provides a means of
255 modifying bootloader configuration.
256 </note>
257 <itemizedlist>
258 <listitem><para>
259 <emphasis><filename>--timeout</filename>:</emphasis>
260 Specifies the number of seconds before the bootloader times
261 out and boots the default option.
262 </para></listitem>
263 <listitem><para>
264 <emphasis><filename>--append</filename>:</emphasis>
265 Specifies kernel parameters.
266 These parameters will be added to the syslinux
267 <filename>APPEND</filename> or <filename>grub</filename>
268 kernel command line.
269 </para></listitem>
270 <listitem><para>
271 <emphasis><filename>--configfile</filename>:</emphasis>
272 Specifies a user-defined configuration file for the
273 bootloader.
274 You can provide a full pathname for the file or a file that
275 exists in the <filename>canned-wks</filename> folder.
276 This option overrides all other bootloader options.
277 </para></listitem>
278 </itemizedlist>
279 </para>
280 </section>
281</chapter>
282<!--
283vim: expandtab tw=80 ts=4
284-->