1SCHROOT(1)                       Debian sbuild                      SCHROOT(1)
2
3
4

NAME

6       schroot - securely enter a chroot environment
7

SYNOPSIS

9       schroot  [-h|--help | -V|--version  | -l|--list | -i|--info  | --config
10       | --location  |  --automatic-session    |  -b|--begin-session  |  --re‐
11       cover-session   | -r|--run-session | -e|--end-session] [-f|--force] [-n
12       session-name|--session-name=session-name] [-d directory|--directory=di‐
13       rectory]    [-u   user|--user=user]   [-p|--preserve-environment]   [-s
14       shell|--shell=shell]  [-q|--quiet  |  -v|--verbose]  [-c   chroot|--ch‐
15       root=chroot     |  [--all  |  --all-chroots  |  --all-source-chroots  |
16       --all-sessions] [--exclude-aliases]] [-o|--option=key=value] [--] [COM‐
17       MAND [ ARG1 [ ARG2 [ ARGn]]]]
18

DESCRIPTION

20       schroot  allows  the user to run a command or a login shell in a chroot
21       environment.  If no command is specified, a login shell will be started
22       in the user's current working directory inside the chroot.
23
24       The  command is a program, plus as many optional arguments as required.
25       Each argument may be separately quoted.
26
27       The directory the command or login shell is run  in  depends  upon  the
28       context.  See --directory option below for a complete description.
29
30       All chroot usage will be logged in the system logs.  Under some circum‐
31       stances, the user may be required to authenticate themselves;  see  the
32       section “Authentication”, below.
33
34       If  no  chroot is specified, the chroot name or alias ‘default’ will be
35       used as a fallback.  This is equivalent to “--chroot=default”.
36

OVERVIEW

38       There is often a need to run  programs  in  a  virtualised  environment
39       rather  than  on the host system directly.  Unlike other virtualisation
40       systems such as kvm or Xen, schroot does not virtualise the entire sys‐
41       tem; it only virtualises the filesystem, and some parts of the filesys‐
42       tem may still be shared with the host.  It is  therefore  fast,  light‐
43       weight  and flexible.  However, it does not virtualise other aspects of
44       the system, such as shared memory, networking, devices etc., and so may
45       be  less  secure  than  other systems, depending upon its intended use.
46       Some examples of existing uses for schroot include:
47
48       •      Running an untrusted program in a sandbox, so that it can't  in‐
49              terfere  with files on the host system; this may also be used to
50              limit the damage a compromised service can inflict upon the host
51
52       •      Using a defined or clean environment, to  guarantee  the  repro‐
53              ducibility and integrity of a given task
54
55       •      Using different versions of an operating system, or even differ‐
56              ent operating systems altogether, e.g. different GNU/Linux  dis‐
57              tributions
58
59       •      Running  32-bit  programs using a 32-bit chroot on a 64-bit host
60              system
61
62       •      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
66       •      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 re‐
70              quired, 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
74       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 ch‐
76       roots for normal users using the same mechanism, but with several addi‐
77       tional  features.  While schroot uses a directory as a chroot just like
78       chroot(8), it does not require this to be a regular  directory  in  the
79       filesystem.   While this is the default, the chroot can also be created
80       from a file, a filesystem, including LVM and Btrfs snapshots and  loop‐
81       back  mounts, or composed of a unionfs overlay.  Being user-extensible,
82       the scope for creating chroots from different sources is  limited  only
83       by  your imagination.  schroot performs permissions checking and allows
84       additional automated setup of the chroot environment, such as  mounting
85       additional  filesystems  and other configuration tasks.  This automated
86       setup is done through the action of setup scripts  which  may  be  cus‐
87       tomised  and extended to perform any actions required.  Typical actions
88       include mounting the user's home directory, setting up  networking  and
89       system  databases,  and even starting up services.  These are again en‐
90       tirely customisable by the admin.  The setup scripts are  run  for  all
91       types  of  chroot, with the exception of the ‘plain’ type, the simplest
92       chroot type, offering no automated setup features at all.  The configu‐
93       ration of schroot is covered in more detail in schroot.conf(5).
94

