1SCHROOT-SETUP(5) Debian sbuild SCHROOT-SETUP(5)
2
6 schroot-setup - schroot chroot setup scripts
7
9 schroot uses scripts to set up and then clean up the chroot environ‐
10 ment. The directory /etc/schroot/setup.d contains scripts run when a
11 chroot is created and destroyed. Several environment variables are set
12 while the scripts are being run, which allows their behaviour to be
13 customised, depending upon, for example, the type of chroot in use.
14 The scripts are run in name order, like those run by init(8), by using
16 the same style of execution as run-parts(8).
17 The setup scripts are all invoked with two options:
19 1 The action to perform.
21 When a session is first started, the chroot is set up by running
23 the scripts in /etc/schroot/setup.d with the ‘setup-start’
24 option. When the session is ended, the scripts in /etc/sch‐
25 root/setup.d are run in reverse order with the ‘setup-stop’
26 option.
27 2 The chroot status.
29 This is either ‘ok’ if there are no problems, or ‘fail’ if some‐
31 thing went wrong. For example, particular actions may be
32 skipped on failure.
33 Note that the scripts should be idempotent. They must be idempotent
35 during the ‘setup-stop’ phase, because they may be run more than once,
36 for example on failure.
37
39 General variables
40 AUTH_USER
41 The username of the user the command in the chroot will run as.
42 CHROOT_NAME
44 The chroot name. Note that this is the name of the orignal
45 chroot before session creation; you probably want SESSION_ID.
46 LIBEXEC_DIR
48 The directory under which helper programs are located.
49 MOUNT_DIR
51 The directory under which non-filesystem chroots are mounted
52 (e.g. block devices and LVM snapshots).
53 PID The process ID of the schroot process.
55 PLATFORM
57 The operating system platform schroot is running upon. This may
58 be used to introduce platform-specific behaviour into the setup
59 scripts where required. Note that the HOST variables are proba‐
60 bly what are required. In the context of schroot, the platform
61 is the supported configuration and behaviour for a given archi‐
62 tecture, and may be identical between different architectures.
63 SESSION_ID
65 The session identifier.
66 VERBOSE
68 Set to ‘quiet’ if only error messages should be printed, ‘nor‐
69 mal’ if other messages may be printed as well, and ‘verbose’ if
70 all messages may be printed. Previously called AUTH_VERBOSITY.
71 CHROOT_SESSION_CREATE
73 Set to ‘true’ if a session will be created, otherwise ‘false’.
74 CHROOT_SESSION_CLONE
76 Set to ‘true’ if a session will be cloned, otherwise ‘false’.
77 CHROOT_SESSION_PURGE
79 Set to ‘true’ if a session will be purged, otherwise ‘false’.
80 CHROOT_SESSION_SOURCE
82 Set to ‘true’ if a session will be created from a source chroot,
83 otherwise ‘false’.
84 CHROOT_TYPE
86 The type of the chroot. This is useful for restricting a setup
87 task to particular types of chroot (e.g. only block devices or
88 LVM snapshots).
89 CHROOT_NAME
91 The name of the chroot. This is useful for restricting a setup
92 task to a particular chroot, or set of chroots.
93 CHROOT_ALIAS
95 The name of the alias used to select the chroot. This is useful
96 for specialising a setup task based upon one of its alternative
97 alias names, or the default chroot name. For example, it could
98 be used to specify additional sources in /etc/apt/sources.list,
99 such as a stable-security alias for a stable chroot, or an
100 experimental alias for an unstable chroot.
101 CHROOT_DESCRIPTION
103 The description of the chroot.
104 CHROOT_MOUNT_LOCATION
106 The location to mount the chroot. It is used for mount point
107 creation and mounting.
108 CHROOT_LOCATION
110 The location of the chroot inside the mount point. This is to
111 allow multiple chroots on a single filesystem. Set for all
112 mountable chroot types.
113 CHROOT_PATH
115 The absolute path to the chroot. This is typically
116 CHROOT_MOUNT_LOCATION and CHROOT_LOCATION concatenated together.
117 This is the path which should be used to access the chroots.
118 Plain and directory chroot variables
120 These chroot types use only general variables.
121 File variables
123 CHROOT_FILE
124 The file containing the chroot files.
125 CHROOT_FILE_REPACK
127 Set to ‘true’ to repack the chroot into an archive file on end‐
128 ing a session, otherwise ‘false’.
129 Mountable chroot variables
131 These variables are only set for directly mountable chroot types.
132 CHROOT_MOUNT_DEVICE
134 The device to mount containing the chroot. mounting.
135 CHROOT_MOUNT_OPTIONS
137 Options to pass to mount(8).
138 CHROOT_LOCATION
140 The location of the chroot inside the mount point. This allows
141 the existence of multiple chroots on a single filesystem.
142 Filesystem union variables
144 CHROOT_UNION_TYPE
145 Union filesystem type.
146 CHROOT_UNION_MOUNT_OPTIONS
148 Union filesystem mount options.
149 CHROOT_UNION_OVERLAY_DIRECTORY
151 Union filesystem overlay directory (writable).
152 CHROOT_UNION_UNDERLAY_DIRECTORY
154 Union filesystem underlay directory (read-only).
155 Block device variables
157 CHROOT_DEVICE
158 The device containing the chroot root filesystem. This is usu‐
159 ally, but not necessarily, the device which will be mounted.
160 For example, an LVM snapshot this will be the original logical
161 volume.
162 LVM snapshot variables
164 CHROOT_LVM_SNAPSHOT_NAME
165 Snapshot name to pass to lvcreate(8).
166 CHROOT_LVM_SNAPSHOT_DEVICE
168 The name of the LVM snapshot device.
169 CHROOT_LVM_SNAPSHOT_OPTIONS
171 Options to pass to lvcreate(8).
172 Custom variables
174 Custom keys set in schroot.conf will be uppercased and set in the envi‐
175 ronment as described in schroot.conf(5).
176
178 Setup script configuration
179 The directory /etc/schroot/default contains the default settings used
180 by setup scripts.
181 config Main configuration file read by setup scripts. The format of
183 this file is described in schroot-script-config(5). This is the
184 default value for the script-config key. Note that this was
185 formerly named /etc/schroot/script-defaults. The following
186 files are referenced by default:
187 copyfiles
189 A list of files to copy into the chroot from the host system.
190 Note that this was formerly named /etc/schroot/copy‐
191 files-defaults.
192 fstab A file in the format decribed in fstab(5), used to mount
194 filesystems inside the chroot. The mount location is relative
195 to the root of the chroot. Note that this was formerly named
196 /etc/schroot/mount-defaults.
197 nssdatabases
199 System databases (as described in /etc/nsswitch.conf on
200 GNU/Linux systems) to copy into the chroot from the host. Note
201 that this was formerly named /etc/schroot/nssdatabases-defaults.
202 Setup scripts
204 The directory /etc/schroot/setup.d contains the chroot setup scripts.
205 00check
207 Print debugging diagnostics and perform basic sanity checking.
208 05file Unpack, clean up, and repack file-based chroots.
210 05fsunion
212 Create and remove union filesystems.
213 05lvm Create and remove LVM snapshots.
215 10mount
217 Mount and unmount filesystems.
218 15binfmt
220 Sets up the QEMU user emulator using binfmt-support. This per‐
221 mits a chroot for a different CPU architecture to be used trans‐
222 parently, providing an alternative to cross-compiling or whole-
223 machine emulation.
224 15killprocs
226 Kill processes still running inside the chroot when ending a
227 session, which would prevent unmounting of filesystems and
228 cleanup of any other resources.
229 20copyfiles
231 Copy files from the host system into the chroot. Configure net‐
232 working by copying hosts and resolv.conf, for example.
233 20nssdatabases
235 Configure system databases by copying passwd, shadow, group etc.
236 into the chroot.
237 50chrootname
239 Set the chroot name (/etc/debian_chroot) in the chroot. This
240 may be used by the shell prompt to display the current chroot.
241
243 Roger Leigh.
244
246 Copyright © 2005-2012 Roger Leigh <rleigh@debian.org>
247 schroot is free software: you can redistribute it and/or modify it
249 under the terms of the GNU General Public License as published by the
250 Free Software Foundation, either version 3 of the License, or (at your
251 option) any later version.
252
254 schroot(1), fstab(5), schroot.conf(5), schroot-script-config(5),
255 run-parts(8).
256Version 1.6.10 05 May 2014 SCHROOT-SETUP(5)