Provided by: schroot_1.2.0-1_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’, ‘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.

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

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