OPTIONS

96       schroot accepts the following options:
97
98   Actions
99       -h, --help
100              Show help summary.
101
102       -V, --version
103              Print version information.
104
105       -l, --list
106              List all available chroots.
107
108       -i, --info
109              Print detailed information about the specified chroots.
110
111       --config
112              Print  configuration  of  the specified chroots.  This is useful
113              for testing that the configuration in use is  the  same  as  the
114              configuration  file.   Any comments in the original file will be
115              missing.
116
117       --location
118              Print location (path) of the specified chroots.  Note  that  ch‐
119              root types which can only be used within a session will not have
120              a location until they are active.
121
122   General options
123       -q, --quiet
124              Print only essential messages.
125
126       -v, --verbose
127              Print all messages.
128
129   Chroot selection
130       -c, --chroot=chroot
131              Specify a chroot or active session to use.  This option  may  be
132              used  multiple  times  to specify more than one chroot, in which
133              case its effect is similar to --all.  The  chroot  name  may  be
134              prefixed  with a namespace; see the section “Chroot Namespaces”,
135              below.
136
137       -a, --all
138              Select all chroots, source chroots and active sessions.  When  a
139              command  has  been specified, the command will be run in all ch‐
140              roots, source chroots and active sessions.  If --info  has  been
141              used,  display  information about all chroots.  This option does
142              not make sense to use with a login shell (run  when  no  command
143              has  been  specified).   This option is equivalent to “--all-ch‐
144              roots --all-source-chroots --all-sessions”.
145
146       --all-chroots
147              Select all chroots.  Identical to --all, except that source  ch‐
148              roots and active sessions are not considered.
149
150       --all-sessions
151              Select all active sessions.  Identical to --all, except that ch‐
152              roots and source chroots are not considered.
153
154       --all-source-chroots
155              Select all source chroots.  Identical to --all, except that  ch‐
156              roots and sessions are not considered.
157
158       --exclude-aliases
159              Do not select aliases in addition to chroots.  This ensures that
160              only real chroots are selected, and are only listed once.
161
162   Chroot environment
163       -d, --directory=directory
164              Change to directory inside the chroot before running the command
165              or  login  shell.   If  directory is not available, schroot will
166              exit with an error status.
167
168              The default behaviour is as follows (all directory paths are in‐
169              side  the  chroot).  A login shell is run in the current working
170              directory.  If this is not available, it will  try  $HOME  (when
171              --preserve-environment is used), then the user's home directory,
172              and / inside the chroot in turn.  A command is always run in the
173              current working directory inside the chroot.  If none of the di‐
174              rectories are available, schroot will exit with an error status.
175
176       -u, --user=user
177              Run as a different user.  The default is to run as  the  current
178              user.   If  required,  the  user may be required to authenticate
179              themselves with a password.  For further  information,  see  the
180              section “Authentication”, below.
181
182       -p, --preserve-environment
183              Preserve  the  user's environment inside the chroot environment.
184              The default is to use a clean environment;  this  option  copies
185              the entire user environment and sets it in the session.  The en‐
186              vironment variables allowed are subject to certain restrictions;
187              see the section “Environment”, below.
188
189       -s, --shell=shell
190              Use shell as the login shell.  When running a login shell a num‐
191              ber of potential shells will be considered, in this  order:  the
192              command  in  the SHELL environment variable (if --preserve-envi‐
193              ronment is used, or preserve-environment is enabled), the user's
194              shell  in  the ‘passwd’ database, /bin/bash and finally /bin/sh.
195              This option overrides this list, and will use the  shell  speci‐
196              fied.   This  option also overrides the shell configuration key,
197              if set.
198
199       -o, --option=key=value
200              Set an option.  The value of selected configuration keys in sch‐
201              root.conf  may  be  modified using this option.  The key must be
202              present in the user-modifiable-keys configuration  key  in  sch‐
203              root.conf,  or additionally the user-modifiable-keys key if run‐
204              ning as (or switching to) the root user.  The key and value  set
205              here  will  be  set in the environment of the setup scripts, and
206              may hence be used to customise the chroot on a  per-session  ba‐
207              sis.
208
209   Session actions
210       --automatic-session
211              Begin, run and end a session automatically.  This is the default
212              action, so does not require specifying in normal operation.
213
214       -b, --begin-session
215              Begin a session.  A unique session identifier  (session  ID)  is
216              returned  on standard output.  The session ID is required to use
217              the other session options.  Note that the session identifier may
218              be specified with the --session-name option.
219
220       --recover-session
221              Recover  an existing session.  If an existing session has become
222              unavailable, for example becoming unmounted  due  to  a  reboot,
223              this  option  will make the session available for use again, for
224              example by remounting it.  The session ID is specified with  the
225              --chroot option.
226
227       -r, --run-session
228              Run  an  existing session.  The session ID is specified with the
229              --chroot option.
230
231       -e, --end-session
232              End an existing session.  The session ID is specified  with  the
233              --chroot option.
234
235   Session options
236       -n, --session-name=session-name
237              Name a session.  The specified session-name replaces the default
238              session name containing an automatically-generated  session  ID.
239              The  session  name must not contain a namespace qualifier, since
240              sessions are always created  within  the  ‘session:’  namespace.
241              The  session  name is also subject to the chroot naming restric‐
242              tions documented in schroot.conf(5).
243
244       -f, --force
245              Force a session operation, even  if  it  would  otherwise  fail.
246              This  may  be used to forcibly end a session, even if it has ac‐
247              tive users.  This does not guarantee that the  session  will  be
248              ended cleanly; filesystems may not be unmounted, for example.
249
250   Separator
251       --     End  of  options.   Used  to indicate the end of the schroot op‐
252              tions; any following options will be passed to the command being
253              run, rather than to schroot.
254

