SCHROOT-SETUP(5)

💖 SCHROOT-SETUP(5) — the schroot chroot setup scripts situation 💖

okay bestie, welcome to the schroot-setup manual page ✨ — it lives in the Debian sbuild neck of the woods and it's all about the lil scripts that set up (and then politely tear down) your chroot environment. no cap.

---

🌸 NAME 🌸

schroot-setup — schroot chroot setup scripts. that's it, that's the name 🫶

---

✨ DESCRIPTION ✨

so schroot uses scripts to set up the chroot environment and then clean up after itself. the directory /etc/schroot/setup.d is where these scripts live, and they get run whenever a chroot is created and destroyed. 💅

while the scripts are running, a whole bunch of environment variables get set, which lets you customise their behaviour depending on stuff like — for example — which type of chroot is in use. the way that it's customisable? obsessed. 😌

the scripts run in name order, exactly like the ones run by init(8), using the same style of execution as run-parts(8). periodt.

every setup script gets invoked with two options:

1. The action to perform.

when a session is first started, the chroot gets set up by running the scripts in /etc/schroot/setup.d with the setup-start option. and when the session is ended, those same scripts in /etc/schroot/setup.d get run in reverse order with the setup-stop option. 🦋

2. The chroot status.

this is either ok if there are no problems, or fail if something went wrong. like, for example, particular actions may be skipped on failure. 🙈

⚠️ bestie, listen: 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. not me warning you twice. 💀

---

🌈 ENVIRONMENT 🌈

🎀 General variables

• AUTH_USER — the username of the user the command in the chroot will run as. 👑
• CHROOT_NAME — the chroot name. note that this is the name of the original chroot before session creation — you probably want SESSION_ID instead, bestie. fr fr.
• LIBEXEC_DIR — the directory under which helper programs are located.
• MOUNT_DIR — the directory under which non-filesystem chroots are mounted (e.g. block devices and LVM snapshots).
• PID — the process ID of the schroot process.
• PLATFORM — 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 actually required. in the context of schroot, the platform is the supported configuration and behaviour for a given architecture, and may be identical between different architectures. 🤔
• SESSION_ID — the session identifier. this is the one you want, remember? 💅
• VERBOSE — 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 AUTH_VERBOSITY. (glow-up, honestly ✨)
• CHROOT_SESSION_CREATE — set to true if a session will be created, otherwise false.
• CHROOT_SESSION_CLONE — set to true if a session will be cloned, otherwise false.
• CHROOT_SESSION_PURGE — set to true if a session will be purged, otherwise false.
• CHROOT_SESSION_SOURCE — set to true if a session will be created from a source chroot, otherwise false.
• CHROOT_TYPE — the type of the chroot. this is useful for restricting a setup task to particular types of chroot (e.g. only block devices or LVM snapshots). 🧚
• CHROOT_NAME — the name of the chroot. this is useful for restricting a setup task to a particular chroot, or set of chroots. (yes, it's here again — two different flavours of the same name, iconic behaviour honestly)
• CHROOT_ALIAS — the name of the alias used to select the chroot. this is useful for specialising a setup task based upon one of its alternative alias names, or the default chroot name. for example, it could be used to specify additional sources in /etc/apt/sources.list, such as a stable-security alias for a stable chroot, or an experimental alias for an unstable chroot. 🔥
• CHROOT_DESCRIPTION — the description of the chroot.
• CHROOT_MOUNT_LOCATION — the location to mount the chroot. it is used for mount point creation and mounting.
• CHROOT_LOCATION — 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.
• CHROOT_PATH — 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. simple, clean, minimal, we love her. 🎀

🍓 File variables

• CHROOT_FILE — the file containing the chroot files.
• CHROOT_FILE_REPACK — 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.

• CHROOT_MOUNT_DEVICE — the device to mount containing the chroot.
• CHROOT_MOUNT_OPTIONS — options to pass to mount(8).
• CHROOT_LOCATION — the location of the chroot inside the mount point. this allows the existence of multiple chroots on a single filesystem.

🦋 Filesystem union variables

• CHROOT_UNION_TYPE — union filesystem type.
• CHROOT_UNION_MOUNT_OPTIONS — union filesystem mount options.
• CHROOT_UNION_OVERLAY_DIRECTORY — union filesystem overlay directory (writable).
• CHROOT_UNION_UNDERLAY_DIRECTORY — union filesystem underlay directory (read-only).

⭐ Block device variables

• CHROOT_DEVICE — the device containing the chroot root filesystem. this is usually, but not necessarily, the device which will be mounted. for example, for a LVM snapshot this will be the original logical volume. 🤯

🧚 LVM snapshot variables

• CHROOT_LVM_SNAPSHOT_NAME — snapshot name to pass to lvcreate(8).
• CHROOT_LVM_SNAPSHOT_DEVICE — the name of the LVM snapshot device.
• CHROOT_LVM_SNAPSHOT_OPTIONS — options to pass to lvcreate(8).

👑 Custom variables

custom keys set in schroot.conf will be uppercased and set in the environment as described in schroot.conf(5). main character energy for your own variables, honestly. 💅

---

🎀 FILES 🎀

📁 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: 👇
• copyfiles — a list of files to copy into the chroot from the host system. note that this was formerly named /etc/schroot/copyfiles-defaults.
• fstab — a file in the format described 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 /etc/schroot/mount-defaults.
• nssdatabases — 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.

🛠️ Setup scripts

the directory /etc/schroot/setup.d contains the chroot setup scripts. say hi to the whole squad 👋

• 00check — print debugging diagnostics and perform basic sanity checking. the vibe check script. ✅
• 05file — unpack, clean up, and repack file-based chroots.
• 05fsunion — create and remove union filesystems.
• 05lvm — create and remove LVM snapshots.
• 10mount — mount and unmount filesystems.
• 15binfmt — sets up the QEMU user emulator using binfmt-support. this permits a chroot for a different CPU architecture to be used transparently, providing an alternative to cross-compiling or whole-machine emulation. absolutely ate. 🔥
• 15killprocs — kill processes still running inside the chroot when ending a session, which would prevent unmounting of filesystems and cleanup of any other resources. (sorry to those processes but it's necessary 😭)
• 20copyfiles — copy files from the host system into the chroot. configure networking by copying hosts and resolv.conf, for example.
• 20nssdatabases — configure system databases by copying passwd, shadow, group etc. into the chroot.
• 50chrootname — set the chroot name (/etc/debian_chroot) in the chroot. this may be used by the shell prompt to display the current chroot. 🐚

---

💖 AUTHORS 💖

Roger Leigh. that's the one. 🫶

---

📜 COPYRIGHT 📜

Copyright © 2005-2012 Roger Leigh <rleigh@codelibre.net>

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 👀

schroot(1), fstab(5), schroot.conf(5), schroot-script-config(5), run-parts(8).

---

and that's the whole page, bestie!! this is Version 1.6.13 from 14 Aug 2022 — go forth and set up chroots, you absolute icon 💅✨🌸🦋💖