# Partition Management for the Debian Installer

Anton Zinoviev anton@lml.bas.bg
2003,2004,2007 Anton Zinoviev

This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available as `/usr/share/common-licenses/GPL` in the Debian GNU/Linux distribution or on the World Wide Web at the GNU website. You can also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.

## Introduction

There are many wishlist features that we might desire from any installer of GNU/Linux and that are related to partitioning:

- The partitioner should support different file systems. Some of them need more care than only libraries and suitable arguments for `mount`.

- It should support not only regular partitions but also software RAID and LVM as well as encrypted file systems.

- It should be able to partition disks automatically and allow the user to inspect and customise the automatic partitioning later.

- It should be able to resize partitions and move their contents from one place to another.

- The users should be protected from mistakes – by allowing them to undo their partitioning operations.

- The partitioner should discover that there is already some installed GNU/Linux system and analyse its `fstab`, `passwd`, etc. in order to provide an automatic upgrade from the old already installed GNU/Linux system to the new one.

One nice feature of the Debian installer is that it is modular. Its components are packaged in separate udebs and they can have relatively independent development process. This document describes how we can solve all mentioned tasks keeping the Debian installer as modular as it is now. Ideally in order to add some new feature only a few new udebs must be all that is needed – no changes in the existing udebs and no recompilation would be required.

The script `partman` from the package partman-base opens the main partitioning menu; it may look like this one:

    +------------------+ [!!] Partition the storage devices +-----------------+
    |             Partition, free space or device to be modified              |
    |                                                                         |
    |        IDE1 master - Seagate U Series 40810 (40.0 GB)                   |
    |                 #3 primary    2.1 GB B F ext3       /                   |
    |                    pri/log    4.4 GB     FREE SPACE                     |
    |                 #5 logical    3.6 GB                                    |
    |                 #7 logical   10.0 GB   F ext3       /usr                |
    |                 #8 logical   19.9 GB   K ext2       /home               |
    |        IDE2 master - Maxtor 6Y120L0 (122.9 GB)                          |
    |                 #7 logical    1.0 GB     linux-swap                     |
    |                    logical  114.5 GB     FREE SPACE                     |
    |                 #5 logical    5.5 GB     reiserfs                       |
    |                 #6 logical    1.9 GB                                    |
    |                                                                         |
    |        Undo changes to partitions                                       |
    |        Finish partitioning and write changes to disk                    |
    |                                                                         |
    |      <Go Back>                                          <Continue>      |
    |                                                                         |
    +-------------------------------------------------------------------------+

When the users choose some free space they are offered to create a new partition just like they are in `cfdisk`. When users choose a partition they are offered with a menu with various editing operations:

    +------------------+ [!!] Partition the storage devices +-----------------+
    |                    Settings on the partition:                           |
    |                                                                         |
    |           Usage method:          format the partition                   |
    |           File system:           ext3                                   |
    |           Mount point:           /var/mail                              |
    |           Mount options:         noatime,nodev,nosuid,noexec,usrquota   |
    |           Bootable flag:         off                                    |
    |           Size:                  995.2 MB                               |
    |                                                                         |
    |           Finished setting up partition                                 |
    |           Delete the partition                                          |
    |                                                                         |
    |      <Go Back>                                          <Continue>      |
    |                                                                         |
    +-------------------------------------------------------------------------+

All udebs are allowed to add items to this menu as well as to several other menus. They can add new items in the list of devices such as software RAID and LVM devices, networked file systems, encrypted partitions, etc. The package partman-partitioning is responsible for pure partitioning operations such as creation of new partitions and deletion. The packages partman-target and partman-basicmethods are responsible for the items `Choose how this partition should be used' and `Choose a file system'. The package partman-basicfilesystems adds support for `ext2`, `linux-swap`, `fat16` and `fat32`. The package partman-ext3 adds support for `ext3`.

## Changes in partman since 2005

This chapter documents important changes in the sctructure of partman. It is provided as a test if you need to reread some of the sections in this document.

- New directory `check.d` with some of the scripts formerly in `finish.d`

- New directory `display.d` with different methods to do the partitioning (manual, automatic, etc.)

- New command GET_LABEL_TYPE in parted_server

## Package interrelations

### Basics

The GNU Parted disk partitioning library provides high-level, architecture independent functions for operations such as creating, deleting, resizing and moving of partitions. Most of the functions of libparted work in a nondestructive way. The partition table is written in data structures and any change in the partition table happens only in these data structures rather than directly on the disk. This makes possible to implement partitioning tools based on libparted that support undoing of the editing operations.

However we have to solve two problems. The first is that we want to use as much as possible shell scripts rather than C programs. The second is that different programs have to operate with same instance of libparted structures. For example the user can use some tool for automatic partitioning, then correct or customise the automatic partitioning, perform some other arbitrary operations being still allowed to undo everything.

There is one obvious solution of these two problems – we keep the data structures of libparted in a daemon process and communicate with it in order to make changes in these data structures. This process is `/bin/parted_server` from the package partman-base.

The scripts from `/lib/partman/init.d/` are executed before all partitioning operations. They can be used to initialise the partitioning system. The scripts may be invoked more than once in which case they should behave properly. For example this directory can contain a script to discover the existing hard drives. If invoked for second time the script must either do nothing or check if there is some new kernel module giving access to new still undiscovered device.

