1SCHROOT-FAQ(7)                   Debian sbuild                  SCHROOT-FAQ(7)
2
3
4

NAME

6       schroot - frequently asked questions
7

DESCRIPTION

9       This  manual  page covers various frequently asked questions about con‐
10       figuration and usage of schroot.
11

CONFIGURATION

13   Why is schroot overwriting configuration files in the chroot?
14       By default, schroot copies over the  system  NSS  databases  (‘passwd’,
15       ‘shadow’,  ‘group’, ‘gshadow’, ‘services’, ‘protocols’, ‘networks’, and
16       ‘hosts’, etc.) into the chroot.  The reason for this is that the chroot
17       environment  is  not  a completely separate system, and it copying them
18       over keeps them synchronised.  However, this is not  always  desirable,
19       particularly if installing a package in the chroot creates system users
20       and groups which are not present on the host, since these  will  disap‐
21       pear next time the databases are copied over.
22
23       The  suggested  workaround here is to disable the copying.  This may be
24       achieved by setting the setup.nssdatabases key  to  be  empty  in  sch‐
25       root.conf.   In prior schroot releases, this was done by commenting out
26       the NSSDATABASES file for the  chroot  (/etc/schroot/default/config  by
27       default).  The database list may also be customised by editing the file
28       containing the database list (/etc/schroot/default/nssdatabases by  de‐
29       fault).
30
31       In  the  future,  we will be working on a better scheme for keeping the
32       host and chroot databases in sync which can merge entries  rather  than
33       overwriting  the  entire database, which would preserve chroot-specific
34       changes.
35
36   Should I use the plain or directory chroot type?
37       These two chroot types are basically equivalent, since  they  are  both
38       just  directories in the filesystem.  plain is very simple and does not
39       perform any setup tasks; the only reason you would want to use it is if
40       you're  upgrading  from a program such as dchroot(1) or chroot(8) which
41       don't do anything other than running a command or shell in a directory.
42       On  the  other  hand, directory chroots do run setup scripts, which can
43       mount additional filesystems and do other setup tasks.
44

ADVANCED CONFIGURATION

46   What are snapshots and unions?
47       Some chroot types support cloning.  This means when you  start  a  ses‐
48       sion, you get a copy of the chroot which lasts just for the lifetime of
49       the session.  This is useful when you want a temporary clean copy of  a
50       system  for  a  single  task,  which is then automatically deleted when
51       you're done with it.  For example, the Debian package build dæmons  run
52       sbuild(1)  to  build  Debian packages, and this program uses schroot to
53       create a clean build environment for each package.   Without  snapshot‐
54       ting, the chroot would need to be reset to its initial state at the end
55       of each build to make it ready for the next one, and  any  debris  left
56       over  from  package removals or earlier builds could interfere with the
57       next build.
58
59       The most commonly-used snapshotting method is to use LVM snapshots (ch‐
60       root  type  ‘lvm-snapshot’).   In this case the chroot must exist on an
61       LVM logical volume (LV); snapshots of an  LV  may  then  be  made  with
62       lvcreate(8)  during  chroot session setup.  However, these use up a lot
63       of disk space.  A newer method is to use Btrfs snapshots which  use  up
64       much  less  disk  space (chroot type ‘btrfs-snapshot’), and may be more
65       reliable than LVM snapshots.  Btrfs is however still experimental,  but
66       it is hoped that it will become the recommended method as it matures.
67
68       Unions  are an alternative to snapshots.  In this situation, instead of
69       creating a copy of the chroot filesystem, we overlay a read-write  tem‐
70       porary filesystem on top of the chroot filesystem so that any modifica‐
71       tions are stored in the overlay, leaving the original chroot filesystem
72       untouched.   The  Linux  kernel  has yet to integrate support for union
73       filesystems such as aufs and unionfs, so LVM snapshots  are  still  the
74       recommended method at present.
75

USAGE

77   Can I run a dæmons in a chroot?
78       A common problem is trying to run a dæmon in a chroot, and finding that
79       this doesn't work.  Typically, the dæmon is  killed  shortly  after  it
80       starts up.
81
82       When  schroot  runs, it begins a session, runs the specified command or
83       shell, waits for the command or shell to exit, and  then  it  ends  the
84       session.   For  a  normal command or shell, this works just fine.  How‐
85       ever, dæmons normally start up by running in the background and detach‐
86       ing  from  the controlling terminal.  They do this by forking twice and
87       letting the parent processes exit.  Unfortunately, this  means  schroot
88       detects  that the program exited (the dæmon is a orphaned grandchild of
89       this process) and it then ends the session.  Part of ending the session
90       is  killing  all  processes  running inside the chroot, which means the
91       dæmon is killed as the session ends.
92
93       In consequence, it's not possible to run a dæmon directly with schroot.
94       You  can however do it if you create a session with --begin-session and
95       then run the dæmon with --run-session.  It's your responsibility to end
96       the  session with --end-session when the dæmon has terminated or you no
97       longer need it.
98
99   How do I manually cleaning up a broken session?
100       Occasionally, it may be necessary to manually clean  up  sessions.   If
101       something changes on your system which causes the setup scripts to fail
102       when ending a session, for example removal of a needed file  or  direc‐
103       tory,  it  may not be possible for schroot to clean everything up auto‐
104       matically.  For each of the session directories listed in the  “Session
105       directories” section in schroot(1), any files with the name of the ses‐
106       sion ID need deleting, and any directories with the name of the session
107       ID  need umounting (if there are any filesystems mounted under it), and
108       then also removing.
109
110       For example, to remove a session named my-session by hand:
111
112       •      Remove the session configuration file
113              % rm /var/lib/schroot/session/my-session
114
115       •      Check for mounted filesystems
116              % /usr/libexec/schroot/schroot-listmounts -m \
117                /var/run/schroot/mount/my-session
118
119       •      Unmount any mounted filesystems
120
121       •      Remove /var/run/schroot/mount/my-session
122
123       •      Repeat  for  the  other  directories   such   as   /var/lib/sch‐
124              root/union/underlay,      /var/lib/schroot/union/overlay     and
125              /var/lib/schroot/unpack
126
127       NOTE: Do not remove any directories without checking if there  are  any
128       filesystems  mounted  below them, since filesystems such as /home could
129       still be bind mounted.  Doing so could cause irretrievable data loss!
130

