diff options
Diffstat (limited to 'documentation/ref-manual/ref-kickstart.rst')
-rw-r--r-- | documentation/ref-manual/ref-kickstart.rst | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-kickstart.rst b/documentation/ref-manual/ref-kickstart.rst new file mode 100644 index 0000000000..45222de05b --- /dev/null +++ b/documentation/ref-manual/ref-kickstart.rst | |||
@@ -0,0 +1,212 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******************************************* | ||
4 | OpenEmbedded Kickstart (``.wks``) Reference | ||
5 | ******************************************* | ||
6 | |||
7 | .. _openembedded-kickstart-wks-reference: | ||
8 | |||
9 | Introduction | ||
10 | ============ | ||
11 | |||
12 | The current Wic implementation supports only the basic kickstart | ||
13 | partitioning 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 | |||
22 | This chapter provides a reference on the available kickstart commands. | ||
23 | The information lists the commands, their syntax, and meanings. | ||
24 | Kickstart commands are based on the Fedora kickstart versions but with | ||
25 | modifications to reflect Wic capabilities. You can see the original | ||
26 | documentation for those commands at the following link: | ||
27 | http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html | ||
28 | |||
29 | Command: part or partition | ||
30 | ========================== | ||
31 | |||
32 | Either of these commands creates a partition on the system and uses the | ||
33 | following syntax: | ||
34 | :: | ||
35 | |||
36 | part [mntpoint] | ||
37 | partition [mntpoint] | ||
38 | |||
39 | If you do not | ||
40 | provide mntpoint, Wic creates a partition but does not mount it. | ||
41 | |||
42 | The ``mntpoint`` is where the partition is mounted and must be in one of | ||
43 | the following forms: | ||
44 | |||
45 | - ``/path``: For example, "/", "/usr", or "/home" | ||
46 | |||
47 | - ``swap``: The created partition is used as swap space | ||
48 | |||
49 | Specifying a mntpoint causes the partition to automatically be mounted. | ||
50 | Wic achieves this by adding entries to the filesystem table (fstab) | ||
51 | during image generation. In order for Wic to generate a valid fstab, you | ||
52 | must 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 | |||
64 | Here 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 | |||
68 | Here is a list that describes other supported options you can use with | ||
69 | the ``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 | |||
188 | Command: bootloader | ||
189 | =================== | ||
190 | |||
191 | This command specifies how the bootloader should be configured and | ||
192 | supports 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. | ||