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 by removing or
24 commenting out the databases in the NSSDATABASES file in the script-
25 config file for the chroot. These are /etc/schroot/default/nss‐
26 databases and /etc/schroot/default/config by default.
27 In the future, we will be working on a better scheme for keeping the
29 host and chroot databases in sync which can merge entries rather than
30 overwriting the entire database, which would preserve chroot-specific
31 changes.
32 Should I use the plain or directory chroot type?
34 These two chroot types are basically equivalent, since they are both
35 just directories in the filesystem. plain is very simple and does not
36 perform any setup tasks; the only reason you would want to use it is if
37 you're upgrading from a program such as dchroot(1) or chroot(8) which
38 don't do anything other than running a command or shell in a directory.
39 On the other hand, directory chroots do run setup scripts, which can
40 mount additional filesystems and do other setup tasks.
41
43 What are snapshots and unions?
44 Some chroot types support cloning. This means when you start a ses‐
45 sion, you get a copy of the chroot which lasts just for the lifetime of
46 the session. This is useful when you want a temporary clean copy of a
47 system for a single task, which is then automatically deleted when
48 you're done with it. For example, the Debian package build dæmons run
49 sbuild(1) to build Debian packages, and this program uses schroot to
50 create a clean build environment for each package. Without snapshot‐
51 ting, the chroot would need to be reset to its initial state at the end
52 of each build to make it ready for the next one, and any debris left
53 over from package removals or earlier builds could interfere with the
54 next build.
55 The most commonly-used snapshotting method is to use LVM snapshots
57 (chroot type ‘lvm-snapshot’). In this case the chroot must exist on an
58 LVM logical volume (LV); snapshots of an LV may then be made with
59 lvcreate(8) during chroot session setup. However, these use up a lot
60 of disk space. A newer method is to use Btrfs snapshots which use up
61 much less disk space (chroot type ‘btrfs-snapshot’), and may be more
62 reliable than LVM snapshots. Btrfs is however still experimental, but
63 it is hoped that it will become the recommended method as it matures.
64 Unions are an alternative to snapshots. In this situation, instead of
66 creating a copy of the chroot filesystem, we overlay a read-write tem‐
67 porary filesystem on top of the chroot filesystem so that any modifica‐
68 tions are stored in the overlay, leaving the original chroot filesystem
69 untouched. The Linux kernel has yet to integrate support for union
70 filesystems such as aufs and unionfs, so LVM snapshots are still the
71 recommended method at present.
72
74 Can I run a dæmons in a chroot?
75 A common problem is trying to run a dæmon in a chroot, and finding that
76 this doesn't work. Typically, the dæmon is killed shortly after it
77 starts up.
78 When schroot runs, it begins a session, runs the specified command or
80 shell, waits for the command or shell to exit, and then it ends the
81 session. For a normal command or shell, this works just fine. How‐
82 ever, dæmons normally start up by running in the background and detach‐
83 ing from the controlling terminal. They do this by forking twice and
84 letting the parent processes exit. Unfortunately, this means schroot
85 detects that the program exited (the dæmon is a orphaned grandchild of
86 this process) and it then ends the session. Part of ending the session
87 is killing all processes running inside the chroot, which means the
88 dæmon is killed as the session ends.
89 In consequence, it's not possible to run a dæmon directly with schroot.
91 You can however do it if you create a session with --begin-session and
92 then run the dæmon with --run-session. It's your responsibility to end
93 the session with --end-session when the daemon has terminated or you no
94 longer need it.
95 How do I manually cleaning up a broken session?
97 Occasionally, it may be necessary to manually clean up sessions. If
98 something changes on your system which causes the setup scripts to fail
99 when ending a session, for example removal of a needed file or direc‐
100 tory, it may not be possible for schroot to clean everything up auto‐
101 matically. For each of the session directories listed in the “Session
102 directories” section in schroot(1), any files with the name of the ses‐
103 sion ID need deleting, and any directories with the name of the session
104 ID need umounting (if there are any filesystems mounted under it), and
105 then also removing.
106 For example, to remove a session named my-session by hand:
108 · Remove the session configuration file
110 % rm /var/lib/schroot/session/my-session↵
111 · Check for mounted filesystems
113 % /usr/libexec/schroot/schroot-listmounts -m /var/lib/sch‐
114 root/mount/my-session↵
115 · Unmount any mounted filesystems
117 · Remove /var/lib/schroot/mount/my-session
119 · Repeat for the other directories such as /var/lib/sch‐
121 root/union/underlay, /var/lib/schroot/union/overlay and
122 /var/lib/schroot/unpack
123 NOTE: Do not remove any directories without checking if there are any
125 filesystems mounted below them, since filesystems such as /home could
126 still be bind mounted. Doing so could cause irretrievable data loss!
127
129 How do I use sessions?
130 In normal use, running a command might look like this:
131 % schroot -c squeeze -- command↵
132 which would run the command command in the squeeze chroot. While it's
134 not apparent that a session is being used here, schroot is actually
135 doing the following steps:
136 · Creating a session using the squeeze chroot. This will be auto‐
138 matically given a unique name, such as
139 squeeze-57a69547-e014-4f5d-a98b-f4f35a005307, though you don't
140 usually need to know about this
141 · Setup scripts are run to create the session chroot and configure
143 it for you
144 · The command command is run inside the session chroot
146 · Setup scripts are run to clean up the session chroot
148 · The session is deleted
150 Now, if you wanted to run more than one command, you could run a shell
152 and run them interactively, or you could put them into shell script and
153 run that instead. But you might want to do something in between, such
154 as running arbitrary commands from a program or script where you don't
155 know which commands to run in advance. You might also want to preseve
156 the chroot state in between commands, where the normal automatic ses‐
157 sion creation would reset the state in between each command. This is
158 what sessions are for: once created, the session is persistent and
159 won't be automatically removed. With a session, you can run as many
160 commands as you like, but you need to create and delete the session by
161 hand since schroot can't know by itself when you're done with it unlike
162 in the single command case above. This is quite easy:
163 % schroot --begin-session -c squeeze↵
164 squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
165 This created a new session based upon the squeeze chroot. The unique
167 name for the session, the session ID, was printed to standard output,
168 so we could also save it as a shell variable at the same time like so:
169 % SESSION=$(schroot --begin-session -c squeeze)↵
170 % echo $SESSION↵
171 squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
172 Now we have created the session and got the session ID, we can run com‐
174 mands in it using the session ID:
175 % schroot --run-session -c squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
176 -- command1↵
177 or
179 % schroot --run-session -c "$SESSION" -- command1↵
180 and then as many more commands as we like
182 % schroot --run-session -c "$SESSION" -- command2↵
183 % schroot --run-session -c "$SESSION" -- command3↵
184 % schroot --run-session -c "$SESSION" -- command4↵
185 etc.
187 When we are done with the session, we can remove it with --end-session:
189 % schroot --end-session -c
190 squeeze-57a69547-e014-4f5d-a98b-f4f35a005307↵
191 or
193 % schroot --end-session -c $SESSION↵
194 Since the automatically generated session names can be long and
196 unwieldy, the --session-name option allows you to provide you own name:
197 % schroot --begin-session -c squeeze --session-name my-name↵
199 my-name
200
202 Getting help and getting involved
203 The mailing list <buildd-tools-devel@lists.alioth.debian.org> is used
204 for both user support and development discussion. The list may be sub‐
205 scribed to from the project website at
206 https://alioth.debian.org/projects/buildd-tools/ or the Mailman list
207 interface at http://lists.alioth.debian.org/mailman/listinfo/buildd-
208 tools-devel.
209 Reporting bugs
211 On Debian systems, bugs may be reported using the reportbug(1) tool, or
212 alternatively by mailing <submit@bugs.debian.org> (see
213 http://bugs.debian.org for details on how to do that).
214 Getting the latest sources
216 schroot is maintained in the git version control system. You can get
217 the latest sources from git://git.debian.org/git/buildd-tools/schroot.
218 % git clone git://git.debian.org/git/buildd-tools/schroot↵
219 The master branch containes the current development release. Stable
221 releases are found on branches, for example the 1.4 series of releases
222 are on the schroot-1.4 branch.
223
225 Roger Leigh.
226
228 Copyright © 2005-2010 Roger Leigh <rleigh@debian.org>
229 schroot is free software: you can redistribute it and/or modify it
231 under the terms of the GNU General Public License as published by the
232 Free Software Foundation, either version 3 of the License, or (at your
233 option) any later version.
234
236 dchroot(1), schroot(1), sbuild(1), schroot-setup(5), schroot.conf(5).
237Version 1.4.10 22 Aug 2010 SCHROOT-FAQ(7)