Provided by: schroot_1.4.25-1_amd64 bug

NAME

       schroot - securely enter a chroot environment

SYNOPSIS

       schroot  [-h|--help  |  -V|--version   | -l|--list | -i|--info  | --config | --location  |
       --automatic-session  |  -b|--begin-session  |  --recover-session    |  -r|--run-session  |
       -e|--end-session]    [-f|--force]    [-n   session-name|--session-name=session-name]   [-d
       directory|--directory=directory]   [-u    user|--user=user]    [-p|--preserve-environment]
       [-q|--quiet  |  -v|--verbose]  [-c  chroot|--chroot=chroot    |  --all  |  --all-chroots |
       --all-source-chroots | --all-sessions] [--] [COMMAND [ ARG1 [ ARG2 [ ARGn]]]]

DESCRIPTION

       schroot allows the user to run a command or a login shell in a chroot environment.  If  no
       command  is  specified,  a  login  shell  will  be  started  in the user's current working
       directory inside the chroot.

       The command is a program, plus as many optional arguments as required.  Each argument  may
       be separately quoted.

       The  directory  the  command  or  login  shell  is  run  in depends upon the context.  See
       --directory option below for a complete description.

       All chroot usage will be logged in the system logs.  Under some  circumstances,  the  user
       may be required to authenticate themselves; see the section “Authentication”, below.

       If  no chroot is specified, the chroot name or alias ‘default’ will be used as a fallback.
       This is equivalent to “--chroot=default”.

OVERVIEW

       There is often a need to run programs in a virtualised environment rather than on the host
       system directly.  Unlike other virtualisation systems such as kvm or Xen, schroot does not
       virtualise the entire system; it only virtualises the filesystem, and some  parts  of  the
       filesystem  may  still  be  shared  with  the host.  It is therefore fast, lightweight and
       flexible.  However, it does not virtualise other aspects of the  system,  such  as  shared
       memory,  networking, devices etc., and so may be less secure than other systems, depending
       upon its intended use.  Some examples of existing uses for schroot include:

       ·      Running an untrusted program in a sandbox, so that it can't interfere with files on
              the  host  system;  this may also be used to limit the damage a compromised service
              can inflict upon the host

       ·      Using a  defined  or  clean  environment,  to  guarantee  the  reproducibility  and
              integrity of a given task

       ·      Using  different  versions  of  an  operating  system,  or even different operating
              systems altogether, e.g. different GNU/Linux distributions

       ·      Running 32-bit programs using a 32-bit chroot on a 64-bit host system

       ·      Automatic building of Debian packages using sbuild(1), which builds each package in
              a pristine chroot snapshot when using LVM snapshots or unions

       ·      Supporting  multiple  system  images  in  a cluster setup, where modifying the base
              image is time-consuming and/or supporting all the required configurations needed by
              users  is difficult: different chroots can support all the different configurations
              required, and cluster users may be given access to the chroots they need (which can
              include root access for trusted users to maintain their own images)

       A  chroot may be used directly as root by running chroot(8), but normal users are not able
       to use this command.  schroot allows access to chroots for normal  users  using  the  same
       mechanism,  but  with  permissions checking and allowing additional automated setup of the
       chroot environment, such as mounting additional filesystems and other configuration tasks.
       This  automated  setup is done through the action of setup scripts which may be customised
       and extended to perform any actions required.

