chrootmd — Smart chroot detection and rescue CLI

ALPHA — Not ready for production. Expect breaking changes and sharp edges.

chrootmd is a cross‑distro Linux rescue CLI that scans attached drives, detects Linux installations, and prepares safe chroots to run common repair tasks (GRUB reinstall, updates, initramfs rebuild, password resets, and more).

Highlights

• Auto‑detects Linux roots and profiles OS, hostname, users, package manager
• Preps a ready‑to‑use chroot with bind mounts and DNS
• Distro‑aware actions: apt/dnf/zypper/pacman; update/initramfs/GRUB/user ops
• Safety features: optional Btrfs snapshots, backups before risky changes, dry‑run mode
• JSON output for scripting and automation

Requirements

• Root privileges (sudo supported; the CLI attempts to re‑exec with sudo)
• Linux live environment or any Linux system with lsblk, mount, umount, chroot
• For actions: grub-install, grub-mkconfig, package manager tools, and initramfs tools as appropriate for the target system

Install

1. From source

   git clone https://github.com/your-org/chrootmd.git cd chrootmd cargo build --release install -Dm755 target/release/chrootmd ~/.local/bin/chrootmd

2. Binary release (recommended)

• Download the latest release from GitHub Releases and place chrootmd in your PATH (e.g., /usr/local/bin).

Quickstart

• List detected installs (JSON available with --json):

  sudo chrootmd probe

• Interactively pick a target and print its ID:

  sudo chrootmd pick

• Enter a ready chroot shell for a target by ID or short ID:

  sudo chrootmd enter --target

• Run rescue actions:

  sudo chrootmd run fix-grub --target sudo chrootmd run update-system --target sudo chrootmd run rebuild-initramfs --target sudo chrootmd run user-password alice --target sudo chrootmd run fstab-check --target sudo chrootmd run package apt-get install -y vim --target sudo chrootmd run service enable ssh --target

• Collect logs bundle for support:

  sudo chrootmd logs --target

CLI Overview

• probe: scan drives and list detected Linux installs
• pick: interactive selector to choose a target
• enter: prepare mounts and open a shell in target chroot
• run : run a named action inside the target
• actions: list available actions (context‑aware)
• doctor: validate environment and dependencies
• logs: collect var/log, etc/fstab, etc/os-release into a tar.gz, plus offline journalctl output (if available) and firmware diagnostics

Global flags

• -t, --target : select target by ID or short ID
• -y, --yes: assume yes for prompts (policy setting)
• --dry-run: print commands without executing
• --json: JSON output for scripting

Configuration

• File: ~/.config/chrootmd/config.toml
• Options:
  • assume_yes = true|false
  • dry_run = true|false
  • json = true|false
  • snapshots = true|false (enable Btrfs read‑only snapshots before risky ops)

Safety and behavior

• Dry‑run prints the exact operations without touching the system
• Before GRUB/installramfs actions chrootmd can create backups under /var/backups inside the target
• If snapshots are enabled and the root FS is Btrfs, chrootmd attempts a read‑only subvolume snapshot before risky ops
• All mounts are cleaned up on exit; teardown is robust and attempts lazy unmounts as needed

Supported distros and tooling

• Detection is generic via /etc/os-release and presence of package manager data directories
• Actions support apt, dnf/yum, zypper, pacman, and common initramfs tools (update‑initramfs, dracut, mkinitcpio)

Troubleshooting

• Run sudo chrootmd doctor to validate dependencies
• If probe finds nothing, ensure you run as root and your target partitions are visible (lsblk)
• For UEFI systems, ensure /boot/efi is listed in the target’s fstab so it can be mounted
• If a mount fails, check the target’s fstab sources (UUID/PARTUUID/LABEL) exist under /dev/disk/by-*

Docs

• User manual (usage, flags, examples): see docs/user-manual.md
• Architecture & internals: see docs/overview.md

Roadmap

• Stabilize scanning on complex layouts (LVM/RAID/btrfs subvolumes)
• Expand actions (bootloader variants, secure boot flows)
• Add richer logging and diagnostics bundles
• Improve interactive pick UX and add TUI

Contributing

• PRs and issues welcome. Please include doctor output and logs bundles when reporting problems.

License

• GPL‑3.0‑or‑later (see LICENSE)