AUTHENTICATION

256       If  the  user is not an allowed user, or a member of the allowed groups
257       (or if changing to root, the allowed root users or allowed root groups)
258       for the specified chroot(s), permission will be immediately denied.  If
259       switching users, and the user running the command has access, the  user
260       will  be  required  to authenticate themselves using the credentials of
261       the user being switched to.
262
263       On systems supporting Pluggable Authentication Modules  (PAM),  schroot
264       will  use  PAM  for  authentication and authorisation of users.  If and
265       when required, schroot will prompt for  a  password.   If  PAM  is  not
266       available,  all  authentication will automatically fail (user switching
267       is not supported without PAM).
268
269       Note that when PAM is in use, the root user is not granted any  special
270       privileges by default in the program.  However, the default PAM config‐
271       uration permits root to log in without a password (pam_rootok.so),  but
272       this  may be disabled to prevent root from accessing any chroots except
273       if specifically permitted.  In such a situation, root must be added  to
274       the  allowed users or groups as for any other user or group.  If PAM is
275       not available, the root user will be permitted to access  all  chroots,
276       even when not explicitly granted access.
277

CHROOT NAMESPACES

279   Namespace basics
280       There  are three different types of chroot: regular chroots, source ch‐
281       roots and session chroots.  These different types of chroot  are  sepa‐
282       rated  into  different namespaces.  A namespace is a prefix to a chroot
283       name.  Currently there are three namespaces: ‘chroot:’,  ‘source:’  and
284       ‘session:’.   Use  --list  --all  to  list all available chroots in all
285       namespaces.  Because ‘:’ is used as the separator between namespace and
286       chroot  names,  it  is  not  permitted  to use this character in chroot
287       names.
288
289       Depending upon the action you request schroot to take, it may look  for
290       the  chroot  in  one of the three namespaces, or a particular namespace
291       may be specified.  For example, a chroot named “sid” is actually  named
292       “chroot:sid”  if  the  namespace  is included, but the namespace may be
293       omitted for most actions.
294
295   Source chroots
296       Some chroot types, for example LVM snapshots and Btrfs snapshots,  pro‐
297       vide session-managed copy-on-write snapshots of the chroot.  These also
298       provide a source chroot to allow easy access to the filesystem used  as
299       a  source  for  snapshotting.   These are regular chroots as well, just
300       with the snapshotting disabled.   For  a  chroot  named  “sid-snapshot”
301       (i.e. with a fully qualified name of “chroot:sid-snapshot”), there will
302       also be a  corresponding  source  chroot  named  “source:sid-snapshot”.
303       Earlier  versions  of  schroot provided source chroots with a ‘-source’
304       suffix.  These are also provided for compatibility.  In  this  example,
305       this would be called “chroot:sid-snapshot-source”.  These compatibility
306       names will be dropped in a future  version,  so  programs  and  scripts
307       should  switch  to  using the namespace-qualified names rather than the
308       old suffix.
309
310   Session chroots
311       All sessions created with --begin-session are placed within  the  ‘ses‐
312       sion:’  namespace.   A  session  named with --session-name may have any
313       name, even the same name as the chroot it was created  from,  providing
314       that  it  is  unique  within this namespace.  This was not permitted in
315       previous versions of schroot which did not have namespaces.
316
317   Actions and default namespaces
318       All actions use ‘chroot:’ as the default namespace, with  some  session
319       actions  being  the  exception.   --run-session,  --recover-session and
320       --end-session use ‘session:’ as the default  namespace  instead,  since
321       these  actions  work  on session chroots.  The upshot is that the name‐
322       space is usually never required except when you need to work with a ch‐
323       root in a namespace other than the default, such as when using a source
324       chroot.  To make chroot selection unambiguous, it is always possible to
325       use  the  full name including the namespace, even when not strictly re‐
326       quired.
327

