schroot.conf

Langue: en

Version: 22 Aug 2010 (fedora - 01/12/10)

Section: 5 (Format de fichier)

NAME

schroot.conf - chroot definition file for schroot

DESCRIPTION

BI]schroot.conf is a plain UTF-8 text file, describing the chroots available for use with schroot.

Comments are introduced following a [oq]CR][sh][cq] ([lq]hash[rq]) character at the beginning of a line, or following any other text. All text right of the [oq]CR][sh][cq] is treated as a comment.

The configuration format is an INI-style format, split into groups of key-value pairs separated by section names in square brackets.

General options

A chroot is defined as a group of key-value pairs, which is started by a name in square brackets on a line by itself. The file may contain multiple groups which therefore define multiple chroots.

A chroot definition is started by the name of the chroot in square brackets. For example,

CR][lB]sid[rB]

This is then followed by several key-value pairs, one per line:

CBI]type=CI]type
The type of the chroot. Valid types are [oq]plain[cq], [oq]directory[cq], [oq]file[cq], [oq]loopback[cq], [oq]block-device[cq], [oq]btrfs-snapshot[cq] and [oq]lvm-snapshot[cq]. If empty or omitted, the default type is [oq]plain[cq]. Note that [oq]plain[cq] chroots do not run setup scripts and mount filesystems; [oq]directory[cq] is recommended (see [lq]Plain and directory chroots[rq], below).
CBI]description=CI]description
A short description of the chroot. This may be localised for different languages; see the section [lq]Localisation[rq] below.
CBI]priority=CI]number
Set the priority of a chroot. CI]number is a positive integer indicating whether a distribution is older than another. For example, [lq]oldstable[rq] and [lq]oldstable-security[rq] might be [oq]0[cq], while [lq]stable[rq] and [lq]stable-security[rq] are [oq]1[cq], [lq]testing[rq] is [oq]2[cq] and [lq]unstable[rq] is [oq]3[cq]. The values are not important, but the difference between them is. This option is deprecated and no longer used by schroot, but is still permitted to be used; it will be obsoleted and removed in a future release.
CBI]message-verbosity=CI]verbosity
Set the verbosity of messages printed by schroot when setting up, running commands and cleaning up the chroot. Valid settings are [oq]quiet[cq] (suppress most messages), [oq]normal[cq] (the default) and [oq]verbose[cq] (show all messages). This setting is overridden by the options --quiet and --verbose.
CBI]users=CI]user1,user2,...
A comma-separated list of users which are allowed access to the chroot. If empty or omitted, no users will be allowed access (unless a group they belong to is also specified in CI]groups).
CBI]groups=CI]group1,group2,...
A comma-separated list of groups which are allowed access to the chroot. If empty or omitted, no groups of users will be allowed access.
CBI]root-users=CI]user1,user2,...
A comma-separated list of users which are allowed password-less root access to the chroot. If empty or omitted, no users will be allowed root access without a password (but if a user or a group they belong to is in CI]users or CI]groups, respectively, they may gain access with a password). See the section [lq]Security[rq] below.
CBI]root-groups=CI]group1,group2,...
A comma-separated list of groups which are allowed password-less root access to the chroot. If empty or omitted, no users will be allowed root access without a password (but if a user or a group they belong to is in CI]users or CI]groups, respectively, they may gain access with a password). See the section [lq]Security[rq] below.
CBI]aliases=CI]alias1,alias2,...
A comma-separated list of aliases (alternate names) for this chroot. For example, a chroot named [lq]sid[rq] might have an [oq]unstable[cq] alias for convenience.
CBI]run-setup-scripts=CI]true|CI]false
Set whether chroot setup scripts will be run. The default is to run setup scripts for all chroot types except [oq]plain[cq]. Setup scripts are required to mount and configure the chroot environment. This option is deprecated and no longer used by schroot, but is still permitted to be used; it will be obsoleted and removed in a future release.
CBI]run-exec-scripts=CI]true|CI]false Set whether chroot
execution scripts will be run. The default is the same as the default for the CI]run-setup-scripts key. This option was called CI]run-session-scripts in versions prior to 0.2.5. This option is deprecated and no longer used by schroot, but is still permitted to be used; it will be obsoleted and removed in a future release.
CBI]script-config=CI]filename
The behaviour of the chroot setup scripts may be customised on a per-chroot basis by providing a shell script which the scripts will source. The filename is relative to /etc/schroot. The default filename is [oq]default/config[cq]. Alternatives are [oq]minimal/config[cq] (minimal configuration), [oq]desktop/config[cq] (for running desktop applications in the chroot, making more functionality from the host system available in the chroot) and [oq]sbuild/config[cq] (for using the chroot for Debian package building).
Desktop users should note that the fstab file desktop/fstab will need editing if you use gdm3. The CI]preserve-environment key should also be set to [oq]true[cq] so that the environment is preserved inside the chroot.
If none of the configuration profiles provided above meet your needs, then they may be edited to further customise them, and/or copied and used as a template for entirely new profiles. Settings for specific chroots may also be set in a single script by using conditionals checking the chroot name and/or type. Note that the script will be sourced once for each and every script invocation, and must be idempotent. The file format is documented in schroot-script-config(5).
CBI]command-prefix=CI]command,option1,option2,...
A comma-separated list of a command and the options for the command. This command and its options will be prefixed to all commands run inside the chroot.
CBI]personality=CI]persona
Set the personality (process execution domain) to use. This option is useful when using a 32-bit chroot on 64-bit system, for example. Valid options on Linux are [oq]bsd[cq], [oq]hpux[cq], [oq]irix32[cq], [oq]irix64[cq], [oq]irixn32[cq], [oq]iscr4[cq], [oq]linux[cq], [oq]linux32[cq], [oq]linux_32bit[cq], [oq]osf4[cq], [oq]osr5[cq], [oq]riscos[cq], [oq]scorvr3[cq], [oq]solaris[cq], [oq]sunos[cq], [oq]svr4[cq], [oq]uw7[cq], [oq]wysev386[cq], and [oq]xenix[cq]. The default value is [oq]linux[cq]. There is also the special option [oq]undefined[cq] (personality not set). For a 32-bit chroot on a 64-bit system, [oq]linux32[cq] is the option required. The only valid option for non-Linux systems is [oq]undefined[cq]. The default value for non-Linux systems is [oq]undefined[cq].
CBI]preserve-environment=CI]true|CI]false
By default, the environment will not be preserved inside the chroot, instead a minimal environment will be used. Set to CI]true to always preserve the environment. This is useful for example when running X applications inside the chroot, which need the environment to function correctly. The environment may also be preserved using the --preserve-environment option.
CBI]environment-filter=CI]regex
The environment to be set in the chroot will be filtered in order to remove environment variables which may pose a security risk. Any environment variable matching the specified POSIX extended regular expression will be removed prior to executing any command in the chroot.
Potentially dangerous environment variables are removed for safety by default using the following regular expression: [lq]CR]^(BASH_ENV:|CDPATH:|ENV:|HOSTALIASES:|IFS:|KRB5_CONFIG:|KRBCONFDIR:|KRBTKFILE:|KRB_CONF:|LD_.*:|LOCALDOMAIN:|NLSPATH:|PATH_LOCALE:|RES_OPTIONS:|TERMINFO:|TERMINFO_DIRS:|TERMPATH)$[rq].

