Provided by: dchroot_1.6.1-1_i386 bug

NAME

       dchroot - enter a chroot environment

SYNOPSIS

       dchroot  [-h|--help | -V|--version  | -l|--list | -i|--info  | --config
       |   --location]   [--directory=directory]   [-d|--preserve-environment]
       [-q|--quiet  |  -v|--verbose]  [-c  chroot|--chroot=chroot    |  --all]
       [COMMAND [ ARG1 [ ARG2 [ ARGn]]]]

DESCRIPTION

       dchroot 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 home directory inside the chroot.

       The command is one or more arguments which will be run  in  the  user's
       default  shell  using  its  -c  option.  As a result, shell code may be
       embedded in this argument.  If multiple command options are used,  they
       are  concatenated together, separated by spaces.  Users should be aware
       of the shell quoting issues this presents, and should  use  schroot  if
       necessary, which does not have any quoting issues.

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

       This  version  of  dchroot  is  a  compatibility  wrapper  around   the
       schroot(1) program.  It is provided for backward compatibility with the
       dchroot command-line options, but schroot  is  recommended  for  future
       use.    See   the   section   “Incompatibilities”   below   for   known
       incompatibilities with older versions of dchroot.

       If no chroot is specified, the chroot name or alias ‘default’  will  be
       used as a fallback.

OPTIONS

       dchroot accepts the following options:

   Basic options
       -h, --help
              Show help summary.

       -a, --all
              Select all chroots.

       -c, --chroot=chroot
              Specify a chroot to use.  This option may be used multiple times
              to specify more than one chroot, in which  case  its  effect  is
              similar to --all.

       -l, --list
              List all available chroots.

       -i, --info
              Print  detailed  information  about the specified chroots.  Note
              that earlier versions of dchroot did not include this option.

       -p, --path
              Print location (path) of 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.   Note that earlier versions of dchroot did not include
              this option.

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

              The default behaviour is as follows  (all  directory  paths  are
              inside the chroot).  Unless the --preserve-environment option is
              used to preserve the environment, the  login  shell  or  command
              will  run  in  the  user's  home  directory,  or  /  if the home
              directory is not  available.   When  the  --preserve-environment
              option  is  used,  it  will  attempt  to use the current working
              directory, again falling back to / if it is not accessible.   If
              none of the directories are available, dchroot will exit with an
              error status.

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

       -q, --quiet
              Print only essential messages.

       -v, --verbose
              Print all messages.  Note that earlier versions of  dchroot  did
              not include this option.

       -V, --version
              Print version information.

       Note that earlier versions of dchroot did not provide long options.

INCOMPATIBILITIES

   Debian dchroot prior to version 0.99.0
       ·      Log messages are worded and formatted differently.

       ·      su(1)  is  no longer used to run commands in the chroot; this is
              done by  dchroot  internally.   This  change  may  cause  subtle
              differences.   If  you find an incompatibility, please report it
              so it may be corrected.

       ·      dchroot  provides  a  restricted  subset  of  the  functionality
              implemented  by  schroot, but is still schroot underneath.  Thus
              dchroot is still subject to schroot security checking, including
              PAM  authentication  and  authorisation, and session management,
              for example, and hence may behave slightly differently to  older
              dchroot versions in some circumstances.

   Debian dchroot prior to version 1.5.1
       ·      This   version   of  dchroot  uses  schroot.conf  to  store  the
              configuration   for   available   chroots,   rather   than   the
              dchroot.conf   file   used   historically.    dchroot  supported
              automatic migration of dchroot.conf to the schroot.conf  keyfile
              format  with  its  --config option from versions 0.2.2 to 1.5.0;
              support for the old format is now no longer available.

   DSA dchroot
       Machines run by the Debian System Administrators for the Debian Project
       have   a  dchroot-dsa  package  which  provides  an  alternate  dchroot
       implementation.

       ·      All the above incompatibilities apply.

       ·      This version of dchroot has incompatible  command-line  options,
              and while some of those options are supported or have equivalent
              options by a different name, the -c option is  not  required  to
              specify  a  chroot, and this version of dchroot cannot implement
              this behaviour in a backward-compatible manner (because if -c is
              omitted,  the  default  chroot  is  used).  DSA dchroot uses the
              first non-option as the chroot to use, only allowing one  chroot
              to be used at once.

