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:
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
recstrap /mnt recstrap --rootfs /media/usb/filesystem.erofs /mnt recstrap --check /mnt recstrap --force /mnt Pre-flight Validation
Before extraction, recstrap validates critical conditions to catch problems early. Use --check to run only validation without extracting.
- Target is not a protected system path (never overridable)
- Running as root
- Target is writable
- Target is not on the running system's root filesystem or another host system directory (only
--allow-host-root-fs, never implied by--force) - Target is a mount point (
--allow-non-mountpointor--force) - Target is empty,
lost+foundaside (--allow-nonemptyor--force) - At least 2 GB free on the target
- A rootfs image was found
- The rootfs is an image file or a partition, not a directory
- The rootfs is not inside the target
- The rootfs is EROFS: an image file named
.erofs, with the EROFS superblock magic - 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:
# 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
| Feature | recstrap | pacstrap |
|---|---|---|
| Source | EROFS image | Package repository |
| Speed | Fast (extract only) | Slower (download + install) |
| Package selection | Full base system | Selectable packages |
| Offline capable | Yes (from live ISO) | No (needs network) |
See Also
- recfstab - Generate fstab entries
- recchroot - Enter chroot environment
- Installation Tools Overview - Workflow overview