___________ __________ _____ ________ ________ .____ ___________ \_ _____/ \______ \ / _ \ / _____/ / _____/ | | \_ _____/ | __) | _/ / /_\ \ / \ ___ / \ ___ | | | __)_ | \ | | \ / | \ \ \_\ \ \ \_\ \ | |___ | \ \___ / |____|_ / \____|__ / \______ / \______ / |_______ \ /_______ / \/ \/ \/ \/ \/ \/ \/

chroot Cheatsheet

← Back to cheatsheets

← Home

chroot changes the apparent root directory for the current running process and its children. Used for system maintenance, creating isolated environments, and recovery operations.

Basic Usage

  • chroot <newroot> <command> - Change root and run command
  • chroot <newroot> /bin/sh - Change root and start POSIX shell
  • chroot <newroot> /bin/bash - Change root and start bash
  • chroot <newroot> /usr/bin/env sh - Change root with env resolving the shell from PATH

Common Use Cases

System Recovery/Maintenance

# Boot from live CD/USB, mount root filesystem
mount /dev/sda2 /mnt

# Mount necessary filesystems
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys

# Chroot into the system
chroot /mnt /bin/bash

Testing/Debugging

# Chroot into a directory with minimal system
chroot /path/to/root /bin/sh

# Run specific command in chroot
chroot /path/to/root /usr/bin/ls -la /

Required Setup Before chroot

Before using chroot, you typically need to:

  1. Mount the target filesystem
  • mount /dev/sdaX /mnt - Mount root partition
  • mount /dev/sdaY /mnt/boot - Mount separate /boot (if you have one)
  • mount /dev/sdaZ /mnt/home - Mount separate /home (if you have one)
  1. Mount essential virtual filesystems
  • mount --bind /dev /mnt/dev - Bind device directory
  • mount --bind /proc /mnt/proc - Bind proc filesystem
  • mount --bind /sys /mnt/sys - Bind sys filesystem
  • mount --bind /dev/pts /mnt/dev/pts - Bind pseudo-terminals (optional but recommended)
  • mount --tmpfs /mnt/run - Mount tmpfs for /run (if needed)
  1. Copy network configuration (if needed)
  • cp /etc/resolv.conf /mnt/etc/resolv.conf - DNS resolution
  1. Ensure shell and binaries exist in new root
  • Check /mnt/bin/sh, /mnt/bin/bash, etc. exist

Mounting Essential Filesystems

  • mount --bind /dev <newroot>/dev - Bind device directory
  • mount --bind /proc <newroot>/proc - Bind proc filesystem
  • mount --bind /sys <newroot>/sys - Bind sys filesystem
  • mount --bind /dev/pts <newroot>/dev/pts - Bind pseudo-terminals
  • mount --tmpfs /run <newroot>/run - Mount tmpfs for /run
  • mount -t tmpfs none <newroot>/tmp - Mount tmpfs for /tmp (optional)

Practical Examples

System Recovery Session

# 1. Mount root filesystem
mount /dev/sda2 /mnt

# If you have separate /boot and /home partitions, mount them too
mount /dev/sda1 /mnt/boot   # /boot (if separate)
mount /dev/sda3 /mnt/home   # /home (if separate)

# 2. Mount virtual filesystems
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys
mount --bind /dev/pts /mnt/dev/pts

# 3. Copy network config (if needed)
cp /etc/resolv.conf /mnt/etc/resolv.conf

# 4. Chroot and work
chroot /mnt /bin/bash

# Inside chroot:
# - Fix boot issues
# - Update packages
# - Edit configuration files
# - Reinstall bootloader

# 5. Exit chroot
exit

# 6. Unmount everything
umount /mnt/dev/pts
umount /mnt/sys
umount /mnt/proc
umount /mnt/dev
umount /mnt/home   # if mounted
umount /mnt/boot   # if mounted
umount /mnt

Package Management in Chroot

# Arch Linux
chroot /mnt pacman -Syu

# Debian/Ubuntu
chroot /mnt apt update
chroot /mnt apt upgrade

# Red Hat/CentOS/Fedora
chroot /mnt dnf update

Exiting Chroot

  • exit - Exit shell (returns to original root)
  • Ctrl+D - Exit shell (same as exit)
  • Unmount all bind mounts and any additional partitions (/boot, /home, etc.) before disconnecting live media or rebooting

Unmounting After Chroot

  • umount <newroot>/dev/pts - Unmount pseudo-terminals
  • umount <newroot>/sys - Unmount sys
  • umount <newroot>/proc - Unmount proc
  • umount <newroot>/dev - Unmount dev
  • umount <newroot>/run - Unmount run (if mounted)
  • umount <newroot>/home - Unmount separate /home (if mounted)
  • umount <newroot>/boot - Unmount separate /boot (if mounted)
  • umount <newroot> - Unmount root filesystem

If unmounting fails:

  • fuser -m <mountpoint> - Find processes using mount
  • fuser -km <mountpoint> - Kill processes using mount
  • lsof <mountpoint> - List open files on mount
  • umount -l <mountpoint> - Lazy unmount (unmount when not busy)

Troubleshooting

"chroot: failed to run command '/bin/bash': No such file or directory"

  • Check that `/bin/bash` exists in the new root
  • Verify architecture matches (32-bit vs 64-bit)
  • Check library dependencies with `ldd /mnt/bin/bash`

"chroot: cannot change root directory to '/mnt': Operation not permitted"

  • chroot requires root privileges - use `sudo` or `su`
  • Verify the directory is actually mounted
  • Check filesystem permissions

Network Not Working in Chroot

  • Copy `/etc/resolv.conf` from host: `cp /etc/resolv.conf /mnt/etc/resolv.conf`
  • Bind mount `/etc/resolv.conf`: `mount --bind /etc/resolv.conf /mnt/etc/resolv.conf`
  • Ensure network is up in chroot if using network commands

Tips

  • Always mount /dev, /proc, and /sys before chrooting for full functionality
  • Use `mount --bind` instead of copying files when possible (reflects host changes)
  • Copy or bind mount `/etc/resolv.conf` if you need DNS in chroot
  • Use `exit` to leave chroot, don't just close terminal
  • Unmount bind mounts in reverse order of mounting
  • Check library dependencies if binaries don't run: `ldd <binary>`
  • Use `arch-chroot` on Arch Linux for automatic setup of bind mounts
  • Create chroot environment with `debootstrap` (Debian/Ubuntu) or `pacstrap` (Arch)
  • Test chroot setup with simple command first: `chroot /mnt /bin/echo "Hello"`
  • Be careful - filesystem operations in chroot affect the actual system
  • Use chroot for system maintenance, recovery, building packages, and testing
  • Some distributions provide helper scripts: `arch-chroot` (Arch), `systemd-nspawn` (systemd)

← Back to cheatsheets

← Home