Any udeb may install a script in this directory. For example the script `/lib/partman/init.d/30parted` from the package partman-base is responsible for running `parted_server`. Notice that the scripts are prefixed by a two-digit number. This number determines the order the scripts are executed. If any of the scripts exit with non-zero exit code the partitioning will be aborted. This means that in almost all cases these scripts must end with exit-code 0.

When the initialisation completes, the scripts from `/lib/partman/display.d` are executed. These scripts are supposed to make the actual partitioning interactively or non-interactively. The exit code code of these scripts is interpreted as follows:

code = 0

  The script did nothing, move to the next script in `display.d`.

1 <= code <= 99

  Restart the partitioning (move again to the first script in `display.d`).

100 <= code <= 254

  The script successfully partitioned the disks, do not execute the following scripts in `display.d`.

code = 255

  Abort the partitioning.

When the disks become ready, the scripts in `/lib/partman/check.d` are executed. They have to check if everything is OK to proceed with commiting the changes on the disks, mounting file systems, etc. For example the package partman-target installs there a script to check if there is a root file system. If a script in `check.d` exits with non-zero exit code then the scripts in `display.d` are executed again and as a result the user is allowed to fix the partitioning.

The directory `check.d` is remarkable with the fact that some of the scripts in it are installed by non-partman packages. The packages for the various bootloaders (lilo, grub, palo, etc.) install there scripts to ensure the partitioning scheme conforms to their requirements.

While the user is modifying the partitions this happens only in the memory of the computer and not in the edited devices. This is because almost all changes happen either in the data-structures of `parted_server` or in files in the installer's ram-disk. That's why we can provide the user with the option to undo everything. When the user chooses to undo the scripts in the directory `/lib/partman/undo.d/` are executed. Any udeb may install a script in this directory. For example the script `/lib/partman/undo.d/30parted` is responsible for restoring the contents of the data structures of `parted_server`. In most cases the scripts from `undo.d` must exit with exit-code 0. If any of the scripts exit with non-zero exit code the partitioning will be aborted.

In order to perform the editing operations on the storage devices (and in particular to transfer the partitions from the internal data-structures of `parted_server` to the hard disks) the scripts from the directory `/lib/partman/commit.d/` are executed. The order in which these scripts are executed is determined again by two-digit prefixes in the script names. Every script from `commit.d` is guaranteed that the scripts ordered before it have been already executed. However if any of the scripts exit with non-zero exit-code the execution of the scripts in `commit.d` will be stopped. In this case the partitioning will continue and the user is expected to fix the problem. If any script exits with non-zero exit code it is supposed to inform the user what went wrong using debconf.

There are two cases when the scripts from `commit.d` are executed. The first case is when the user wants to commit the changes to the disks but continue partitioning. The second case is when the partitioning ends. In the first case if none of the scripts fails the scripts from `init.d` will be also executed and the user will be returned to the partitioning dialog. In the second case the scripts from `finish.d` will be executed. In both cases if any of the scripts in `commit.d` fail the user will be returned immediately back to the partitioning dialog.

The scripts from `/lib/partman/finish.d/` are responsible for final tasks such as to mount partitions on `/target`, generate of `fstab`, stop `parted_server` etc.

What tasks will be performed depends on what udebs are unpacked. If the packages responsible for mounting partitions and creating fstab are not unpacked we have only a simple partitioner providing partitioned-harddrives. If they are unpacked they provide also made-filesystems and mounted-partitions.

If any of these scripts exit with non-zero exit-code the execution of the scripts will be stopped. If the exit-code was 1 then the user will be returned back to the partitioning dialog and is expected to correct the problem. If the exit-code was neither 0 nor 1 then the partitioning will be aborted.

For every hard disk in the system the script `/lib/partman/init.d/30parted` creates a subdirectory in `/var/lib/partman/devices/` and informs `parted_server` that the device is to be edited (`opens' the device). All udebs that provide storage device (software RAID, LVM, encrypted partitions) must do the same. This subdirectory must contain at least three files – `device`, `model` and `size`. The first contains the name of a device file (for example `/dev/ide/host0/bus0/target0/lun0/disc`). The second contains the name of the device (for example `Maxtor 6Y120L0'). The third contains the physical size of the storage device (in bytes, for example `122942324736').

Please notice that udebs that provide support for storage `devices' that cannot be partitioned (such as networked file systems) should not create a subdirectory in `/var/lib/partman/devices` and certainly cannot provide the device to the management of `parted_server`.

The subdirectories of `/var/lib/partman/devices/` can but are not obligated to contain additional information. We call these subdirectories device directories.

Every partition in a device managed by `parted_server` is given a unique name having the form first_byte-last_byte. This name can be used to determine where the partition starts and where it ends.

Unlike one can suppose `parted_server` always measures sizes and places in bytes rather than in sectors. Last_byte is the number of the last byte of the last sector of the partition.

If the device directory contains a subdirectory named `first_byte-last_byte` then this subdirectory stores information about the partition. We call this subdirectory directory of the partition. We call the stringfirst_byte-last_byte `id' of the partition.

### Menu-directories

There are several menus involved in partitioning. In order to keep the Debian installer modular and extensible we want to allow every udeb to install items in these menus. Let us be more specific. When the users decide to format some existing partition we need a menu with an item for every supported file system. Obviously we don't want to hardwire the list of the supported file systems anywhere in our installer. If we want to add support to the installer say for XFS or UMSDOS file systems, only a few new udebs must be all that is needed.

