Provided by: schroot_1.4.25-1_amd64 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]

       The name is subject to certain naming restrictions.  For further details, see the  section
       “Chroot Names” below.

       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’, ‘btrfs-snapshot’ and ‘lvm-snapshot’.   If  empty  or  omitted,  the
              default  type  is  ‘plain’.  Note that ‘plain’ chroots do not run setup scripts and
              mount filesystems; ‘directory’ is  recommended  for  normal  use  (see  “Plain  and
              directory chroots”, below).

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

       message-verbosity=verbosity
              Set  the verbosity of messages printed by schroot when setting up, running commands
              and cleaning up the chroot.  Valid settings are ‘quiet’ (suppress  most  messages),
              ‘normal’  (the  default)  and  ‘verbose’  (show  all  messages).   This  setting is
              overridden by the options --quiet and --verbose.

       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.   Aliases  are
              subject to the same naming restrictions as the chroot name itself.

       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  @SCHROOT_SYSCONF_DIR@.   The  default  filename  is ‘default/config’.
              Alternatives are ‘minimal/config’ (minimal  configuration),  ‘desktop/config’  (for
              running desktop applications in the chroot, making more functionality from the host
              system available in the chroot) and  ‘sbuild/config’  (for  using  the  chroot  for
              Debian package building).

              Desktop  users  should  note that the fstab file desktop/fstab will need editing if
              you use gdm3.  The preserve-environment key should also be set to  ‘true’  so  that
              the environment is preserved inside the chroot.

              If none of the configuration profiles provided above meet your needs, then they may
              be edited to further customise them, and/or copied  and  used  as  a  template  for
              entirely  new  profiles.  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
              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).

              Note that the different profiles have  different  security  implications;  see  the
              section “Security” below for further details.

       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.   This  is
              useful  for  adding commands such as nice, ionice or eatmydata for all commands run
              inside the chroot.  nice and ionice will affect CPU and I/O scheduling.   eatmydata
              ingores  filesystem  fsync operations, and is useful for throwaway snapshot chroots
              where you don't care about dataloss, but do care about high speed.

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

       preserve-environment=true|false
              By  default,  the  environment  will  not be preserved inside the chroot, instead a
              minimal environment will be used.  Set to true to always preserve the  environment.
              This  is  useful  for  example when running X applications inside the chroot, which
              need the environment to function correctly.  The environment may also be  preserved
              using the --preserve-environment option.

       environment-filter=regex
              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.  In consequence, filesystems such as /proc are not mounted
       in plain chroots; it is the responsibility of the system administrator to  configure  such
       chroots  by  hand,  whereas directory chroots are automatically configured.  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
              (they should be set in the fstab file just like in /etc/fstab on the host).

              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).  Note that a corresponding source chroot (of type ‘file’) will be created for each
       chroot  of  this  type;  this is for convenient access to the source archive, e.g. for the
       purpose of updating. These additional options are also implemented:

       file=filename
              The file containing the archived chroot environment (mandatory).  This  must  be  a
              tar  (tape archive), optionally compressed with gzip or bzip2.  The file extensions
              used to determine the type are are .tar, .tar.gz, .tar.bz2, .tgz, and  .tbz.   This
              file  must  be owned by the root user, and not be writable by other.  Note that zip
              archives are no longer supported; zip was not  able  to  archive  named  pipes  and
              device nodes, so was not suitable for archiving chroots.

       location=path
              This  is  the  path  to the chroot inside the archive.  For example, if the archive
              contains a chroot in /squeeze, you would specify “/squeeze” here.  If the chroot is
              the  only  thing in the archive, i.e. / is the root filesystem for the chroot, this
              option should be left blank, or omitted entirely.

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

   Btrfs snapshot chroots
       Chroots of type ‘btrfs-snapshot’ are a Btrfs  snapshot  created  from  an  existing  Btrfs
       subvolume  on  a  mounted  Btrfs  filesystem.  A snapshot will be created from this source
       subvolume on demand at the start of a session, and then the snapshot will be mounted.   At
       the  end  of  the  session,  the snapshot will be unmounted and deleted.  This chroot type
       implements the source chroot options (see “Source chroot options”, below).   Note  that  a
       corresponding  source chroot (of type ‘directory’) will be created for each chroot of this
       type; this is for convenient access to the source volume.  These  additional  options  are
       also implemented:

       btrfs-source-subvolume=directory
              The directory containing the source subvolume.

       btrfs-snapshot-directory=directory
              The directory in which to store the snapshots of the above source subvolume.

   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.

       LVM  snapshot  chroots  implement  the source chroot options (see “Source chroot options”,
       below), and all the options for ‘block-device’.  Note that a corresponding  source  chroot
       (of  type  ‘block-device’)  will  be  created  for  each  chroot of this type; this is for
       convenient access to the source device. This additional option is also implemented:

       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
       The  ‘btrfs-snapshot’,  ‘file’  and  ‘lvm-snapshot’ chroot types implement source chroots.
       Additionally, chroot types with  union  support  enabled  implement  source  chroots  (see
       “Filesystem Union chroot options”, below).  These are chroots which automatically create a
       copy  of  themselves  before  use,  and  are  usually  session  managed.   These   chroots
       additionally  provide an extra chroot in the source: namespace, to allow convenient access
       to the original (non-snapshotted) data, and to aid in  chroot  maintenance.   I.e.  for  a
       chroot named wheezy (chroot:wheezy), a corresponding source:wheezy chroot will be created.
       For compatibility with older versions of schroot  which  did  not  support  namespaces,  a
       chroot with a -source suffix appended to the chroot name will be created in addition (i.e.
       wheezy-source using the above example).  Note  that  these  compatibility  names  will  be
       removed in schroot 1.5.0, so the use of the source: namespace is preferred over the use of
       the -source suffix form.  See schroot(1) for further details.

       These chroots provide the following additional options:

       source-clone=true|false
              Set whether the source chroot should be automatically  cloned  (created)  for  this
              chroot.  The default is true to automatically clone, but if desired may be disabled
              by setting to false.  If disabled, the source chroot will be inaccessible.

       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
       The ‘block-device’, ‘loopback’ and ‘lvm-snapshot’ chroot types 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
       The ‘block-device’, ‘directory’ and ‘loopback’ chroot types 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’,
              ‘overlayfs’ 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’,
              ‘overlayfs’ and ‘unionfs’ each 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 ‘@SCHROOT_OVERLAY_DIR@’.

       union-underlay-directory=directory
              Specify  the  directory where the read-only underlying directories will be created.
              The default is ‘@SCHROOT_UNDERLAY_DIR@’.

   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.