OPTIONS

       schroot accepts the following options:

   Actions
       -h, --help
              Show help summary.

       -V, --version
              Print version information.

       -l, --list
              List all available chroots.

       -i, --info
              Print detailed information about the specified chroots.

       --config
              Print configuration of the specified chroots.  This is useful for testing that  the
              configuration  in  use  is the same as the configuration file.  Any comments in the
              original file will be missing.

       --location
              Print location (path) of the specified chroots.  Note that chroot types  which  can
              only be used within a session will not have a location until they are active.

   General options
       -q, --quiet
              Print only essential messages.

       -v, --verbose
              Print all messages.

   Chroot selection
       -c, --chroot=chroot
              Specify  a chroot or active session to use.  This option may be used multiple times
              to specify more than one chroot, in which case its effect is similar to --all.  The
              chroot  name may be prefixed with a namespace; see the section “Chroot Namespaces”,
              below.

       -a, --all
              Select all chroots, source chroots and active sessions.  When a  command  has  been
              specified,  the  command  will  be  run  in  all chroots, source chroots and active
              sessions.  If --info has been used, display information about  all  chroots.   This
              option  does  not  make  sense  to use with a login shell (when no command has been
              specified).  This  option  is  equivalent  to  “--all-chroots  --all-source-chroots
              --all-sessions”.

       --all-chroots
              Select  all  chroots.   Identical  to  --all, except that source chroots and active
              sessions are not considered.

       --all-sessions
              Select all active sessions.  Identical to --all, except  that  chroots  and  source
              chroots are not considered.

       --all-source-chroots
              Select  all  source  chroots.  Identical to --all, except that chroots and sessions
              are not considered.

   Chroot environment
       -d, --directory=directory
              Change to directory inside the chroot before running the command  or  login  shell.
              If directory is not available, schroot will exit with an error status.

              The default behaviour is as follows (all directory paths are inside the chroot).  A
              login shell is run in the current working directory.  If this is not available,  it
              will  try  $HOME  (when  --preserve-environment  is  used),  then  the  user's home
              directory, and / inside the chroot in turn.  A command is always run in the current
              working  directory  inside  the  chroot.  If none of the directories are available,
              schroot will exit with an error status.

       -u, --user=user
              Run as a different user.  The default is to run as the current user.  If  required,
              the  user  may be required to authenticate themselves with a password.  For further
              information, see the section “Authentication”, below.

       -p, --preserve-environment
              Preserve the user's environment inside the chroot environment.  The default  is  to
              use a clean environment; this option copies the entire user environment and sets it
              in  the  session.   The  environment  variables  allowed  are  subject  to  certain
              restrictions; see the section “Environment”, below.

   Session actions
       --automatic-session
              Begin,  run  and  end a session automatically.  This is the default action, so does
              not require specifying in normal operation.

       -b, --begin-session
              Begin a session.  A unique session identifier (session ID) is returned on  standard
              output.   The  session  ID is required to use the other session options.  Note that
              the session identifier may be specified with the --session-name option.

       --recover-session
              Recover an existing session.  If an existing session has  become  unavailable,  for
              example  becoming  unmounted  due  to  a  reboot, this option will make the session
              available for use again, for example by remounting it.  The session ID is specified
              with the --chroot option.

       -r, --run-session
              Run an existing session.  The session ID is specified with the --chroot option.

       -e, --end-session
              End an existing session.  The session ID is specified with the --chroot option.

   Session options
       -n, --session-name=session-name
              Name  a  session.   The  specified  session-name  replaces the default session name
              containing an automatically-generated  session  ID.   The  session  name  must  not
              contain  a  namespace  qualifier,  since  sessions  are  always  created within the
              ‘session:’ namespace.  The session name  is  also  subject  to  the  chroot  naming
              restrictions documented in schroot.conf(5).

       -f, --force
              Force  a  session  operation, even if it would otherwise fail.  This may be used to
              forcibly end a session, even if it has active users.  This does not guarantee  that
              the session will be ended cleanly; filesystems may not be unmounted, for example.

   Separator
       --     End  of  options.   Used  to indicate the end of the schroot options; any following
              options will be passed to the command being run, rather than to schroot.

AUTHENTICATION

       If the user is not an allowed user, or a member of the allowed groups (or if  changing  to
       root,  the  allowed  root  users  or  allowed  root  groups)  for the specified chroot(s),
       permission will be immediately denied.  If switching  users,  and  the  user  running  the
       command  has  access,  the  user  will  be  required  to authenticate themselves using the
       credentials of the user being switched to.

       On systems supporting Pluggable Authentication Modules (PAM), schroot  will  use  PAM  for
       authentication  and authorisation of users.  If and when required, schroot will prompt for
       a password.  If PAM is not available, all authentication  will  automatically  fail  (user
       switching is not supported without PAM).

       Note  that  when  PAM  is  in  use, the root user is not granted any special privileges by
       default in the program.  However, the default PAM configuration permits  root  to  log  in
       without  a  password  (pam_rootok.so),  but  this  may  be  disabled  to prevent root from
       accessing any chroots except if specifically permitted.  In such a situation, root must be
       added  to  the  allowed  users  or  groups  as for any other user or group.  If PAM is not
       available, the root user will be permitted to access all chroots, even when not explicitly
       granted access.

