schroot-setup - schroot chroot setup scripts
schroot uses scripts to set up and then clean up the chroot
environment. The directory /etc/schroot/setup.d contains scripts run
when a chroot is created and destroyed. Several environment variables
are set while the scripts are being run, which allows their behaviour
to be customised, depending upon, for example, the type of chroot in
The scripts are run in name order, like those run by init(8), by using
the same style of execution as run-parts(8).
The setup scripts are all invoked with two options:
1 The action to perform.
When a session is first started, the chroot is set up by running
the scripts in /etc/schroot/setup.d with the ‘setup-start’
option. When the session is ended, the scripts in
/etc/schroot/setup.d are run in reverse order with the
2 The chroot status.
This is either ‘ok’ if there are no problems, or ‘fail’ if
something went wrong. For example, particular actions may be
skipped on failure.
Note that the scripts should be idempotent. They must be idempotent
during the ‘setup-stop’ phase, because they may be run more than once,
for example on failure.
The username of the user the command in the chroot will run as.
The host system architecture schroot is running upon. This may
be used to introduce architecture-specific behaviour into the
setup scripts where required. HOST is the GNU triplet for the
architecture, while HOST_OS, HOST_VENDOR and HOST_CPU are the
component parts of the triplet.
The directory under which helper programs are located.
The directory under which non-filesystem chroots are mounted
(e.g. block devices and LVM snapshots).
PID The process ID of the schroot process.
The operating system platform schroot is running upon. This may
be used to introduce platform-specific behaviour into the setup
scripts where required. Note that the HOST variables are
probably what are required. In the context of schroot, the
platform is the supported configuration and behaviour for a
given architecture, and may be identical between different
The session identifier.
Set to ‘quiet’ if only error messages should be printed,
‘normal’ if other messages may be printed as well, and ‘verbose’
if all messages may be printed. Previously called
Set to ‘true’ if a session will be created, otherwise ‘false’.
Set to ‘true’ if a session will be cloned, otherwise ‘false’.
Set to ‘true’ if a session will be purged, otherwise ‘false’.
The type of the chroot. This is useful for restricting a setup
task to particular types of chroot (e.g. only block devices or
The name of the chroot. This is useful for restricting a setup
task to a particular chroot, or set of chroots.
The description of the chroot.
The location to mount the chroot. It is used for mount point
creation and mounting.
The location of the chroot inside the mount point. This is to
allow multiple chroots on a single filesystem. Set for all
mountable chroot types.
The absolute path to the chroot. This is typically
CHROOT_MOUNT_LOCATION and CHROOT_LOCATION concatenated together.
This is the path which should be used to access the chroots.
Plain and directory chroot variables
These chroot types use only general variables.
The file containing the chroot files.
Set to ‘true’ to repack the chroot into an archive file on
ending a session, otherwise ‘false’.
Mountable chroot variables
These variables are only set for directly mountable chroot types.
The device to mount containing the chroot. mounting.
Options to pass to mount(8).
The location of the chroot inside the mount point. This allows
the existence of multiple chroots on a single filesystem.
Filesystem union variables
Union filesystem type.
Union filesystem mount options.
Union filesystem overlay directory (writable).
Union filesystem underlay directory (read-only).
Block device variables
The device containing the chroot root filesystem. This is
usually, but not necessarily, the device which will be mounted.
For example, an LVM snapshot this will be the original logical
LVM snapshot variables
Snapshot name to pass to lvcreate(8).
The name of the LVM snapshot device.
Options to pass to lvcreate(8).
Setup script configuration
The directory /etc/schroot/default contains the default settings used
by setup scripts.
config Main configuration file read by setup scripts. The format of
this file is described in schroot-script-config(5). This is the
default value for the script-config key. Note that this was
formerly named /etc/schroot/script-defaults. The following
files are referenced by default:
A list of files to copy into the chroot from the host system.
Note that this was formerly named
fstab A file in the format decribed in fstab(5), used to mount
filesystems inside the chroot. The mount location is relative
to the root of the chroot. Note that this was formerly named
System databases (as described in /etc/nsswitch.conf on
GNU/Linux systems) to copy into the chroot from the host. Note
that this was formerly named /etc/schroot/nssdatabases-defaults.
The directory /etc/schroot/setup.d contains the chroot setup scripts.
Print debugging diagnostics and perform basic sanity checking.
05file Unpack, clean up, and repack file-based chroots.
Create and remove union filesystems.
05lvm Create and remove LVM snapshots.
Mount and unmount filesystems.
Kill processes still running inside the chroot when ending a
session, which would prevent unmounting of filesystems and
cleanup of any other resources.
Copy files from the host system into the chroot. Configure
networking by copying hosts and resolv.conf, for example.
Configure system databases by copying passwd, shadow, group etc.
into the chroot.
Set the chroot name (/etc/debian_chroot) in the chroot. This
may be used by the shell prompt to display the current chroot.
Copyright © 2005-2010 Roger Leigh <firstname.lastname@example.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.
schroot(1), fstab(5), schroot.conf(5), schroot-script-config(5),