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

Provided by: schroot_1.2.1-1ubuntu2_i386

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]

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’ 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 and wanna-
build.

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.

script-config=filename
The behaviour of the chroot setup and execution scripts may be
customised on a per-chroot basis by providing a shell script
which the scripts will source. The filename is relative to
/etc/schroot. The default filename is ‘script-defaults’. The
recommended method of customisation is to copy this script and
amend the copy; or alter the original to set the defaults for
all chroots. Settings for specific chroots may also be set in a
single script by using conditionals checking the chroot name
and/or type. Note that the setup script will be sourced once
for each and every setup and exec script invocation, and must be
idempotent. The file format is documented in schroot-script-
config(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’.

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

These chroot types 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. 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.

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.

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. They implement the mountable chroot options
(see “Mountable chroot options”, below), plus an additional option:

file=file 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. They implement the mountable chroot options (see “Mountable
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”.

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.

Mountable chroot options
Some chroots 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=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.

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.

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

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

AUTHORS

       Roger Leigh.

COPYRIGHT

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

       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.

Ubuntu manuals