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