Provided by: schroot_1.2.1-1ubuntu2_i386 bug

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.

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

SEE ALSO

       sbuild(1), schroot(1), schroot-script-config(5), mount(8).