Plain and directory chroots

Chroots of type [oq]plain[cq] or [oq]directory[cq] are directories accessible in the filesystem. The two types are equivalent except for the fact that directory chroots run setup scripts, whereas plain chroots do not. In consequence, filesystems such as /proc are not mounted in plain chroots; it is the responsibility of the system administrator to configure such chroots by hand, whereas directory chroots are automatically configured. Additionally, directory chroots implement the filesystem union chroot options (see [lq]Filesystem Union chroot options[rq], below).

These chroot types have an additional (mandatory) configuration option:

CBI]directory=CI]directory
The directory containing the chroot environment. This is where the root will be changed to when executing a login shell or a command. The directory must exist and have read and execute permissions to allow users access to it. Note that on Linux systems it will be bind-mounted elsewhere for use as a chroot; the directory for [oq]plain[cq] chroots is mounted with the --rbind option to mount(8), while for [oq]directory[cq] chroots --bind is used instead so that sub-mounts are not preserved (they should be set in the fstab file just like in /etc/fstab on the host).
This option was previously named CI]location, but was renamed to avoid ambiguity with the option by the same name for mountable chroot options (see [lq]Mountable chroot options[rq], below). The name CI]location is deprecated, but still valid; it will be obsoleted and removed in a future release. It is recommended to use CI]directory rather than CI]location. Note that it is an error to use both CI]directory and CI]location at the same time.