DIRECTORY FALLBACKS

       dchroot  will  select an appropriate directory to use within the chroot
       based upon whether the --directory  or  --preserve-environment  options
       are  used.   When explicitly specifying a directory, only one directory
       will be used for safety and consistency, while for  a  login  shell  or
       command  several possibilities may be tried.  Note that due to multiple
       fallbacks being  considered  for  commands,  it  is  dangerous  to  run
       commands using dchroot; use schroot instead.  The following subsections
       list the fallback sequence for each case.  CWD is the  current  working
       directory, DIR is the directory specified with --directory.

   Login shell or command
       ┌────────────────────┬──────────────────────────────────────────┐
       │Transition          │                                          │
       │(Host → Chroot)     │ Comment                                  │
       ├────────────────────┼──────────────────────────────────────────┤
       │CWD → passwd pw_dir │ Normal  behaviour  (if  --directory  and │
       │                    │ --preserve-environment are not used)     │
       │CWD → /             │ If passwd pw_dir is nonexistent          │
       │FAIL                │ If / is nonexistent                      │
       └────────────────────┴──────────────────────────────────────────┘
   --preserve-environment used
       ┌────────────────┬──────────────────────────────────────────┐
       │Transition      │                                          │
       │(Host → Chroot) │ Comment                                  │
       ├────────────────┼──────────────────────────────────────────┤
       │CWD → CWD       │ Normal           behaviour           (if │
       │                │ --preserve-environment used)             │
       │CWD → /         │ If CWD is nonexistent                    │
       │FAIL            │ If / is nonexistent                      │
       └────────────────┴──────────────────────────────────────────┘
   --directory used
       ┌────────────────┬──────────────────────────────────────────┐
       │Transition      │                                          │
       │(Host → Chroot) │ Comment                                  │
       ├────────────────┼──────────────────────────────────────────┤
       │CWD → DIR       │ Normal behaviour                         │
       │FAIL            │ If DIR is nonexistent                    │
       └────────────────┴──────────────────────────────────────────┘
       No fallbacks should exist under any circumstances.

   Debugging
       Note  that --debug=notice will show the internal fallback list computed
       for the session.

EXAMPLES

       $ dchroot -l↵
       Available chroots: sarge [default], sid

       $ dchroot -p sid↵
       /srv/chroot/sid

       $ dchroot -q -c sid -- uname -smr↵
       Linux 2.6.16.17 ppc
       $ dchroot -q -c sid -- "uname -smr"↵
       Linux 2.6.16.17 ppc

       $ dchroot -q -c sid "ls -1 / | tac | head -n 4"↵
       var
       usr
       tmp
       sys

       $ dchroot -c sid↵
       I: [sid chroot] Running login shell: “/bin/bash”
       $

       Use -- to allow options beginning with ‘-’ or ‘--’ in  the  command  to
       run in the chroot.  This prevents them being interpreted as options for
       dchroot 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.

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.

FILES

       /etc/schroot/schroot.conf
              The system-wide schroot definition  file.   This  file  must  be
              owned by the root user, and not be writable by other.

AUTHORS

       Roger Leigh.

       This  implementation  of  dchroot uses the same command-line options as
       the original dchroot by David Kimdon <dwhedon@debian.org>,  but  is  an
       independent implementation.

COPYRIGHT

       Copyright © 2005-2012  Roger Leigh <rleigh@debian.org>

       dchroot  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

       schroot(1), sbuild(1), chroot(2), schroot-setup(5), schroot.conf(5).