diff options
Diffstat (limited to 'poky/documentation/ref-manual/ref-kickstart.xml')
| -rw-r--r-- | poky/documentation/ref-manual/ref-kickstart.xml | 334 |
1 files changed, 334 insertions, 0 deletions
diff --git a/poky/documentation/ref-manual/ref-kickstart.xml b/poky/documentation/ref-manual/ref-kickstart.xml new file mode 100644 index 000000000..a58f9d7c9 --- /dev/null +++ b/poky/documentation/ref-manual/ref-kickstart.xml @@ -0,0 +1,334 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='ref-kickstart'> +<title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title> + + <section id='openembedded-kickstart-wks-reference'> + <title>Introduction</title> + + <para> + The current Wic implementation supports only the basic kickstart + partitioning commands: + <filename>partition</filename> (or <filename>part</filename> + for short) and <filename>bootloader</filename>. + <note> + Future updates will implement more commands and options. + If you use anything that is not specifically supported, results + can be unpredictable. + </note> + </para> + + <para> + This chapter provides a reference on the available kickstart + commands. + The information lists the commands, their syntax, and meanings. + Kickstart commands are based on the Fedora kickstart versions but + with modifications to reflect Wic capabilities. + You can see the original documentation for those commands at the + following link: + <literallayout class='monospaced'> + <ulink url='http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html'>http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html</ulink> + </literallayout> + </para> + </section> + + <section id='command-part-or-partition'> + <title>Command: part or partition</title> + + <para> + Either of these commands creates a partition on the system and uses + the following syntax: + <literallayout class='monospaced'> + part [<replaceable>mntpoint</replaceable>] + partition [<replaceable>mntpoint</replaceable>] + </literallayout> + If you do not provide <replaceable>mntpoint</replaceable>, Wic + creates a partition but does not mount it. + </para> + + <para> + The <filename><replaceable>mntpoint</replaceable></filename> is + where the partition is mounted and must be in one of the + following forms: + <itemizedlist> + <listitem><para> + <filename>/<replaceable>path</replaceable></filename>: + For example, "/", "/usr", or "/home" + </para></listitem> + <listitem><para> + <filename>swap</filename>: + The created partition is used as swap space + </para></listitem> + </itemizedlist> + </para> + + <para> + Specifying a <replaceable>mntpoint</replaceable> causes the + partition to automatically be mounted. + Wic achieves this by adding entries to the filesystem table (fstab) + during image generation. + In order for Wic to generate a valid fstab, you must also provide + one of the <filename>--ondrive</filename>, + <filename>--ondisk</filename>, or + <filename>--use-uuid</filename> partition options as part of the + command. + <note> + The mount program must understand the PARTUUID syntax you use + with <filename>--use-uuid</filename> and non-root + <replaceable>mountpoint</replaceable>, including swap. + The busybox versions of these application are currently + excluded. + </note> + Here is an example that uses "/" as the + <replaceable>mountpoint</replaceable>. + The command uses <filename>--ondisk</filename> to force the + partition onto the + <filename>sdb</filename> disk: + <literallayout class='monospaced'> + part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 + </literallayout> + </para> + + <para> + Here is a list that describes other supported options you can use + with the <filename>part</filename> and + <filename>partition</filename> commands: + <itemizedlist> + <listitem><para> + <emphasis><filename>--size</filename>:</emphasis> + The minimum partition size in MBytes. + Specify an integer value such as 500. + Do not append the number with "MB". + You do not need this option if you use + <filename>--source</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>--fixed-size</filename>:</emphasis> + The exact partition size in MBytes. + You cannot specify with <filename>--size</filename>. + An error occurs when assembling the disk image if the + partition data is larger than + <filename>--fixed-size</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>--source</filename>:</emphasis> + This option is a Wic-specific option that names the source + of the data that populates the partition. + The most common value for this option is "rootfs", but you + can use any value that maps to a valid source plug-in. + For information on the source plug-ins, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + + <para>If you use <filename>--source rootfs</filename>, Wic + creates a partition as large as needed and fills it with + the contents of the root filesystem pointed to by the + <filename>-r</filename> command-line option or the + equivalent rootfs derived from the <filename>-e</filename> + command-line option. + The filesystem type used to create the partition is driven + by the value of the <filename>--fstype</filename> option + specified for the partition. + See the entry on <filename>--fstype</filename> that follows + for more information.</para> + + <para>If you use + <filename>--source <replaceable>plugin-name</replaceable></filename>, + Wic creates a partition as large as needed and fills it + with the contents of the partition that is generated by the + specified plug-in name using the data pointed to by the + <filename>-r</filename> command-line option or the + equivalent rootfs derived from the <filename>-e</filename> + command-line option. + Exactly what those contents are and filesystem type used are + dependent on the given plug-in implementation. + </para> + + <para>If you do not use the <filename>--source</filename> + option, the <filename>wic</filename> command creates an + empty partition. + Consequently, you must use the <filename>--size</filename> + option to specify the size of the empty partition. + </para></listitem> + <listitem><para> + <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis> + Forces the partition to be created on a particular disk. + </para></listitem> + <listitem><para> + <emphasis><filename>--fstype</filename>:</emphasis> + Sets the file system type for the partition. + Valid values are: + <itemizedlist> + <listitem><para> + <filename>ext4</filename> + </para></listitem> + <listitem><para> + <filename>ext3</filename> + </para></listitem> + <listitem><para> + <filename>ext2</filename> + </para></listitem> + <listitem><para> + <filename>btrfs</filename> + </para></listitem> + <listitem><para> + <filename>squashfs</filename> + </para></listitem> + <listitem><para> + <filename>swap</filename> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis><filename>--fsoptions</filename>:</emphasis> + Specifies a free-form string of options to be used when + mounting the filesystem. + This string is copied into the + <filename>/etc/fstab</filename> file of the installed + system and should be enclosed in quotes. + If not specified, the default string is "defaults". + </para></listitem> + <listitem><para> + <emphasis><filename>--label label</filename>:</emphasis> + Specifies the label to give to the filesystem to be made on + the partition. + If the given label is already in use by another filesystem, + a new label is created for the partition. + </para></listitem> + <listitem><para> + <emphasis><filename>--active</filename>:</emphasis> + Marks the partition as active. + </para></listitem> + <listitem><para> + <emphasis><filename>--align (in KBytes)</filename>:</emphasis> + This option is a Wic-specific option that says to start + partitions on boundaries given + <replaceable>x</replaceable> KBytes. + </para></listitem> + <listitem><para> + <emphasis><filename>--no-table</filename>:</emphasis> + This option is a Wic-specific option. + Using the option reserves space for the partition and + causes it to become populated. + However, the partition is not added to the partition table. + </para></listitem> + <listitem><para> + <emphasis><filename>--exclude-path</filename>:</emphasis> + This option is a Wic-specific option that excludes the given + relative path from the resulting image. + This option is only effective with the rootfs source + plug-in. + </para></listitem> + <listitem><para> + <emphasis><filename>--extra-space</filename>:</emphasis> + This option is a Wic-specific option that adds extra space + after the space filled by the content of the partition. + The final size can exceed the size specified by the + <filename>--size</filename> option. + The default value is 10 Mbytes. + </para></listitem> + <listitem><para> + <emphasis><filename>--overhead-factor</filename>:</emphasis> + This option is a Wic-specific option that multiplies the + size of the partition by the option's value. + You must supply a value greater than or equal to "1". + The default value is "1.3". + </para></listitem> + <listitem><para> + <emphasis><filename>--part-name</filename>:</emphasis> + This option is a Wic-specific option that specifies a name + for GPT partitions. + </para></listitem> + <listitem><para> + <emphasis><filename>--part-type</filename>:</emphasis> + This option is a Wic-specific option that specifies the + partition type globally unique identifier (GUID) for GPT + partitions. + You can find the list of partition type GUIDs at + <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>. + </para></listitem> + <listitem><para> + <emphasis><filename>--use-uuid</filename>:</emphasis> + This option is a Wic-specific option that causes Wic to + generate a random GUID for the partition. + The generated identifier is used in the bootloader + configuration to specify the root partition. + </para></listitem> + <listitem><para> + <emphasis><filename>--uuid</filename>:</emphasis> + This option is a Wic-specific option that specifies the + partition UUID. + </para></listitem> + <listitem><para> + <emphasis><filename>--fsuuid</filename>:</emphasis> + This option is a Wic-specific option that specifies the + filesystem UUID. + You can generate or modify + <link linkend='var-WKS_FILE'><filename>WKS_FILE</filename></link> + with this option if a preconfigured filesystem UUID is + added to the kernel command line in the bootloader + configuration before you run Wic. + </para></listitem> + <listitem><para> + <emphasis><filename>--system-id</filename>:</emphasis> + This option is a Wic-specific option that specifies the + partition system ID, which is a one byte long, hexadecimal + parameter with or without the 0x prefix. + </para></listitem> + <listitem><para> + <emphasis><filename>--mkfs-extraopts</filename>:</emphasis> + This option specifies additional options to pass to the + <filename>mkfs</filename> utility. + Some default options for certain filesystems do not take + effect. + See Wic's help on kickstart + (i.e. <filename>wic help kickstart</filename>). + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='command-bootloader'> + <title>Command: bootloader</title> + + <para> + This command specifies how the bootloader should be configured and + supports the following options: + <note> + Bootloader functionality and boot partitions are implemented by + the various <filename>--source</filename> plug-ins that + implement bootloader functionality. + The bootloader command essentially provides a means of + modifying bootloader configuration. + </note> + <itemizedlist> + <listitem><para> + <emphasis><filename>--timeout</filename>:</emphasis> + Specifies the number of seconds before the bootloader times + out and boots the default option. + </para></listitem> + <listitem><para> + <emphasis><filename>--append</filename>:</emphasis> + Specifies kernel parameters. + These parameters will be added to the syslinux + <filename>APPEND</filename> or <filename>grub</filename> + kernel command line. + </para></listitem> + <listitem><para> + <emphasis><filename>--configfile</filename>:</emphasis> + Specifies a user-defined configuration file for the + bootloader. + You can provide a full pathname for the file or a file that + exists in the <filename>canned-wks</filename> folder. + This option overrides all other bootloader options. + </para></listitem> + </itemizedlist> + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