CHROOT NAMESPACES

   Namespace basics
       There  are  three  different  types of chroot: regular chroots, source chroots and session
       chroots.  These different types of chroot are  separated  into  different  namespaces.   A
       namespace  is a prefix to a chroot name.  Currently there are three namespaces: ‘chroot:’,
       ‘source:’ and ‘session:’.   Use  --list  --all  to  list  all  available  chroots  in  all
       namespaces.   Because  ‘:’ is used as the separator between namespace and chroot names, it
       is not permitted to use this character in chroot names.

       Depending upon the action you request schroot to take, it may look for the chroot  in  one
       of  the  three  namespaces,  or  a  particular namespace may be specified.  For example, a
       chroot named “sid” is actually named “chroot:sid” if the namespace is  included,  but  the
       namespace may be omitted for most actions.

   Source chroots
       Some  chroot types, for example LVM snapshots and Btrfs snapshots, provide session-managed
       copy-on-write snapshots of the chroot.  These also provide a source chroot to  allow  easy
       access  to the filesystem used as a source for snapshotting.  These are regular chroots as
       well, just with the snapshotting disabled.  For a chroot named “sid-snapshot” (i.e. with a
       fully  qualified name of “chroot:sid-snapshot”), there will also be a corresponding source
       chroot named “source:sid-snapshot”.  Earlier versions of schroot provided  source  chroots
       with  a  ‘-source’  suffix.   These are also provided for compatibility.  In this example,
       this would be called “chroot:sid-snapshot-source”.   These  compatibility  names  will  be
       dropped in a future version, so programs and scripts should switch to using the namespace-
       qualified names rather than the old suffix.

   Session chroots
       All sessions created with --begin-session are placed within the ‘session:’  namespace.   A
       session  named  with --session-name may have any name, even the same name as the chroot it
       was created from, providing that it  is  unique  within  this  namespace.   This  was  not
       permitted in previous versions of schroot which did not have namespaces.

   Actions and default namespaces
       All  actions  use  ‘chroot:’ as the default namespace, with some session actions being the
       exception.  --run-session, --recover-session  and  --end-session  use  ‘session:’  as  the
       default  namespace  instead,  since  these actions work on session chroots.  The upshot is
       that the namespace is usually never required except when you need to work with a chroot in
       a  namespace  other  than the default, such as when using a source chroot.  To make chroot
       selection unambiguous, it is always possible to use the full name including the namespace,
       even when not strictly required.

PERFORMANCE

       Performance  on  some  filesystems, for example Btrfs, is bad when running dpkg due to the
       amount of fsync operations performed.  This may be mitigated by installing  the  eatmydata
       package  and then adding eatmydata to the command-prefix configuration key, which disables
       all fsync operations.  Note that this should only be done in snapshot chroots  where  data
       loss  is  not  an  issue.   This  is  useful when using a chroot for package building, for
       example.

