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,

CR][lB]sid[rB]

This is then followed by several key-value pairs:

type=type

The type of the chroot. Valid types are [lq]plain[rq], [lq]file[rq], [lq]block-device[rq] and [lq]lvm-snapshot[rq]. If empty or omitted, the default type is [lq]plain[rq].

description=description

A short description of the chroot. This may be localised for different languages; see the section [lq]Localisation[rq] below.

priority=number

Set the priority of a chroot. number is a positive integer indicating whether a distribution is older than another. For example, [lq]oldstable[rq] and [lq]oldstable-security[rq] might be 0, while [lq]stable[rq] and [lq]stable-security[rq] 1, [lq]testing[rq] 2 and [lq]unstable[rq] 3. The values are not important, but the difference between them is. This is used by sbuild when using the schroot chroot mode.

groups=group1,group2,...

A comma-separated list of groups which are allowed access to the chroot. If empty or omitted, no users will be allowed access.

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's group is in groups, they may gain access with a password).

aliases=alias1,alias2,...

A comma-separated list of aliases (alternate names) for this chroot. For example, a chroot named [lq]sid[rq] might have an [lq]unstable[rq] alias for convenience.

run-setup-scripts=true|false

Set whether chroot setup scripts will be run. The default is not to run setup scripts ([lq]false[rq]), for safety reasons (so it won't clobber your passwd and other critical files). The default for session-managed chroots ([lq]file[rq] and [lq]lvm-snapshot[rq]) is to run setup scripts. If type is set to a value other than [lq]plain[rq], setup scripts are required to mount and configure the chroot environment. If enabled for a [lq]plain[rq] chroot, the chroot will support simple session management (not true session management, because it does not make a copy of the chroot). If your chroots are exclusively controlled by schroot, set to [lq]true[rq].

run-exec-scripts=true|false

Set whether chroot execution scripts will be run. The default is are the same as for the run-setup-scripts key. This option was called run-setup-scripts in releases up to version 0.2.5.

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. For example, if set to [lq]linux32[rq], this will cause all commands run in the chroot to have a linux32 prefix added.

Chroots of type [lq]plain[rq] are directories accessible in the filesystem. They have an additional (mandatory) configuration option:

location=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.

Chroots of type [lq]file[rq] are files on the current filesystem containing an archive of the chroot files. They implement the source chroot options (see [lq]source chroot options[rq], below) and have an additional (mandatory) configuration option:

file=filename

The file containing the archived chroot environment. This must be a tar (tape archive), optionally compressed with gzip or bzip2, or a zip archive. The file extensions used to determine the type are are .tar, .tar.gz, .tar.bz2, .tgz, .tbz and .zip. This file must be owned by the root user, and not be writable by other.

Chroots of type [lq]block-device[rq] are a filesystem available on an unmounted block device. The device will be mounted and unmounted on demand. They have additional options:

device=device

This is the device name of the block device, including the absolute path. For example, [lq]/dev/sda5[rq].

mount-options=mount_options

Mount options for the block device. These are additional options to pass to mount(8). For example, [lq]-o atime,sync,user_xattr[rq].

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.

Chroots of type [lq]lvm-snapshot[rq] are a filesystem available on an LVM logical volume (LV). A snapshot LV will be created from this LV on demand, and then the snapshot will be mounted. At the end of the session, the snapshot LV will be unmounted and removed. For each chroot of this type, a corresponding [lq]block-device[rq] chroot will be created, with a -source suffix appended to the chroot name and all its aliases; this is for convenient access to the source device.

They implement the source chroot options (see [lq]source chroot options[rq], below), and all the options for [lq]block-device[rq], plus an additional option:

lvm-snapshot-options=snapshot_options

Snapshot options. These are additional options to pass to lvcreate(8). For example, [lq]-L 2g[rq] to create a snapshot 2 GiB in size. Note: the LV name ([lq]-n[rq]), the snapshot option ([lq]-s[rq]) and the original LV path may not be specfied here; they are set automatically by schroot.

Some chroots implement source chroots. These are chroots which automatically create a copy of themselves before use, and are usually session managed. These chroots also provide an additional chroot with a -source suffix added to their name, to allow access to the original data, to aid in chroot maintenance. These chroots provide the following additional options:

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

Some keys may be localised in multiple lanuages. This is achieved by adding the locale name in square brackets after the key name. For example:

CR]description[en_GB]=CI]British English translation

This will localise the description key for the en_GB locale. CR]description[fr]=CI]French translation

This will localise the description key for all French locales.