SCHROOT-FAQ(7)

💖 NAME 💖

okay so this is schroot-faq — the frequently asked questions page for schroot, manual section 7. it's the group chat archive of every question bestie has ever asked about schroot, answered. 🫶

---

✨ DESCRIPTION ✨

this manual page covers the various frequently asked questions about configuration and usage of schroot. that's it, that's the whole vibe. lowkey essential reading, no cap. 💅

---

🌸 CONFIGURATION 🌸

🎀 Why is schroot overwriting configuration files in the chroot?

bestie. bestie. it's not being rude, it's being helpful. by default, schroot copies over the system NSS databases (passwd, shadow, group, gshadow, services, protocols, networks, and hosts, etc.) into the chroot. why? because a chroot environment isn't a completely separate system, so copying them over keeps them synchronised. iconic behaviour, honestly. ✨

but — and this is the part that has you in the group chat like 😭 — it's not always what you want. especially if installing a package in the chroot creates system users and groups that don't exist on the host, because those little guys will vanish the next time the databases get copied over. gone. poof. 💀

the suggested workaround is to just disable the copying. how? set the setup.nssdatabases key to be empty in schroot.conf. in prior schroot releases, this was done by commenting out the NSSDATABASES file for the chroot (/etc/schroot/default/config by default). and you can also customise the database list itself by editing the file containing the database list (/etc/schroot/default/nssdatabases by default). slay. 🎀

in the future, they'll 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. we're manifesting it. 🌈

🦋 Should I use the plain or directory chroot type?

okay so these two chroot types are basically equivalent, since they're both just directories in the filesystem. twins fr fr.

• plain is very simple and does not perform any setup tasks. the only reason you'd want 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.
• directory chroots, on the other hand, do run setup scripts, which can mount additional filesystems and do other setup tasks. main character energy. 👑

---

💜 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. so valid. 🫶

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. mess. 🙈

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. we believe in her. 🌱

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. periodt. 💅

---

🌈 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. the audacity. 😭

here's the tea. when schroot runs, it:

1. begins a session,
2. runs the specified command or shell,
3. waits for the command or shell to exit,
4. 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 an orphaned grandchild of this process) and it then ends the session. and part of ending the session is killing all processes running inside the chroot, which means the dæmon is killed as the session ends. rip. 💀

so 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. and it's your responsibility to end the session with --end-session when the dæmon has terminated or you no longer need it. okay bestie, that's on you. 🫶

🧚 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.

so 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/x86_64-linux-gnu/schroot/schroot-listmounts -m \
  /var/run/schroot/mount/my-session↵

• Unmount any mounted filesystems
• Remove /var/run/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 — like running arbitrary commands from a program or script where you don't know which commands to run in advance. 👀

you might also want to preserve 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. and 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

obsessed. giving her a name is giving her a whole identity. 🎀

---

🦋 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. come hang out. 💖

🐛 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 contains 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-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. slay, libre, etc. 💜

---

💫 SEE ALSO 💫

dchroot(1), sbuild(1), schroot(1), schroot.conf(5). schroot-setup(5),

---

and that's the whole page bestie!! 🎀 this was schroot-faq(7) from the Debian sbuild manual set, Version 1.6.13, dated 14 Aug 2022 — so go forth, read your configs, and don't delete any mounted directories, i'm begging you. mwah. 💖✨🦋