File chroots

Chroots of type [oq]file[cq] are files on the current filesystem containing an archive of the chroot files. They implement the source chroot options (see [lq]Source chroot options[rq], below) and have an additional (mandatory) configuration option:
CBI]file=CI]filename
The file containing the archived chroot environment. This must be a tar (tape archive), optionally compressed with gzip or bzip2, or a zip archive. The file extensions used to determine the type are are .tar, .tar.gz, .tar.bz2, .tgz, .tbz and .zip. This file must be owned by the root user, and not be writable by other.
CBI]location=CI]path
This is the path to the chroot inside the archive. For example, if the archive contains a chroot in /squeeze, you would specify [lq]/squeeze[rq] here. If the chroot is the only thing in the archive, i.e. / is the root filesystem for the chroot, this option should be left blank, or omitted entirely.

Loopback chroots

Chroots of type [oq]loopback[cq] are a filesystem available as a file on disk, accessed via a loopback mount. The file will be loopback mounted and unmounted on demand. Loopback chroots implement the mountable chroot and filesystem union chroot options (see [lq]Mountable chroot options[rq] and [lq]Filesystem Union chroot options[rq], below), plus an additional option:
CBI]file=CI]filename
This is the filename of the file containing the filesystem, including the absolute path. For example [lq]/srv/chroot/sid[rq].

Block device chroots

Chroots of type [oq]block-device[cq] are a filesystem available on an unmounted block device. The device will be mounted and unmounted on demand. Block device chroots implement the mountable chroot and filesystem union chroot options (see [lq]Mountable chroot options[rq] and [lq]Filesystem Union chroot options[rq], below), plus an additional option:
CBI]device=CI]device
This is the device name of the block device, including the absolute path. For example, [lq]/dev/sda5[rq].

Btrfs snapshot chroots

Chroots of type [oq]btrfs-snapshot[cq] are a Btrfs snapshot created from an existing Btrfs subvolume on a mounted Btrfs filesystem. A snapshot will be created from this source subvolume on demand at the start of a session, and then the snapshot will be mounted. At the end of the session, the snapshot will be unmounted and deleted.

For each chroot of this type, a corresponding [oq]directory[cq] chroot will be created, with a -source suffix appended to the chroot name and all its aliases; this is for convenient access to the source subvolume. This chroot type implements the source chroot options (see [lq]Source chroot options[rq], below), plus these additional options:

CBI]btrfs-source-subvolume=CI]directory
The directory containing the source subvolume.
CBI]btrfs-snapshot-directory=CI]directory
The directory in which to store the snapshots of the above source subvolume.

LVM snapshot chroots

Chroots of type [oq]lvm-snapshot[cq] are a filesystem available on an LVM logical volume (LV). A snapshot LV will be created from this LV on demand, and then the snapshot will be mounted. At the end of the session, the snapshot LV will be unmounted and removed. For each chroot of this type, a corresponding [oq]block-device[cq] chroot will be created, with a -source suffix appended to the chroot name and all its aliases; this is for convenient access to the source device.