PERFORMANCE

329       Performance on some filesystems, for example Btrfs, is bad when running
330       dpkg due to the amount of fsync operations performed.  This may be mit‐
331       igated by installing the eatmydata package and then adding eatmydata to
332       the  command-prefix  configuration key, which disables all fsync opera‐
333       tions.  Note that this should only be done in  snapshot  chroots  where
334       data  loss  is  not  an  issue.  This is useful when using a chroot for
335       package building, for example.
336

DIRECTORY FALLBACKS

338       schroot will select an appropriate directory to use within  the  chroot
339       based  upon  whether an interactive login shell will be used, or a com‐
340       mand invoked, and additionally if the --directory option is  used.   In
341       the  case  of running commands directly, or explicitly specifying a di‐
342       rectory, only one directory will be used for  safety  and  consistency,
343       while  for  a login shell several possibilities may be tried.  The fol‐
344       lowing subsections list the fallback sequence for each  case.   CWD  is
345       the  current  working  directory,  DIR  is the directory specified with
346       --directory.
347
348   Login shell
349       ┌────────────────────┬──────────────────────────────────────────┐
350       │Transition          │                                          │
351       │(Host → Chroot)     │ Comment                                  │
352       ├────────────────────┼──────────────────────────────────────────┤
353       │CWD → CWD           │ Normal behaviour (if --directory is  not │
354       │                    │ used)                                    │
355       │CWD → $HOME         │ If CWD is nonexistent and --preserve-en‐ │
356       │                    │ vironment is used                        │
357       │CWD → passwd pw_dir │ If CWD is nonexistent (or --preserve-en‐ │
358       │                    │ vironment is used and no $HOME exists)   │
359       │CWD → /             │ None of the above exist                  │
360FAIL                │ If / is nonexistent                      │
361       └────────────────────┴──────────────────────────────────────────┘
362   Command
363       ┌────────────────┬──────────────────────────────────────────┐
364       │Transition      │                                          │
365       │(Host → Chroot) │ Comment                                  │
366       ├────────────────┼──────────────────────────────────────────┤
367       │CWD → CWD       │ Normal  behaviour (if --directory is not │
368       │                │ used)                                    │
369FAIL            │ If CWD is nonexistent                    │
370       └────────────────┴──────────────────────────────────────────┘
371       No fallbacks should exist under any circumstances.
372
373   --directory used
374       ┌────────────────┬──────────────────────────────────────────┐
375       │Transition      │                                          │
376       │(Host → Chroot) │ Comment                                  │
377       ├────────────────┼──────────────────────────────────────────┤
378       │CWD → DIR       │ Normal behaviour                         │
379FAIL            │ If DIR is nonexistent                    │
380       └────────────────┴──────────────────────────────────────────┘
381       No fallbacks should exist under any circumstances.
382
383   Debugging
384       Note that --debug=notice will show the internal fallback list  computed
385       for the session.
386

