Docs: recstrap

Documentation

recstrap

Extract the base system (LevitateOS or AcornOS) to a target directory. Like pacstrap for Arch Linux.

Overview

recstrap extracts the system's EROFS image from the live ISO to a mounted target directory.

recstrap is EROFS-only. The rootfs is an .erofs image file or a partition holding one; anything else (including .squashfs) is rejected. It mounts the image read-only and copies its files into the target.

After running recstrap, complete the installation: generate /etc/fstab with recfstab, then configure the system, set passwords and install the bootloader with recsetup.

Usage

Options as printed by recstrap --help:

Text
Extracts the EROFS rootfs image to a target directory. This is the pacstrap equivalent - it only extracts files; the live install docs describe the rest of the installation.

Usage: recstrap [OPTIONS] <TARGET>

Arguments:
  <TARGET>
          Target directory (must be mounted, e.g., /mnt)

Options:
      --rootfs <ROOTFS>
          Rootfs image (auto-detected on the live ISO if not specified)

  -f, --force
          Shorthand for --allow-non-mountpoint --allow-nonempty

      --allow-non-mountpoint
          Allow a target directory that is not a mount point

      --allow-nonempty
          Allow a target directory that already contains files

      --allow-host-root-fs
          Allow extracting onto a filesystem the running system has mounted at / or another system directory such as /home (never implied by --force)

  -q, --quiet
          Quiet mode - minimal output for scripting

  -c, --check
          Check mode - run pre-flight validation only, don't extract

      --json
          Print progress as JSON lines on stdout (one event per line: start, progress, verify, done; with --check, one checked); errors go to stderr as JSON

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Examples:
  recstrap /mnt --check       Check the target without extracting
  recstrap /mnt               Extract the live ISO's system image
  recstrap /mnt --rootfs /path/to/filesystem.erofs

After extraction: preview fstab with 'recfstab /mnt', write it with
'recfstab /mnt --write', then inspect configuration with 'recsetup inspect --root /mnt'.

Examples

Extract to mounted root partition
recstrap /mnt
Use custom EROFS image location
recstrap --rootfs /media/usb/filesystem.erofs /mnt
Run pre-flight checks only (no extraction)
recstrap --check /mnt
Skip the mount point and empty-target checks
recstrap --force /mnt

Pre-flight Validation

Before extraction, recstrap validates critical conditions to catch problems early. Use --check to run only validation without extracting.

  1. Target is not a protected system path (never overridable)
  2. Running as root
  3. Target is writable
  4. Target is not on the running system's root filesystem or another host system directory (only --allow-host-root-fs, never implied by --force)
  5. Target is a mount point (--allow-non-mountpoint or --force)
  6. Target is empty, lost+found aside (--allow-nonempty or --force)
  7. At least 2 GB free on the target
  8. A rootfs image was found
  9. The rootfs is an image file or a partition, not a directory
  10. The rootfs is not inside the target
  11. The rootfs is EROFS: an image file named .erofs, with the EROFS superblock magic
  12. The running kernel supports EROFS (built in or loadable)

After extraction, recstrap checks that bin, etc, lib, sbin, usr and var exist in the target before it reports success.

EROFS Auto-Detection

If --rootfs is not specified, recstrap searches these paths in order:

  • /run/live-rootfs.erofs - the live system's handle to the rootfs payload partition or image file
  • /run/live-media/live/filesystem.erofs - the image file on the mounted boot medium

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.

Post-Extraction

After recstrap completes, continue with the installation:

Shell
# Generate fstab
recfstab --write /mnt

# Configure the system
recsetup apply --root /mnt --timezone Europe/Brussels --locale en_US.UTF-8

# Set the root password (root is locked by default)
recchroot /mnt -- passwd

# Install systemd-boot and the A/B boot entries
recsetup apply --root /mnt --boot ab --slot-a /dev/nvme0n1p2 --slot-b /dev/nvme0n1p3 --machine-id && recab verify-installation --root /mnt

# Unmount and reboot
umount /mnt/boot
umount /mnt/var
umount /mnt
reboot

Comparison with pacstrap

Featurerecstrappacstrap
SourceEROFS imagePackage repository
SpeedFast (extract only)Slower (download + install)
Package selectionFull base systemSelectable packages
Offline capableYes (from live ISO)No (needs network)

See Also