Provided by: dchroot_1.4.25-1_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  “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.

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.

CONFIGURATION

       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.

INCOMPATIBILITIES

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

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

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

MIGRATION

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

       1      Dump    the    dchroot    configuration    in    schroot    keyfile    format    to
              /etc/schroot/schroot.conf.

              # 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 schroot.conf(5).

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

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/dchroot.conf
              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 /etc/schroot/schroot.conf.

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

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