ADVANCED USAGE

132   How do I use sessions?
133       In normal use, running a command might look like this:
134       % schroot -c squeeze -- command
135
136       which would run the command command in the squeeze chroot.  While  it's
137       not apparent that a session is being used here, schroot is actually do‐
138       ing the following steps:
139
140       •      Creating a session using the squeeze chroot.  This will be auto‐
141              matically      given      a     unique     name,     such     as
142              squeeze-57a69547-e014-4f5d-a98b-f4f35a005307, though  you  don't
143              usually need to know about this
144
145       •      Setup scripts are run to create the session chroot and configure
146              it for you
147
148       •      The command command is run inside the session chroot
149
150       •      Setup scripts are run to clean up the session chroot
151
152       •      The session is deleted
153
154       Now, if you wanted to run more than one command, you could run a  shell
155       and run them interactively, or you could put them into shell script and
156       run that instead.  But you might want to do something in between,  such
157       as  running arbitrary commands from a program or script where you don't
158       know which commands to run in advance.  You might also want to  preseve
159       the  chroot  state in between commands, where the normal automatic ses‐
160       sion creation would reset the state in between each command.   This  is
161       what  sessions  are  for:  once  created, the session is persistent and
162       won't be automatically removed.  With a session, you can  run  as  many
163       commands  as you like, but you need to create and delete the session by
164       hand since schroot can't know by itself when you're done with it unlike
165       in the single command case above.  This is quite easy:
166       % schroot --begin-session -c squeeze
167       squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
168
169       This  created  a new session based upon the squeeze chroot.  The unique
170       name for the session, the session ID, was printed to  standard  output,
171       so we could also save it as a shell variable at the same time like so:
172       % SESSION=$(schroot --begin-session -c squeeze)
173       % echo $SESSION
174       squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
175
176       Now we have created the session and got the session ID, we can run com‐
177       mands in it using the session ID:
178       % schroot --run-session -c squeeze-57a69547-e014-4f5d-a98b-f4f35a005307 \
179         -- command1
180
181       or
182       % schroot --run-session -c "$SESSION" -- command1
183
184       and then as many more commands as we like
185       % schroot --run-session -c "$SESSION" -- command2
186       % schroot --run-session -c "$SESSION" -- command3
187       % schroot --run-session -c "$SESSION" -- command4
188
189       etc.
190
191       When we are done with the session, we can remove it with --end-session:
192       % schroot --end-session -c squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
193
194       or
195       % schroot --end-session -c "$SESSION"
196
197       Since the automatically generated session names can  be  long  and  un‐
198       wieldy, the --session-name option allows you to provide you own name:
199
200       % schroot --begin-session -c squeeze --session-name my-name
201       my-name
202

CONTRIBUTING

204   Getting help and getting involved
205       The  mailing  list <buildd-tools-devel@lists.alioth.debian.org> is used
206       for both user support and development discussion.  The list may be sub‐
207       scribed   to   from   the   project   website   at   https://alioth.de
208       bian.org/projects/buildd-tools/  or  the  Mailman  list  interface   at
209       http://lists.alioth.debian.org/mailman/listinfo/buildd-tools-devel.
210
211   Reporting bugs
212       On Debian systems, bugs may be reported using the reportbug(1) tool, or
213       alternatively by mailing <submit@bugs.debian.org> (see  http://bugs.de
214       bian.org for details on how to do that).
215
216   Getting the latest sources
217       schroot  is  maintained in the git version control system.  You can get
218       the latest sources from git://git.debian.org/git/buildd-tools/schroot.
219       % git clone git://git.debian.org/git/buildd-tools/schroot
220
221       The master branch containes the current  development  release.   Stable
222       releases  are found on branches, for example the 1.4 series of releases
223       are on the schroot-1.4 branch.
224

AUTHORS

226       Roger Leigh.
227
229       Copyright © 2005-2012  Roger Leigh <rleigh@debian.org>
230
231       schroot is free software: you can redistribute it and/or modify it  un‐
232       der  the  terms  of  the GNU General Public License as published by the
233       Free Software Foundation, either version 3 of the License, or (at  your
234       option) any later version.
235

SEE ALSO

237       dchroot(1), sbuild(1), schroot(1), schroot.conf(5).  schroot-setup(5),
238
239
240
241Version 1.6.10                    05 May 2014                   SCHROOT-FAQ(7)
Impressum