.. _custom_partitions:

Custom Disk Partitions
======================

.. sidebar:: Abstract

   This page provides details about the opportunities and limitations
   of customizing the partition table in addition to the volume management
   settings from :ref:`custom_volumes`.

{kiwi} has its own partitioning schema, which is defined according to several
different user configurations: boot firmware, boot partition,
expandable layouts, etc. Those supported features have an impact on the
partitioning schema.

MBR or GUID partition tables are not flexible, have limitations, and are
tied to some specific disk geometry. Because of that, the preferred alternative
to disk layouts based on traditional partition tables is using flexible
approaches like logical volumes.

However, under certain conditions, additional entries to the low-level
partition table are needed. For this purpose, the `<partitions>` section
exists and allows you to add custom entries, as shown in the following
example:

.. code:: xml

   <partitions>
       <partition name="var" size="100" mountpoint="/var" filesystem="ext3"/>
   </partitions>

Each `<partition>` entry puts a partition of the configured size in the
low-level partition table, creates a filesystem on it, and includes
it in the system's fstab file. If parts of the root filesystem are
moved into their own partition, as in the above example,
this partition will also contain the data that gets installed during
the image creation process to that area.

The following attributes must/can be set to configure a partition entry:

name="identifier"
  Mandatory name of the partition as handled by {kiwi}.

  .. note::

     The following reserved names cannot be used
     because they are already represented by existing attributes:
     `root`, `readonly`, `boot`, `prep`, `spare`, `swap`, `efi_csm`,
     and `efi`.

partition_name="name"
  Optional name of the partition as it appears when listing the
  table contents with tools like `gdisk`. If no name is set,
  {kiwi} constructs a name of the form `p.lx(identifier_from_name_attr)`.

partition_type="type_identifier"
  Optional partition type identifier as handled by {kiwi}.
  Allowed values are `t.linux` and `t.raid`. If not specified,
  `t.linux` is the default.

size="size_string"
  Mandatory size of the partition. A size string can end with `M` or
  `G` to indicate a megabyte or gigabyte value. Without a unit
  specification, megabyte is used.

mountpoint="path"
  Optional mountpoint to mount the partition in the system.

filesystem="btrfs|ext2|ext3|ext4|squashfs|xfs
  Optional filesystem configuration to create one of the supported
  filesystems on the partition.

label="string"
  Optional filesystem label if a filesystem is provided. If no
  label is specified, the `name` identifier is set as the filesystem
  label.

clone="number"
  Optional setting to indicate that this partition should be
  cloned `number` of times. A clone partition is content-wise an
  exact byte-for-byte copy of the origin. However, to avoid conflicts at boot
  time, the UUID of any cloned partition will be made unique. In the
  sequence of partitions, the clone(s) will always be created first,
  followed by the partition considered the origin. The origin
  partition is the one that will be referenced and used by the
  system.

part_id="number"
  Specify the partition number for this partition. This is the number
  used for the partition in the partition table. The value impacts the
  name of the Unix device node associated with the partition. This means
  if the disk name is, e.g., `/dev/sda` and `part_id="42"` is set, the
  Unix node for this partition will be `/dev/sda42`. Please note that
  the number has no impact on the geometry or order of partitions as
  they are created. The partitions in the `<partitions>` section are still
  created in the order in which they are listed. Please also note, if
  custom partition IDs are used, it is strongly recommended that they
  be used across all partitions created by kiwi. The reason for this
  is that kiwi uses an incremental counter that, by default, matches
  the number of the partition in the table. If custom partition
  IDs are not used for all partitions, this results in a mix of
  numbers, which works but is not obviously visible when reading the
  image description. Because of that, also see the information about

  the `<type>` attributes `eficsmpart_id`, `efipart_id`,
  `rootpart_id`, and `bootpart_id`.

Despite the customization options of the partition table shown above,
there are the following limitations:

1. By default, the root partition is always the last one.

   Disk images built with {kiwi} are designed to be expandable.
   For this feature to work, the partition containing the system's
   rootfs must always be the last one. If this is unwanted for
   some reason, {kiwi} offers an opportunity for one extra/spare
   partition with the option to also be placed at the end of the
   table. For details, look up `spare_part` in :ref:`image-description-elements`.

2. By default, there are no gaps in the partition table.

   The way partitions are configured is done such that there are no
   gaps in the table of the image. However, leaving some space
   free at the **end** of the partition geometry is possible in the
   following ways:

   * **Deploy with unpartitioned free space.**

     To leave space unpartitioned on the first boot of a disk image,
     it is possible to configure an `<oem-systemsize>` that is
     smaller than the disk the image gets deployed to. Details
     about this setting can be found in :ref:`image-description-elements`.

   * **Build with unpartitioned free space.**

     To leave space unpartitioned at build time of the image, it
     is possible to disable `<oem-resize>` and configure an
     `<oem-systemsize>` which is smaller than the kiwi-calculated
     disk size or the fixed setting for the disk size via the
     `size>` element.

   * **Build with unpartitioned free space.**

     Setting some unpartitioned free space on the disk can be done using
     the `unpartitioned` attribute of the `size` element in the type's section.
     For details, see :ref:`disk-the-size-element`.

   * **Resize built image adding unpartitioned free space.**

     A built image can be resized by using the `kiwi-ng image resize` command
     and setting a new extended size for the disk. See {kiwi} commands docs
     :ref:`here <db_kiwi_image_resize>`.