EXAMPLES

388   List available chroots
389       % schroot -l
390       chroot:default
391       chroot:etch
392       chroot:sid
393       chroot:testing
394       chroot:unstable
395
396   Get information about a chroot
397       % schroot -i -c sid
398         ——— Chroot ———
399         Name                   sid
400         Description            Debian sid (unstable)
401         Type                   plain
402         Priority               3
403         Users                  rleigh
404         Groups                 sbuild
405         Root Users
406         Root Groups            sbuild
407         Aliases                unstable unstable-sbuild unstable-p
408       owerpc-sbuild
409         Environment Filter     ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I\
410       FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA\
411       IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE\
412       RMPATH)$
413         Run Setup Scripts      true
414         Script Configuration   script-defaults
415         Session Managed        true
416         Personality            linux32
417         Location               /srv/chroot/sid
418
419       Use  --all or -c multiple times to use all or multiple chroots, respec‐
420       tively.
421
422   Running commands in a chroot
423       % schroot -c sid /bin/ls
424       [sid chroot] Running command: “/bin/ls”
425       CVS          sbuild-chroot.c   sbuild-session.h  schroot.conf.5
426       Makefile     sbuild-chroot.h   schroot.1         schroot.conf.5.in
427       Makefile.am  sbuild-config.c   schroot.1.in
428       Makefile.in  sbuild-config.h   schroot.c
429       pam          sbuild-session.c  schroot.conf
430       % schroot -c sid -- ls -1 | head -n 5
431       [sid chroot] Running command: “ls -1”
432       ABOUT-NLS
433       AUTHORS
434       COPYING
435       ChangeLog
436       INSTALL
437
438       Use -- to allow options beginning with ‘-’ or ‘--’ in  the  command  to
439       run in the chroot.  This prevents them being interpreted as options for
440       schroot itself.  Note that the top line was echoed to  standard  error,
441       and  the  remaining  lines to standard output.  This is intentional, so
442       that program output from commands run in the chroot may  be  piped  and
443       redirected as required; the data will be the same as if the command was
444       run directly on the host system.
445
446   Switching users
447       % schroot -c sid -u root
448       Password:
449       [sid chroot] (rleigh→root) Running login shell: “/bin/bash”
450       #
451
452       If the user ‘rleigh’ was in root-users in /etc/schroot/schroot.conf, or
453       one  of  the  groups  he  belonged to was in root-groups, they would be
454       granted root access without authentication, but the  PAM  authorisation
455       step is still applied.
456
457   Sessions
458       A  chroot  may  be needed to run more than one command.  In particular,
459       where the chroot is created on the fly from an LVM  LV  or  a  file  on
460       disc,  there is a need to make the chroot persistent while a given task
461       (or set of tasks) is performed.  Sessions exist for this purpose.   For
462       simple  chroot  types  such as ‘plain’ and ‘directory’, sessions may be
463       created but are not strictly necessary.
464
465       Let's start by looking at a session-capable chroot:
466
467       % schroot -i -c sid-snap
468         ——— Chroot ———
469         Name                   sid-snap
470         Description            Debian sid snapshot
471         Type                   lvm-snapshot
472         Priority               3
473         Users                  maks rleigh
474         Groups                 sbuild
475         Root Users
476         Root Groups            root sbuild
477         Aliases
478         Environment Filter     ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I\
479       FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA\
480       IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE\
481       RMPATH)$
482         Run Setup Scripts      true
483         Script Configuration   script-defaults
484         Session Managed        true
485         Personality            linux
486         Device                 /dev/hda_vg/sid_chroot
487         Mount Options          -o atime,async,user_xattr
488         Source Users
489         Source Groups          root rleigh
490         Source Root Users
491         Source Root Groups     root rleigh
492         LVM Snapshot Options   --size 2G -c 128
493
494       Note that the Session Managed option is set to ‘true’.  This is  a  re‐
495       quirement  in order to use session management, and is supported by most
496       chroot types.  Next, we will create a new session:
497
498       % schroot -b -c sid-snap
499       sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f
500
501       The session ID of the newly-created session  is  returned  on  standard
502       output.  It is common to store it like this:
503
504       % SESSION=$(schroot -b -c sid-snap)
505       % echo $SESSION
506       sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f
507
508       The  session may be used just like any normal chroot.  This is what the
509       session looks like:
510
511       % schroot -i -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f
512         ——— Session ———
513         Name                   sid-snap-46195b04-0893-49bf-beb8-0d\
514       4ccc899f0f
515         Description            Debian sid snapshot
516         Type                   lvm-snapshot
517         Priority               3
518         Users                  maks rleigh
519         Groups                 sbuild
520         Root Users
521         Root Groups            root sbuild
522         Aliases
523         Environment Filter     ^(BASH_ENV|CDPATH|ENV|HOSTALIASES|I\
524       FS|KRB5_CONFIG|KRBCONFDIR|KRBTKFILE|KRB_CONF|LD_.*|LOCALDOMA\
525       IN|NLSPATH|PATH_LOCALE|RES_OPTIONS|TERMINFO|TERMINFO_DIRS|TE\
526       RMPATH)$
527         Run Setup Scripts      true
528         Script Configuration   script-defaults
529         Session Managed        true
530         Personality            linux
531         Mount Location         /var/lib/schroot/mount/sid-snap-461\
532       95b04-0893-49bf-beb8-0d4ccc899f0f
533         Path                   /var/lib/schroot/mount/sid-snap-461\
534       95b04-0893-49bf-beb8-0d4ccc899f0f
535         Mount Device           /dev/hda_vg/sid-snap-46195b04-0893-\
536       49bf-beb8-0d4ccc899f0f
537         Device                 /dev/hda_vg/sid_chroot
538         Mount Options          -o atime,async,user_xattr
539         Source Users
540         Source Groups          root rleigh
541         Source Root Users
542         Source Root Groups     root rleigh
543         LVM Snapshot Device    /dev/hda_vg/sid-snap-46195b04-0893-\
544       49bf-beb8-0d4ccc899f0f
545         LVM Snapshot Options   --size 2G -c 128
546
547       Now the session has been created, commands may be run in it:
548
549       % schroot -r -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f -- \
550         uname -sr
551       I: [sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f chroot] Running \
552       command: “uname -sr”
553       Linux 2.6.18-3-powerpc
554       % schroot -r -c $SESSION -- uname -sr
555       I: [sid-snap-fe170af9-d9be-4800-b1bd-de275858b938 chroot] Running \
556       command: “uname -sr”
557       Linux 2.6.18-3-powerpc
558
559       When all the commands to run in the session have  been  performed,  the
560       session may be ended:
561
562       % schroot -e -c sid-snap-46195b04-0893-49bf-beb8-0d4ccc899f0f↵
563       % schroot -e -c $SESSION↵
564
565       Finally,  the  session  names  can be long and unwieldy.  A name may be
566       specified instead of using the automatically generated session ID:
567
568       % schroot -b -c sid-snap -n my-session-name↵
569       my-session-name
570

