Provided by: schroot_1.4.7-1_i386 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-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.

       -a, --all
              Select all chroots and active sessions.  When a command has been
              specified,  the  command  will  be run in all 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-sessions”.

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

       --all-sessions
              Select all active sessions.  Identical  to  --all,  except  that
              chroots 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.
              Note  that it is not currently possible to create a session with
              the same name as a chroot or alias.

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

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.

EXAMPLES

   List available chroots
       % schroot -l␍
       default
       etch
       sid
       testing
       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/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-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

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