mirror of
git://git.yoctoproject.org/poky.git
synced 2025-07-19 12:59:02 +02:00
59f95aaae4
The YP manual set was using the plugin term inconsistently. It was appearing as "plugin" as well as "plug-in". The plugins in the project are all named without a hyphen. The term itself is either/or according to Google. I have changed all references to plugin so that they do not use a hyphen. (From yocto-docs rev: 715bb58e2347c5e37a49da7d9e3e230503672337) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
335 lines
17 KiB
XML
335 lines
17 KiB
XML
<!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 plugin.
|
|
For information on the source plugins, see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plugin-interface'>Using the Wic Plugins 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 plugin 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 plugin 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
|
|
plugin.
|
|
</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> plugins 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
|
|
-->
|