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.
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.
- profile=directory
- script-config=filename
- The behaviour of the chroot setup scripts may be customised on a
per-chroot basis by setting a specific configuration profile. The
directory is relative to /etc/schroot. The default is
‘default’. The files in this directory are sourced by the
setup scripts, and so their behaviour may be customised by selecting the
appropriate profile. Alternatives are ‘minimal’ (minimal
configuration), ‘desktop’ (for running desktop applications
in the chroot, making more functionality from the host system available in
the chroot) and ‘sbuild’ (for using the chroot for Debian
package building). Other packages may provide additional profiles. The
default values of the keys setup.config,
setup.copyfiles,
setup.fstab and
setup.nssdatabases are set based upon the
profile setting.
- Note that the profile key replaces the
older script-config key. The
script-config key is exactly the same as
profile, but has
“/config” appended to it. The default filename is
‘default/config’. Either of these keys may be used. If both
are present, then script-config will take
precedence (profile will be unset).
script-config is deprecated and will be
removed in a future release. Note that
profile is equivalent to
script-config if the file sourced by
script-config only contains the standard
variables provided by schroot; if any additional variables or shell script
fragments have been added, please also set
setup.config, which will continue to allow
this file to be sourced. It is recommended to replace the use of the
sourced file with additional keys in schroot.conf where possible, but it
will continue to be possible to source an additional configuration file
using setup.config.
- Desktop users should note that the fstab file desktop/fstab will
need editing if you use gdm3; please see the comments in this file for
further instructions. 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.
- Note that the different profiles have different security implications; see
the section “Security” below for further
details.
- setup.config=filename
- This key specifies a file which the setup scripts will source when they
are run. This defaults to the same value as set by
script-config. The file is a Bourne shell
script, and in consequence may contain any valid shell code, in addition
to simple variable assignments. This will, for example, allow behaviour to
be customised according to the specific chroot type or name. Note that the
script will be sourced once for each and every script invocation, and must
be idempotent.
- All the default settings in this file are now settable using configuration
keys in schroot.conf, as detailed below. Existing configurations
should be modified to use these keys in place of this file. See
schroot-script-config(5) for further details. This type of setup
script configuration file is no longer provided as part of the standard
profiles, but will continue to be sourced if present and this key is
set.
- setup.copyfiles=filename
- A file containing a list of files to copy into the chroot (one file per
line). The file will have the same absolute location inside the
chroot.
- setup.fstab=filename
- The filesystem table file to be used to mount filesystems within the
chroot. The format of this file is the same as for /etc/fstab,
documented in fstab(5). The only difference is that the mountpoint
path fs_dir is relative to the chroot, rather than the root. Also
note that mountpoints are canonicalised on the host, which will ensure
that absolute symlinks point inside the chroot, but complex paths
containing multiple symlinks may be resolved incorrectly; it is
inadvisable to use nested symlinks as mountpoints.
- setup.nssdatabases=filename
- A file listing the system databases to copy into the chroot. The default
databases are ‘passwd’, ‘shadow’,
‘group’ and ‘gshadow’. Other potential
databases which could be added include ‘services’,
‘protocols’, ‘networks’, and
‘hosts’. The databases are copied using getent(1) so
all database sources listed in /etc/nsswitch.conf will be used for
each database.
- setup.services=service1,service2,...
- A comma-separated list of services to run in the chroot. These will be
started when the session is started, and stopped when the session is
ended.
- 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.
- shell=shell
- When running a login shell a number of potential shells will be
considered, in this order: the command in the SHELL environment variable
(if --preserve-environment is used, or
preserve-environment is enabled), the
user's shell in the ‘passwd’ database, /bin/bash and
finally /bin/sh. This setting overrides this list, and will use the
shell specified. It may be overridden using the --shell
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)$”.
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).
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, bzip2, xz, lzop
or lz4. The file extensions used to determine the type are .tar,
.tar.gz, .tar.bz2, .tar.xz, .tar.lzop,
.tar.lz4, .tgz, .tbz, .txz, .tzo and
.tlz4. This file must be owned by the root user, and not be
writable by other. Note that zip archives are no longer supported; zip was
not able to archive named pipes and device nodes, so was not suitable for
archiving chroots.
- 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.
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”.
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”.
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.
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.
Chroots of type ‘custom’ are a special type of
chroot, used for implementing new types of chroot not supported by any of
the above chroot types. This may be useful for implementing and testing a
new chroot type without needing to write any C++ code. However, you will
need to write your own setup script to do the setup work, since by itself
this chroot type does very little. You will also need to add custom keys to
your chroot definition for use in the setup script; unlike the configuration
for the above chroot types, no validation of the options will take place
unless you do it yourself in your custom setup script. These additional
options are also implemented:
- custom-session-cloneable=true|false
- Set whether or not sessions may be cloned using this chroot (enabled by
default).
- custom-session-purgeable=true|false
- Set whether or not sessions may be cloned using this chroot (disabled by
default).
- custom-source-cloneable=true|false
- Set whether or not source chroots may be cloned using this chroot
(disabled by default).
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.
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.
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’, ‘overlayfs’, ‘overlay’
(as of Linux 4.0+) 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’,
‘overlayfs’ and ‘unionfs’ each 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’.
In addition to the configuration keys listed above, it is possible
to add custom keys. These keys will be used to add additional environment
variables to the setup script environment when setup scripts are run. The
only restriction is that the key name consists only of alphanumeric
characters and hyphens, begins with an alphabet character and contains at
least one period. That is to say, that it matches the extended regular
expression “^([a-z][a-z0-9]*\.)+[a-z][a-z0-9-]*$”.
For example:
debian.apt-update=true
debian.distribution=unstable
would set the following environment:
DEBIAN_APT_UPDATE=true
DEBIAN_DISTRIBUTION=unstable
Note that it is an error to use different key names which would
set the same environment variable by mixing periods and hyphens.
Custom configuration keys may also be modified at runtime using
the --option option. However, for security, only selected keys may be
modified. These keys are specified using the following options:
- user-modifiable-keys=key1,key2,..
- Set the keys which users may modify using --option.
- root-modifiable-keys=key1,key2,..
Set the keys which the
- root user may modify using --option. Note that the root user may
use the keys specified in
user-modifiable-keys in addition to those
specified here.
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.