[d-i/debian-installer.git] / doc / devel / partman-auto-recipe.txt

partman-auto recipe files

Contents:
  0. Introduction
  1. Format of the recipes
  2. Examples
  3. LVM specific options
  4. Architecture specific recipes
  5. Limitations
  6. How the actual partition sizes are computed
  7. Appendix

0. INTRODUCTION
---------------

partman-auto is the part of the partitioner that automatically partitions
disks. It is controlled by recipes, which are provided in partman-auto as
files, but may also be provided by other udebs, or by preseeding. This
document explains the format of the recipes and how to use them.


1. FORMAT OF THE RECIPES
------------------------

All new lines and tabs in the recipe are converted to spaces.
Then two or more consecutive spaces are converted to one space.
Almost all tokens must be separated by spaces.  An important exception
is the opening curly bracket ("{"); before it there must be _no_
space.

In the following rules we denote spaces by "_".

<recipe>::=<header>_<partitions>

<header>::=<simple name>|<debconf name>

<simple name>::=<name>_:

<name> can be for example "Multi user system".

<debconf name>::=<debconf template>_::

The purpose of <debconf name> is to allow translation of the names of
the recipes into different languages.

<partitions>::=<partition>|<partition>_<partitions>

<partition>::=<limits>_<specifiers>_.

<limits>::=<minimal size>_<priority>_<maximal size>_<parted fs>

<minimal size> is the minimal allowed size of the partition in
megabytes.  It is rounded to cylinder size, so if you make <minimal
size> to be 20 MB and the cylinder size is 12MB, then it is possible
for the partition to be only 12MB.  These sizes may also be given as
a percentage, which makes the size be that percentage of the system's
total RAM, or (as of partman-auto 87) as a number plus a percentage
(e.g. "2000+50%"), which makes the size be that number plus that
percentage of the system's total RAM.

<priority> is some size usually between <minimal size> and <maximal
size>.  It determines the priority of this partition in the contest
with the other partitions for size.  Notice that if <priority> is too
small (relative to the priority of the other partitions) then this
partition will have size close to <minimal size>.  That's why it is
recommended to give small partitions a <priority> larger than their
<maximal size>.

<maximal size> is the maximal size for the partition, i.e. a limit
size such that there is no sense to make this partition larger.
The special value "-1" is used to indicate unlimited partition size.

<parted fs> is the file system as known to parted of this partition.
It may be $default_filesystem to use partman's default (currently ext3).


<specifiers>::=<specifier>|<specifier>_<specifiers>

<specifier>::=<internal specifier>|<regular specifier>|<type specifier>

<internal specifier>::=$primary{_}|$bootable{_}|$default_filesystem{_}

$primary{_} says that the partition should be primary (if possible).
$bootable{_} says that the bootable flag will be set.
$default_filesystem{_} says that partman's default filesystem (currently
ext3) should be used.

<regular specifier>::=<file name>{ <file contents> }

<file name> is a file to be created in the directory of the partition
in partman's filesystem info. (See section 2.4 of the partman manual
for details.)
<file contents> is the information to write in this file.

<type specifier>::=$lvmok{_}|$defaultignore{_}|$lvmignore{_}

$lvmok{_}
        Indicates that the partition is permitted to be an LVM logical 
        volume should an LVM partitioning scheme be in use.
$defaultignore{_}
        Used to void a partition definition so that it is ignored in the
        default case. That is to say it will be valid in the LVM case.
$lvmignore{_}
        Used to void a partition definition so that it is ignored in the
        LVM case. That is to say it will be valid in the default case.

The specifiers defaultignore and lvmignore allow one recipe to define different 
handling of say the /boot partition between an LVM partitioning scheme and a 
non-LVM scheme.

2. EXAMPLES
-----------

Here is a very simple recipe that creates a swap partition and uses the
rest of the disk for one large root filesystem.

partman-auto/text/atomic_scheme ::

500 10000 1000000 ext3
        $primary{ }
        $bootable{ }
        method{ format }
        format{ }
        use_filesystem{ }
        filesystem{ ext3 }
        mountpoint{ / } .

64 512 300% linux-swap
        method{ swap }
        format{ } .

Here the root partition must be at least 500 mb, and has effectively no
maximum size. The swap partition ranges from 64 mb to 3 times the system's
ram.

Note the use of $bootable{ } to make the partition bootable, and $primary{ }
to mark it as the primary partition.

The specifiers used in this example are:
method{ format }
        Used to make the partition be formatted. For swap partitions,
        change it to "swap". To create a new partition but do not
        format it, change "format" to "keep" (such a partition can be
        used to reserve for future use some disk space).
format{ }
        Also needed to make the partition be formatted.
use_filesystem{ }
        Specifies that the partition has a filesystem on it.
filesystem{ ext3 }
        Specifies the filesystem to put on the partition.
mountpoint{ / }
        Where to mount the partition.