EXAMPLES

   List available chroots
       % schroot -l↵
       chroot:default
       chroot:etch
       chroot:sid
       chroot:testing
       chroot:unstable

   Get information about a chroot
       % schroot -i -c sid↵
         ——— Chroot ———
         Name                   sid
         Description            Debian sid (unstable)
         Type                   plain
         Priority               3
         Users                  rleigh
         Groups                 sbuild
         Root Users
         Root Groups            sbuild
         Aliases                unstable unstable-sbuild unstable-p
       owerpc-sbuild
         Environment Filter     ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I
       FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA
       IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE
       RMPATH)$
         Run Setup Scripts      true
         Script Configuration   script-defaults
         Session Managed        true
         Personality            linux32
         Location               /srv/chroot/sid

       Use --all or -c multiple times to use all or multiple chroots, respectively.

   Running commands in a chroot
       % schroot -c sid /bin/ls
       [sid chroot] Running command: “/bin/ls”
       CVS          sbuild-chroot.c   sbuild-session.h  schroot.conf.5
       Makefile     sbuild-chroot.h   schroot.1         schroot.conf.5.in
       Makefile.am  sbuild-config.c   schroot.1.in
       Makefile.in  sbuild-config.h   schroot.c
       pam          sbuild-session.c  schroot.conf

       % schroot -c sid -- ls -1 | head -n 5↵
       [sid chroot] Running command: “ls -1”
       ABOUT-NLS
       AUTHORS
       COPYING
       ChangeLog
       INSTALL

       Use -- to allow options beginning with ‘-’ or ‘--’ in the command to run  in  the  chroot.
       This  prevents  them  being  interpreted as options for schroot itself.  Note that the top
       line was echoed to standard error, and the remaining lines to standard  output.   This  is
       intentional,  so  that  program  output  from  commands run in the chroot may be piped and
       redirected as required; the data will be the same as if the command was  run  directly  on
       the host system.

   Switching users
       % schroot -c sid -u root↵
       Password:
       [sid chroot] (rleigh→root) Running login shell: “/bin/bash”
       #

       If  the user ‘rleigh’ was in root-users in /etc/schroot/schroot.conf, or one of the groups
       he  belonged  to  was  in  root-groups,  they  would  be  granted  root   access   without
       authentication, but the PAM authorisation step is still applied.

   Sessions
       A  chroot  may be needed to run more than one command.  In particular, where the chroot is
       created on the fly from an LVM LV or a file on disc, there is a need to  make  the  chroot
       persistent  while  a  given  task (or set of tasks) is performed.  Sessions exist for this
       purpose.  For simple chroot types such as ‘plain’ and ‘directory’, sessions may be created
       but are not strictly necessary.

       Let's start by looking at a session-capable chroot:

       % schroot -i -c sid-snap↵
         ——— Chroot ———
         Name                   sid-snap
         Description            Debian sid snapshot
         Type                   lvm-snapshot
         Priority               3
         Users                  maks rleigh
         Groups                 sbuild
         Root Users
         Root Groups            root sbuild
         Aliases
         Environment Filter     ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I
       FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA
       IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE
       RMPATH)$
         Run Setup Scripts      true
         Script Configuration   script-defaults
         Session Managed        true
         Personality            linux
         Device                 /dev/hda_vg/sid_chroot
         Mount Options          -o atime,async,user_xattr
         Source Users
         Source Groups          root rleigh
         Source Root Users
         Source Root Groups     root rleigh
         LVM Snapshot Options   --size 2G -c 128

       Note  that the Session Managed option is set to ‘true’.  This is a requirement in order to
       use session management, and is supported by most chroot types.  Next, we will create a new
       session:

       % schroot -b -c sid-snap↵
       sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f

       The  session ID of the newly-created session is returned on standard output.  It is common
       to store it like this:

       % SESSION=$(schroot -b -c sid-snap)↵
       % echo $SESSION↵
       sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f

       The session may be used just like any normal chroot.  This is what the session looks like:

       % schroot -i -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f↵
         ——— Session ———
         Name                   sid-snap-46195b04-0893-49bf-beb8-0d
       4ccc899f0f
         Description            Debian sid snapshot
         Type                   lvm-snapshot
         Priority               3
         Users                  maks rleigh
         Groups                 sbuild
         Root Users
         Root Groups            root sbuild
         Aliases
         Environment Filter     ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I
       FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA
       IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE
       RMPATH)$
         Run Setup Scripts      true
         Script Configuration   script-defaults
         Session Managed        true
         Personality            linux
         Mount Location         /var/lib/schroot/mount/sid-snap-461
       95b04-0893-49bf-beb8-0d4ccc899f0f
         Path                   /var/lib/schroot/mount/sid-snap-461
       95b04-0893-49bf-beb8-0d4ccc899f0f
         Mount Device           /dev/hda_vg/sid-snap-46195b04-0893-
       49bf-beb8-0d4ccc899f0f
         Device                 /dev/hda_vg/sid_chroot
         Mount Options          -o atime,async,user_xattr
         Source Users
         Source Groups          root rleigh
         Source Root Users
         Source Root Groups     root rleigh
         LVM Snapshot Device    /dev/hda_vg/sid-snap-46195b04-0893-
       49bf-beb8-0d4ccc899f0f
         LVM Snapshot Options   --size 2G -c 128

       Now the session has been created, commands may be run in it:

       % schroot -r -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f -- uname -sr↵
       I: [sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f chroot] Running command: “uname -sr”
       Linux 2.6.18-3-powerpc
       % schroot -r -c $SESSION -- uname -sr↵
       I: [sid-snap-fe170af9-d9be-4800-b1bd-de275858b938 chroot] Running command: “uname -sr”
       Linux 2.6.18-3-powerpc

       When all the commands to run in the session have been performed, the session may be ended:

       % schroot -e -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f↵
       % schroot -e -c $SESSION↵

       Finally, the session names can be long and unwieldy.  A name may be specified  instead  of
       using the automatically generated session ID:

       % schroot -b -c sid-snap -n my-session-name↵
       my-session-name

