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

       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.

       -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
         Run Execution Scripts  false
         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
         Run Execution 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
         Run Execution 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/setup.d

       /etc/schroot/exec.d
              The  system-wide  chroot  setup  and execution 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), schroot-setup(5), schroot.conf(5).