In order to achieve this flexibility the package partman-base provides support for the so-called menu-directories. Every such directory contains files named `question` and `priority`. They contain the name of a Debconf template and the priority of the question correspondingly. The template must have exactly the following type and choices fields:

    Type: select
    Choices-C: ${CHOICES}
    Choices: ${DESCRIPTIONS}

All other files in the menu directory are subdirectories. Any udeb can install such a subdirectory in order to add items to the menu. For example the udebs for software RAID volumes can install in the menu of the editing operations an item to resize the chosen partition to have the same size as another. These subdirectories must contain two scripts – `choices` and `do_option`. The purpose of the first script is to print menu items. For every menu item `choices` must print a line having the form

    menu_item_id<TAB>The text for the user

The script `choices` is allowed to print nothing. In this case no item for the menu is created. Here `<TAB>` is ASCII 9. The text `The text for the user' will be presented to the users. If they choose this particular menu item the script `do_option` will be invoked.

The script `choices` may be given some arguments depending on the particular menu-directory. The first argument given to `do_option` is always the `menu_item_id` of the chosen menu item. The rest of the arguments are the same as the arguments given to `choices`.

Let we take as an example the menu that the users see when they choose to edit some particular partition. The file `question` in the menu-directory for this menu contains the text `partman/active_partition`. This is the name of a Debconf-template with type `select' and description `Please choose what to do with this partition'. The package partman-partitioning installs in this menu-directory some subdirectories – `62change_name`, `65toggle_bootable` and `85delete`. The script `62change_name/choices` is given two arguments – the hard disk we edit and the id of the partition. It checks if the type of the partition table supports partition names in which case it prints the line

    setname<TAB>Set the name of the partition

If the partition table doesn't support names, then this script prints nothing. When the user chooses to `set the name of the partition' the script `62change_name/do_option` is invoked. Its first argument is `setname` (this is the first part of the line printed by `choices`) and the other arguments are the same to the arguments given to the script `choices`. In our case the script `do_option` ignores its first argument. The script `do_option` can use its first argument in order to determine which menu item the user has chosen in cases when `choices` has printed several.

Notice that the names of the subdirectories in any menu-directory start with two digits. They are used to determine the order of the items in the menu.

### Partitioning

The partitioning starts with the menu of the menu-directory `/lib/partman/choose_partition`. This is the main partitioning menu. Every udeb is allowed to install new items in it. If the script `do_option` exits with exit-code 0 the user will be shown again the main partitioning menu. If the script exits with exit-code 100 this means that the partitioning should be finished. In this case the scripts from `commit.d` and `finish.d` will be executed as described in . If the script `do_option` exits with exit code 255 the partitioning will be aborted immediately.

The main partitioning menu always contains an item for every partitioned storage device, an item for every partition and an item for every free space.

If the user chooses a storage device the menu of the menu-directory `/lib/partman/storage_device` will be opened. The first argument given to `choices` is the device directory

We are not going to describe the arguments given to `do_option`. Look at .

.

If the user chooses a free space the menu-directory `/lib/partman/free_space` will be opened. The first argument given to `choices` is the device directory. The second argument is the id of the free space.

If the user chooses an active partition the menu-directory `/lib/partman/active_partition` will be opened. The first argument given to `choices` is the device directory. The second argument is the id of the chosen partition. If the script `do_option` exits with exit-code 0 the user will be shown again the menu `active_partition` for the same partition. If the script `do_option` exits with exit-code 100 or 255 the user will be returned back to the main partitioning menu. This should happen when the id of the partition is invalidated, for example when the partition is deleted or resized.

In the main partitioning menu the partitions are presented by lines of this kind:

    #8 primary   19.9 GB   K ext2       /home

Notice that it is useless to indicate that the partition is primary if the type of the partition table is `mac' as this partition table doesn't support logical partitions. On the other hand this partition table supports partition names. We see that we need a flexible way to determine how the partitions are presented in the main partitioning menu.

The directory `/lib/partman/visual.d` contains scripts that print the parts of the partition line. For example the script `/lib/partman/visual.d/filesystem` prints strings like `ext3' or `FREE SPACE'. These scripts usually start with the following cliche:

    cd $1

    num=$2
    id=$3
    size=$4
    type=$5
    fs=$6
    path=$7
    shift; shift; shift; shift; shift; shift; shift
    name=$*

$1 is the device directory. $num is the number of the partition (for example `/dev/hda6` has number 6). $id is the id of the partition. $size is the size of the partition (in bytes). If this is an active partition then $type is either `primary' or `logical'. If this is a free space then $type shows what partition can be created in it and $type can be `primary', `logical', `pri/log' or `unusable'. $fs is `free' if this is a free space. Otherwise $fs is the type of the file system of this partition as known to `parted_server`. $path is a device name for the partition, for example `/dev/ide/host0/bus0/target0/lun0/part6`. $name is the name of the partition or the empty string if the partition table doesn't support partition names.

The script `/lib/partman/commit.d/30parted` transfers the partition tables from the internal structures of `parted_server` to the disks. The script `/lib/partman/finish.d/80parted` stops `parted_server`.

The package partman-base installs in `update.d` (see ) a script to ensure that for every partition that contains some file system there is a file `detected_filesystem` in the directory of the partition whose contents is the type of the detected file system as returned by `parted_server`.

### Setup `/target`

Without the package partman-target the packages partman-base and partman-partitioning provide only the regular partitioning operations. However if the package partman-target is also unpacked then the user will be provided with options to choose file systems for the partitions, specify wether they should be formatted and select mount points. The package partman-target adds to the menu directory `/lib/partman/active_partition` the item `Usage method:'. If the user chooses this item the menu directory `/lib/partman/choose_method` will be opened. The scripts `choices` from `choose_method` are given the device directory as first argument and the partition id as second argument.

