Provided by:
schroot_1.4.23-1_i386 
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 for normal use
(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. This is useful for adding
commands such as nice, ionice or eatmydata for all commands run
inside the chroot. nice and ionice will affect CPU and I/O
scheduling. eatmydata ingores filesystem fsync operations, and
is useful for throwaway snapshot chroots where you don't care
about dataloss, but do care about high speed.
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). Note that a
corresponding source chroot (of type 'file') will be created for each
chroot of this type; this is for convenient access to the source
archive, e.g. for the purpose of updating. These additional options are
also implemented:
file=filename
The file containing the archived chroot environment (mandatory).
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. This chroot type
implements the source chroot options (see "Source chroot options",
below). Note that a corresponding source chroot (of type 'directory')
will be created for each chroot of this type; this is for convenient
access to the source volume. These additional options are also
implemented:
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.
LVM snapshot chroots implement the source chroot options (see "Source
chroot options", below), and all the options for 'block-device'. Note
that a corresponding source chroot (of type 'block-device') will be
created for each chroot of this type; this is for convenient access to
the source device. This additional option is also implemented:
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
The 'btrfs-snapshot', 'file' and 'lvm-snapshot' chroot types implement
source chroots. Additionally, chroot types with union support enabled
implement source chroots (see "Filesystem Union chroot options",
below). These are chroots which automatically create a copy of
themselves before use, and are usually session managed. These chroots
additionally provide an extra chroot in the source: namespace, to allow
convenient access to the original (non-snapshotted) data, and to aid in
chroot maintenance. I.e. for a chroot named wheezy (chroot:wheezy), a
corresponding source:wheezy chroot will be created. For compatibility
with older versions of schroot which did not support namespaces, a
chroot with a -source suffix appended to the chroot name will be
created in addition (i.e. wheezy-source using the above example). Note
that these compatibility names will be removed in schroot 1.5.0, so the
use of the source: namespace is preferred over the use of the -source
suffix form. See schroot(1) for further details.
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
The 'block-device', 'loopback' and 'lvm-snapshot' chroot types
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
The 'block-device', 'directory' and 'loopback' chroot types 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 trust with 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.
EXAMPLE
# Sample configuration
[sid]
type=plain
description=Debian unstable
description[fr_FR]=Debian instable
directory=/srv/chroot/sid
priority=3
users=jim
groups=sbuild
root-users=rleigh
aliases=unstable,default
[etch]
type=block-device
description=Debian testing (32-bit)
priority=2
groups=users
#groups=sbuild-security
aliases=testing
device=/dev/hda_vg/etch_chroot
mount-options=-o atime
personality=linux32
[sid-file]
type=file
description=Debian sid file-based chroot
priority=3
groups=sbuild
file=/srv/chroots/sid.tar.gz
[sid-snapshot]
type=lvm-snapshot
description=Debian unstable LVM snapshot
priority=3
groups=sbuild
users=rleigh
source-root-users=rleigh
source-root-groups=admin
device=/dev/hda_vg/sid_chroot
mount-options=-o atime,sync,user_xattr
lvm-snapshot-options=--size 2G
FILES
Chroot definitions
/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.
/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.
AUTHORS
Roger Leigh.
COPYRIGHT
Copyright (C) 2005-2010 Roger Leigh <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).