Comprehensive README with usage guide and troubleshooting

.gitattributes

@@ -1 +0,0 @@
-*.lz4 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,4 +1 @@
-PBX.img
+*.zst
-PBX.qcow2
-PBX-Test.qcow2
-*.snapshot*

CloneToDisk.sh

@@ -128,7 +128,7 @@ dialogue() {
     echo -e "${RED}WARNING: ALL DATA ON ${disk_name} WILL BE DESTROYED${RESET}"
   elif [[ $NO_RETABLE == false ]]; then
     echo -e "${YELLOW}INFO: Running in NO WRITE mode. No data will be written to disk${RESET}"
-  elif
+  else
     echo -e "${YELLOW}WARNING: Existing partitions will be used but filesystems and file data may be modified${RESET}"
   fi
 
@@ -156,7 +156,6 @@ rewrite_gpt_table() {
   sgdisk -n 3:0:0 -t 3:8e00 -c 3:"Linux LVM" $disk_name
 
   partprobe 2>/dev/null ||
-
     lsblk $disk_name
 
   echo -e "${GREEN}GPT table created. ${RESET}"

README.md

@@ -1,2 +1,151 @@
-## Used for writing a Debian FreePBX image to a new drive
+# PBX Image Script
-WIP
+
+Fast deployment tool for cloning PBXact/FreePBX systems using tar archives and zstd compression.
+
+## Overview
+
+This tool creates and restores complete PBX system images including:
+- Root filesystem with LVM
+- Boot partition (ext4)
+- EFI system partition (FAT32)
+- GRUB bootloader configuration
+- fstab generation with proper filesystem UUIDs
+
+## Requirements
+
+**Environment:**
+- Live Linux USB (must boot in UEFI mode)
+- Root access
+
+**Dependencies:**
+```bash
+apt install gdisk pv lvm2 zstd dosfstools e2fsprogs parted util-linux coreutils
+```
+
+The deployment script checks for missing tools automatically.
+
+## Usage
+
+### 1. Creating an Image
+
+Extract from an existing `.img` file with LVM:
+
+```bash
+sudo ./fs_extract.sh
+```
+
+**What it does:**
+- Mounts the image via loopback
+- Activates LVM volume group
+- Detects kernel version from `/boot/vmlinuz-*`
+- Creates `PBX-Image-<kernel-version>.tar.zst` with progress bar
+- Excludes sockets and special files automatically
+
+The resulting archive contains the complete filesystem ready for deployment.
+
+### 2. Deploying to New Hardware
+
+Clone the archive to a target disk:
+
+```bash
+sudo ./CloneToDisk.sh
+```
+
+**Interactive process:**
+1. Shows available disks (`lsblk`)
+2. Prompts for target disk (e.g., `sda`, `vdb`)
+3. **Requires typing `yes` to confirm** (prevents accidents)
+4. Partitions disk (GPT: EFI + boot + LVM)
+5. Creates ext4/vfat filesystems
+6. Extracts tar archive with progress bar
+7. Generates `/etc/fstab` with correct UUIDs
+8. Installs GRUB to EFI partition
+9. Configures bootloader
+
+**Time:** ~5-10 minutes depending on image size and disk speed.
+
+### Command-Line Options
+
+```bash
+./CloneToDisk.sh [options]
+
+--nowrite      Skip image extraction (only partition/format)
+--noretable    Use existing partition table (don't repartition)
+--nocleanup    Leave filesystems mounted after completion
+-h             Show help
+```
+
+## Partition Layout
+
+Created automatically by `CloneToDisk.sh`:
+
+| Partition | Size | Type | Mount Point | Filesystem |
+|-----------|------|------|-------------|------------|
+| 1 | 512MB | EFI System | `/boot/efi` | FAT32 |
+| 2 | 1GB | Linux | `/boot` | ext4 |
+| 3 | Remaining | LVM PV | (LVM) | - |
+
+**LVM Layout** (on partition 3):
+
+| LV | Size | Mount Point | Filesystem |
+|----|------|-------------|------------|
+| `SangomaPBX-vg/root` | Remaining | `/` | ext4 |
+| `SangomaPBX-vg/swap_1` | 4GB | swap | swap |
+
+## Image Storage
+
+**Do not store images in git.**
+
+Images are distributed via [Gitea Releases](https://git.archfox.org/poslop/PBX-Image-Script/releases).
+
+To use:
+1. Download the latest `.tar.zst` from releases
+2. Place in the same directory as `CloneToDisk.sh`
+3. Run the script
+
+## Files
+
+- **`fs_extract.sh`** - Creates image from disk image file
+- **`CloneToDisk.sh`** - Deploys image to physical disk
+- **`fstab_template`** - Template for generating `/etc/fstab` with UUID placeholders
+
+## Technical Details
+
+**Compression:**
+- Uses zstd (fast compression, good ratio)
+- Excludes logs, caches, temp files, and sockets
+- Typical compression ratio: ~40-60% depending on content
+
+**Boot Configuration:**
+- UEFI only (no legacy BIOS support)
+- Uses `grub-install` and `update-grub` in chroot
+- Mounts `/sys/firmware/efi/efivars` for EFI variable access
+- Automatically detects and uses correct kernel version
+
+**Safety Features:**
+- Dependency checking before execution
+- Explicit confirmation required (`yes` not just `y`)
+- Color-coded warnings (red for destructive, yellow for info)
+- Cleans up mounts automatically on exit or error
+
+## Troubleshooting
+
+**"NO TAR.ZST FILE FOUND"**
+- Download image from releases page
+- Place in current directory or `./Image/` subdirectory
+
+**"Missing required tools"**
+- Run: `apt install gdisk pv lvm2 zstd dosfstools e2fsprogs parted util-linux coreutils`
+
+**GRUB installation fails**
+- Verify you booted the live USB in UEFI mode (not legacy BIOS)
+- Check `/sys/firmware/efi/efivars` exists
+
+**Mount errors**
+- Use `--nocleanup` to inspect state
+- Manually unmount with `umount -lf /mnt/debian/*`
+- Deactivate LVM: `vgchange -an SangomaPBX-vg`
+
+## License
+
+Internal tooling for PBXact deployment.