NAME
schroot - frequently asked questions
DESCRIPTION
This manual page covers various frequently asked questions about
configuration and usage of schroot.
CONFIGURATION
Why is schroot overwriting configuration files in the chroot?
By default, schroot copies over the system NSS databases (‘passwd’,
‘shadow’, ‘group’, ‘gshadow’, ‘services’, ‘protocols’, ‘networks’, and
‘hosts’, etc.) into the chroot. The reason for this is that the chroot
environment is not a completely separate system, and it copying them
over keeps them synchronised. However, this is not always desirable,
particularly if installing a package in the chroot creates system users
and groups which are not present on the host, since these will
disappear next time the databases are copied over.
The suggested workaround here is to disable the copying by removing or
commenting out the databases in the NSSDATABASES file in the script-
config file for the chroot. These are
/etc/schroot/default/nssdatabases and /etc/schroot/default/config by
default.
In the future, we will be working on a better scheme for keeping the
host and chroot databases in sync which can merge entries rather than
overwriting the entire database, which would preserve chroot-specific
changes.
Should I use the plain or directory chroot type?
These two chroot types are basically equivalent, since they are both
just directories in the filesystem. plain is very simple and does not
perform any setup tasks; the only reason you would want to use it is if
you’re upgrading from a program such as dchroot(1) or chroot(8) which
don’t do anything other than running a command or shell in a directory.
On the other hand, directory chroots do run setup scripts, which can
mount additional filesystems and do other setup tasks.
ADVANCED CONFIGURATION
What are snapshots and unions?
Some chroot types support cloning. This means when you start a
session, you get a copy of the chroot which lasts just for the lifetime
of the session. This is useful when you want a temporary clean copy of
a system for a single task, which is then automatically deleted when
you’re done with it. For example, the Debian package build dæmons run
sbuild(1) to build Debian packages, and this program uses schroot to
create a clean build environment for each package. Without
snapshotting, the chroot would need to be reset to its initial state at
the end of each build to make it ready for the next one, and any debris
left over from package removals or earlier builds could interfere with
the next build.
The most commonly-used snapshotting method is to use LVM snapshots
(chroot type ‘lvm-snapshot’). In this case the chroot must exist on an
LVM logical volume (LV); snapshots of an LV may then be made with
lvcreate(8) during chroot session setup. However, these use up a lot
of disk space. A newer method is to use Btrfs snapshots which use up
much less disk space (chroot type ‘btrfs-snapshot’), and may be more
reliable than LVM snapshots. Btrfs is however still experimental, but
it is hoped that it will become the recommended method as it matures.
Unions are an alternative to snapshots. In this situation, instead of
creating a copy of the chroot filesystem, we overlay a read-write
temporary filesystem on top of the chroot filesystem so that any
modifications are stored in the overlay, leaving the original chroot
filesystem untouched. The Linux kernel has yet to integrate support
for union filesystems such as aufs and unionfs, so LVM snapshots are
still the recommended method at present.
USAGE
Can I run a dæmons in a chroot?
A common problem is trying to run a dæmon in a chroot, and finding that
this doesn’t work. Typically, the dæmon is killed shortly after it
starts up.
When schroot runs, it begins a session, runs the specified command or
shell, waits for the command or shell to exit, and then it ends the
session. For a normal command or shell, this works just fine.
However, dæmons normally start up by running in the background and
detaching from the controlling terminal. They do this by forking twice
and letting the parent processes exit. Unfortunately, this means
schroot detects that the program exited (the dæmon is a orphaned
grandchild of this process) and it then ends the session. Part of
ending the session is killing all processes running inside the chroot,
which means the dæmon is killed as the session ends.
In consequence, it’s not possible to run a dæmon directly with schroot.
You can however do it if you create a session with --begin-session and
then run the dæmon with --run-session. It’s your responsibility to end
the session with --end-session when the daemon has terminated or you no
longer need it.
How do I manually cleaning up a broken session?
Occasionally, it may be necessary to manually clean up sessions. If
something changes on your system which causes the setup scripts to fail
when ending a session, for example removal of a needed file or
directory, it may not be possible for schroot to clean everything up
automatically. For each of the session directories listed in the
“Session directories” section in schroot(1), any files with the name of
the session ID need deleting, and any directories with the name of the
session ID need umounting (if there are any filesystems mounted under
it), and then also removing.
For example, to remove a session named my-session by hand:
· Remove the session configuration file
% rm /var/lib/schroot/session/my-session␍
· Check for mounted filesystems
% /usr/lib/schroot/schroot-listmounts -m /var/lib/schroot/mount/my-session␍
· Unmount any mounted filesystems
· Remove /var/lib/schroot/mount/my-session
· Repeat for the other directories such as
/var/lib/schroot/union/underlay, /var/lib/schroot/union/overlay
and /var/lib/schroot/unpack
NOTE: Do not remove any directories without checking if there are any
filesystems mounted below them, since filesystems such as /home could
still be bind mounted. Doing so could cause irretrievable data loss!
ADVANCED USAGE
How do I use sessions?
In normal use, running a command might look like this:
% schroot -c squeeze -- command␍
which would run the command command in the squeeze chroot. While it’s
not apparent that a session is being used here, schroot is actually
doing the following steps:
· Creating a session using the squeeze chroot. This will be
automatically given a unique name, such as
squeeze-57a69547-e014-4f5d-a98b-f4f35a005307, though you don’t
usually need to know about this
· Setup scripts are run to create the session chroot and configure
it for you
· The command command is run inside the session chroot
· Setup scripts are run to clean up the session chroot
· The session is deleted
Now, if you wanted to run more than one command, you could run a shell
and run them interactively, or you could put them into shell script and
run that instead. But you might want to do something in between, such
as running arbitrary commands from a program or script where you don’t
know which commands to run in advance. You might also want to preseve
the chroot state in between commands, where the normal automatic
session creation would reset the state in between each command. This
is what sessions are for: once created, the session is persistent and
won’t be automatically removed. With a session, you can run as many
commands as you like, but you need to create and delete the session by
hand since schroot can’t know by itself when you’re done with it unlike
in the single command case above. This is quite easy:
% schroot --begin-session -c squeeze␍
squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
This created a new session based upon the squeeze chroot. The unique
name for the session, the session ID, was printed to standard output,
so we could also save it as a shell variable at the same time like so:
% SESSION=$(schroot --begin-session -c squeeze)␍
% echo $SESSION␍
squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
Now we have created the session and got the session ID, we can run
commands in it using the session ID:
% schroot --run-session -c squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
-- command1␍
or
% schroot --run-session -c "$SESSION" -- command1␍
and then as many more commands as we like
% schroot --run-session -c "$SESSION" -- command2␍
% schroot --run-session -c "$SESSION" -- command3␍
% schroot --run-session -c "$SESSION" -- command4␍
etc.
When we are done with the session, we can remove it with --end-session:
% schroot --end-session -c
squeeze-57a69547-e014-4f5d-a98b-f4f35a005307␍
or
% schroot --end-session -c $SESSION␍
Since the automatically generated session names can be long and
unwieldy, the --session-name option allows you to provide you own name:
% schroot --begin-session -c squeeze --session-name my-name␍
my-name
CONTRIBUTING
Getting help and getting involved
The mailing list <buildd-tools-devel@lists.alioth.debian.org> is used
for both user support and development discussion. The list may be
subscribed to from the project website at
https://alioth.debian.org/projects/buildd-tools/ or the Mailman list
interface at http://lists.alioth.debian.org/mailman/listinfo/buildd-
tools-devel.
Reporting bugs
On Debian systems, bugs may be reported using the reportbug(1) tool, or
alternatively by mailing <submit@bugs.debian.org> (see
http://bugs.debian.org for details on how to do that).
Getting the latest sources
schroot is maintained in the git version control system. You can get
the latest sources from git://git.debian.org/git/buildd-tools/schroot.
% git clone git://git.debian.org/git/buildd-tools/schroot␍
The master branch containes the current development release. Stable
releases are found on branches, for example the 1.4 series of releases
are on the schroot-1.4 branch.
AUTHORS
Roger Leigh.
COPYRIGHT
Copyright © 2005-2010 Roger Leigh <rleigh@debian.org>
schroot is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
SEE ALSO
dchroot(1), schroot(1), sbuild(1), schroot-setup(5), schroot.conf(5).