Provided by: dchroot_1.6.10-1ubuntu3_amd64 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).