The package partman-basicmethods adds in the menu of the menu directory `choose_method` three items: `Do not use the partition', `Format the partition' and `Keep and use the existing data in the partition' (the last only if some file system is detected). Other udebs can provide another methods to use partitions.

Every partition that is to be used somehow in the future Debian system should have a file named `method' in its directory (what is `directory of a partition' is described in ). The scripts `do_option` of the menu directory `choose_method` manage the file `method`. It contains the name of the usage method chosen by the user. For example if the user chooses to `format the partition' the contents of this file will be `format' and if the user chooses to `keep and use the existing data' the contents of this file will be `keep'. Partitions that won't be used do not have a file `method`.

The udebs providing methods may provide also translatable names of the methods for the user interface using debconf templates named `partman/method_long/some_method` and `partman/method_short/some_method`. For example the package partman-palo providing method `palo` can provide also the following debconf templates:

    Template: partman/method_long/palo
    Type: text
    _Description: Palo boot partition

    Template: partman/method_short/palo
    Type: text
    _Description: Palo

Another job for the scripts `do_option` of the menu directory `choose_method` is to create or remove a file named `use_filesystem` in the directory of the partitions. This file is created when the usage method requires the partition to be used together with some file system. Otherwise it is removed. Example methods that are used together with a file system are `format the partition' and `keep and use the existing data'. Example methods that are not used together with a file system are `LVM physical volume' and `PALO boot partition'.

Finally, the scripts `do_option` of the menu directory `choose_method` have to create or remove a file named `format' in the directory of the partitions. If the partition directory contains a file named `format` then it will be formatted. Otherwise it will not be formatted. For example if the user chooses to `format the partition' the script `do_option` will create a file `format`. If the user chooses to `keep and use the existing data' the file `format` will be removed if it exists.

The menu item `Choose a file system' in the menu directory `active_partition` is also provided by the package partman-target. If the user chooses it the menu `choose_filesystem` will be opened. This menu however is not produced using a menu directory.

Packages that provide support for some file system should install a script in the directory `/lib/partman/valid_filesystems`. The first argument given to this script is some device directory, the second argument is the id of some partition and the third argument is one of the strings `formatable' and `existing'. If it is `formatable' then the job of the script is to check if the specified partition can be formatted and used. If the third argument is `existing' then the job of the script is to check if the partition can be used without formatting. In either case if the partition can be used then the script should print a line with the identifier of the type of the file system.

Packages that provide support for some file systems use the directory `/lib/partman/parted_names` to define a mapping from the unique file system type identifiers to the names used by `parted_server`. Suppose for example that the package providing support for UMSDOS file system chooses the string `umsdos' as unique identifier for the file system. Then this package must install in this directory a file named `umsdos` whose contents is the string `fat16'. This means that `parted_server` will know UMSDOS file systems as being fat16 file systems.

The udebs providing file systems may provide also translatable names of the file systems for the user interface using debconf templates named `partman/filesystem_long/some_filesystem` and `partman/filesystem_short/some_filesystem`. For example the package partman-ext3 providing file system with unique identifier `ext3` can provide also the following debconf templates:

    Template: partman/filesystem_long/ext3
    Type: text
    _Description: Extended 3

    Template: partman/filesystem_short/ext3
    Type: text
    _Description: Ext3