TROUBLESHOOTING

572       If something is not working, and it's not clear from the error messages
573       what  is wrong, try using the --debug=level option to turn on debugging
574       messages.  This gives a great deal more information.  Valid debug  lev‐
575       els are ‘none’, and ‘notice’, ‘info’, ‘warning’ and ‘critical’ in order
576       of increasing severity.  The lower the severity level, the more output.
577
578       If you are still having trouble, the developers may be contacted on the
579       mailing list:
580       Debian buildd-tools Developers
581       <buildd-tools-devel@lists.alioth.debian.org>
582

BUGS

584       On the mips and mipsel architectures, Linux kernels up to and including
585       at least version 2.6.17 have broken personality(2) support,  which  re‐
586       sults  in  a  failure  to set the personality.  This will be seen as an
587       “Operation not permitted” (EPERM) error.  To work around this  problem,
588       set personality to ‘undefined’, or upgrade to a more recent kernel.
589

ENVIRONMENT

591       By  default,  the environment is not preserved, and the following envi‐
592       ronment variables are defined: HOME, LOGNAME, PATH, SHELL,  TERM  (pre‐
593       served  if  already defined), and USER.  The environment variables SCH‐
594       ROOT_COMMAND, SCHROOT_USER, SCHROOT_GROUP, SCHROOT_UID and  SCHROOT_GID
595       are  set  inside  the chroot specifying the command being run, the user
596       name, group name, user ID and group  ID,  respectively.   Additionally,
597       the  environment  variables SCHROOT_SESSION_ID, SCHROOT_CHROOT_NAME and
598       SCHROOT_ALIAS_NAME specify the session ID,  the  original  chroot  name
599       prior  to  session  creation, and the alias used to originally identify
600       the selected chroot, respectively.
601
602       The following, potentially dangerous, environment variables are removed
603       for  safety  by  default:  BASH_ENV,  CDPATH,  ENV,  HOSTALIASES,  IFS,
604       KRB5_CONFIG,  KRBCONFDIR,  KRBTKFILE,  KRB_CONF,  LD_.*,   LOCALDOMAIN,
605       NLSPATH,   PATH_LOCALE,   RES_OPTIONS,   TERMINFO,  TERMINFO_DIRS,  and
606       TERMPATH.  If desired, the environment-filter  configuration  key  will
607       allow  the exclusion list to the modified; see schroot.conf(5) for fur‐
608       ther details.
609

