Documentation
recchroot
Enter a chroot environment with proper bind mounts. Like arch-chroot for Arch Linux.
Overview
recchroot sets up the necessary bind mounts (/proc, /sys, /dev, /run), enters the chroot, runs your command (or root's login shell in the target), 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
Options as printed by recchroot --help:
Enter chroot with proper bind mounts (like arch-chroot)
Usage: recchroot <CHROOT_DIR> [COMMAND]...
Arguments:
<CHROOT_DIR> Chroot directory (e.g., /mnt)
[COMMAND]... Command to run (default: root's login shell in the target)
Options:
-h, --help Print help
-V, --version Print version
Examples:
recchroot /mnt Open the target's root shell
recchroot /mnt passwd Set the target's root password
recchroot /mnt /bin/sh -c 'cat /etc/os-release'
Requires root. The target's /dev, /proc, /sys and /run are prepared for the
command and cleaned up when it exits. Type 'exit' to leave the target shell. Examples
recchroot /mnt recchroot /mnt -- passwd recchroot /mnt -- bootctl status recchroot /mnt -- passwd yourname Mount Handling
| Source | Target | Purpose |
|---|---|---|
/proc | <chroot>/proc | Process information filesystem |
/sys | <chroot>/sys | Kernel/hardware information; bound recursively, so EFI variables come along on UEFI |
/dev | <chroot>/dev | Device nodes |
/run | <chroot>/run | Runtime data (udev, systemd) |
DNS resolution: the live system's /etc/resolv.conf is bind-mounted over the target's for the session, so network operations work without writing into the target. A target resolv.conf that is a symlink is left alone; it resolves inside the chroot.
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
While the session is open, recchroot itself ignores those signals (the command gets the default handling), so an interrupt stops the command and recchroot still undoes its mounts. Unmounts run in reverse order with MNT_DETACH; a mount that cannot be removed is reported as an error.
Protected Paths
The tool refuses host system directories as a target. The list is PROTECTED_PATHS in tools/recstrap/src/guard.rs.
Error Codes
Every failure prints a code such as E004; the number is also the exit status. The codes and their meaning are the Code enum in tools/recstrap/src/error.rs.
Exit Status
recchroot returns the exit status of the command run inside the chroot: 0 for 0, 5 for 5. A command killed by signal N gives 128+N, as shells report it.
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 |
| efivars | Included with /sys on UEFI | Mounted on UEFI |
| resolv.conf | Bind mounted for the session | Bind mounted |
| Default command | Root's login shell in the target | /bin/bash |
| Cleanup on signal | Yes | Yes |
| Implementation | Rust | Bash script |
See Also
- recstrap - Extract the base system
- recfstab - Generate fstab entries
- Installation Tools Overview - Workflow overview