Docs: recchroot

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:

Text
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

Enter interactive shell
recchroot /mnt
Run single command
recchroot /mnt -- passwd
Check the installed bootloader
recchroot /mnt -- bootctl status
Set a user's password
recchroot /mnt -- passwd yourname

Mount Handling

SourceTargetPurpose
/proc<chroot>/procProcess information filesystem
/sys<chroot>/sysKernel/hardware information; bound recursively, so EFI variables come along on UEFI
/dev<chroot>/devDevice nodes
/run<chroot>/runRuntime 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

Featurerecchrootarch-chroot
Bind mounts/proc, /sys, /dev, /runSame
efivarsIncluded with /sys on UEFIMounted on UEFI
resolv.confBind mounted for the sessionBind mounted
Default commandRoot's login shell in the target/bin/bash
Cleanup on signalYesYes
ImplementationRustBash script

See Also