FILES

611   Configuration files
612       /etc/schroot/schroot.conf
613              The system-wide chroot definition file.  This file must be owned
614              by the root user, and not be writable by other.
615
616       /etc/schroot/chroot.d
617              Additional  chroot definitions may be placed in files under this
618              directory.  They are treated in  exactly  that  same  manner  as
619              /etc/schroot/schroot.conf.   Each  file  may contain one or more
620              chroot definitions.  Note that the files in this directory  fol‐
621              low  the  same  naming  rules  as run-parts(8) when run with the
622              --lsbsysinit option.
623
624       /etc/schroot/setup.d
625              The system-wide chroot setup script directories.   See  schroot-
626              setup(5).
627
628       /etc/pam.d/schroot
629              PAM configuration.
630
631   System directories
632       /usr/libexec/schroot
633              Directory containing helper programs used by setup scripts.
634
635   Session directories
636       Each  directory contains a directory or file with the name of each ses‐
637       sion.  Not all chroot types make use of all the following directories.
638
639       /var/lib/schroot/session
640              Directory containing the session configuration for  each  active
641              session.
642
643       /var/run/schroot/mount
644              Directory used to mount the filesystems used by each active ses‐
645              sion.
646
647       /var/lib/schroot/union/underlay
648              Directory used for filesystem union source (underlay).
649
650       /var/lib/schroot/union/overlay
651              Directory used for filesystem union writeable overlay.
652
653       /var/lib/schroot/unpack
654              Directory used for unpacking file chroots.
655

AUTHORS

657       Roger Leigh.
658
660       Copyright © 2005-2012  Roger Leigh <rleigh@debian.org>
661
662       schroot is free software: you can redistribute it and/or modify it  un‐
663       der  the  terms  of  the GNU General Public License as published by the
664       Free Software Foundation, either version 3 of the License, or (at  your
665       option) any later version.
666

SEE ALSO

668       dchroot(1),  sbuild(1),  chroot(2), schroot.conf(5).  schroot-setup(5),
669       schroot-faq(7), run-parts(8),
670
671
672
673Version 1.6.10                    05 May 2014                       SCHROOT(1)
Impressum