It is also possible to specify mount options. For example, to specify
"nodev,ro" for a partition, add the following lines for that partition:
        options/nodev{ nodev }
        options/ro{ ro }

It is also possible to specify filesystem labels, for filesystems that
support labels (e.g. ext2, ext3). For example, to specify a label of
"fred" for a partition, add the following line for that partition:
        label{ fred }
Note that the partition must be one that will be reformatted during
the installation, i.e. one for which you have specified
        method{ format }

Here is another example; this time there is a smaller root partition, and a
separate /home partition.

partman-auto/text/home_scheme ::

300 4000 7000 ext3
        $primary{ }
        $bootable{ }
        method{ format }
        format{ }
        use_filesystem{ }
        filesystem{ ext3 }
        mountpoint{ / } .

64 512 300% linux-swap
        method{ swap }
        format{ } .

100 10000 1000000000 ext3
        method{ format }
        format{ }
        use_filesystem{ }
        filesystem{ ext3 }
        mountpoint{ /home } .

Notice that the partitions will be created in the order they are defined
in the recipe.

3. LVM SPECIFIC OPTIONS
-----------------------

When using the "lvm" autopartioning method, specific options are recognized in
the recipe. Those enable multiple disks to be partitioned at once, specifying
partitions holding Physical Volumes, which Volume Group a Physical Volume
holds, in which Volume Group a Logical Volume is put and the name of the
Logical Volumes.

Multiple disks can also be partitioned at the same time. Those must be
specified in partman-auto/disk. Partitions that are neither on a Logical
Volume, nor have a specific device specified (e.g. /boot) will default on
being on the first disk.
    
To explicitly declare a Physical Volume, define a partition as follows:

100 1000 1000000000 ext3
        $defaultignore{ }
        $primary{ }
        method{ lvm }
        device{ /dev/hdb }
        vg_name{ vg00 } .
    
Both "device{ ... }" and "vg_name{ }" are optional.
    
The device *must* be listed in partman-auto/disk.
    
The Volume Group holding a Logical Volume can be specified using
"in_vg{ }", e.g.:

96 512 300% linux-swap
        $lvmok{ }
        in_vg{ vg00 }
        lv_name{ myswap }
        method{ swap }
        format{ } .

"lv_name{ }" specifies the name of the Logical Volume being created.

4. ARCHITECTURE DEPENDENT RECIPES
---------------------------------

Some architectures have specific requirements for their partitions.
For example many of them require special partitions to support
bootloading.

For example, newworld powerpc machines need a newworld boot partition at
the start of the disk. Here is an example fragment of a recipe file to
create one; it should come before other partitions in a recipe. Notice that
the partition is not formatted.

1 1 1 hfs
        $bootable{ }
        method{ newworld } .

Another example is a netwinder, which requires a small /boot partition
formated in revision 0 ext2.

50 500 100 ext2
        $primary{ }
        $bootable{ }
        method{ format }
        format{ }
        use_filesystem{ }
        filesystem{ ext2r0 }
        mountpoint{ /boot } .

And finally, an example of how to set up the efi boot partition needed on
ia64.

100 100 150 fat16
        $primary{ }
        method{ efi }
        format{ } .

For other examples, see the architecture-specific recipes in partman-auto.


5. LIMITATIONS
--------------

Due to limitation of the algorithms in partman-auto, there must be at
least one partition with high maximal size so that the whole free
space can be used.  Usually you can give the partition containing
/home a maximal size 1000000000 which is high enough for the present
storage devices. If the large /home is not an option for you, you can
also define in the recipe one additional partition with size
1000000000, method "keep" and leave it unmounted.  When the
installation completes you can remove it.

Do not use higher than 1000000000 numbers because the shell arithmetic
is limited to 31 bits (on i386).


6. HOW THE ACTUAL PARTITION SIZES ARE COMPUTED
----------------------------------------------

Suppose we have to create N partitions and min[i], max[i] and
priority[i] are the minimal size, the maximal size and the priority of
the partition #i as described in section 1.

Let free_space be the size of the free space to partition.

Then do the following:

for(i=1;i<=N;i++) {
   factor[i] = priority[i] - min[i];
}
ready = FALSE;
while (! ready) {
   minsum = min[1] + min[2] + ... + min[N];
   factsum = factor[1] + factor[2] + ... + factor[N];
   ready = TRUE;
   for(i=1;i<=N;i++) {
      x = min[i] + (free_space - minsum) * factor[i] / factsum;
      if (x > max[i])
         x = max[i];
      if (x != min[i]) {
         ready = FALSE;
         min[i] = x;
      }
   }
}

Then min[i] will be the size of partition #i.


7. APPENDIX
-----------

On May 25th 2004, it was noted that on i386 systems, the very minimum size of
a Debian installation on a classical (/, /usr, /usr, /home) setup was:
48MB on / (6MB on /boot)
77MB on /usr
17MB on /var
It is thus wise to use minimum values with this consideration in mind.

#261244: 70MB are required for /var
#265290: 1.8GB are not enough for / with desktop