1DCHROOT(1) Debian sbuild DCHROOT(1)
2
6 dchroot - enter a chroot environment
7
9 dchroot [-h|--help | -V|--version | -l|--list | -i|--info | --config
10 | --location] [--directory=directory] [-d|--preserve-environment]
11 [-q|--quiet | -v|--verbose] [-c chroot|--chroot=chroot | --all] [COM‐
12 MAND [ ARG1 [ ARG2 [ ARGn]]]]
13
15 dchroot allows the user to run a command or a login shell in a chroot
16 environment. If no command is specified, a login shell will be started
17 in the user's home directory inside the chroot.
18 The command is one or more arguments which will be run in the user's
20 default shell using its -c option. As a result, shell code may be
21 embedded in this argument. If multiple command options are used, they
22 are concatenated together, separated by spaces. Users should be aware
23 of the shell quoting issues this presents, and should use schroot if
24 necessary, which does not have any quoting issues.
25 The directory the command or login shell is run in depends upon the
27 context. See --directory option below for a complete description.
28 This version of dchroot is a compatibility wrapper around the sch‐
30 root(1) program. It is provided for backward compatibility with the
31 dchroot command-line options, but schroot is recommended for future
32 use. See the section “Migration” below for help migrating an existing
33 dchroot configuration to schroot. See the section “Incompatibilities”
34 below for known incompatibilities with older versions of dchroot.
35 If no chroot is specified, the chroot name or alias ‘default’ will be
37 used as a fallback. If using the configuration in /etc/dchroot.conf,
38 the first chroot in the file is the default.
39
41 dchroot accepts the following options:
42 Basic options
44 -h, --help
45 Show help summary.
46 -a, --all
48 Select all chroots.
49 -c, --chroot=chroot
51 Specify a chroot to use. This option may be used multiple times
52 to specify more than one chroot, in which case its effect is
53 similar to --all.
54 -l, --list
56 List all available chroots.
57 -i, --info
59 Print detailed information about the specified chroots. Note
60 that earlier versions of dchroot did not include this option.
61 -p, --path
63 Print location (path) of the specified chroots.
64 --config
66 Print configuration of the specified chroots. This is useful
67 for testing that the configuration in use is the same as the
68 configuration file. Any comments in the original file will be
69 missing. Note that earlier versions of dchroot did not include
70 this option.
71 --directory=directory
73 Change to directory inside the chroot before running the command
74 or login shell. If directory is not available, dchroot will
75 exit with an error status.
76 The default behaviour is as follows (all directory paths are
78 inside the chroot). Unless the --preserve-environment option is
79 used to preserve the environment, the login shell or command
80 will run in the user's home directory, or / if the home direc‐
81 tory is not available. When the --preserve-environment option
82 is used, it will attempt to use the current working directory,
83 again falling back to / if it is not accessible. If none of the
84 directories are available, dchroot will exit with an error sta‐
85 tus.
86 -d, --preserve-environment
88 Preserve the user's environment inside the chroot environment.
89 The default is to use a clean environment; this option copies
90 the entire user environment and sets it in the session.
91 -q, --quiet
93 Print only essential messages.
94 -v, --verbose
96 Print all messages. Note that earlier versions of dchroot did
97 not include this option.
98 -V, --version
100 Print version information.
101 Note that earlier versions of dchroot did not provide long options.
103
105 The dchroot configuration file, /etc/dchroot.conf, used by earlier ver‐
106 sions of dchroot, has the following format:
107 · ‘#’ starts a comment line.
109 · Blank lines are ignored.
111 · Chroot definitions are a single line containing an identifier,
113 path, and an optional personality separated by whitespace.
114 · The first chroot is also the default chroot.
116 An example file:
118 # Example comment
120 sarge /srv/chroot/sarge
122 sid /srv/chroot/sid linux32
123 This file defines a chroot called ‘sarge’, located at
125 /srv/chroot/sarge, and a second chroot called ‘sid’, located at
126 /srv/chroot/sid. The second chroot uses the ‘linux32’ personality,
127 which allows a 32-bit chroot to be used on a 64-bit system. ‘sarge’ is
128 the default chroot, because it was listed first, which means if the -c
129 option is omitted this chroot will be used.
130
132 Debian dchroot prior to version 0.99.0
133 · Log messages are worded and formatted differently.
134 · The parsing of /etc/dchroot.conf uses a smaller list of allowed
136 whitespace characters (space and tab), which may cause a parse
137 error during tokenising if the file contains odd characters as
138 separators, such as carriage returns, vertical tabs and form
139 feeds.
140 · su(1) is no longer used to run commands in the chroot; this is
142 done by dchroot internally. This change may cause subtle dif‐
143 ferences. If you find an incompatibility, please report it so
144 it may be corrected.
145 · dchroot provides a restricted subset of the functionality imple‐
147 mented by schroot, but is still schroot underneath. Thus dch‐
148 root is still subject to schroot security checking, including
149 PAM authentication and authorisation, and session management,
150 for example, and hence may behave slightly differently to older
151 dchroot versions in some circumstances.
152 DSA dchroot
154 Machines run by the Debian System Administrators for the Debian Project
155 have a dchroot-dsa package which provides an alternate dchroot imple‐
156 mentation.
157 · All the above incompatibilities apply.
159 · This version of dchroot has incompatible command-line options,
161 and while some of those options are supported or have equivalent
162 options by a different name, the -c option is not required to
163 specify a chroot, and this version of dchroot cannot implement
164 this behaviour in a backward-compatible manner (because if -c is
165 omitted, the default chroot is used). DSA dchroot uses the
166 first non-option as the chroot to use, only allowing one chroot
167 to be used at once.
168 · This version of dchroot has an incompatible format for dch‐
170 root.conf. While the first two fields are the same, the remain‐
171 ing fields are an optional users, a list of users permitted to
172 access the chroot, instead of the personality field allowed by
173 this version. If access restrictions are needed, please use
174 /etc/schroot/schroot.conf and add the allowed users there, as
175 shown in “Migration” below.
176
178 To migrate an existing dchroot configuration to schroot, perform the
179 following steps:
180 1 Dump the dchroot configuration in schroot keyfile format to
182 /etc/schroot/schroot.conf.
183 # dchroot --config >> /etc/schroot/schroot.conf
185 2 Edit /etc/schroot/schroot.conf to add access to the users and/or
187 groups which are to be allowed to access the chroots, and make
188 any other desired changes to the configuration. See sch‐
189 root.conf(5).
190 3 Remove /etc/dchroot.conf, so that dchroot will subsequently use
192 /etc/schroot/schroot.conf for its configuration.
193
195 $ dchroot -l
196 Available chroots: sarge [default], sid
197 $ dchroot -p sid
199 /srv/chroot/sid
200 $ dchroot -q -c sid -- uname -smr
202 Linux 2.6.16.17 ppc
203 $ dchroot -q -c sid -- "uname -smr"
204 Linux 2.6.16.17 ppc
205 $ dchroot -q -c sid "ls -1 / | tac | head -n 4"
207 var
208 usr
209 tmp
210 sys
211 $ dchroot -c sid
213 I: [sid chroot] Running login shell: “/bin/bash”
214 $
215 Use -- to allow options beginning with ‘-’ or ‘--’ in the command to
217 run in the chroot. This prevents them being interpreted as options for
218 dchroot itself. Note that the top line was echoed to standard error,
219 and the remaining lines to standard output. This is intentional, so
220 that program output from commands run in the chroot may be piped and
221 redirected as required; the data will be the same as if the command was
222 run directly on the host system.
223
225 If something is not working, and it's not clear from the error messages
226 what is wrong, try using the --debug=level option to turn on debugging
227 messages. This gives a great deal more information. Valid debug lev‐
228 els are ‘none’, and ‘notice’, ‘info’, ‘warning’ and ‘critical’ in order
229 of increasing severity. The lower the severity level, the more output.
230 If you are still having trouble, the developers may be contacted on the
232 mailing list:
233 Debian buildd-tools Developers
234 <buildd-tools-devel@lists.alioth.debian.org>
235
237 On the mips and mipsel architectures, Linux kernels up to and including
238 at least version 2.6.17 have broken personality(2) support, which
239 results in a failure to set the personality. This will be seen as an
240 “Operation not permitted” (EPERM) error. To work around this problem,
241 set personality to ‘undefined’, or upgrade to a more recent kernel.
242
244 /etc/dchroot.conf
245 The system-wide dchroot chroot definition file. This file must
246 be owned by the root user, and not be writable by other. If
247 present, this file will be used in preference to /etc/sch‐
248 root/schroot.conf.
249 /etc/schroot/schroot.conf
251 The system-wide schroot definition file. This file must be
252 owned by the root user, and not be writable by other. It is
253 recommended that this file be used in preference to /etc/dch‐
254 root.conf, because the chroots can be used interchangeably with
255 schroot, and the user and group security policies provided by
256 schroot are also enforced.
257
259 Roger Leigh.
260 This implementation of dchroot uses the same command-line options as
262 the original dchroot by David Kimdon <dwhedon@debian.org>, but is an
263 independent implementation.
264
266 Copyright © 2005-2010 Roger Leigh <rleigh@debian.org>
267 dchroot is free software: you can redistribute it and/or modify it
269 under the terms of the GNU General Public License as published by the
270 Free Software Foundation, either version 3 of the License, or (at your
271 option) any later version.
272
274 schroot(1), sbuild(1), chroot(2), schroot-setup(5), schroot.conf(5).
275Version 1.4.10 22 Aug 2010 DCHROOT(1)