Man Linux: Main Page and Category List


       dchroot - enter a chroot environment


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


       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 “Migration” below for help migrating an existing
       dchroot configuration to schroot.  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.  If using the configuration  in  /etc/dchroot.conf,
       the first chroot in the file is the default.


       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.

              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.

              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.


       The  dchroot  configuration  file,  /etc/dchroot.conf,  used by earlier
       versions of dchroot, has the following format:

       ·      ‘#’ starts a comment line.

       ·      Blank lines are ignored.

       ·      Chroot definitions are a single line containing  an  identifier,
              path, and an optional personality separated by whitespace.

       ·      The first chroot is also the default chroot.

       An example file:

              # Example comment

              sarge /srv/chroot/sarge
              sid /srv/chroot/sid linux32

       This    file    defines   a   chroot   called   ‘sarge’,   located   at
       /srv/chroot/sarge,  and  a  second  chroot  called  ‘sid’,  located  at
       /srv/chroot/sid.   The  second  chroot  uses the ‘linux32’ personality,
       which allows a 32-bit chroot to be used on a 64-bit system.  ‘sarge’ is
       the  default chroot, because it was listed first, which means if the -c
       option is omitted this chroot will be used.


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

       ·      The parsing of /etc/dchroot.conf uses a smaller list of  allowed
              whitespace  characters  (space and tab), which may cause a parse
              error during tokenising if the file contains odd  characters  as
              separators,  such  as  carriage  returns, vertical tabs and form

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

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

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

       ·      This   version   of  dchroot  has  an  incompatible  format  for
              dchroot.conf.  While the first two  fields  are  the  same,  the
              remaining  fields  are  an  optional  users,  a  list  of  users
              permitted to access the chroot, instead of the personality field
              allowed  by  this  version.   If access restrictions are needed,
              please use /etc/schroot/schroot.conf and add the  allowed  users
              there, as shown in “Migration” below.


       To  migrate  an  existing dchroot configuration to schroot, perform the
       following steps:

       1      Dump the dchroot configuration  in  schroot  keyfile  format  to

              # dchroot --config >> /etc/schroot/schroot.conf

       2      Edit /etc/schroot/schroot.conf to add access to the users and/or
              groups which are to be allowed to access the chroots,  and  make
              any   other   desired   changes   to   the  configuration.   See

       3      Remove /etc/dchroot.conf, so that dchroot will subsequently  use
              /etc/schroot/schroot.conf for its configuration.


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

       $ dchroot -p sid

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

       $ dchroot -q -c sid "ls -1 / | tac | head -n 4"

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


       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

       If you are still having trouble, the developers may be contacted on the
       mailing list:
       Debian buildd-tools Developers


       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.


              The  system-wide dchroot chroot definition file.  This file must
              be owned by the root user, and not be  writable  by  other.   If
              present,   this   file   will   be   used   in   preference   to

              The system-wide schroot definition  file.   This  file  must  be
              owned  by  the  root  user, and not be writable by other.  It is
              recommended  that  this  file   be   used   in   preference   to
              /etc/dchroot.conf,    because    the   chroots   can   be   used
              interchangeably with schroot, and the user  and  group  security
              policies provided by schroot are also enforced.


       Roger Leigh.

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


       Copyright © 2005-2010  Roger Leigh <>

       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.


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