7313ddacbfb107fe0694a41ae7002f3ecde79d80
[d-i/debian-installer.git] / doc / devel / partman-auto-recipe.txt
1 partman-auto recipe files
2
3 Contents:
4   0. Introduction
5   1. Format of the recipes
6   2. Examples
7   3. LVM specific options
8   4. Architecture specific recipes
9   5. Limitations
10   6. How the actual partition sizes are computed
11   7. Appendix
12
13 0. INTRODUCTION
14 ---------------
15
16 partman-auto is the part of the partitioner that automatically partitions
17 disks. It is controlled by recipes, which are provided in partman-auto as
18 files, but may also be provided by other udebs, or by preseeding. This
19 document explains the format of the recipes and how to use them.
20
21
22 1. FORMAT OF THE RECIPES
23 ------------------------
24
25 All new lines and tabs in the recipe are converted to spaces.
26 Then two or more consecutive spaces are converted to one space.
27 Almost all tokens must be separated by spaces.  An important exception
28 is the opening curly bracket ("{"); before it there must be _no_
29 space.
30
31 In the following rules we denote spaces by "_".
32
33 <recipe>::=<header>_<partitions>
34
35 <header>::=<simple name>|<debconf name>
36
37 <simple name>::=<name>_:
38
39 <name> can be for example "Multi user system".
40
41 <debconf name>::=<debconf template>_::
42
43 The purpose of <debconf name> is to allow translation of the names of
44 the recipes into different languages.
45
46 <partitions>::=<partition>|<partition>_<partitions>
47
48 <partition>::=<limits>_<specifiers>_.
49
50 <limits>::=<minimal size>_<priority>_<maximal size>_<parted fs>
51
52 <minimal size> is the minimal allowed size of the partition in
53 megabytes.  It is rounded to cylinder size, so if you make <minimal
54 size> to be 20 MB and the cylinder size is 12MB, then it is possible
55 for the partition to be only 12MB.  These sizes may also be given as
56 a percentage, which makes the size be that percentage of the system's
57 total RAM, or (as of partman-auto 87) as a number plus a percentage
58 (e.g. "2000+50%"), which makes the size be that number plus that
59 percentage of the system's total RAM.
60
61 <priority> is some size usually between <minimal size> and <maximal
62 size>.  It determines the priority of this partition in the contest
63 with the other partitions for size.  Notice that if <priority> is too
64 small (relative to the priority of the other partitions) then this
65 partition will have size close to <minimal size>.  That's why it is
66 recommended to give small partitions a <priority> larger than their
67 <maximal size>.
68
69 <maximal size> is the maximal size for the partition, i.e. a limit
70 size such that there is no sense to make this partition larger.
71 The special value "-1" is used to indicate unlimited partition size.
72
73 <parted fs> is the file system as known to parted of this partition.
74 It may be $default_filesystem to use partman's default (currently ext3).
75
76
77 <specifiers>::=<specifier>|<specifier>_<specifiers>
78
79 <specifier>::=<internal specifier>|<regular specifier>|<type specifier>
80
81 <internal specifier>::=$primary{_}|$bootable{_}|$default_filesystem{_}
82
83 $primary{_} says that the partition should be primary (if possible).
84 $bootable{_} says that the bootable flag will be set.
85 $default_filesystem{_} says that partman's default filesystem (currently
86 ext3) should be used.
87
88 <regular specifier>::=<file name>{ <file contents> }
89
90 <file name> is a file to be created in the directory of the partition
91 in partman's filesystem info. (See section 2.4 of the partman manual
92 for details.)
93 <file contents> is the information to write in this file.
94
95 <type specifier>::=$lvmok{_}|$defaultignore{_}|$lvmignore{_}
96
97 $lvmok{_}
98         Indicates that the partition is permitted to be an LVM logical 
99         volume should an LVM partitioning scheme be in use.
100 $defaultignore{_}
101         Used to void a partition definition so that it is ignored in the
102         default case. That is to say it will be valid in the LVM case.
103 $lvmignore{_}
104         Used to void a partition definition so that it is ignored in the
105         LVM case. That is to say it will be valid in the default case.
106
107 The specifiers defaultignore and lvmignore allow one recipe to define different 
108 handling of say the /boot partition between an LVM partitioning scheme and a 
109 non-LVM scheme.
110
111 2. EXAMPLES
112 -----------
113
114 Here is a very simple recipe that creates a swap partition and uses the
115 rest of the disk for one large root filesystem.
116
117 partman-auto/text/atomic_scheme ::
118
119 500 10000 1000000 ext3
120         $primary{ }
121         $bootable{ }
122         method{ format }
123         format{ }
124         use_filesystem{ }
125         filesystem{ ext3 }
126         mountpoint{ / } .
127
128 64 512 300% linux-swap
129         method{ swap }
130         format{ } .
131
132 Here the root partition must be at least 500 mb, and has effectively no
133 maximum size. The swap partition ranges from 64 mb to 3 times the system's
134 ram.
135
136 Note the use of $bootable{ } to make the partition bootable, and $primary{ }
137 to mark it as the primary partition.
138
139 The specifiers used in this example are:
140 method{ format }
141         Used to make the partition be formatted. For swap partitions,
142         change it to "swap". To create a new partition but do not
143         format it, change "format" to "keep" (such a partition can be
144         used to reserve for future use some disk space).
145 format{ }
146         Also needed to make the partition be formatted.
147 use_filesystem{ }
148         Specifies that the partition has a filesystem on it.
149 filesystem{ ext3 }
150         Specifies the filesystem to put on the partition.
151 mountpoint{ / }
152         Where to mount the partition.
153
154 It is also possible to specify mount options. For example, to specify
155 "nodev,ro" for a partition, add the following lines for that partition:
156         options/nodev{ nodev }
157         options/ro{ ro }
158
159 It is also possible to specify filesystem labels, for filesystems that
160 support labels (e.g. ext2, ext3). For example, to specify a label of
161 "fred" for a partition, add the following line for that partition:
162         label{ fred }
163 Note that the partition must be one that will be reformatted during
164 the installation, i.e. one for which you have specified
165         method{ format }
166
167 Here is another example; this time there is a smaller root partition, and a
168 separate /home partition.
169
170 partman-auto/text/home_scheme ::
171
172 300 4000 7000 ext3
173         $primary{ }
174         $bootable{ }
175         method{ format }
176         format{ }
177         use_filesystem{ }
178         filesystem{ ext3 }
179         mountpoint{ / } .
180
181 64 512 300% linux-swap
182         method{ swap }
183         format{ } .
184
185 100 10000 1000000000 ext3
186         method{ format }
187         format{ }
188         use_filesystem{ }
189         filesystem{ ext3 }
190         mountpoint{ /home } .
191
192 Notice that the partitions will be created in the order they are defined
193 in the recipe.
194
195 3. LVM SPECIFIC OPTIONS
196 -----------------------
197
198 When using the "lvm" autopartioning method, specific options are recognized in
199 the recipe. Those enable multiple disks to be partitioned at once, specifying
200 partitions holding Physical Volumes, which Volume Group a Physical Volume
201 holds, in which Volume Group a Logical Volume is put and the name of the
202 Logical Volumes.
203
204 Multiple disks can also be partitioned at the same time. Those must be
205 specified in partman-auto/disk. Partitions that are neither on a Logical
206 Volume, nor have a specific device specified (e.g. /boot) will default on
207 being on the first disk.
208     
209 To explicitly declare a Physical Volume, define a partition as follows:
210
211 100 1000 1000000000 ext3
212         $defaultignore{ }
213         $primary{ }
214         method{ lvm }
215         device{ /dev/hdb }
216         vg_name{ vg00 } .
217     
218 Both "device{ ... }" and "vg_name{ }" are optional.
219     
220 The device *must* be listed in partman-auto/disk.
221     
222 The Volume Group holding a Logical Volume can be specified using
223 "in_vg{ }", e.g.:
224
225 96 512 300% linux-swap
226         $lvmok{ }
227         in_vg{ vg00 }
228         lv_name{ myswap }
229         method{ swap }
230         format{ } .
231
232 "lv_name{ }" specifies the name of the Logical Volume being created.
233
234 4. ARCHITECTURE DEPENDENT RECIPES
235 ---------------------------------
236
237 Some architectures have specific requirements for their partitions.
238 For example many of them require special partitions to support
239 bootloading.
240
241 For example, newworld powerpc machines need a newworld boot partition at
242 the start of the disk. Here is an example fragment of a recipe file to
243 create one; it should come before other partitions in a recipe. Notice that
244 the partition is not formatted.
245
246 1 1 1 hfs
247         $bootable{ }
248         method{ newworld } .
249
250 Another example is a netwinder, which requires a small /boot partition
251 formated in revision 0 ext2.
252
253 50 500 100 ext2
254         $primary{ }
255         $bootable{ }
256         method{ format }
257         format{ }
258         use_filesystem{ }
259         filesystem{ ext2r0 }
260         mountpoint{ /boot } .
261
262 And finally, an example of how to set up the efi boot partition needed on
263 ia64.
264
265 100 100 150 fat16
266         $primary{ }
267         method{ efi }
268         format{ } .
269
270 For other examples, see the architecture-specific recipes in partman-auto.
271
272
273 5. LIMITATIONS
274 --------------
275
276 Due to limitation of the algorithms in partman-auto, there must be at
277 least one partition with high maximal size so that the whole free
278 space can be used.  Usually you can give the partition containing
279 /home a maximal size 1000000000 which is high enough for the present
280 storage devices. If the large /home is not an option for you, you can
281 also define in the recipe one additional partition with size
282 1000000000, method "keep" and leave it unmounted.  When the
283 installation completes you can remove it.
284
285 Do not use higher than 1000000000 numbers because the shell arithmetic
286 is limited to 31 bits (on i386).
287
288
289 6. HOW THE ACTUAL PARTITION SIZES ARE COMPUTED
290 ----------------------------------------------
291
292 Suppose we have to create N partitions and min[i], max[i] and
293 priority[i] are the minimal size, the maximal size and the priority of
294 the partition #i as described in section 1.
295
296 Let free_space be the size of the free space to partition.
297
298 Then do the following:
299
300 for(i=1;i<=N;i++) {
301    factor[i] = priority[i] - min[i];
302 }
303 ready = FALSE;
304 while (! ready) {
305    minsum = min[1] + min[2] + ... + min[N];
306    factsum = factor[1] + factor[2] + ... + factor[N];
307    ready = TRUE;
308    for(i=1;i<=N;i++) {
309       x = min[i] + (free_space - minsum) * factor[i] / factsum;
310       if (x > max[i])
311          x = max[i];
312       if (x != min[i]) {
313          ready = FALSE;
314          min[i] = x;
315       }
316    }
317 }
318
319 Then min[i] will be the size of partition #i.
320
321
322 7. APPENDIX
323 -----------
324
325 On May 25th 2004, it was noted that on i386 systems, the very minimum size of
326 a Debian installation on a classical (/, /usr, /usr, /home) setup was:
327 48MB on / (6MB on /boot)
328 77MB on /usr
329 17MB on /var
330 It is thus wise to use minimum values with this consideration in mind.
331
332 #261244: 70MB are required for /var
333 #265290: 1.8GB are not enough for / with desktop