Chapter 3. Package interrelations

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:

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.^[1] 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'). ^[2] 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.^[3] 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.

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.

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 Section 3.1, “Basics”. 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^[4].

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 usualy 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 Section 4.4, “Updating partition directories”) 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.

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 Section 3.1, “Basics”). 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'.

Finaly, 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 Section 4.4, “Updating partition directories”) 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.