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

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