They implement the source chroot options (see [lq]Source chroot options[rq], below), and all the options for [oq]block-device[cq], plus an additional option:

CBI]lvm-snapshot-options=CI]snapshot_options
Snapshot options. These are additional options to pass to lvcreate(8). For example, [lq]-L 2g[rq] to create a snapshot 2 GiB in size. Note: the LV name (-n), the snapshot option (-s) and the original LV path may not be specfied here; they are set automatically by schroot.

Source chroot options

Some chroots implement source chroots. These are chroots which automatically create a copy of themselves before use, and are usually session managed. These chroots additionally provide an extra chroot with a -source suffix added to their name, to allow access to the original data, and to aid in chroot maintenance. These chroots provide the following additional options:
CBI]source-clone=CI]true|CI]false
Set whether the source chroot should be automatically cloned (created) for this chroot. The default is CI]true to automatically clone, but if desired may be disabled by setting to CI]false. If disabled, the source chroot will be inaccessible.
CBI]source-users=CI]user1,user2,...
A comma-separated list of users which are allowed access to the source chroot. If empty or omitted, no users will be allowed access. This will become the CI]users option in the source chroot.
CBI]source-groups=CI]group1,group2,...
A comma-separated list of groups which are allowed access to the source chroot. If empty or omitted, no users will be allowed access. This will become the CI]groups option in the source chroot.
CBI]source-root-users=CI]user1,user2,...

 A comma-separated list of users which are allowed password-less root access to the source chroot. If empty or omitted, no users will be allowed root access without a password (but if a user is in CI]users, they may gain access with a password). This will become the CI]root-users option in the source chroot. See the section [lq]Security[rq] below.
CBI]source-root-groups=CI]group1,group2,...

 A comma-separated list of groups which are allowed password-less root access to the source chroot. If empty or omitted, no users will be allowed root access without a password (but if a user's group is in CI]groups, they may gain access with a password). This will become the CI]root-groups option in the source chroot. See the section [lq]Security[rq] below.

Mountable chroot options

Some chroots implement device mounting. These are chroots which require the mounting of a device in order to access the chroot. These chroots provide the following additional options:
CBI]mount-options=CI]options
Mount options for the block device. These are additional options to pass to mount(8). For example, [lq]-o atime,sync,user_xattr[rq].
CBI]location=CI]path
This is the path to the chroot inside the filesystem on the device. For example, if the filesystem contains a chroot in /chroot/sid, you would specify [lq]/chroot/sid[rq] here. If the chroot is the only thing on the filesystem, i.e. / is the root filesystem for the chroot, this option should be left blank, or omitted entirely.

Filesystem Union chroot options

Some chroots allow for the creation of a session using filesystem unions to overlay the original filesystem with a separate writable directory. The original filesystem is read-only, with any modifications made to the filesystem made in the overlying writable directory, leaving the original filesystem unchanged. A union permits multiple sessions to access and make changes to a single chroot simultaneously, while keeping the changes private to each session. To enable this feature, set CI]union-type to any supported value. If enabled, the chroot will also be a source chroot, which will provide additional options (see [lq]Source chroot options[rq], above). All entries are optional.
CBI]union-type=CI]type
Set the union filesystem type. Currently supported filesystems are [oq]aufs[cq] and [oq]unionfs[cq]. The default is [oq]none[cq], which disables this feature.
CBI]union-mount-options=CI]options
Union filesystem mount options (branch configuration), used for mounting the union filesystem specified with union-type. This replaces the complete [lq]-o[rq] string for mount and allows for the creation of complex filesystem unions. Note that [oq]aufs[cq] and [oq]unionfs[cq] have different supported mount options. Note: One can use the variables [lq]${CHROOT_UNION_OVERLAY_DIRECTORY}[rq] and [lq]${CHROOT_UNION_UNDERLAY_DIRECTORY}[rq] to refer to the writable overlay session directory and read-only underlying directory which are to form the union. See schroot-setup(5) for a complete variable list.
CBI]union-overlay-directoryCI]=directory
Specify the directory where the writeable overlay session directories will be created. The default is [oq]/var/lib/schroot/union/overlay[cq].
CBI]union-underlay-directoryCI]=directory
Specify the directory where the read-only underlying directories will be created. The default is [oq]/var/lib/schroot/union/underlay[cq].

