1SCHROOT-FAQ(7) Debian sbuild SCHROOT-FAQ(7)
2
6 schroot - frequently asked questions
7
9 This manual page covers various frequently asked questions about con‐
10 figuration and usage of schroot.
11
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 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 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 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
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 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 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
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 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 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 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 For example, to remove a session named my-session by hand:
111 • Remove the session configuration file
113 % rm /var/lib/schroot/session/my-session↵
114 • Check for mounted filesystems
116 % /usr/libexec/schroot/schroot-listmounts -m \
117 /var/run/schroot/mount/my-session↵
118 • Unmount any mounted filesystems
120 • Remove /var/run/schroot/mount/my-session
122 • 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 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
132 How do I use sessions?
133 In normal use, running a command might look like this:
134 % schroot -c squeeze -- command↵
135 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 • 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 • Setup scripts are run to create the session chroot and configure
146 it for you
147 • The command command is run inside the session chroot
149 • Setup scripts are run to clean up the session chroot
151 • The session is deleted
153 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 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 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 or
182 % schroot --run-session -c "$SESSION" -- command1↵
183 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 etc.
190 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 or
195 % schroot --end-session -c "$SESSION"↵
196 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 % schroot --begin-session -c squeeze --session-name my-name↵
201 my-name
202
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 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 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 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
226 Roger Leigh.
227
229 Copyright © 2005-2012 Roger Leigh <rleigh@debian.org>
230 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
237 dchroot(1), sbuild(1), schroot(1), schroot.conf(5). schroot-setup(5),
238Version 1.6.10 05 May 2014 SCHROOT-FAQ(7)