Ubuntu Manpage: schroot.conf - chroot definition file for schroot

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’, ‘zfs-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
ignores 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.

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).

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, 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.

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.

ZFS snapshot chroots
Chroots of type ‘zfs-snapshot’ are a ZFS clone created from an existing ZFS dataset. A
snapshot and clone will be created from this source subvolume on demand at the start of a
session, and then the clone will be mounted. At the end of the session, the clone will be
unmounted and the clone and snapshot will be 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:

zfs-dataset=dataset_name
Name of the ZFS source dataset to use.

zfs-snapshot-options=snapshot_options
Snapshot options. These are additional options to pass to zfs snapshot.

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 specified here; they are
set automatically by schroot.

Custom chroots
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).

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’,
‘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’.

Customisation
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.

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 must begin with a lowercase or an uppercase letter, or a
       digit.   The  remaining  characters  may  additionally  be  dash  (‘-’),  period (‘.’), or
       underscore (‘_’).

       The rationale for these restrictions is as follows:

       Generic
              Unfortunately, not all the places that deal  with  chroot  names  can  handle  non-
              printable and other characters properly, and it's hard to update all of them.  This
              is mostly about the various shell scripts where it's also unwise to assume  authors
              always create safe code.

       ‘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 described 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 © 2005-2012  Roger Leigh <rleigh@codelibre.net>

       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.