1SCHROOT(1) Debian sbuild SCHROOT(1)
2
6 schroot - securely enter a chroot environment
7
9 schroot [-h|--help | -V|--version | -l|--list | -i|--info | --config
10 | --location | --automatic-session | -b|--begin-session |
11 --recover-session | -r|--run-session | -e|--end-session] [-f|--force]
12 [-n session-name|--session-name=session-name] [-d directory|--direc‐
13 tory=directory] [-u user|--user=user] [-p|--preserve-environment]
14 [-q|--quiet | -v|--verbose] [-c chroot|--chroot=chroot | --all |
15 --all-chroots | --all-source-chroots | --all-sessions] [COMMAND [ ARG1
16 [ ARG2 [ ARGn]]]]
17
19 schroot allows the user to run a command or a login shell in a chroot
20 environment. If no command is specified, a login shell will be started
21 in the user's current working directory inside the chroot.
22 The command is a program, plus as many optional arguments as required.
24 Each argument may be separately quoted.
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 All chroot usage will be logged in the system logs. Under some circum‐
30 stances, the user may be required to authenticate themselves; see the
31 section “Authentication”, below.
32 If no chroot is specified, the chroot name or alias ‘default’ will be
34 used as a fallback. This is equivalent to “--chroot=default”.
35
37 There is often a need to run programs in a virtualised environment
38 rather than on the host system directly. Unlike other virtualisation
39 systems such as kvm or Xen, schroot does not virtualise the entire sys‐
40 tem; it only virtualises the filesystem, and some parts of the filesys‐
41 tem may still be shared with the host. It is therefore fast, light‐
42 weight and flexible. However, it does not virtualise other aspects of
43 the system, such as shared memory, networking, devices etc., and so may
44 be less secure than other systems, depending upon its intended use.
45 Some examples of existing uses for schroot include:
46 · Running an untrusted program in a sandbox, so that it can't
48 interfere with files on the host system; this may also be used
49 to limit the damage a compromised service can inflict upon the
50 host
51 · Using a defined or clean environment, to guarantee the repro‐
53 ducibility and integrity of a given task
54 · Using different versions of an operating system, or even differ‐
56 ent operating systems altogether, e.g. different GNU/Linux dis‐
57 tributions
58 · Running 32-bit programs using a 32-bit chroot on a 64-bit host
60 system
61 · Automatic building of Debian packages using sbuild(1), which
63 builds each package in a pristine chroot snapshot when using LVM
64 snapshots or unions
65 · Supporting multiple system images in a cluster setup, where mod‐
67 ifying the base image is time-consuming and/or supporting all
68 the required configurations needed by users is difficult: dif‐
69 ferent chroots can support all the different configurations
70 required, and cluster users may be given access to the chroots
71 they need (which can include root access for trusted users to
72 maintain their own images)
73 A chroot may be used directly as root by running chroot(8), but normal
75 users are not able to use this command. schroot allows access to
76 chroots for normal users using the same mechanism, but with permissions
77 checking and allowing additional automated setup of the chroot environ‐
78 ment, such as mounting additional filesystems and other configuration
79 tasks. This automated setup is done through the action of setup
80 scripts which may be customised and extended to perform any actions
81 required.
82
84 schroot accepts the following options:
85 Actions
87 -h, --help
88 Show help summary.
89 -V, --version
91 Print version information.
92 -l, --list
94 List all available chroots.
95 -i, --info
97 Print detailed information about the specified chroots.
98 --config
100 Print configuration of the specified chroots. This is useful
101 for testing that the configuration in use is the same as the
102 configuration file. Any comments in the original file will be
103 missing.
104 --location
106 Print location (path) of the specified chroots. Note that
107 chroot types which can only be used within a session will not
108 have a location until they are active.
109 General options
111 -q, --quiet
112 Print only essential messages.
113 -v, --verbose
115 Print all messages.
116 Chroot selection
118 -c, --chroot=chroot
119 Specify a chroot or active session to use. This option may be
120 used multiple times to specify more than one chroot, in which
121 case its effect is similar to --all. The chroot name may be
122 prefixed with a namespace; see the section “Chroot Namespaces”,
123 below.
124 -a, --all
126 Select all chroots, source chroots and active sessions. When a
127 command has been specified, the command will be run in all
128 chroots, source chroots and active sessions. If --info has been
129 used, display information about all chroots. This option does
130 not make sense to use with a login shell (when no command has
131 been specified). This option is equivalent to “--all-chroots
132 --all-source-chroots --all-sessions”.
133 --all-chroots
135 Select all chroots. Identical to --all, except that source
136 chroots and active sessions are not considered.
137 --all-sessions
139 Select all active sessions. Identical to --all, except that
140 chroots and source chroots are not considered.
141 --all-source-chroots
143 Select all source chroots. Identical to --all, except that
144 chroots and sessions are not considered.
145 Chroot environment
147 -d, --directory=directory
148 Change to directory inside the chroot before running the command
149 or login shell. If directory is not available, schroot will
150 exit with an error status.
151 The default behaviour is as follows (all directory paths are
153 inside the chroot). A login shell is run in the current working
154 directory. If this is not available, it will try $HOME (when
155 --preserve-environment is used), then the user's home directory,
156 and / inside the chroot in turn. A command is always run in the
157 current working directory inside the chroot. If none of the
158 directories are available, schroot will exit with an error sta‐
159 tus.
160 -u, --user=user
162 Run as a different user. The default is to run as the current
163 user. If required, the user may be required to authenticate
164 themselves with a password. For further information, see the
165 section “Authentication”, below.
166 -p, --preserve-environment
168 Preserve the user's environment inside the chroot environment.
169 The default is to use a clean environment; this option copies
170 the entire user environment and sets it in the session. The
171 environment variables allowed are subject to certain restric‐
172 tions; see the section “Environment”, below.
173 Session actions
175 --automatic-session
176 Begin, run and end a session automatically. This is the default
177 action, so does not require specifying in normal operation.
178 -b, --begin-session
180 Begin a session. A unique session identifier (session ID) is
181 returned on standard output. The session ID is required to use
182 the other session options. Note that the session identifier may
183 be specified with the --session-name option.
184 --recover-session
186 Recover an existing session. If an existing session has become
187 unavailable, for example becoming unmounted due to a reboot,
188 this option will make the session available for use again, for
189 example by remounting it. The session ID is specified with the
190 --chroot option.
191 -r, --run-session
193 Run an existing session. The session ID is specified with the
194 --chroot option.
195 -e, --end-session
197 End an existing session. The session ID is specified with the
198 --chroot option.
199 Session options
201 -n, --session-name=session-name
202 Name a session. The specified session-name replaces the default
203 session name containing an automatically-generated session ID.
204 The session name must not contain a namespace qualifier, since
205 sessions are always created within the ‘session:’ namespace.
206 -f, --force
208 Force a session operation, even if it would otherwise fail.
209 This may be used to forcibly end a session, even if it has
210 active users. This does not guarantee that the session will be
211 ended cleanly; filesystems may not be unmounted, for example.
212
214 If the user is not an allowed user, or a member of the allowed groups
215 (or if changing to root, the allowed root users or allowed root groups)
216 for the specified chroot(s), permission will be immediately denied. If
217 switching users, and the user running the command has access, the user
218 will be required to authenticate themselves using the credentials of
219 the user being switched to.
220 On systems supporting Pluggable Authentication Modules (PAM), schroot
222 will use PAM for authentication and authorisation of users. If and
223 when required, schroot will prompt for a password. If PAM is not
224 available, all authentication will automatically fail (user switching
225 is not supported without PAM).
226 Note that when PAM is in use, the root user is not granted any special
228 privileges by default in the program. However, the default PAM config‐
229 uration permits root to log in without a password (pam_rootok.so), but
230 this may be disabled to prevent root from accessing any chroots except
231 if specifically permitted. In such a situation, root must be added to
232 the allowed users or groups as for any other user or group. If PAM is
233 not available, the root user will be permitted to access all chroots,
234 even when not explicitly granted access.
235
237 Namespace basics
238 There are three different types of chroot: regular chroots, source
239 chroots and session chroots. These different types of chroot are sepa‐
240 rated into different namespaces. A namespace is a prefix to a chroot
241 name. Currently there are three namespaces: ‘chroot:’, ‘source:’ and
242 ‘session:’. Use --list --all to list all available chroots in all
243 namespaces. Because ‘:’ is used as the separator between namespace and
244 chroot names, it is not permitted to use this character in chroot
245 names.
246 Depending upon the action you request schroot to take, it may look for
248 the chroot in one of the three namespaces, or a particular namespace
249 may be specified. For example, a chroot named “sid” is actually named
250 “chroot:sid” if the namespace is included, but the namespace may be
251 omitted for most actions.
252 Source chroots
254 Some chroot types, for example LVM snapshots and Btrfs snapshots, pro‐
255 vide session-managed copy-on-write snapshots of the chroot. These also
256 provide a source chroot to allow easy access to the filesystem used as
257 a source for snapshotting. These are regular chroots as well, just
258 with the snapshotting disabled. For a chroot named “sid-snapshot”
259 (i.e. with a fully qualified name of “chroot:sid-snapshot”), there will
260 also be a corresponding source chroot named “source:sid-snapshot”.
261 Earlier versions of schroot provided source chroots with a ‘-source’
262 suffix. These are also provided for compatibility. In this example,
263 this would be called “chroot:sid-snapshot-source”. These compatibility
264 names will be dropped in a future version, so programs and scripts
265 should switch to using the namespace-qualified names rather than the
266 old suffix.
267 Session chroots
269 All sessions created with --begin-session are placed within the ‘ses‐
270 sion:’ namespace. A session named with --session-name may have any
271 name, even the same name as the chroot it was created from, providing
272 that it is unique within this namespace. This was not permitted in
273 previous versions of schroot which did not have namespaces.
274 Actions and default namespaces
276 All actions use ‘chroot:’ as the default namespace, with some session
277 actions being the exception. --run-session, --recover-session and
278 --end-session use ‘session:’ as the default namespace instead, since
279 these actions work on session chroots. The upshot is that the names‐
280 pace is usually never required except when you need to work with a
281 chroot in a namespace other than the default, such as when using a
282 source chroot. To make chroot selection unambiguous, it is always pos‐
283 sible to use the full name including the namespace, even when not
284 strictly required.
285
287 List available chroots
288 % schroot -l↵
289 chroot:default
290 chroot:etch
291 chroot:sid
292 chroot:testing
293 chroot:unstable
294 Get information about a chroot
296 % schroot -i -c sid↵
297 ——— Chroot ———
298 Name sid
299 Description Debian sid (unstable)
300 Type plain
301 Priority 3
302 Users rleigh
303 Groups sbuild
304 Root Users
305 Root Groups sbuild
306 Aliases unstable unstable-sbuild unstable-p
307 owerpc-sbuild
308 Environment Filter ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I
309 FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA
310 IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE
311 RMPATH)$
312 Run Setup Scripts true
313 Script Configuration script-defaults
314 Session Managed true
315 Personality linux32
316 Location /srv/chroot/sid
317 Use --all or -c multiple times to use all or multiple chroots, respec‐
319 tively.
320 Running commands in a chroot
322 % schroot -c sid /bin/ls↵
323 [sid chroot] Running command: “/bin/ls”
324 CVS sbuild-chroot.c sbuild-session.h schroot.conf.5
325 Makefile sbuild-chroot.h schroot.1 schroot.conf.5.in
326 Makefile.am sbuild-config.c schroot.1.in
327 Makefile.in sbuild-config.h schroot.c
328 pam sbuild-session.c schroot.conf
329 % schroot -c sid -- ls -1 | head -n 5↵
331 [sid chroot] Running command: “ls -1”
332 ABOUT-NLS
333 AUTHORS
334 COPYING
335 ChangeLog
336 INSTALL
337 Use -- to allow options beginning with ‘-’ or ‘--’ in the command to
339 run in the chroot. This prevents them being interpreted as options for
340 schroot itself. Note that the top line was echoed to standard error,
341 and the remaining lines to standard output. This is intentional, so
342 that program output from commands run in the chroot may be piped and
343 redirected as required; the data will be the same as if the command was
344 run directly on the host system.
345 Switching users
347 % schroot -c sid -u root↵
348 Password:
349 [sid chroot] (rleigh→root) Running login shell: “/bin/bash”
350 #
351 If the user ‘rleigh’ was in root-users in /etc/schroot/schroot.conf, or
353 one of the groups he belonged to was in root-groups, they would be
354 granted root access without authentication, but the PAM authorisation
355 step is still applied.
356 Sessions
358 A chroot may be needed to run more than one command. In particular,
359 where the chroot is created on the fly from an LVM LV or a file on
360 disc, there is a need to make the chroot persistent while a given task
361 (or set of tasks) is performed. Sessions exist for this purpose. For
362 simple chroot types such as ‘plain’ and ‘directory’, sessions may be
363 created but are not strictly necessary.
364 Let's start by looking at a session-capable chroot:
366 % schroot -i -c sid-snap↵
368 ——— Chroot ———
369 Name sid-snap
370 Description Debian sid snapshot
371 Type lvm-snapshot
372 Priority 3
373 Users maks rleigh
374 Groups sbuild
375 Root Users
376 Root Groups root sbuild
377 Aliases
378 Environment Filter ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I
379 FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA
380 IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE
381 RMPATH)$
382 Run Setup Scripts true
383 Script Configuration script-defaults
384 Session Managed true
385 Personality linux
386 Device /dev/hda_vg/sid_chroot
387 Mount Options -o atime,async,user_xattr
388 Source Users
389 Source Groups root rleigh
390 Source Root Users
391 Source Root Groups root rleigh
392 LVM Snapshot Options --size 2G -c 128
393 Note that the Session Managed option is set to ‘true’. This is a
395 requirement in order to use session management, and is supported by
396 most chroot types. Next, we will create a new session:
397 % schroot -b -c sid-snap↵
399 sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f
400 The session ID of the newly-created session is returned on standard
402 output. It is common to store it like this:
403 % SESSION=$(schroot -b -c sid-snap)↵
405 % echo $SESSION↵
406 sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f
407 The session may be used just like any normal chroot. This is what the
409 session looks like:
410 % schroot -i -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f↵
412 ——— Session ———
413 Name sid-snap-46195b04-0893-49bf-beb8-0d
414 4ccc899f0f
415 Description Debian sid snapshot
416 Type lvm-snapshot
417 Priority 3
418 Users maks rleigh
419 Groups sbuild
420 Root Users
421 Root Groups root sbuild
422 Aliases
423 Environment Filter ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I
424 FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA
425 IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE
426 RMPATH)$
427 Run Setup Scripts true
428 Script Configuration script-defaults
429 Session Managed true
430 Personality linux
431 Mount Location /var/lib/schroot/mount/sid-snap-461
432 95b04-0893-49bf-beb8-0d4ccc899f0f
433 Path /var/lib/schroot/mount/sid-snap-461
434 95b04-0893-49bf-beb8-0d4ccc899f0f
435 Mount Device /dev/hda_vg/sid-snap-46195b04-0893-
436 49bf-beb8-0d4ccc899f0f
437 Device /dev/hda_vg/sid_chroot
438 Mount Options -o atime,async,user_xattr
439 Source Users
440 Source Groups root rleigh
441 Source Root Users
442 Source Root Groups root rleigh
443 LVM Snapshot Device /dev/hda_vg/sid-snap-46195b04-0893-
444 49bf-beb8-0d4ccc899f0f
445 LVM Snapshot Options --size 2G -c 128
446 Now the session has been created, commands may be run in it:
448 % schroot -r -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f -- uname
450 -sr↵
451 I: [sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f chroot] Running com‐
452 mand: “uname -sr”
453 Linux 2.6.18-3-powerpc
454 % schroot -r -c $SESSION -- uname -sr↵
455 I: [sid-snap-fe170af9-d9be-4800-b1bd-de275858b938 chroot] Running com‐
456 mand: “uname -sr”
457 Linux 2.6.18-3-powerpc
458 When all the commands to run in the session have been performed, the
460 session may be ended:
461 % schroot -e -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f↵
463 % schroot -e -c $SESSION↵
464 Finally, the session names can be long and unwieldy. A name may be
466 specified instead of using the automatically generated session ID:
467 % schroot -b -c sid-snap -n my-session-name↵
469 my-session-name
470
472 If something is not working, and it's not clear from the error messages
473 what is wrong, try using the --debug=level option to turn on debugging
474 messages. This gives a great deal more information. Valid debug lev‐
475 els are ‘none’, and ‘notice’, ‘info’, ‘warning’ and ‘critical’ in order
476 of increasing severity. The lower the severity level, the more output.
477 If you are still having trouble, the developers may be contacted on the
479 mailing list:
480 Debian buildd-tools Developers
481 <buildd-tools-devel@lists.alioth.debian.org>
482
484 On the mips and mipsel architectures, Linux kernels up to and including
485 at least version 2.6.17 have broken personality(2) support, which
486 results in a failure to set the personality. This will be seen as an
487 “Operation not permitted” (EPERM) error. To work around this problem,
488 set personality to ‘undefined’, or upgrade to a more recent kernel.
489
491 By default, the environment is not preserved, and the following envi‐
492 ronment variables are defined: HOME, LOGNAME, PATH, SHELL, TERM (pre‐
493 served if already defined), and USER. The environment variables SCH‐
494 ROOT_COMMAND, SCHROOT_USER, SCHROOT_GROUP, SCHROOT_UID and SCHROOT_GID
495 are set inside the chroot specifying the command being run, the user
496 name, group name, user ID and group ID, respectively.
497 The following, potentially dangerous, environment variables are removed
499 for safety by default: BASH_ENV, CDPATH, ENV, HOSTALIASES, IFS,
500 KRB5_CONFIG, KRBCONFDIR, KRBTKFILE, KRB_CONF, LD_.*, LOCALDOMAIN,
501 NLSPATH, PATH_LOCALE, RES_OPTIONS, TERMINFO, TERMINFO_DIRS, and
502 TERMPATH. If desired, the environment-filter configuration key will
503 allow the exclusion list to the modified; see schroot.conf(5) for fur‐
504 ther details.
505
507 Configuration files
508 /etc/schroot/schroot.conf
509 The system-wide chroot definition file. This file must be owned
510 by the root user, and not be writable by other.
511 /etc/schroot/chroot.d
513 Additional chroot definitions may be placed in files under this
514 directory. They are treated in exactly that same manner as
515 /etc/schroot/schroot.conf. Each file may contain one or more
516 chroot definitions. Note that the files in this directory fol‐
517 low the same naming rules as run-parts(8) when run with the
518 --lsbsysinit option.
519 /etc/schroot/setup.d
521 The system-wide chroot setup script directories. See schroot-
522 setup(5).
523 /etc/pam.d/schroot
525 PAM configuration.
526 System directories
528 /usr/libexec/schroot
529 Directory containing helper programs used by setup scripts.
530 Session directories
532 Each directory contains a directory or file with the name of each ses‐
533 sion. Not all chroot types make use of all the following directories.
534 /var/lib/schroot/session
536 Directory containing the session configuration for each active
537 session.
538 /var/lib/schroot/mount
540 Directory used to mount the filesystems used by each active ses‐
541 sion.
542 /var/lib/schroot/union/underlay
544 Directory used for filesystem union source (underlay).
545 /var/lib/schroot/union/overlay
547 Directory used for filesystem union writeable overlay.
548 /var/lib/schroot/unpack
550 Directory used for unpacking file chroots.
551
553 Roger Leigh.
554
556 Copyright © 2005-2010 Roger Leigh <rleigh@debian.org>
557 schroot is free software: you can redistribute it and/or modify it
559 under the terms of the GNU General Public License as published by the
560 Free Software Foundation, either version 3 of the License, or (at your
561 option) any later version.
562
564 dchroot(1), sbuild(1), chroot(2), run-parts(8), schroot-setup(5), sch‐
565 root-faq(7), schroot.conf(5).
566Version 1.4.10 22 Aug 2010 SCHROOT(1)