Provided by: schroot_1.4.0-1ubuntu1_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.

       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), the user will be required to  authenticate
       themselves  (typically  with  a password, but this depends upon the PAM
       configuration).  All chroot usage will be logged in the system logs.

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

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.

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

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

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

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

AUTHORS

       Roger Leigh.

COPYRIGHT

       Copyright © 2005-2008  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.conf(5).