CHROOT NAMES

       A  number  of  characters  or  words  are  not permitted in a chroot name, session name or
       configuration filename.  The name may not contain a leading period (‘.’).  The  characters
       ‘:’  (colon),  ‘,’ (comma) and ‘/’ (forward slash) are not permitted anywhere in the name.
       The name  may  also  not  contain  a  trailing  tilde  (‘~’).   The  rationale  for  these
       restrictions is given below.

       ‘.’    A  leading  period  could  be  used to create a name with a relative path in it, in
              combination with ‘/’, and this  could  allow  overwriting  of  files  on  the  host
              filesystem.  Not allowing this character also means hidden files cannot be created.
              It also means some editor backups are automatically ignored.  Periods  are  allowed
              anywhere else in the name.

       ‘:’    A  colon  is  used  as  a namespace delimiter, and so is not permitted as part of a
              chroot or session name.  LVM snapshot names may also not contain this character due
              to a naming restriction by lvcreate(8).

       ‘/’    Names  containing  this  character  are not valid filenames.  A forward slash would
              potentially allow creation of files in subdirectories.

       ‘,’    Commas are used to separate items in lists.  Aliases are separated  by  commas  and
              hence can't contain commas in their name.

       ‘~’    Filenames  containing  trailing  tildes are used for editor backup files, which are
              ignored.  Tildes are allowed anywhere else in the name.

       ‘dpkg-old’
       ‘dpkg-dist’
       ‘dpkg-new’
       ‘dpkg-tmp’
              These names may not appear at the end  of  a  name.   These  are  saved  copies  of
              conffiles used by the dpkg package manager, and will be ignored.

SECURITY

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

       Do not give chroot root access to users you would not trust with root access to  the  host
       system.

   Profiles
       Depending  upon which profile you have configured with the script-config option, different
       filesystems will be mounted inside the chroot, and different files will be copied into the
       chroot  from  the  host.  Some profiles will mount the host's /dev, while others will not.
       Some profiles also bind mount additional parts of the host filesystem in  order  to  allow
       use  of  certain  features,  including user's home directories and specific parts of /var.
       Check the profile's fstab file to be certain of  what  will  be  mounted,  and  the  other
       profile  files  to  see  which  files and system databases will be copied into the chroot.
       Choose a different profile or edit the files to further restrict what  is  made  available
       inside the chroot.

       There  is  a  tradeoff  between  security  (keeping the chroot as minimal as possible) and
       usability (which sometimes  requires  access  to  parts  of  the  host  filesystem).   The
       different  profiles  make  different  tradeoffs, and it is important that you assess which
       meets the security/usability tradeoff you require.

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

       [sid-file]
       type=file
       description=Debian sid file-based chroot
       priority=3
       groups=sbuild
       file=/srv/chroots/sid.tar.gz

       [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

FILES

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

       @SCHROOT_CONF_CHROOT_D@
              Additional  chroot  definitions  may be placed in files under this directory.  They
              are treated in exactly that same manner as @SCHROOT_CONF@.  Each file  may  contain
              one or more chroot definitions.

   Setup script configuration
       The  directory  @SCHROOT_SYSCONF_DIR@/default  contains the default settings used by setup
       scripts.

       config Main configuration file read  by  setup  scripts.   The  format  of  this  file  is
              described   in  schroot-script-config(5).   This  is  the  default  value  for  the
              script-config     key.      Note     that     this     was      formerly      named
              @SCHROOT_SYSCONF_DIR@/script-defaults.   The  following  files  are  referenced  by
              default:

       copyfiles
              A list of files to copy into the chroot from the host system.  Note that  this  was
              formerly named @SCHROOT_SYSCONF_DIR@/copyfiles-defaults.

       fstab  A  file  in  the  format decribed in fstab(5), used to mount filesystems inside the
              chroot.  The mount location is relative to the root of the chroot.  Note that  this
              was formerly named @SCHROOT_SYSCONF_DIR@/mount-defaults.

       nssdatabases
              System  databases (as described in /etc/nsswitch.conf on GNU/Linux systems) to copy
              into  the  chroot  from  the   host.    Note   that   this   was   formerly   named
              @SCHROOT_SYSCONF_DIR@/nssdatabases-defaults.

AUTHORS

       Roger Leigh.

COPYRIGHT

       Copyright © 2005-2011  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), schroot-faq(7), mount(8).