Localisation

Some keys may be localised in multiple languages. This is achieved by adding the locale name in square brackets after the key name. For example:

CR]description[en_GB]=CI]British English translation

This will localise the CI]description key for the en_GB locale.

CR]description[fr]=CI]French translation

This will localise the CI]description key for all French locales.

SECURITY

Note that giving untrusted users root access to chroots is a serious security risk! Although the untrusted user will only have root access to files inside the chroot, in practice there are many obvious ways of breaking out of the chroot and of disrupting services on the host system. As always, this boils down to trust. Don't give chroot root access to users you would not trust with root access to the host system.

EXAMPLE

CR]# Sample configuration
CR]
CR][sid]
CR]type=plain
CR]description=Debian unstable
CR]description[fr_FR]=Debian instable
CR]directory=/srv/chroot/sid
CR]priority=3
CR]users=jim
CR]groups=sbuild
CR]root-users=rleigh
CR]aliases=unstable,default
CR]
CR][etch]
CR]type=block-device
CR]description=Debian testing (32-bit)
CR]priority=2
CR]groups=users
CR]#groups=sbuild-security
CR]aliases=testing
CR]device=/dev/hda_vg/etch_chroot
CR]mount-options=-o atime
CR]personality=linux32
CR]
CR][sid-file]
CR]type=file
CR]description=Debian sid file-based chroot
CR]priority=3
CR]groups=sbuild
CR]file=/srv/chroots/sid.tar.gz
CR]
CR][sid-snapshot]
CR]type=lvm-snapshot
CR]description=Debian unstable LVM snapshot
CR]priority=3
CR]groups=sbuild
CR]users=rleigh
CR]source-root-users=rleigh
CR]source-root-groups=admin
CR]device=/dev/hda_vg/sid_chroot
CR]mount-options=-o atime,sync,user_xattr
CR]lvm-snapshot-options=--size 2G

FILES

Chroot definitions

BI]/etc/schroot/schroot.conf
The system-wide chroot definition file. This file must be owned by the root user, and not be writable by other.
BI]/etc/schroot/chroot.d
Additional chroot definitions may be placed in files under this directory. They are treated in exactly that same manner as /etc/schroot/schroot.conf. Each file may contain one or more chroot definitions.

Setup script configuration

The directory BI]/etc/schroot/default contains the default settings used by setup scripts.
BI]config
Main configuration file read by setup scripts. The format of this file is described in schroot-script-config(5). This is the default value for the CI]script-config key. Note that this was formerly named /etc/schroot/script-defaults. The following files are referenced by default:
BI]copyfiles
A list of files to copy into the chroot from the host system. Note that this was formerly named /etc/schroot/copyfiles-defaults.
BI]fstab
A file in the format decribed in fstab(5), used to mount filesystems inside the chroot. The mount location is relative to the root of the chroot. Note that this was formerly named /etc/schroot/mount-defaults.
BI]nssdatabases
System databases (as described in /etc/nsswitch.conf on GNU/Linux systems) to copy into the chroot from the host. Note that this was formerly named /etc/schroot/nssdatabases-defaults.

AUTHORS

Roger Leigh. Copyright © 2005-2010 Roger Leigh CR]<rleigh@debian.org>

schroot is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

SEE ALSO

sbuild(1), schroot(1), schroot-script-config(5), schroot-faq(7), mount(8).