GitHub

recstrap

Extract the LevitateOS base system to a target directory. Like pacstrap for Arch Linux.

Overview

recstrap extracts the LevitateOS EROFS image from the live ISO to a mounted target directory. This is the equivalent of Arch Linux's pacstrap command.

After running recstrap, you must manually complete the installation: generate /etc/fstab, install a bootloader, set passwords, and configure the system.

Usage

recstrap [OPTIONS] <TARGET>
Argument Description
TARGET Target directory (must be mounted, e.g., /mnt)

Options

Option Description
--erofs Custom EROFS image location (auto-detected from live ISO if not specified)
-f, --force Allow extraction even if target is not empty or not a mount point
-q, --quiet Minimal output for scripting
-c, --check Run pre-flight validation only, do not extract
--version Show version
--help Show help

Examples

Extract to mounted root partition 
recstrap /mnt
Use custom EROFS image location 
recstrap /mnt --erofs /media/usb/filesystem.erofs
Run pre-flight checks only (no extraction) 
recstrap /mnt --check
Force extraction to non-empty directory 
recstrap /mnt --force

Pre-flight Validation

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

  1. Running as root
  2. fsck.erofs is available
  3. Target directory exists
  4. Target is a directory (not a file)
  5. Target is not a protected system path
  6. Target is writable
  7. Target is a mount point (skipped with --force)
  8. Target is empty (skipped with --force; lost+found ignored)
  9. Sufficient disk space (minimum 2GB)
  10. EROFS image exists
  11. EROFS image is a regular file
  12. EROFS image is readable
  13. EROFS image is not inside the target directory
  14. Extraction completes successfully

EROFS Auto-Detection

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

  • /media/cdrom/live/filesystem.erofs
  • /run/initramfs/live/filesystem.erofs
  • /run/archiso/bootmnt/live/filesystem.erofs
  • /mnt/cdrom/live/filesystem.erofs

Protected Paths

These paths are always blocked as extraction targets, even with --force: 

/  /bin  /boot  /dev  /etc  /home  /lib  /lib64  /opt
/proc  /root  /run  /sbin  /srv  /sys  /tmp  /usr  /var

Use a mount point like /mnt instead.

Error Codes

Code Exit Description
E001 1 Target directory does not exist
E002 2 Target is not a directory
E003 3 Target directory not writable
E004 4 EROFS image not found
E005 5 EROFS extraction command failed
E006 6 Extracted system verification failed
E007 7 EROFS tools not installed
E008 8 Must run as root
E009 9 Target directory not empty (use --force)
E010 10 Target is a protected system path
E011 11 Target is not a mount point (use --force)
E012 12 Insufficient disk space
E013 13 EROFS image is not a regular file
E014 14 EROFS image is not readable
E015 15 EROFS image is inside target directory

Post-Extraction

After recstrap completes, continue with the installation: 

# Generate fstab
recfstab /mnt >> /mnt/etc/fstab

# Copy pre-built UKI
mkdir -p /mnt/boot/EFI/Linux
cp /media/cdrom/boot/uki/levitateos.efi /mnt/boot/EFI/Linux/

# Enter chroot
recchroot /mnt

# Set root password
passwd

# Install bootloader (auto-discovers UKI)
bootctl install

# Exit and reboot
exit
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