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