Provided by: schroot_1.4.0-1ubuntu1_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 to
              run setup scripts for all chroot types  except  ‘plain’.   Setup
              scripts   are   required  to  mount  and  configure  the  chroot
              environment.  This option is deprecated and no  longer  used  by
              schroot, but is still permitted to be used; it will be obsoleted
              and removed in a future release.

       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.  This option  is
              deprecated and no longer used by schroot, but is still permitted
              to be used; it  will  be  obsoleted  and  removed  in  a  future
              release.

       script-config=filename
              The behaviour of the chroot setup 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 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
       directory  chroots  run  setup  scripts,  whereas plain chroots do not.
       Additionally, directory chroots implement the filesystem  union  chroot
       options (see “Filesystem Union chroot options”, below).

       These chroot types have an additional (mandatory) configuration option:

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

              This  option  was  previously named location, but was renamed to
              avoid ambiguity with the option by the same name  for  mountable
              chroot  options  (see  “Mountable  chroot options”, below).  The
              name location  is  deprecated,  but  still  valid;  it  will  be
              obsoleted and removed in a future release.  It is recommended to
              use directory rather than location.  Note that it is an error to
              use both directory and location at the same time.

   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.   Loopback  chroots implement the mountable
       chroot and filesystem  union  chroot  options  (see  “Mountable  chroot
       options”  and  “Filesystem  Union  chroot  options”,  below),  plus  an
       additional option:

       file=filename
              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.   Block  device  chroots  implement  the  mountable  chroot and
       filesystem union chroot options (see  “Mountable  chroot  options”  and
       “Filesystem Union 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=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.

   Filesystem Union chroot options
       Some chroots allow for the  creation  of  a  session  using  filesystem
       unions  to  overlay  the  original  filesystem with a separate writable
       directory.   The   original   filesystem   is   read-only,   with   any
       modifications  made  to  the  filesystem made in the overlying writable
       directory, leaving the original filesystem unchanged.  A union  permits
       multiple  sessions  to  access  and  make  changes  to  a single chroot
       simultaneously, while keeping the changes private to each session.   To
       enable  this  feature,  set  union-type  to  any  supported  value.  If
       enabled, the chroot will also be a source chroot,  which  will  provide
       additional  options  (see “Source chroot options”, above).  All entries
       are optional.

       union-type=type
              Set the union filesystem type.  Currently supported  filesystems
              are ‘aufs’ and ‘unionfs’.  The default is ‘none’, which disables
              this feature.

       union-mount-options=options
              Union filesystem mount options (branch configuration), used  for
              mounting  the  union filesystem specified with union-type.  This
              replaces the complete “-o” string for mount and allows  for  the
              creation  of  complex  filesystem  unions.  Note that ‘aufs’ and
              ‘unionfs’ have different supported mount options.  Note: One can
              use   the   variables   “${CHROOT_UNION_OVERLAY_DIRECTORY}”  and
              “${CHROOT_UNION_UNDERLAY_DIRECTORY}” to refer  to  the  writable
              overlay  session  directory  and  read-only underlying directory
              which are  to  form  the  union.   See  schroot-setup(5)  for  a
              complete variable list.

       union-overlay-directory=directory
              Specify  the  directory  where  the  writeable  overlay  session
              directories    will    be    created.     The     default     is
              ‘/var/lib/schroot/union/overlay’.

       union-underlay-directory=directory
              Specify the directory where the read-only underlying directories
              will       be       created.        The        default        is
              ‘/var/lib/schroot/union/underlay’.

   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
       directory=/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

       [sid-file]
       type=file
       description=Debian sid file-based chroot
       priority=3
       groups=sbuild
       file=/srv/chroots/sid.tar.gz
       run-setup-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

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