Section: Debian sbuild (5)Updated: 30 Dec 2010Local indexUp
NAME
schroot.conf - chroot definition file for schroot
DESCRIPTION
schroot.conf is a plain UTF-8 text file, describing the chroots
available for use with schroot.
Comments are introduced following a '#' ("hash")
character at the beginning of a line, or following any other text. All text
right of the '#' 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,
[sid]
The name is subject to certain naming restrictions. For further details, see
the section "Chroot Names" below.
This is then followed by several key-value pairs, one per line:
type=type
The type of the chroot. Valid types are 'plain', 'directory',
'file', 'loopback', 'block-device',
'btrfs-snapshot' and 'lvm-snapshot'. If empty or omitted,
the default type is 'plain'. Note that 'plain' chroots do not
run setup scripts and mount filesystems; 'directory' is recommended
(see "Plain and directory chroots", below).
description=description
A short description of the chroot. This may be localised for different
languages; see the section "Localisation" below.
priority=number
Set the priority of a chroot. number is a positive integer indicating
whether a distribution is older than another. For example, "oldstable"
and "oldstable-security" might be '0', while "stable"
and "stable-security" are '1', "testing" is '2'
and "unstable" is '3'. 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.
message-verbosity=verbosity
Set the verbosity of messages printed by schroot when setting up, running
commands and cleaning up the chroot. Valid settings are 'quiet'
(suppress most messages), 'normal' (the default) and 'verbose'
(show all messages). This setting is overridden by the options --quiet
and --verbose.
users=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 groups).
groups=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.
root-users=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
users or groups, respectively, they may gain access with a
password). See the section "Security" below.
root-groups=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
users or groups, respectively, they may gain access with a
password). See the section "Security" below.
aliases=alias1,alias2,...
A comma-separated list of aliases (alternate names) for this chroot. For
example, a chroot named "sid" might have an 'unstable' alias
for convenience. Aliases are subject to the same naming restrictions as the
chroot name itself.
run-setup-scripts=true|false
Set whether chroot setup scripts will be run. The default is to run setup
scripts for all chroot types except 'plain'. 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.
run-exec-scripts=true|false Set whether chroot
execution scripts will be run. The default is the same as the default for the
run-setup-scripts key. This option was called
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.
script-config=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
'default/config'. Alternatives are 'minimal/config' (minimal
configuration), 'desktop/config' (for running desktop applications in
the chroot, making more functionality from the host system available in the
chroot) and 'sbuild/config' (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 preserve-environment key should also be
set to 'true' 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).
Note that the different profiles have different security implications; see the
section "Security" below for further details.
command-prefix=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.
personality=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 'bsd', 'hpux', 'irix32', 'irix64',
'irixn32', 'iscr4', 'linux', 'linux32',
'linux_32bit', 'osf4', 'osr5', 'riscos',
'scorvr3', 'solaris', 'sunos', 'svr4',
'uw7', 'wysev386', and 'xenix'. The default value is
'linux'. There is also the special option 'undefined'
(personality not set). For a 32-bit chroot on a 64-bit system,
'linux32' is the option required. The only valid option for non-Linux
systems is 'undefined'. The default value for non-Linux systems is
'undefined'.
preserve-environment=true|false
By default, the environment will not be preserved inside the chroot, instead a
minimal environment will be used. Set to 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.
environment-filter=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:
"^(BASH_ENV:|CDPATH:|ENV:|HOSTALIASES:|IFS:|KRB5_CONFIG:|KRBCONFDIR:|KRBTKFILE:|KRB_CONF:|LD_.*:|LOCALDOMAIN:|NLSPATH:|PATH_LOCALE:|RES_OPTIONS:|TERMINFO:|TERMINFO_DIRS:|TERMPATH)$".
Plain and directory chroots
Chroots of type 'plain' or 'directory' 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
"Filesystem Union chroot options", below).
These chroot types have an additional (mandatory) configuration option:
directory=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 'plain' chroots is mounted with the --rbind
option to
mount(8),
while for 'directory' 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 location, but was renamed to avoid
ambiguity with the option by the same name for mountable chroot options
(see "Mountable chroot options", below). The name
location is deprecated, but still valid; it will be obsoleted and
removed in a future release. It is recommended to use directory
rather than location. Note that it is an error to use both
directory and location at the same time.
File chroots
Chroots of type 'file' are files on the current filesystem containing
an archive of the chroot files. They implement the source chroot options
(see "Source chroot options", below) and have an additional
(mandatory) configuration option:
file=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.
location=path
This is the path to the chroot inside the archive. For example, if the
archive contains a chroot in /squeeze, you would specify
"/squeeze" 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 'loopback' 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 "Mountable chroot
options" and "Filesystem Union chroot options", below),
plus an additional option:
file=filename
This is the filename of the file containing the filesystem, including the
absolute path. For example "/srv/chroot/sid".
Block device chroots
Chroots of type 'block-device' 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 "Mountable chroot options" and
"Filesystem Union chroot options", below), plus an additional
option:
device=device
This is the device name of the block device, including the absolute path. For
example, "/dev/sda5".
Btrfs snapshot chroots
Chroots of type 'btrfs-snapshot' 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 'directory' 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 "Source
chroot options", below), plus these additional options:
btrfs-source-subvolume=directory
The directory containing the source subvolume.
btrfs-snapshot-directory=directory
The directory in which to store the snapshots of the above source subvolume.
LVM snapshot chroots
Chroots of type 'lvm-snapshot' 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
'block-device' 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 "Source chroot
options", below), and all the options for 'block-device', plus
an additional option:
lvm-snapshot-options=snapshot_options
Snapshot options. These are additional options to pass to lvcreate(8). For
example, "-L 2g" 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:
source-clone=true|false
Set whether the source chroot should be automatically cloned (created) for this
chroot. The default is true to automatically clone, but if desired
may be disabled by setting to false. If disabled, the source chroot
will be inaccessible.
source-users=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
users option in the source chroot.
source-groups=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
groups option in the source chroot.
source-root-users=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 users, they may
gain access with a password). This will become the root-users option
in the source chroot. See the section "Security" below.
source-root-groups=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 groups,
they may gain access with a password). This will become the
root-groups option in the source chroot. See the section
"Security" 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:
mount-options=options
Mount options for the block device. These are additional options to pass to
mount(8).
For example, "-o atime,sync,user_xattr".
location=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 "/chroot/sid" 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 union-type to any supported
value. If enabled, the chroot will also be a source chroot, which will
provide additional options (see "Source chroot options", above).
All entries are optional.
union-type=type
Set the union filesystem type. Currently supported filesystems are
'aufs' and 'unionfs'. The default is 'none', which
disables this feature.
union-mount-options=options
Union filesystem mount options (branch configuration), used for mounting the
union filesystem specified with union-type. This replaces the complete
"-o" string for mount and allows for the creation of complex
filesystem unions. Note that 'aufs' and 'unionfs' have
different supported mount options.
Note:
One can use the variables "${CHROOT_UNION_OVERLAY_DIRECTORY}" and
"${CHROOT_UNION_UNDERLAY_DIRECTORY}" 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.
union-overlay-directory=directory
Specify the directory where the writeable overlay session directories will be
created. The default is '/var/lib/schroot/union/overlay'.
union-underlay-directory=directory
Specify the directory where the read-only underlying directories will be
created. The default is '/var/lib/schroot/union/underlay'.
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:
description[en_GB]=British English translation
This will localise the description key for the en_GB locale.
description[fr]=French translation
This will localise the description key for all French locales.
CHROOT NAMES
A number of characters or words are not permitted in a chroot name, session
name or configuration filename. The name may not contain a leading period
('.'). The characters ':' (colon), ',' (comma) and
'/' (forward slash) are not permitted anywhere in the name. The name
may also not contain a trailing tilde ('~'). The rationale for these
restrictions is given below.
'.'
A leading period could be used to create a name with a relative path in it, in
combination with '/', and this could allow overwriting of files on the
host filesystem. Not allowing this character also means hidden files cannot be
created. It also means some editor backups are automatically ignored. Periods
are allowed anywhere else in the name.
':'
A colon is used as a namespace delimiter, and so is not permitted as part of a
chroot or session name. LVM snapshot names may also not contain this character
due to a naming restriction by
lvcreate(8).
'/'
Names containing this character are not valid filenames. A forward slash would
potentially allow creation of files in subdirectories.
','
Commas are used to separate items in lists. Aliases are separated by commas
and hence can't contain commas in their name.
'~'
Filenames containing trailing tildes are used for editor backup files, which
are ignored. Tildes are allowed anywhere else in the name.
'dpkg-old'
'dpkg-dist'
'dpkg-new'
'dpkg-tmp'
These names may not appear at the end of a name. These are saved copies of
conffiles used by the dpkg package manager, and will be ignored.
SECURITY
Untrusted users
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.
Do not give chroot root access to users you would not trustwith root access to the host system.
Profiles
Depending upon which profile you have configured with the
script-config option, different filesystems will be mounted inside
the chroot, and different files will be copied into the chroot from the host.
Some profiles will mount the host's /dev, while others will not. Some
profiles also bind mount additional parts of the host filesystem in order to
allow use of certain features, including user's home directories and specific
parts of /var. Check the profile's fstab file to be certain of
what will be mounted, and the other profile files to see which files and system
databases will be copied into the chroot. Choose a different profile or edit
the files to further restrict what is made available inside the chroot.
There is a tradeoff between security (keeping the chroot as minimal as
possible) and usability (which sometimes requires access to parts of the host
filesystem). The different profiles make different tradeoffs, and it is
important that you assess which meets the security/usability tradeoff you
require.
The system-wide chroot definition file. This file must be owned by the root
user, and not be writable by other.
/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 /etc/schroot/default contains the default
settings used by setup scripts.
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 script-config key. Note that this
was formerly named /etc/schroot/script-defaults. The following
files are referenced by default:
copyfiles
A list of files to copy into the chroot from the host system. Note that this
was formerly named /etc/schroot/copyfiles-defaults.
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.
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.
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.