GitHub

recchroot

Enter a chroot environment with proper bind mounts. Like arch-chroot for Arch Linux.

Overview

recchroot sets up the necessary bind mounts (/dev, /proc, /sys, /run), enters the chroot, runs your command (or an interactive shell), and cleans up on exit. This is the equivalent of Arch Linux's arch-chroot command.

The tool handles mount cleanup automatically, even if the command fails or is interrupted with Ctrl+C.

Usage

recchroot <CHROOT_DIR> [COMMAND]...
Argument Description
CHROOT_DIR Directory to chroot into (e.g., /mnt)
COMMAND Command to run (default: /bin/bash)

Options

Option Description
--version Show version
--help Show help

Examples

Enter interactive shell 
recchroot /mnt
Run single command 
recchroot /mnt passwd
Install bootloader 
recchroot /mnt bootctl install
Run multiple commands with shell 
recchroot /mnt /bin/bash -c 'passwd && bootctl install'

Mount Handling

Required mounts (always created):

Source Target Purpose
/proc /proc Process information filesystem
/sys /sys Kernel/hardware information
/dev /dev Device nodes
/run /run Runtime data (udev, systemd)

Optional mounts (created if source exists):

Source Target Purpose
/sys/firmware/efi/efivars /sys/firmware/efi/efivars EFI variables (for bootloader installation)

DNS resolution: /etc/resolv.conf is copied into the chroot so network operations work.

Cleanup Behavior

Mounts are always cleaned up, even when:

  • The command exits with an error
  • The command is interrupted with Ctrl+C (SIGINT)
  • The process receives SIGTERM or SIGQUIT
  • Mount setup fails partway through

Unmounts are performed in reverse order with MNT_DETACH to handle busy filesystems. Unmount failures are warnings, not errors.

Protected Paths

These paths cannot be used as chroot targets: 

/  /bin  /boot  /dev  /etc  /home  /lib  /lib64  /opt
/proc  /root  /run  /sbin  /srv  /sys  /tmp  /usr  /var

Use a mount point like /mnt instead.

Error Codes

Code Exit Description
E001 1 Target directory does not exist
E002 2 Target is not a directory
E003 3 Failed to create mount point directory
E004 4 Mount operation failed
E005 5 Unmount operation failed (warning only)
E006 6 Command execution failed
E007 7 Must run as root
E008 8 Target is a protected system path

Exit Status

recchroot returns the exit status of the command run inside the chroot. If the command exits with status 0, recchroot exits with 0. If the command exits with status 5, recchroot exits with 5.

Errors from recchroot itself use the error codes in the table above.

Comparison with arch-chroot

Feature recchroot arch-chroot
Bind mounts /proc, /sys, /dev, /run Same + /sys/firmware/efi/efivars
efivars mount Automatic if UEFI Automatic if UEFI
resolv.conf Copied Bind mounted
Cleanup on signal Yes Yes
Implementation Rust Bash script

See Also