Chroot Guide for Debian/Ubuntu

Introduction

A chroot (change root) environment allows you to switch the root directory of a Linux session to a different filesystem, enabling you to work within a broken or inaccessible Debian/Ubuntu system as if it were the active system. This is particularly useful for repairing boot issues, recovering files, updating configurations, or resetting passwords. This guide provides step-by-step instructions to set up a chroot environment from a Debian/Ubuntu live USB/CD.

Prerequisites

  • A Debian or Ubuntu live USB/CD (preferably the same version as your system).
  • Access to a live session by booting from the live media and selecting “Try Ubuntu/Debian.”
  • Basic familiarity with the terminal.
  • Administrative (root) privileges in the live environment.

Critical Warning: Verify Partitions Before Mounting

Setting Up a Chroot Environment

Step 1: Boot into the Live Environment

  1. Insert your Debian/Ubuntu live USB/CD and boot your computer.
  2. Select “Try Ubuntu/Debian” to enter the live session.
  3. Open a terminal (e.g., press Ctrl+Alt+T).

Step 2: Identify and Mount the Root Partition

Identify the disk and partition layout, then mount the root filesystem of your installed system:

# List disks and partitions
lsblk

# Mount the root partition (e.g., /dev/sda2)
sudo mkdir -p /mnt
sudo mount /dev/sda2 /mnt  # Replace sda2 with your root partition
  • Explanation:
    • lsblk: Displays block devices and their partitions. Identify your root partition (typically ext4, mounted as / on the installed system).
    • sudo mount /dev/sda2 /mnt: Mounts the root partition to /mnt. Replace sda2 with the correct partition (e.g., /dev/nvme0n1p2 for NVMe drives).

Step 3: Mount Additional Filesystems

For a fully functional chroot environment, mount essential system directories:

# Mount /dev, /proc, /sys
sudo mount --bind /dev /mnt/dev
sudo mount --bind /proc /mnt/proc
sudo mount --bind /sys /mnt/sys

# Mount /dev/pts for pseudo-terminals (required for some commands)
sudo mount --bind /dev/pts /mnt/dev/pts

# Mount EFI System Partition (ESP) for UEFI systems
sudo mkdir -p /mnt/boot/efi
sudo mount /dev/sda1 /mnt/boot/efi  # Replace sda1 with your ESP (typically FAT32, 100-550 MB)
  • Explanation:
    • --bind: Binds system directories to the chroot environment to provide access to devices, processes, and system information.
    • /dev/pts: Required for terminal-related operations.
    • /boot/efi: Mount the ESP if your system uses UEFI (verify with lsblk or fdisk -l).

Step 4: Optional - Enable Networking

If you need internet access in the chroot (e.g., for package updates):

# Copy resolv.conf for DNS resolution
sudo cp /etc/resolv.conf /mnt/etc/resolv.conf

# Bind-mount /run for network services
sudo mount --bind /run /mnt/run
  • Explanation:
    • resolv.conf: Provides DNS settings for internet access.
    • /run: Required for modern network management (e.g., NetworkManager, systemd-resolved).

Step 5: Enter the Chroot Environment

Switch to the chroot environment:

sudo chroot /mnt
  • Explanation:
    • chroot /mnt: Changes the root directory to /mnt, making it the new / for the session. You are now operating within the installed system’s filesystem.

Step 6: Perform Repairs or Tasks

Common tasks in the chroot environment include:

  • Update GRUB:
    grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB  # UEFI
# OR
grub-install --target=i386-pc /dev/sda  # Legacy (replace sda with your disk)
update-grub
  • Reset Root Password:
    passwd
  • Update Packages:
    apt update
apt upgrade
  • Repair Filesystem:
    fsck /dev/sda2  # Replace sda2 with your root partition

Step 7: Exit and Unmount

Exit the chroot and unmount all filesystems:

exit
sudo umount /mnt/dev/pts /mnt/dev /mnt/proc /mnt/sys /mnt/boot/efi /mnt/run /mnt
  • Explanation:
    • exit: Exits the chroot environment.
    • umount: Unmounts all bound and mounted filesystems. Ensure all are unmounted to avoid disk issues.

Tips and Troubleshooting

Common Issues

  • “chroot: failed to run command”:
    • Ensure the root partition is mounted correctly (lsblk to verify).
    • Check that /mnt/bin/bash exists. If missing, the system may be corrupted or use a different shell (e.g., try chroot /mnt /bin/sh).
  • Missing ESP in UEFI systems:
    • Verify the ESP (/dev/sda1, FAT32) is mounted at /mnt/boot/efi using lsblk.
    • If missing, create one (see Linux Boot Repair Guide).
  • No internet in chroot:
    • Confirm /etc/resolv.conf is copied and /run is mounted.
    • Test with ping 8.8.8.8 or apt update.
  • Wrong partition mounted:
    • Double-check the partition layout with lsblk or fdisk -l before mounting.
    • Mounting the wrong partition can lead to unintended changes or data loss.
  • Unmount failures:
    • If umount fails, check for open processes using the mount point:
      lsof | grep /mnt
    • Kill processes or use umount -l (lazy unmount) as a last resort.

Additional Tips

  • Backup Critical Files: Before chroot, back up important files (e.g., /mnt/etc, /mnt/boot):
    sudo cp -r /mnt/etc /mnt/etc.bak
  • Verify Partition Layout: Use lsblk or fdisk -l to confirm the correct disk and partition before mounting.
  • Test Changes: After making changes, reboot to test. If issues persist, re-enter the live session and chroot again.
  • Use SSH Tunneling for Remote Access: For remote servers, use SSH tunneling to access the live environment:
    ssh -L 2222:remote.linux.server:22 user@ssh.example.com
    Then connect via SSH to localhost:2222.
  • Boot Repair Tool: If manual chroot fails, try the boot-repair tool in the live session:
    sudo add-apt-repository ppa:yannubuntu/boot-repair
sudo apt update
sudo apt install -y boot-repair
boot-repair

Next Steps

In future tutorials, we’ll explore:

  • Advanced GRUB configuration in chroot.
  • Filesystem recovery using chroot.
  • Automating chroot setup with scripts.

Resources

Practice setting up a chroot environment in a test system to master Debian/Ubuntu repairs, and always verify partitions to avoid data loss!