1SCHROOT.CONF(5) Debian sbuild SCHROOT.CONF(5)
2
6 schroot.conf - chroot definition file for schroot
7
9 schroot.conf is a plain UTF-8 text file, describing the chroots avail‐
10 able for use with schroot.
11 Comments are introduced following a ‘#’ (“hash”) character at the
13 beginning of a line, or following any other text. All text right of
14 the ‘#’ is treated as a comment.
15 The configuration format is an INI-style format, split into groups of
17 key-value pairs separated by section names in square brackets.
18 General options
20 A chroot is defined as a group of key-value pairs, which is started by
21 a name in square brackets on a line by itself. The file may contain
22 multiple groups which therefore define multiple chroots.
23 A chroot definition is started by the name of the chroot in square
25 brackets. For example,
26 [sid]
28 This is then followed by several key-value pairs, one per line:
30 type=type
32 The type of the chroot. Valid types are ‘plain’, ‘directory’,
33 ‘file’, ‘loopback’, ‘block-device’, ‘btrfs-snapshot’ and
34 ‘lvm-snapshot’. If empty or omitted, the default type is
35 ‘plain’. Note that ‘plain’ chroots do not run setup scripts and
36 mount filesystems; ‘directory’ is recommended (see “Plain and
37 directory chroots”, below).
38 description=description
40 A short description of the chroot. This may be localised for
41 different languages; see the section “Localisation” below.
42 priority=number
44 Set the priority of a chroot. number is a positive integer
45 indicating whether a distribution is older than another. For
46 example, “oldstable” and “oldstable-security” might be ‘0’,
47 while “stable” and “stable-security” are ‘1’, “testing” is ‘2’
48 and “unstable” is ‘3’. The values are not important, but the
49 difference between them is. This option is deprecated and no
50 longer used by schroot, but is still permitted to be used; it
51 will be obsoleted and removed in a future release.
52 message-verbosity=verbosity
54 Set the verbosity of messages printed by schroot when setting
55 up, running commands and cleaning up the chroot. Valid settings
56 are ‘quiet’ (suppress most messages), ‘normal’ (the default) and
57 ‘verbose’ (show all messages). This setting is overridden by
58 the options --quiet and --verbose.
59 users=user1,user2,...
61 A comma-separated list of users which are allowed access to the
62 chroot. If empty or omitted, no users will be allowed access
63 (unless a group they belong to is also specified in groups).
64 groups=group1,group2,...
66 A comma-separated list of groups which are allowed access to the
67 chroot. If empty or omitted, no groups of users will be allowed
68 access.
69 root-users=user1,user2,...
71 A comma-separated list of users which are allowed password-less
72 root access to the chroot. If empty or omitted, no users will
73 be allowed root access without a password (but if a user or a
74 group they belong to is in users or groups, respectively, they
75 may gain access with a password). See the section “Security”
76 below.
77 root-groups=group1,group2,...
79 A comma-separated list of groups which are allowed password-less
80 root access to the chroot. If empty or omitted, no users will
81 be allowed root access without a password (but if a user or a
82 group they belong to is in users or groups, respectively, they
83 may gain access with a password). See the section “Security”
84 below.
85 aliases=alias1,alias2,...
87 A comma-separated list of aliases (alternate names) for this
88 chroot. For example, a chroot named “sid” might have an ‘unsta‐
89 ble’ alias for convenience.
90 run-setup-scripts=true|false
92 Set whether chroot setup scripts will be run. The default is to
93 run setup scripts for all chroot types except ‘plain’. Setup
94 scripts are required to mount and configure the chroot environ‐
95 ment. This option is deprecated and no longer used by schroot,
96 but is still permitted to be used; it will be obsoleted and
97 removed in a future release.
98 run-exec-scripts=true|false Set whether chroot
100 execution scripts will be run. The default is the same as the
101 default for the run-setup-scripts key. This option was called
102 run-session-scripts in versions prior to 0.2.5. This option is
103 deprecated and no longer used by schroot, but is still permitted
104 to be used; it will be obsoleted and removed in a future
105 release.
106 script-config=filename
108 The behaviour of the chroot setup scripts may be customised on a
109 per-chroot basis by providing a shell script which the scripts
110 will source. The filename is relative to /etc/schroot. The
111 default filename is ‘default/config’. Alternatives are ‘mini‐
112 mal/config’ (minimal configuration), ‘desktop/config’ (for run‐
113 ning desktop applications in the chroot, making more functional‐
114 ity from the host system available in the chroot) and
115 ‘sbuild/config’ (for using the chroot for Debian package build‐
116 ing).
117 Desktop users should note that the fstab file desktop/fstab will
119 need editing if you use gdm3. The preserve-environment key
120 should also be set to ‘true’ so that the environment is pre‐
121 served inside the chroot.
122 If none of the configuration profiles provided above meet your
124 needs, then they may be edited to further customise them, and/or
125 copied and used as a template for entirely new profiles. Set‐
126 tings for specific chroots may also be set in a single script by
127 using conditionals checking the chroot name and/or type. Note
128 that the script will be sourced once for each and every script
129 invocation, and must be idempotent. The file format is docu‐
130 mented in schroot-script-config(5).
131 command-prefix=command,option1,option2,...
133 A comma-separated list of a command and the options for the com‐
134 mand. This command and its options will be prefixed to all com‐
135 mands run inside the chroot.
136 personality=persona
138 Set the personality (process execution domain) to use. This
139 option is useful when using a 32-bit chroot on 64-bit system,
140 for example. Valid options on Linux are ‘bsd’, ‘hpux’,
141 ‘irix32’, ‘irix64’, ‘irixn32’, ‘iscr4’, ‘linux’, ‘linux32’,
142 ‘linux_32bit’, ‘osf4’, ‘osr5’, ‘riscos’, ‘scorvr3’, ‘solaris’,
143 ‘sunos’, ‘svr4’, ‘uw7’, ‘wysev386’, and ‘xenix’. The default
144 value is ‘linux’. There is also the special option ‘undefined’
145 (personality not set). For a 32-bit chroot on a 64-bit system,
146 ‘linux32’ is the option required. The only valid option for
147 non-Linux systems is ‘undefined’. The default value for non-
148 Linux systems is ‘undefined’.
149 preserve-environment=true|false
151 By default, the environment will not be preserved inside the
152 chroot, instead a minimal environment will be used. Set to true
153 to always preserve the environment. This is useful for example
154 when running X applications inside the chroot, which need the
155 environment to function correctly. The environment may also be
156 preserved using the --preserve-environment option.
157 environment-filter=regex
159 The environment to be set in the chroot will be filtered in
160 order to remove environment variables which may pose a security
161 risk. Any environment variable matching the specified POSIX
162 extended regular expression will be removed prior to executing
163 any command in the chroot.
164 Potentially dangerous environment variables are removed for
166 safety by default using the following regular expression:
167 “^(BASH_ENV|CDPATH|ENV|HOSTALIASES|IFS|KRB5_CONFIG|KRBCONFDIR
168 |KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMAIN|NLSPATH|PATH_LOCALE
169 |RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TERMPATH)$”.
170 Plain and directory chroots
172 Chroots of type ‘plain’ or ‘directory’ are directories accessible in
173 the filesystem. The two types are equivalent except for the fact that
174 directory chroots run setup scripts, whereas plain chroots do not. In
175 consequence, filesystems such as /proc are not mounted in plain
176 chroots; it is the responsibility of the system administrator to con‐
177 figure such chroots by hand, whereas directory chroots are automati‐
178 cally configured. Additionally, directory chroots implement the
179 filesystem union chroot options (see “Filesystem Union chroot options”,
180 below).
181 These chroot types have an additional (mandatory) configuration option:
183 directory=directory
185 The directory containing the chroot environment. This is where
186 the root will be changed to when executing a login shell or a
187 command. The directory must exist and have read and execute
188 permissions to allow users access to it. Note that on Linux
189 systems it will be bind-mounted elsewhere for use as a chroot;
190 the directory for ‘plain’ chroots is mounted with the --rbind
191 option to mount(8), while for ‘directory’ chroots --bind is used
192 instead so that sub-mounts are not preserved (they should be set
193 in the fstab file just like in /etc/fstab on the host).
194 This option was previously named location, but was renamed to
196 avoid ambiguity with the option by the same name for mountable
197 chroot options (see “Mountable chroot options”, below). The
198 name location is deprecated, but still valid; it will be obso‐
199 leted and removed in a future release. It is recommended to use
200 directory rather than location. Note that it is an error to use
201 both directory and location at the same time.
202 File chroots
204 Chroots of type ‘file’ are files on the current filesystem containing
205 an archive of the chroot files. They implement the source chroot
206 options (see “Source chroot options”, below) and have an additional
207 (mandatory) configuration option:
208 file=filename
210 The file containing the archived chroot environment. This must
211 be a tar (tape archive), optionally compressed with gzip or
212 bzip2, or a zip archive. The file extensions used to determine
213 the type are are .tar, .tar.gz, .tar.bz2, .tgz, .tbz and .zip.
214 This file must be owned by the root user, and not be writable by
215 other.
216 location=path
218 This is the path to the chroot inside the archive. For example,
219 if the archive contains a chroot in /squeeze, you would specify
220 “/squeeze” here. If the chroot is the only thing in the ar‐
221 chive, i.e. / is the root filesystem for the chroot, this option
222 should be left blank, or omitted entirely.
223 Loopback chroots
225 Chroots of type ‘loopback’ are a filesystem available as a file on
226 disk, accessed via a loopback mount. The file will be loopback mounted
227 and unmounted on demand. Loopback chroots implement the mountable
228 chroot and filesystem union chroot options (see “Mountable chroot
229 options” and “Filesystem Union chroot options”, below), plus an addi‐
230 tional option:
231 file=filename
233 This is the filename of the file containing the filesystem,
234 including the absolute path. For example “/srv/chroot/sid”.
235 Block device chroots
237 Chroots of type ‘block-device’ are a filesystem available on an
238 unmounted block device. The device will be mounted and unmounted on
239 demand. Block device chroots implement the mountable chroot and
240 filesystem union chroot options (see “Mountable chroot options” and
241 “Filesystem Union chroot options”, below), plus an additional option:
242 device=device
244 This is the device name of the block device, including the abso‐
245 lute path. For example, “/dev/sda5”.
246 Btrfs snapshot chroots
248 Chroots of type ‘btrfs-snapshot’ are a Btrfs snapshot created from an
249 existing Btrfs subvolume on a mounted Btrfs filesystem. A snapshot
250 will be created from this source subvolume on demand at the start of a
251 session, and then the snapshot will be mounted. At the end of the ses‐
252 sion, the snapshot will be unmounted and deleted.
253 For each chroot of this type, a corresponding ‘directory’ chroot will
255 be created, with a -source suffix appended to the chroot name and all
256 its aliases; this is for convenient access to the source subvolume.
257 This chroot type implements the source chroot options (see “Source
258 chroot options”, below), plus these additional options:
259 btrfs-source-subvolume=directory
261 The directory containing the source subvolume.
262 btrfs-snapshot-directory=directory
264 The directory in which to store the snapshots of the above
265 source subvolume.
266 LVM snapshot chroots
268 Chroots of type ‘lvm-snapshot’ are a filesystem available on an LVM
269 logical volume (LV). A snapshot LV will be created from this LV on
270 demand, and then the snapshot will be mounted. At the end of the ses‐
271 sion, the snapshot LV will be unmounted and removed. For each chroot
272 of this type, a corresponding ‘block-device’ chroot will be created,
273 with a -source suffix appended to the chroot name and all its aliases;
274 this is for convenient access to the source device.
275 They implement the source chroot options (see “Source chroot options”,
277 below), and all the options for ‘block-device’, plus an additional
278 option:
279 lvm-snapshot-options=snapshot_options
281 Snapshot options. These are additional options to pass to
282 lvcreate(8). For example, “-L 2g” to create a snapshot 2 GiB in
283 size. Note: the LV name (-n), the snapshot option (-s) and the
284 original LV path may not be specfied here; they are set automat‐
285 ically by schroot.
286 Source chroot options
288 Some chroots implement source chroots. These are chroots which auto‐
289 matically create a copy of themselves before use, and are usually ses‐
290 sion managed. These chroots additionally provide an extra chroot with
291 a -source suffix added to their name, to allow access to the original
292 data, and to aid in chroot maintenance. These chroots provide the fol‐
293 lowing additional options:
294 source-clone=true|false
296 Set whether the source chroot should be automatically cloned
297 (created) for this chroot. The default is true to automatically
298 clone, but if desired may be disabled by setting to false. If
299 disabled, the source chroot will be inaccessible.
300 source-users=user1,user2,...
302 A comma-separated list of users which are allowed access to the
303 source chroot. If empty or omitted, no users will be allowed
304 access. This will become the users option in the source chroot.
305 source-groups=group1,group2,...
307 A comma-separated list of groups which are allowed access to the
308 source chroot. If empty or omitted, no users will be allowed
309 access. This will become the groups option in the source
310 chroot.
311 source-root-users=user1,user2,...
313 A comma-separated list of users which are allowed password-less
314 root access to the source chroot. If empty or omitted, no users
315 will be allowed root access without a password (but if a user is
316 in users, they may gain access with a password). This will
317 become the root-users option in the source chroot. See the sec‐
318 tion “Security” below.
319 source-root-groups=group1,group2,...
321 A comma-separated list of groups which are allowed password-
322 less root access to the source chroot. If empty or omitted, no
323 users will be allowed root access without a password (but if a
324 user's group is in groups, they may gain access with a pass‐
325 word). This will become the root-groups option in the source
326 chroot. See the section “Security” below.
327 Mountable chroot options
329 Some chroots implement device mounting. These are chroots which
330 require the mounting of a device in order to access the chroot. These
331 chroots provide the following additional options:
332 mount-options=options
334 Mount options for the block device. These are additional
335 options to pass to mount(8). For example, “-o
336 atime,sync,user_xattr”.
337 location=path
339 This is the path to the chroot inside the filesystem on the
340 device. For example, if the filesystem contains a chroot in
341 /chroot/sid, you would specify “/chroot/sid” here. If the
342 chroot is the only thing on the filesystem, i.e. / is the root
343 filesystem for the chroot, this option should be left blank, or
344 omitted entirely.
345 Filesystem Union chroot options
347 Some chroots allow for the creation of a session using filesystem
348 unions to overlay the original filesystem with a separate writable
349 directory. The original filesystem is read-only, with any modifica‐
350 tions made to the filesystem made in the overlying writable directory,
351 leaving the original filesystem unchanged. A union permits multiple
352 sessions to access and make changes to a single chroot simultaneously,
353 while keeping the changes private to each session. To enable this fea‐
354 ture, set union-type to any supported value. If enabled, the chroot
355 will also be a source chroot, which will provide additional options
356 (see “Source chroot options”, above). All entries are optional.
357 union-type=type
359 Set the union filesystem type. Currently supported filesystems
360 are ‘aufs’ and ‘unionfs’. The default is ‘none’, which disables
361 this feature.
362 union-mount-options=options
364 Union filesystem mount options (branch configuration), used for
365 mounting the union filesystem specified with union-type. This
366 replaces the complete “-o” string for mount and allows for the
367 creation of complex filesystem unions. Note that ‘aufs’ and
368 ‘unionfs’ have different supported mount options. Note: One can
369 use the variables “${CHROOT_UNION_OVERLAY_DIRECTORY}” and
370 “${CHROOT_UNION_UNDERLAY_DIRECTORY}” to refer to the writable
371 overlay session directory and read-only underlying directory
372 which are to form the union. See schroot-setup(5) for a com‐
373 plete variable list.
374 union-overlay-directory=directory
376 Specify the directory where the writeable overlay session direc‐
377 tories will be created. The default is ‘/var/lib/sch‐
378 root/union/overlay’.
379 union-underlay-directory=directory
381 Specify the directory where the read-only underlying directories
382 will be created. The default is ‘/var/lib/schroot/union/under‐
383 lay’.
384 Localisation
386 Some keys may be localised in multiple languages. This is achieved by
387 adding the locale name in square brackets after the key name. For
388 example:
389 description[en_GB]=British English translation
390 This will localise the description key for the en_GB locale.
392 description[fr]=French translation
393 This will localise the description key for all French locales.
395
397 Note that giving untrusted users root access to chroots is a serious
398 security risk! Although the untrusted user will only have root access
399 to files inside the chroot, in practice there are many obvious ways of
400 breaking out of the chroot and of disrupting services on the host sys‐
401 tem. As always, this boils down to trust. Don't give chroot root
402 access to users you would not trust with root access to the host sys‐
403 tem.
404
406 # Sample configuration
407 [sid]
409 type=plain
410 description=Debian unstable
411 description[fr_FR]=Debian instable
412 directory=/srv/chroot/sid
413 priority=3
414 users=jim
415 groups=sbuild
416 root-users=rleigh
417 aliases=unstable,default
418 [etch]
420 type=block-device
421 description=Debian testing (32-bit)
422 priority=2
423 groups=users
424 #groups=sbuild-security
425 aliases=testing
426 device=/dev/hda_vg/etch_chroot
427 mount-options=-o atime
428 personality=linux32
429 [sid-file]
431 type=file
432 description=Debian sid file-based chroot
433 priority=3
434 groups=sbuild
435 file=/srv/chroots/sid.tar.gz
436 [sid-snapshot]
438 type=lvm-snapshot
439 description=Debian unstable LVM snapshot
440 priority=3
441 groups=sbuild
442 users=rleigh
443 source-root-users=rleigh
444 source-root-groups=admin
445 device=/dev/hda_vg/sid_chroot
446 mount-options=-o atime,sync,user_xattr
447 lvm-snapshot-options=--size 2G
448
450 Chroot definitions
451 /etc/schroot/schroot.conf
452 The system-wide chroot definition file. This file must be owned
453 by the root user, and not be writable by other.
454 /etc/schroot/chroot.d
456 Additional chroot definitions may be placed in files under this
457 directory. They are treated in exactly that same manner as
458 /etc/schroot/schroot.conf. Each file may contain one or more
459 chroot definitions.
460 Setup script configuration
462 The directory /etc/schroot/default contains the default settings used
463 by setup scripts.
464 config Main configuration file read by setup scripts. The format of
466 this file is described in schroot-script-config(5). This is the
467 default value for the script-config key. Note that this was
468 formerly named /etc/schroot/script-defaults. The following
469 files are referenced by default:
470 copyfiles
472 A list of files to copy into the chroot from the host system.
473 Note that this was formerly named /etc/schroot/copy‐
474 files-defaults.
475 fstab A file in the format decribed in fstab(5), used to mount
477 filesystems inside the chroot. The mount location is relative
478 to the root of the chroot. Note that this was formerly named
479 /etc/schroot/mount-defaults.
480 nssdatabases
482 System databases (as described in /etc/nsswitch.conf on
483 GNU/Linux systems) to copy into the chroot from the host. Note
484 that this was formerly named /etc/schroot/nssdatabases-defaults.
485
487 Roger Leigh.
488
490 Copyright © 2005-2010 Roger Leigh <rleigh@debian.org>
491 schroot is free software: you can redistribute it and/or modify it
493 under the terms of the GNU General Public License as published by the
494 Free Software Foundation, either version 3 of the License, or (at your
495 option) any later version.
496
498 sbuild(1), schroot(1), schroot-script-config(5), schroot-faq(7),
499 mount(8).
500Version 1.4.10 22 Aug 2010 SCHROOT.CONF(5)