1
.\" Copyright © 2010 Roger Leigh <rleigh@debian.org>
3
.\" schroot is free software: you can redistribute it and/or modify it
4
.\" under the terms of the GNU General Public License as published by
5
.\" the Free Software Foundation, either version 3 of the License, or
6
.\" (at your option) any later version.
8
.\" schroot is distributed in the hope that it will be useful, but
9
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
10
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11
.\" General Public License for more details.
13
.\" You should have received a copy of the GNU General Public License
14
.\" along with this program. If not, see
15
.\" <http://www.gnu.org/licenses/>.
17
.TH SCHROOT-FAQ 7 "@RELEASE_DATE_S@" "Version @VERSION@" "Debian sbuild"
19
schroot \- frequently asked questions
21
This manual page covers various frequently asked questions about configuration
24
.SS Why is schroot overwriting configuration files in the chroot?
25
By default, schroot copies over the system NSS databases (\[oq]passwd\[cq],
26
\[oq]shadow\[cq], \[oq]group\[cq], \[oq]gshadow\[cq], \[oq]services\[cq],
27
\[oq]protocols\[cq], \[oq]networks\[cq], and \[oq]hosts\[cq], etc.) into the
28
chroot. The reason for this is that the chroot environment is not a completely
29
separate system, and it copying them over keeps them synchronised. However,
30
this is not always desirable, particularly if installing a package in the
31
chroot creates system users and groups which are not present on the host, since
32
these will disappear next time the databases are copied over.
34
The suggested workaround here is to disable the copying by removing or
35
commenting out the databases in the NSSDATABASES file in the script-config file
36
for the chroot. These are \fI@SCHROOT_SYSCONF_DIR@/default/nssdatabases\fP and
37
\fI@SCHROOT_SYSCONF_DIR@/default/config\fP by default.
39
In the future, we will be working on a better scheme for keeping the host and
40
chroot databases in sync which can merge entries rather than overwriting the
41
entire database, which would preserve chroot-specific changes.
42
.SS Should I use the plain or directory chroot type?
43
These two chroot types are basically equivalent, since they are both just
44
directories in the filesystem. plain is very simple and does not perform any
45
setup tasks; the only reason you would
46
want to use it is if you're upgrading from a program such as
50
which don't do anything other than running a command or shell in a directory.
51
On the other hand, directory chroots do run setup scripts, which can mount
52
additional filesystems and do other setup tasks.
53
.SH ADVANCED CONFIGURATION
54
.SS What are snapshots and unions?
55
Some chroot types support \fIcloning\fP. This means when you start a session,
56
you get a \fIcopy\fP of the chroot which lasts just for the lifetime of the
57
session. This is useful when you want a temporary clean copy of a system for a
58
single task, which is then automatically deleted when you're done with it. For
59
example, the Debian package build d\[ae]mons run
61
to build Debian packages, and this program uses schroot to create a clean build
62
environment for each package. Without snapshotting, the chroot would need to
63
be reset to its initial state at the end of each build to make it ready for the
64
next one, and any debris left over from package removals or earlier builds
65
could interfere with the next build.
67
The most commonly-used snapshotting method is to use LVM snapshots (chroot type
68
\[oq]lvm\-snapshot\[cq]). In this case the chroot must exist on an LVM logical
69
volume (LV); snapshots of an LV may then be made with
71
during chroot session setup. However, these use up a lot of disk space. A
72
newer method is to use Btrfs snapshots which use up much less disk space
73
(chroot type \[oq]btrfs\-snapshot\[cq]), and may be more reliable than LVM
74
snapshots. Btrfs is however still experimental, but it is hoped that it will
75
become the recommended method as it matures.
77
Unions are an alternative to snapshots. In this situation, instead of creating
78
a copy of the chroot filesystem, we overlay a read-write temporary filesystem
79
on top of the chroot filesystem so that any modifications are stored in the
80
overlay, leaving the original chroot filesystem untouched. The Linux kernel
81
has yet to integrate support for union filesystems such as aufs and unionfs, so
82
LVM snapshots are still the recommended method at present.
84
.SS Can I run a d\[ae]mons in a chroot?
85
A common problem is trying to run a d\[ae]mon in a chroot, and finding that
86
this doesn't work. Typically, the d\[ae]mon is killed shortly after it starts
89
When schroot runs, it begins a session, runs the specified command or shell,
90
waits for the command or shell to exit, and then it ends the session. For a
91
normal command or shell, this works just fine. However, d\[ae]mons normally
92
start up by running in the background and detaching from the controlling
93
terminal. They do this by forking twice and letting the parent processes
94
exit. Unfortunately, this means schroot detects that the program exited (the
95
d\[ae]mon is a orphaned grandchild of this process) and it then ends the
96
session. Part of ending the session is killing all processes running inside
97
the chroot, which means the d\[ae]mon is killed as the session ends.
99
In consequence, it's not possible to run a d\[ae]mon \fIdirectly\fP with
100
schroot. You can however do it if you create a session with
101
\fI\-\-begin\-session\fP and then run the d\[ae]mon with
102
\fI\-\-run\-session\fP. It's your responsibility to end the session with
103
\fI\-\-end\-session\fP when the daemon has terminated or you no longer need it.
104
.SS How do I manually cleaning up a broken session?
105
Occasionally, it may be necessary to manually clean up sessions. If something
106
changes on your system which causes the setup scripts to fail when ending a
107
session, for example removal of a needed file or directory, it may not be
108
possible for schroot to clean everything up automatically. For each of the
109
session directories listed in the \[lq]\fISession directories\fP\[rq] section
112
any files with the name of the session ID need deleting, and any directories
113
with the name of the session ID need umounting (if there are any filesystems
114
mounted under it), and then also removing.
116
For example, to remove a session named
117
\fImy-session\fP by hand:
119
Remove the session configuration file
121
\f[CR]%\ \f[CB]rm\ @SCHROOT_SESSION_DIR@/my\-session\fP\fP\[CR]
123
Check for mounted filesystems
125
\f[CR]%\ \f[CB]@SCHROOT_LIBEXEC_DIR@/schroot\-listmounts\ \-m\ @SCHROOT_MOUNT_DIR@/my\-session\fP\fP\[CR]
127
Unmount any mounted filesystems
129
Remove \fI@SCHROOT_MOUNT_DIR@/my\-session\fP
131
Repeat for the other directories such as \fI@SCHROOT_UNDERLAY_DIR@\fP,
132
\fI@SCHROOT_OVERLAY_DIR@\fP and \fI@SCHROOT_FILE_UNPACK_DIR@\fP
134
\fBNOTE:\fP Do not remove any directories without checking if there are any
135
filesystems mounted below them, since filesystems such as \fI/home\fP could
136
still be bind mounted. Doing so could cause irretrievable data loss!
138
.SS How do I use sessions?
139
In normal use, running a command might look like this:
141
\f[CR]%\ \f[CB]schroot\ \-c squeeze \-\- command\fP\fP\[CR]
143
which would run the command \fIcommand\fP in the \fIsqueeze\fP chroot. While
144
it's not apparent that a session is being used here, schroot is actually doing
147
Creating a session using the \fIsqueeze\fP chroot. This will be automatically
148
given a unique name, such as
149
\fIsqueeze\-57a69547\-e014\-4f5d\-a98b\-f4f35a005307\fP, though you don't
150
usually need to know about this
152
Setup scripts are run to create the session chroot and configure it for you
154
The command \fIcommand\fP is run inside the session chroot
156
Setup scripts are run to clean up the session chroot
158
The session is deleted
160
Now, if you wanted to run more than one command, you could run a shell and run
161
them interactively, or you could put them into shell script and run that
162
instead. But you might want to do something in between, such as running
163
arbitrary commands from a program or script where you don't know which commands
164
to run in advance. You might also want to preseve the chroot state in between
165
commands, where the normal automatic session creation would reset the state in
166
between each command. This is what sessions are for: once created, the session
167
is persistent and won't be automatically removed. With a session, you can run
168
as many commands as you like, but you need to create and delete the session by
169
hand since schroot can't know by itself when you're done with it unlike in the
170
single command case above. This is quite easy:
172
\f[CR]% \f[CB]schroot \-\-begin\-session \-c squeeze\fP\fP\[CR]
174
\f[CR]squeeze\-57a69547\-e014\-4f5d\-a98b\-f4f35a005307\fP
176
This created a new session based upon the \fIsqueeze\fP chroot. The unique
177
name for the session, the session ID, was printed to standard output, so we
178
could also save it as a shell variable at the same time like so:
180
\f[CR]% \f[CB]SESSION=$(schroot \-\-begin\-session \-c squeeze)\fP\fP\[CR]
182
\f[CR]% \f[CB]echo $SESSION\fP\fP\[CR]
184
\f[CR]squeeze\-57a69547\-e014\-4f5d\-a98b\-f4f35a005307\fP
186
Now we have created the session and got the session ID, we can run commands in
187
it using the session ID:
189
\f[CR]% \f[CB]schroot \-\-run\-session \-c squeeze\-57a69547\-e014\-4f5d\-a98b\-f4f35a005307 \-\- command1\fP\fP\[CR]
193
\f[CR]% \f[CB]schroot \-\-run\-session \-c "$SESSION" \-\- command1\fP\fP\[CR]
195
and then as many more commands as we like
197
\f[CR]% \f[CB]schroot \-\-run\-session \-c "$SESSION" \-\- command2\fP\fP\[CR]
199
\f[CR]% \f[CB]schroot \-\-run\-session \-c "$SESSION" \-\- command3\fP\fP\[CR]
201
\f[CR]% \f[CB]schroot \-\-run\-session \-c "$SESSION" \-\- command4\fP\fP\[CR]
205
When we are done with the session, we can remove it with \fI\-\-end\-session\fP:
207
\f[CR]% \f[CB]schroot \-\-end\-session \-c squeeze\-57a69547\-e014\-4f5d\-a98b\-f4f35a005307\fP\fP\[CR]
211
\f[CR]% \f[CB]schroot \-\-end\-session \-c $SESSION\fP\fP\[CR]
213
Since the automatically generated session names can be long and unwieldy, the
214
\fI\-\-session\-name\fP option allows you to provide you own name:
216
\f[CR]% \f[CB]schroot \-\-begin\-session \-c squeeze \-\-session\-name my\-name\fP\fP\[CR]
220
.SS Getting help and getting involved
221
The mailing list \f[CR]<buildd-tools-devel@lists.alioth.debian.org>\fP is used
222
for both user support and development discussion. The list may be subscribed
223
to from the project website at
224
\f[CR]https://alioth.debian.org/projects/buildd-tools/\fP or the Mailman list
226
\f[CR]http://lists.alioth.debian.org/mailman/listinfo/buildd-tools-devel\fP.
228
On Debian systems, bugs may be reported using the
230
tool, or alternatively by mailing \f[CR]<submit@bugs.debian.org>\fP (see
231
\f[CR]http://bugs.debian.org\fP for details on how to do that).
232
.SS Getting the latest sources
233
schroot is maintained in the git version control system. You can get the
234
latest sources from \f[CR]git://git.debian.org/git/buildd-tools/schroot\fP.
236
\f[CR]% \f[CB]git clone git://git.debian.org/git/buildd-tools/schroot\fP\fP\[CR]
238
The master branch containes the current development release. Stable releases
239
are found on branches, for example the 1.4 series of releases are on
240
the schroot-1.4 branch.
244
Copyright \(co 2005\-2010 Roger Leigh \f[CR]<rleigh@debian.org>\fP
246
\fBschroot\fP is free software: you can redistribute it and/or modify it under
247
the terms of the GNU General Public License as published by the Free Software
248
Foundation, either version 3 of the License, or (at your option) any later
254
.BR schroot\-setup (5),
255
.BR schroot.conf (5).
257
.\"# The following sets edit modes for GNU EMACS
258
.\"# Local Variables:
added
removed
man/schroot-faq.7.in