Most of the packages that provide support for a file system will have to add an item `Mount point:' to the menu `active_partition`. Of course this item should be shown only when the contents of the file `acting_filesystem` is appropriate. The mount point chosen by the user should be written in a file named `mountpoint` situated in the directory of the partition. If the user chooses not to mount this file system then the file `mountpoint` should be removed (if it exists).

In order to be able to mount file systems and generate fstab the directories `/lib/partman/fstab.d/` and `/lib/partman/mount.d/` are used. The scripts from `fstab.d` should print lines in a form similar to that of `/etc/fstab`:

    file_system   mount_point   type    options  dump  pass

The first field (`file_system`) is the name of a device that can be accessed by the installer. For example this can be `/dev/ide/host0/bus0/target0/lun0/part5` despite that in the future system this device will be named `/dev/hda5`. On the other hand the other five fields should look exactly the same way as in the `fstab` to be generated. For example `options` can contain options such as `quota` that are senseless for the installer.

The scripts from `mount.d` are used to mount file systems. A string having the same form as the lines output by the scripts from `fstab.d` should be given as first argument to any script from `mount.d`. Any script from `mount.d` checks if it can mount the requested file system. If it cannot then the script exits with some non-zero exit code. Otherwise the script must mount the file system in the proper place in the hierarchy over `/target`, print on its standard output a command that should be used in order to unmount the file system and exit with exit code 0.

The scripts in the directories `fstab.d` and `mount.d` are installed by the udebs that provide support for file systems.

Packages that provide support for file systems install in `commit.d` a script to format the partitions that the user has requested to be formatted. The package partman-target installs in `finish.d` a script to mount the partitions on `/target`. The packages that provide support for storage devices (RAID, LVM, etc.) install in `finish.d` a script to add in `/target/etc/fstab` the necessary lines.

The package partman-target installs in `update.d` (see ) a script to ensure that for every partition that is to be used there is a file `acting_filesystem` in the directory of the partition whose contents is the identifier of the type of file system under which the partition should be used.

## `/lib/partman/lib/*`

Various scripts in partman make use of function libraries: separate files, mostly containing shell functions, that are sourced by scripts so they can make use of common functions and code duplication can be avoided.

The main function library is `base.sh`, provided by partman-base. This file is sourced by most scripts in partman as it defines a lot of useful variables and common functions. Some of these are documented in the remainder of this chapter.

The script `base.sh` has become somewhat too long and this probably makes its sourcing slow. Although some reorganization has already taken place, it could be a good idea to split it up further.

Other packages provide more targeted function libraries. In most cases their scope and use can easily be determined from their name.

### Environment

The variables `TAB` and `NL` have values ASCII 9 and ASCII 10 correspondingly. They can be used as temporary values for the variable `IFS`. The function `restore_ifs` restores the variable `IFS` its original value.

The function library `base.sh` also contains simple reimplementations of `basename` and `dirname` so that busybox doesn't have to provide them.

### Menus

The function `debconf_select` is a high level function to ask user with a menu using a Debconf question with type `select'. Synopsis:

    debconf_select priority template choices default

The first argument is the debconf-priority of the question and the second is the name of the template to be used. The third argument is a newline-separated list of items for the menu. Each item has the form

    menu_item_id<TAB>The text for the user

Here `<TAB>` is ASCII 9. The text `The text for the user' is the text of the menu item. If `menu_item_id` of some menu-item is identical with the fourth argument given to `debconf_select` then this menu-item will be default.

If the user cancels the question `debconf_select` returns with exit-code 255. Otherwise the value of the variable `RET` will be the `menu_item_id` of the chosen menu item. If the chosen menu item was chosen by the user then the exit-code is 0. If the item was chosen automatically (due to the debconf-priority or to some other reason) the exit-code is 1.

The function `debconf_select` doesn't care to `db_fset` `$template` `seen` `false`. The template must have exactly the following type and choices fields:

    Type: select
    Choices-C: ${CHOICES}
    Choices: ${DESCRIPTIONS}

The udebs that generate menus using menu-directories use the function `ask_user` instead of `debconf_select`. Synopsis:

    ask_user a_menu_directory additional_optional_arguments...

This function displays the menu for `a_menu_directory`. The first argument is a menu-directory (see ). If the user cancels the dialog then `ask_user` returns with exit code 255. Otherwise it returns with the exit code of the script `do_option`.

If `ask_user` is called re-entrantly from within a `do_option` script, then the calling `do_option` script should typically be careful to handle or discard exit code 255 itself (and sometimes other codes, depending on the protocol in force) to avoid a backup operation inadvertently backing up out of several nested menus at once.

The script `choices` is invoked with `additional_optional_arguments` as arguments. The first argument given to `do_option` is the `menu_item_id` of the chosen menu item and the other arguments are again `additional_optional_arguments`.

To set the default selected item in a menu-directory, use the function `menudir_default_choice`. Synopsis:

    menudir_default_choice a_menu_directory subdirectory menu_item_id

Where the `subdirectory` is the name of a subdirectory in the menu-directory with the leading sequence number stripped off and `menu_item_id` is the id of a menu-item printed by `a_menu_directory/??subdirectory/choices`. The specified item is set as default not forever but only for the next invocation of `ask_user`. It is not an error to set as default non-existing item; in this case the first item in the menu will be default.

The function `partition_tree_choices` prints a sequence of lines in the form

    menu_item_id<TAB>The text for the user

– one for every storage device and one for every partition. The `menu_item_id` of the storage devices is their storage directory. The `menu_item_id` of the partitions has the form storage_directory//partition_id. The output of `partition_tree_choices` can be given as third argument to `debconf_select`.

### Long numbers

Notice that the sizes of most of the present storage devices are so large that we cannot measure them using 32-bit integers. Consequently we cannot use the usual shell arithmetic. The functions `longint_le`, `longint2human`, `human2longint` and `valid_human` exist in order to deal with such big numbers.

The function `longint_le` is used to compare two big numbers.

    longint_le number1 number2

returns with exit code 0 if the first number is less or equal to the second and returns 1 otherwise.

The function `longint2human` accepts in its first argument some number of bytes, converts it to something that is more meaningful for humans and outputs the result. For example

    longint2human 1234567890

gives `1.2 GB`. Notice that this function rounds its argument.

The function `human2longint` is used for the opposite convertion:

    human2longint 1.234Gb

gives `1234000000`.

The function `valid_human` returns with exit code 0 when its first argument is a string that is suitable to be given to `human2longint`. Otherwise it returns with exit code 1.

### Updating partition directories

Different components of the installer may need to get information about the partitions. They can communicate with `parted_server` in order to know the characteristics of the partition. However not everything can be known from `parted_server`. Imagine an udeb that provides the user with the option to upgrade some existing GNU/Linux installation. This udeb analyses the `fstab` and knows that some partition is used as `/home` and should not be formatted. This sort of information has nothing to do with `parted_server`. The udeb stores it in a subdirectory of the device directory named after the id of the partition.

But now a problem arises. Suppose that the user chooses to format some partition as ext2 and mount it on `/home`. The udebs responsible for formatting and mounting create the directories `filesystem` and `mountpoint` in the partition. What will happen if the users change their mind and decide to use the same partition as swap space? Swap spaces have no mount points and the file `mountpoint` should be removed. Who is responsible for removing it? The udeb that allows the user to choose a file system for the partition doesn't have to know that swap-spaces have no mount points, only the udeb that provides support for swap-spaces can know that the file `mountpoint` should be removed.

In order to solve this difficulty every script that makes changes to some partition should invoke the function `update_partition` from `base.sh`. Synopsis:

    update_partition device_directory partition_id

In order to update the contents of the directory `device_directory/partition_id` the function `update_partition` executes the scripts from the directory `/lib/partman/update.d/`. Every udeb is allowed to install scripts in this directory. Their names are prefixed by two-digit numbers that control the order of the execution. The scripts from `update.d` are given several arguments. $1 is the device_directory. $2 is the number of the partition (`/dev/hda6` will have number 6). $3 is the id of the partition. $4 is the length of the partition (in bytes). $5 is the type of the partition, it can be either `primary' or `logical'. $6 is the type of the file system as known to `parted_server`, in most cases you should ignore this argument. $7 is the device name (for example `/dev/ide/host0/bus0/target0/lun0/part6`). "$8 $9 $10 $11 ..." is the name of the partition in partition tables that support partition names. Otherwise $8, $9, $10,... are not defined.

### Communication with `parted_server`

The package partman-base creates two FIFOs – `/var/lib/partman/infifo` and `/var/lib/partman/outfifo`. `Parted_server` reads instructions from `infifo` and responds by writting to `outfifo`. Consequently the clients write to `infifo` and read from `outfifo`. The function library `base.sh` contain several functions to make the communication with `parted_server` easier. Here we will omit the details, if you want to know the exact communication protocol please read how these functions are implemented.

The functions `open_infifo`, `close_infifo`, `open_outfifo` and `close_outfifo` are called without arguments. They open and close `infifo` and `outfifo` assigning them file descriptors 6 and 7 correspondingly. You do not need to use these low-level functions.

The function `write_line` prints its arguments to `outfifo`.

The function `read_line` reads from `infifo` a line, splits it in fields according to `$IFS` and assigns these fields to variables whose names are given to `read_line` as arguments. For example

    read_line x y z

reads a line from `infifo`, splits it and assigns the first field to the variable `x`, the second field to the variable `y` and the rest to the variable `z`. You see that `read_line` is used the same way as the shell operator `read`.

The function `read_paragraph` reads consequently lines from `infifo` until it reaches an empty line. It prints the read lines with the exception of the last empty line.

The function `read_list` reads lines the same way as the function `read_paragraph`. However the function `read_list` always prints only one line that is a comma-separated sequence of the lines read from `infifo`. If `read_paragraph` prints

    This is the first line
    This is the second line
    This is the third line

`read_list` prints

    This is the first line, This is the second line, This is the third line

In order to initiate a communication dialog with `parted_server` you will use the function `open_dialog`. You will invoke it in the device directory of the device you want to issue command about. The first argument of `open_dialog` is a command for `parted_server`. The rest arguments are arguments for the command.

You use the function `close_dialog` in order to terminate the communication dialog.

When you send `parted_server` an order to do some long operation (e.g. resize a file system) the user will be shown a progress bar. You may give a name to it by the function `name_progress_bar`. It may be used right before the command `open_dialog` and accepts only one argument – a template with type text that describes what is being done.

The function `log` appends its arguments to the file `/var/log/partman`. This file is used as log-file also by `parted_server`.

## The commands of `parted_server`

You should be very careful when you communicate with the `parted_server`. If `parted_server` detects any error it will exit immediately. This is safer approach then to try to resolve somehow the error. However this also means that the user will not be shown any information about what happened and why the installer freezed. The log-file `/var/log/partman` can be used to see the reasons why `parted_server` exited.

### Open a new device

Synopsis:

    cd device_directory
    open_dialog OPEN device_name
    read_line status
    close_dialog
    case $status in
        OK)
            # The device has been opened successfully
            ;;
        failed)
            # We wasn't able to open the device
            ;;
    esac

Here `device_name` can be for example `/dev/ide/host0/bus0/target0/lun0/disc`.

### Close a device

Synopsis:

    cd device_directory
    open_dialog CLOSE
    close_dialog

After this command you may not issue commands regarding the device of `device_directory`. This command does not invoke the command COMMIT.

### Does the partition exist on the disk?

Synopsis:

    cd device_directory
    open_dialog VIRTUAL partition_id
    read_line virtuality
    close_dialog
    case $virtuality in
        yes)
            # the partition does not exist on the disk
            # probably because it is newly created
            ;;
        no)
            # the partition exists on the disk
            ;;
    esac

### Remember the partition table as unchanged

Synopsis:

    cd device_directory
    open_dialog DISK_UNCHANGED
    close_dialog

After this command `parted_server` will know that the partition table in its onw internal data structures is the same as the partition table actually existing on the device. The main purpose of this command is to be used for partition tables with type `loop`.

### Report whether the partition table is changed

Synopsis:

    cd device_directory
    open_dialog IS_CHANGED
    read_line changed
    close_dialog
    case $changed in
        yes)
            # the partition table is changed
            ;;
        no)
            # the partition table is not changed
            ;;
    esac

### Dump the partitions

Synopsis:

    cd device_directory
    open_dialog DUMP
    close_dialog

This command prints in `/var/log/partition_dump` all the data regarding the device. It is used for debugging.

### Write partitioning to the disk

Synopsis:

    cd device_directory
    open_dialog COMMIT
    close_dialog

This command transfers the partitions in the device of `device_directory` from the internal structures of `parted_server` to the disk.

### Undo the changes

Synopsis:

    cd device_directory
    open_dialog UNDO
    close_dialog

This command destroys the internal data structures in `parted_server` for a device and then rereads them from the device.

### Get the partitions

Synopsis:

    cd device_directory
    open_dialog PARTITIONS
    while { read_line num id size type fs path name; [ "$id" ]; }; do
        # do something for this partition
    done
    close_dialog

The body of the loop is executed for every partition and free space. $num is the number of the partition (for example `/dev/hda6` has number 6). $id is the id of the partition. $size is the size of the partition (in bytes). If this is an active partition then $type is either `primary' or `logical'. If this is a free space then $type shows what partition can be created in it. In this case $type can be `primary', `logical', `pri/log' or `unusable'. $fs is `free' if this is a free space. Otherwise $fs is the type of the file system of this partition as known to `parted_server`. $path is a device name for the partition, for example `/dev/ide/host0/bus0/target0/lun0/part6`. $name is the name of the partition or the empty string if the partition table doesn't support partition names.

Notice that in the loop-body you may not initiate another dialog with `parted_server`. If you need this you can use the following construction instead:

    cd device_directory
    open_dialog PARTITIONS
    partitions=$(read_paragraph)
    close_dialog

    echo "$partitions" |
    while { read num id size type fs path name; [ "$id" ]; }; do
        # do something for this partition
    done

### Getting info about a partition

Synopsis:

    cd device_directory
    open_dialog PARTITION_INFO partition_id
    read_line num id size type fs path name
    close_dialog

Here `partition_id` is the id of the partition to get info. The meaning of the variables are the same as in the command PARTITIONS.

### Getting cylinder/head/sector geometry of a partition/free space

Synopsis:

    cd device_directory
    open_dialog GET_CHS partition_id
    read_line start_cyl start_head start_sector end_cyl end_head end_sector
    close_dialog

### Getting the supported partition table types

Synopsis:

    cd device_directory
    open_dialog LABEL_TYPES
    supported=$(read_list)
    close_dialog

For the result of this command `device_directory` is irrelevant. Despite this `device_directory` must be a valid device directory.

This command is used to read which types partition tables are supported by `parted_server` (i.e. by libparted). $supported is a comma-separated list of the supported types. At the time of writting the following types are supported: bsd, gpt, mac, dvh, msdos, pc98, sun and loop.

### Get the type of the disk label

Synopsis:

    cd device_directory
    open_dialog GET_LABEL_TYPE
    read_line label_type
    close_dialog
    if [ "$label_type" = unknown ]; then
        echo "The disk is unknown or it has no disk label
              or the disk label is unknown"
    else
        echo "The type of the disk label is:" "$label_type"
    fi

This command returns the type of the disk label (i.e. the partition table) of a disk. It can be used to check if there is a partition table (if not, then it is safe to create a new partition table or to use the entire disk for RAID, LVM, encrypted unit, etc).

### Create a new empty partition table

Synopsis:

    cd device_directory
    open_dialog NEW_LABEL partition_table_type
    close_dialog

This command creates in the device a new empty partition table with type `partition_table_type`. (Of course it won't be written to the disk if you don't use the command COMMIT.)

### Getting the meaningful flags for a partition

Synopsis:

    cd device_directory
    open_dialog VALID_FLAGS partition_id
    meaningful_flags=$(read_list)
    close_dialog

$meaningful_flags is a comma-separated list of the flags that are meaningful for the partition with id `partition_id`.

In order to check wether some particular flag xyz is meaningful you can use this code:

    cd device_directory
    xyz_is_meaningful=no
    open_dialog VALID_FLAGS partition_id
    while { read_line flag; [ "$flag" ]; }; do
        if [ "$flag" = xyz ]; then
            xyz_is_meaningful=yes
            # you may not use break here
        fi
    done
    close_dialog

### Getting the active flags of a partition

Synopsis:

    cd device_directory
    open_dialog GET_FLAGS partition_id
    active_flags=$(read_list)
    close_dialog

$active_flags is a comma-separated list of the flags of the partition with id `partition_id` that are in state 1. This is a sublist of the list returned by the command VALID_FLAGS.

In order to check if some partition is denoted as bootable you can use this code:

    cd device_directory
    is_bootable=no
    open_dialog GET_FLAGS partition_id
    while { read_line flag; [ "$flag" ]; }; do
        if [ "$flag" = boot ]; then
            is_bootable=yes
            # you may not use break here
        fi
    done
    close_dialog

### Set the flags of a partition

Synopsis:

    cd device_directory
    open_dialog SET_FLAGS partition_id
    for flag in all_flags_that_should_be_active; do
        write_line $flag
    done
    write_line NO_MORE
    close_dialog

All flags not listed will be unset. If conflicting flags are listed, only the one with the highest priority will be set. If you want to change the state of a single flag you should use the command SET_FLAG instead.

If you want to denote some partition as non-bootable you can use the following code:

    cd device_directory
    open_dialog GET_FLAGS partition_id
    new_flags=$(
        while { read_line flag; [ "$flag" ]; }; do
            if [ "$flag" != boot ]; then
                echo $flag
            fi
        done
    )
    close_dialog

    open_dialog SET_FLAGS partition_id
    write_line "$new_flags"
    write_line NO_MORE
    close_dialog

### Check if partition names are supported

Synopsis:

    cd device_directory
    open_dialog USES_NAMES
    read_line supported
    close_dialog
    case $supported in
        yes)
            # the partition table supports partition names
            ;;
        no)
            # the partition table doesn't support partition names
            ;;
    esac

### Set the name of a partition

Synopsis:

    cd device_directory
    open_dialog SET_NAME partition_id new_name
    close_dialog

After this command the name of `partition_id` will be `new_name`. It is an error to use this command with a partition table that doesn't support partition names.

### Get the maximum number of primary partitions

Synopsis:

    cd device_directory
    open_dialog GET_MAX_PRIMARY
    read_line primaries
    close_dialog
    logger "This disk may contain up to $primaries primary partitions"

### Check if extended and logical partitions are supported

Synopsis:

    cd device_directory
    open_dialog USES_EXTENDED
    read_line supported
    close_dialog
    case $supported in
        yes)
            # the partition table supports extended and logical partitions
            ;;
        no)
            # the partition table doesn't support extended and logical partitions
            ;;
    esac

### Get the known to `parted_server` file systems

Synopsis:

    cd device_directory
    open_dialog FILE_SYSTEM_TYPES
    known_filesystems=$(read_list)
    close_dialog

$known_filesystems is a comma-separated list of the file systems that are known to `parted_server`. You probably won't need to use this command.

### Try to detect the file system in a partition

Synopsis:

    cd device_directory
    open_dialog GET_FILE_SYSTEM partition_id
    read_line filesystem
    close_dialog
    if [ "$filesystem" = none ]; then
        # no known file system is detected
    else
        # a file system of type $filesystem is detected
    fi

### Change the filesystem of a partition

Synopsis:

    cd device_directory
    open_dialog CHANGE_FILE_SYSTEM partition_id new_filesystem
    close_dialog

libparted assigns every partition some file system. This command can be used to change this file system. The file system assigned to the partition is not necessarily the same as the actual file system. Libparted uses it to determine automatically the type of the partition in some partition tables. For example with msdos partition tables the partitions with file system `ext2' receive type 83. The partitions that are swap spaces receive type 82.

### Create a new partition

Synopsis:

    cd device_directory
    open_dialog NEW_PARTITION type fs freespace position length
    read_line num id size type fs path name
    close_dialog
    if [ "$id" ]; then
        # the partition is successfully created
    else
        # wasn't able to create the partition
    fi

type is either primary or logical. fs is the type of the file system to be assigned to the partition. freespace is the id of some free space. position is either `full', `beginning' or `end' and determines where in freespace to create the new partition. If position is not `full' then length is the length that the new partition should have (in bytes).

If the new file system is successfully created $num is the number of the created partition (for example `/dev/sda6` has number 6). $id is the id of the new partition. $size is the size of the new partition. $size is approximately length but not necessarily the same. $type and $fs are the same as type and fs. $path is a device name, for example `/dev/sda6`. $name is the name of the new partition or an empty string if the partition table doesn't support partition names.

### Delete a partition

Synopsis:

    cd device_directory
    open_dialog DELETE_PARTITION partition_id
    close_dialog

### Resize a partition

Synopsis:

    cd device_directory
    name_progress_bar some/debconf/template
    open_dialog RESIZE_PARTITION partition_id new_size
    read_line new_id
    close_dialog

This command resizes a partition. As usually `new_size` is measured in bytes. $new_id is the new id that the partition receives. The resizing is not supported always. If it fails $new_id will be the same as `partition_id`.

If the partition exists on the storage device and contains some file system, then the data in the partition will be preserved and the new partition table will be written on the storage device. When it is impossible to resize the file system, the partition will be left unresized. When the partition doesn't exist on the storage device, the new version of the partition table will not be written to it.

This command doesn't move the start of the partition but only its end.

The command `name_progress_bar` may be omitted. The debconf template must have type text. It will be used to give the user information of what is being done.

### Get resize range

Synopsis:

    cd device_directory
    open_dialog GET_RESIZE_RANGE partition_id
    read_line minimal_size current_size maximal_size
    close_dialog

This command returns the minimal and the maximal size that can be achieved by using the command RESIZE_PARTITION. $minimal_size, $current_size and $maximal_size are measured in bytes.

### Set/unset a flag of a partition

Synopsis:

    cd device_directory
    open_dialog SET_FLAG partition_id flag state
    close_dialog

This command changes the state of a single flag of a partition. It is available since partman-base 239. flag may be any partition flag name. state may be `on' or `off'. The partition table is not marked as changed if the flag is unknown, invalid for the partition or already in the desired state.

If you want to denote some partition as non-bootable you can use the following code:

    cd device_directory
    open_dialog SET_FLAG partition_id boot off
    close_dialog

## Bugs and limitations

All files and directories are assumed to not contain spaces in their names.

If the partition table supports extended and logical partitions the user won't be shown free spaces whose size is less than one cylinder.