SCHROOT.CONF

NAME

DESCRIPTION

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 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 . 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 profile will take precedence. script-config is deprecated and will be removed in a future release.

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.

This file is deprecated, and no longer exists in the current schroot version, but is still used if present for backward compatibility; it will be obsoleted and removed in a future release. All the settings in this file are now settable using configuration keys in schroot.conf, as detailed below. Existing configuration should be modified to use these keys in place of this file. See schroot-script-config(5). for further details.

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.

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.

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

Plain and directory chroots

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

file=filename

The file containing the archived chroot environment (mandatory). This must be a tar (tape archive), optionally compressed with gzip or bzip2. The file extensions used to determine the type are are .tar, .tar.gz, .tar.bz2, .tgz, and .tbz. 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

file=filename

This is the filename of the file containing the filesystem, including the absolute path. For example "/srv/chroot/sid".

Block device chroots

device=device

This is the device name of the block device, including the absolute path. For example, "/dev/sda5".

Btrfs snapshot chroots

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

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.

Custom chroots

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

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

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

union-type=type

Set the union filesystem type. Currently supported filesystems are 'aufs', 'overlayfs' 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 ''.

union-underlay-directory=directory

Specify the directory where the read-only underlying directories will be created. The default is ''.

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

Do not give chroot root access to users you would not trust with root access to the host system.  

Profiles

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

[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

The system-wide chroot definition file. This file must be owned by the root user, and not be writable by other.

Additional chroot definitions may be placed in files under this directory. They are treated in exactly that same manner as . Each file may contain one or more chroot definitions.

Setup script configuration

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 /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 /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 /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 /nssdatabases-defaults.

AUTHORS

COPYRIGHT

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

Index

NAME

DESCRIPTION

General options

Plain and directory chroots

File chroots

Loopback chroots

Block device chroots

Btrfs snapshot chroots

LVM snapshot chroots

Custom chroots

Source chroot options

Mountable chroot options

Filesystem Union chroot options

Customisation

Localisation

CHROOT NAMES

SECURITY

Untrusted users

Profiles

EXAMPLE

FILES

Chroot definitions

Setup script configuration

AUTHORS

COPYRIGHT

SEE ALSO