TROUBLESHOOTING

       If something is not working, and it's not clear from the error messages what is wrong, try
       using the --debug=level option to turn on debugging messages.  This  gives  a  great  deal
       more  information.   Valid  debug  levels  are ‘none’, and ‘notice’, ‘info’, ‘warning’ and
       ‘critical’ in order of increasing severity.   The  lower  the  severity  level,  the  more
       output.

       If you are still having trouble, the developers may be contacted on the mailing list:
       Debian buildd-tools Developers
       <buildd-tools-devel@lists.alioth.debian.org>

BUGS

       On  the  mips and mipsel architectures, Linux kernels up to and including at least version
       2.6.17 have broken  personality(2)  support,  which  results  in  a  failure  to  set  the
       personality.   This  will  be seen as an “Operation not permitted” (EPERM) error.  To work
       around this problem, set personality to ‘undefined’, or upgrade to a more recent kernel.

ENVIRONMENT

       By default, the environment is not preserved, and the following environment variables  are
       defined:  HOME,  LOGNAME, PATH, SHELL, TERM (preserved if already defined), and USER.  The
       environment  variables  SCHROOT_COMMAND,  SCHROOT_USER,  SCHROOT_GROUP,  SCHROOT_UID   and
       SCHROOT_GID  are  set  inside  the chroot specifying the command being run, the user name,
       group name, user ID and group ID, respectively.

       The following, potentially dangerous, environment variables  are  removed  for  safety  by
       default:  BASH_ENV,  CDPATH,  ENV,  HOSTALIASES,  IFS, KRB5_CONFIG, KRBCONFDIR, KRBTKFILE,
       KRB_CONF, LD_.*, LOCALDOMAIN, NLSPATH, PATH_LOCALE, RES_OPTIONS, TERMINFO,  TERMINFO_DIRS,
       and  TERMPATH.   If  desired,  the  environment-filter  configuration  key  will allow the
       exclusion list to the modified; see schroot.conf(5) for further details.

FILES

   Configuration 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.  Note that the files in this directory
              follow the same naming rules as run-parts(8) when run with the --lsbsysinit option.

       /etc/schroot/setup.d
              The system-wide chroot setup script directories.  See schroot-setup(5).

       /etc/pam.d/schroot
              PAM configuration.

   System directories
       /usr/lib/x86_64-linux-gnu/schroot
              Directory containing helper programs used by setup scripts.

   Session directories
       Each directory contains a directory or file with the name of each session.  Not all chroot
       types make use of all the following directories.

       /var/lib/schroot/session
              Directory containing the session configuration for each active session.

       /var/lib/schroot/mount
              Directory used to mount the filesystems used by each active session.

       /var/lib/schroot/union/underlay
              Directory used for filesystem union source (underlay).

       /var/lib/schroot/union/overlay
              Directory used for filesystem union writeable overlay.

       /var/lib/schroot/unpack
              Directory used for unpacking file chroots.

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

       dchroot(1),   sbuild(1),   chroot(2),   run-parts(8),   schroot-setup(5),  schroot-faq(7),
       schroot.conf(5).