SCHROOT.CONF(5)

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

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 based upon the GLib GKeyFile parser (but is a completely separate implementation).

  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]

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’, ‘block-device’ and ‘lvm-snapshot’. If empty or omitted, the default type is ‘plain’.

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 is used by sbuild when using the schroot chroot mode.

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.

run-setup-scripts=true|false
    Set whether chroot setup scripts will be run. The default is not to run setup scripts (‘false’), for safety reasons (so it won't clobber your passwd and other critical files). The default for session-managed chroots (‘file’ and ‘lvm-snapshot’) is to run setup scripts. If type is set to a value other than ‘plain’ or ‘directory’, setup scripts are required to mount and configure the chroot environment. If enabled for a ‘plain’ or ‘directory’ 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 ‘true’.

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.

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.

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

  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 if run-setup-scripts is set to ‘true’ for ‘plain’ chroots, filesystem mounting is disabled. 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.

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

  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. They have additional options:

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

mount-options=mount_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.

  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. For each chroot of this type, a corresponding ‘block-device’ 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 “Source chroot options”, below), and all the options for ‘block-device’, plus an additional option:

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

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, and to aid in chroot maintenance. These chroots provide the following additional options:

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.

  Localisation

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

SECURITY
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. Don't give chroot root access to users you would not trust with root access to the host system.

EXAMPLE
# Sample configuration
[sid]
type=plain
description=Debian unstable
description[fr_FR]=Debian instable
location=/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
run-setup-scripts=true
run-exec-scripts=true
[sid-file]
type=file
description=Debian sid file-based chroot
priority=3
groups=sbuild
file=/srv/chroots/sid.tar.gz
run-setup-scripts=true
run-exec-scripts=true
[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
run-setup-scripts=true
run-exec-scripts=true

FILES

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

AUTHORS
Roger Leigh.

COPYRIGHT
Copyright © 2005-2006 Roger Leigh <rleigh@debian.org>

This program 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 2 of the License, or (at your option) any later version.

SEE ALSO
sbuild(1), schroot(1), mount(8).