Mok0 at 16:31, 28 September 2026

2026-09-28T16:31:18Z

Mok0: 1 revision imported

2026-09-28T16:29:17Z

1 revision imported

← Older revision		Revision as of 16:29, 28 September 2026
(No difference)

Mok0: 1 revision imported

2026-09-28T16:28:31Z

1 revision imported

Show changes

mok0>Morten Kjeldgaard: Not currently under git control

2026-09-28T16:18:39Z

Not currently under git control

Show changes

mok0>Morten Kjeldgaard: Not currently under git control

2026-09-28T08:02:48Z

Not currently under git control

New page

<small>[[DebianWiki/EditorGuide#translation|Translation(s)]]: [[de/chroot|Deutsch]]<nowiki> </nowiki>- [[chroot|English]]<nowiki> </nowiki>- [[es/chroot|Español]]<nowiki> </nowiki>- [[fr/Chroot|Français]]<nowiki> </nowiki>- [[it/chroot|Italiano]]</small>

-----

[[DebianMan:chroot]] is an utility that changes which folder is considered the root of the filesystem hierarchy by its child processes, so that it is impossible for them to access the parent folder of the new root, even though it physically exists on the disk.

__TOC__

-------

= Common use-cases =

<div>'''<code>chroot</code><nowiki> </nowiki>utility is intended mostly for an occasional, ad-hoc usage.'''

If you regularly need different environments, then consider a container runtime like <code>podman</code> instead.
</div>

* Fast switching to another environment (distro, version, flavor, package mix etc) for the purposes of testing, building, debugging etc.
* Repairing a broken Linux installation by connecting its primary drive as an external device (for example using an USB enclosure) to some other working system and performing operations from within the system being repaired.
* Historically <code>chroot</code> was also used to increase the security of network services running on a given machine: if an attacker managed to trick a service to an [https://en.wikipedia.org/wiki/Arbitrary_code_execution arbitrary code execution], he would still not have access to the whole filesystem of the machine (he would remain in a so called ''chroot jail''). This however does not prevent the attacker from using the machine's network interfaces to further penetrate the internal network, moreover on Linux and some other UNIXes, escaping a "chroot jail" is relatively easy. As a result, for security-related purposes <code>chroot</code> was replaced by virtual machines and containers.

-------

= Basic setup and usage =

''Unless explicitly stated otherwise, all commands in the below subsections require <code>root</code><nowiki> </nowiki>privileges.''

== Create or provide a file hierarchy of a Linux system ==

In the subsequent sections, '''<code>${chrootFolder}</code>''' will refer to the root folder of a file hierarchy created or provided as described below.

* In case of switching to existing installations, it boils down to mounting their root filesystem at a target folder of your choice.
* In case you want to create a fresh Debian image, you can use utilities such as [[DebianMan:mmdebstrap]], for example to create a clean environment to build deb packages:<pre>
mmdebstrap --skip=output/dev,output/mknod --variant=buildd \
trixie "${chrootFolder}" http://deb.debian.org/debian
</pre>

== Mount virtual filesystems ==

As of 2026 these are <code>proc</code>, <code>sysfs</code>, <code>udev</code> and "children" of the latter 2 of which there are too many and which also tend to die off or spawn way too often. Fortunately, [[DebianMan:mount]] has <code>--rbind</code> option that allows to bind an already mounted filesystem together with all its children to an additional target folder. You need to use either <code>--make-rslave</code> or <code>--make-rprivate</code> flag too (see [[DebianMan:mount_namespaces]] for details).
<pre>
mount -t proc proc "${chrootFolder}/proc"
mount --rbind --make-rslave /sys "${chrootFolder}/sys"
mount --rbind --make-rslave /dev "${chrootFolder}/dev"
</pre>
In case you are wondering: <code>proc</code> has 1 child also: <code>binfmt_misc</code>, which is used for registering binary executable handlers/interpreters, which does not make sense in a <code>chroot</code> (the absolute path of a given interpreter needs to be provided, which is inaccessible from a <code>chroot</code>-ed context), therefore no point in binding it.

== Copy the DNS resolver config ==

<pre>
cp /etc/resolv.conf "${chrootFolder}/etc/"
</pre>

== Perform a chroot switch ==

This usually boils down to<pre>
chroot "${chrootFolder}"
</pre>
...which will start an interactive login shell of <code>root</code> user inside the <code>chroot</code>-ed environment, so that you can interactively perform whatever tasks you need.

For non-interactive tasks, you can instead provide an alternative command and its args:<pre>
chroot "${chrootFolder}" /root/myScriptToBeExecutedInChroot.sh myArg1 myArg2
</pre>
<code>/root/myScriptToBeExecutedInChroot.sh</code> is a path inside the <code>chroot</code>-ed hierarchy.

== Cleanup ==

After the <code>chroot</code> process exits, you need to unbind / <code>umount</code> all the virtual filesystems bound / mounted previously. Fortunately <code>umount</code> also has <code>--recursive</code> / <code>-R</code> flag to help with this:<pre>
umount -R "${chrootFolder}/dev"
umount -R "${chrootFolder}/sys"
umount -R "${chrootFolder}/proc"
</pre>
If <code>${chrootFolder}</code> is a mount point of an external drive and you want to <code>umount</code> it also, you can replace all the above commands with the below single one:<pre>
umount -R "${chrootFolder}"
</pre>

-------

= Additional notes and scenarios =

== Running X11 GUI apps ==

Running X11 GUI apps from within a <code>chroot</code>-ed environment and displaying them on host's X11 server works using standard mechanisms: just export the value of <code>DISPLAY</code> env var from the host in the <code>chroot</code> and make sure the host X server will allow connections (for example using [[DebianMan:xhost]] utility).

-----

== Running Systemd services ==

Systemd services will generally refuse to run in a <code>chroot</code>-ed environment. Use [[nspawn|systemd-nspawn]] instead of <code>chroot</code> if you need to run Systemd services.

-----

== Foreign architectures ==

If [[DebianPkg:qemu-user-binfmt]] is installed, it is possible to <code>chroot</code> to a filesystem for any foreign arch it supports.

-----

== Modifying boot data ==

If you want to modify the boot data of another system whose drive you <code>chroot</code>-ed into (this includes for example running <code>update-grub</code>, <code>update-initramfs</code>, installing a new kernel or firmware + kernel modules for boot-critical devices etc), you need to mount its <code>/boot</code> hierarchy. This may include the following:
* <code>/boot</code> itself is sometimes a separate partition, most commonly on systems using some disk encryption scheme.
* On UEFI systems (which includes most of modern x86 and ARM hardware), their ESP partitions are mounted at <code>/boot/efi</code>.

It is usually most convenient to mount these filesystems right after performing a <code>chroot</code> switch.

After performing a <code>chroot</code> switch, check which filesystem are present by running <code>grep /boot /etc/fstab</code>. Below is an example output from a system with both <code>/boot</code> and <code>/boot/efi</code> entries:<pre>
UUID=7a307683-255a-4bac-937f-95aa2af2ca17 /boot ext4 defaults 0 2
UUID=4D18-6163 /boot/efi vfat umask=0077 0 1
</pre>
If <code>/etc/fstab</code> entries use UUIDs as in the example above (which is the default on most modern distros) or unique <code>PARTLABEL</code>s or <code>LABEL</code>s, then all you need to do is to point <code>mount</code> to their corresponding mount-points:<pre>
mount /boot
mount /boot/efi
</pre>
On some older systems, instead of UUIDs or labels, device nodes may be used in <code>/etc/fstab</code>, like for example <code>/dev/sdaX</code> etc. In such case you need to figure out what device node currently corresponds to a given filesystem. Most commonly, it will be another partition on the same physical drive as the root filesystem of that external system.

After you are done with your <code>chroot</code> work, these filesystems may be <code>umount</code>-ed either from within the <code>chroot</code> or after exiting.

-----

[[:Category:System]] | [[:Category:Virtualization]]

Chroot - Revision history

Mok0 at 16:31, 28 September 2026

Mok0: 1 revision imported

Mok0: 1 revision imported

mok0>Morten Kjeldgaard: Not currently under git control

mok0>Morten Kjeldgaard: Not currently under git control