Man Linux: Main Page and Category List

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’,   ‘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  (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 is used by sbuild and wanna-
              build.

       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.

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

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

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

       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.

       For  each  chroot of this type, a corresponding ‘directory’ 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 subvolume.
       This chroot type implements the  source  chroot  options  (see  “Source
       chroot options”, below), plus these additional options:

       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.  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 additionally provide  an  extra  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-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
       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

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

   Setup script configuration
       The directory /etc/schroot/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  /etc/schroot/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
              /etc/schroot/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
              /etc/schroot/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 /etc/schroot/nssdatabases-defaults.

AUTHORS

       Roger Leigh.

COPYRIGHT

       Copyright © 2005-2010  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).