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

@@ -11,7 +11,7 @@ NO_RETABLE=false
 NO_USB=false
 NO_CLEANUP=false
 
-IMG_FILE="PBX-root.img.lz4"
+IMG_FILE="PBX-Image-*.tar.zst"
 
 MOUNT_PATH="/mnt/debian"
 MOUNT_POINTS=("/dev" "/dev/pts" "/proc" "/sys" "/run")
@@ -55,6 +55,7 @@ done
 
 main() {
   root_check
+  check_dependencies
 
   udevadm trigger
 
@@ -73,12 +74,11 @@ main() {
     make_filesystem
   fi
 
+  mount_partitions
   write_img
-
   mount_chroot
 
   gen_fstab
-
   install_grub
 
   echo -e "${GREEN}Restore and resize complete!${RESET}"
@@ -92,6 +92,27 @@ root_check() {
   fi
 }
 
+check_dependencies() {
+  local missing=()
+  local required_tools=("sgdisk" "pv" "pvcreate" "vgcreate" "lvcreate" "vgchange" "mkfs.vfat" "mkfs.ext4" "mkswap" "tar" "zstd" "lsblk" "partprobe" "chroot")
+
+  for tool in "${required_tools[@]}"; do
+    if ! command -v "$tool" &>/dev/null; then
+      missing+=("$tool")
+    fi
+  done
+
+  if [[ ${#missing[@]} -gt 0 ]]; then
+    echo -e "${RED}Missing required tools: ${missing[*]}${RESET}"
+    echo
+    echo "Install with:"
+    echo "  apt install gdisk pv lvm2 zstd dosfstools e2fsprogs parted util-linux coreutils"
+    exit 1
+  fi
+
+  echo -e "${GREEN}All dependencies found${RESET}"
+}
+
 dialogue() {
   lsblk
 
@@ -102,9 +123,30 @@ dialogue() {
 
   echo "Chose disk $disk_name"
   echo
+
+  if [[ $NO_WRITE == false ]]; then
+    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}"
+  else
+    echo -e "${YELLOW}WARNING: Existing partitions will be used but filesystems and file data may be modified${RESET}"
+  fi
+
+  lsblk $disk_name
+  echo
+
+  read -rp "Are you sure you want to continue? (yes/no): " confirm
+  if [[ "$confirm" != "yes" ]]; then
+    echo "Aborted."
+    exit 0
+  fi
 }
 
 rewrite_gpt_table() {
+  vgchange -an $VGROUP 2>/dev/null || true
+  vgremove -f $VGROUP 2>/dev/null || true
+  pvremove -ff $ROOT_PART 2>/dev/null || true
+
   sgdisk -Z $disk_name
 
   sgdisk -c $disk_name
@@ -113,8 +155,7 @@ rewrite_gpt_table() {
   sgdisk -n 2:0:+1G -t 2:8300 -c 2:"boot" $disk_name
   sgdisk -n 3:0:0 -t 3:8e00 -c 3:"Linux LVM" $disk_name
 
-  partprobe || true
+  partprobe 2>/dev/null ||
-
     lsblk $disk_name
 
   echo -e "${GREEN}GPT table created. ${RESET}"
@@ -140,9 +181,10 @@ lvm_init() {
 }
 
 make_filesystem() {
-  mkfs.vfat -F 32 $EFI_PART
+  mkfs.vfat -I -F 32 $EFI_PART
-  mkfs.ext4 $BOOT_PART
+  mkfs.ext4 -F $BOOT_PART
-  mkswap "${VG_PATH}${SWAP_LV}"
+  mkfs.ext4 -F "${VG_PATH}${ROOT_LV}"
+  mkswap -f "${VG_PATH}${SWAP_LV}"
   echo -e "${GREEN}Make filesystems finished.${RESET}"
 }
 
@@ -152,22 +194,19 @@ write_img() {
     return 0
   fi
 
-  img_file_dir="null"
+  local img_file_dir=$(ls -1 ./PBX-Image-*.tar.zst 2>/dev/null | head -n1)
 
-  if [[ -f "./${IMG_FILE}" ]]; then
+  if [[ -z "$img_file_dir" ]]; then
-    img_file_dir="./${IMG_FILE}"
+    img_file_dir=$(ls -1 ./Image/PBX-Image-*.tar.zst 2>/dev/null | head -n1)
-  elif [[ -f "./Image/${IMG_FILE}" ]]; then
+  fi
-    img_file_dir="./Image/${IMG_FILE}"
+  if [[ -z "$img_file_dir" ]]; then
-  elif [[ ! -f $img_file_dir ]]; then
+    echo -e "${RED}NO TAR.ZST FILE FOUND${RESET}"
-    echo -e "${RED}NO IMG FILE FOUND${RESET}"
     exit 100
   fi
 
   echo "Writing image to ${VG_PATH}${ROOT_LV}..."
 
-  lz4 -dc ${img_file_dir} | partclone.ext4 -r -o "${VG_PATH}${ROOT_LV}"
+  pv "${img_file_dir}" | tar -I zstd -x -C "${MOUNT_PATH}"
-
-  partprobe || true
 
   echo -e "${GREEN}Finished writing image to disk${RESET}"
 }
@@ -188,27 +227,33 @@ get_partition() {
 get_partuuid() {
   local target_part="$1"
 
-  local part_uuid="$(
+  blkid -s UUID -o value "$target_part"
-    lsblk -ln -o PATH,PARTUUID $disk_name | awk -v target_part="$target_part" '$1==target_part {print $2}'
+}
-  )"
 
-  printf "$part_uuid"
+mount_partitions() {
+  echo "Mounting partitions..."
+
+  vgchange -ay $VGROUP
+
+  mkdir -p "${MOUNT_PATH}"
+  mount "${VG_PATH}${ROOT_LV}" $MOUNT_PATH
+
+  mkdir -p "${MOUNT_PATH}/boot"
+  mount $BOOT_PART "${MOUNT_PATH}/boot"
+
+  mkdir -p "${MOUNT_PATH}/boot/efi"
+  mount $EFI_PART "${MOUNT_PATH}/boot/efi"
 }
 
 mount_chroot() {
-  vgchange -ay $VGROUP
-
   echo "Mounting restored system..."
 
-  mkdir -p "${MOUNT_PATH}/boot"
-  mkdir -p "${MOUNT_PATH}/boot/efi"
-
-  mount "${VG_PATH}${ROOT_LV}" $MOUNT_PATH
-  mount $BOOT_PART "${MOUNT_PATH}/boot"
-  mount $EFI_PART "${MOUNT_PATH}/boot/efi"
-
   for i in "${MOUNT_POINTS[@]}"; do mount --bind -m "$i" "${MOUNT_PATH}${i}"; done
 
+  if [[ -d /sys/firmware/efi/efivars ]]; then
+    mount -t efivarfs efivarfs "${MOUNT_PATH}/sys/firmware/efi/efivars"
+  fi
+
   echo -e "${GREEN}Mounts prepared for chroot.${RESET}"
 }
 
@@ -229,13 +274,9 @@ gen_fstab() {
 install_grub() {
   echo "Entering chroot to reinstall GRUB..."
 
-  CHROOT_LINUX_INSTALL="apt install --reinstall -y linux-image-6.1.0-44-amd64"
-  CHROOT_INITRAMFS="update-initramfs -u -k all"
   CHROOT_GRUB_INSTALL="grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=debian"
   CHROOT_GRUB_UPDATE="update-grub"
 
-  chroot_cmd "$CHROOT_LINUX_INSTALL"
-  chroot_cmd "$CHROOT_INITRAMFS"
   chroot_cmd "$CHROOT_GRUB_INSTALL"
   chroot_cmd "$CHROOT_GRUB_UPDATE"
 

Image/PBX.img.lz4

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:0bb94626e3a51df1a374c3123ee3746c6920beeb3172de2c74966dea6b2d475d
-size 7809018129

Image/PBX.img3.lz4

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:0b6c2daf667a6c852437975a217e9dd7e3052f5fee8b391ebc1efa67aaca8001
-size 7783924407

Image/extract_partition.sh

@@ -1,28 +0,0 @@
-#!/bin/bash
-set -e
-
-RED='\e[31m'
-GREEN='\e[32m'
-YELLOW='\e[33m'
-RESET='\e[0m'
-
-img_file="PBX-Test.img"
-
-if [[ $EUID -ne 0 ]]; then
-  echo -e "${RED}You must be root to do this." 1>&2
-  exit 100
-fi
-
-losetup -fP $img_file
-loop_device=$(losetup -l | grep $img_file | cut -d ' ' -f1)
-echo $loop_device
-
-vgchange -a y PBX-vg
-
-lvreduce -L 12G -r PBX-vg/root
-
-partclone.ext4 -c -s /dev/mapper/PBX--vg-root | lz4 -z >./PBX-root.img.lz4
-
-vgchange -a n PBX-vg
-
-losetup -D

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.

fs_extract.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+set -e
+
+RED='\e[31m'
+GREEN='\e[32m'
+YELLOW='\e[33m'
+RESET='\e[0m'
+
+IMG_FILE="PBX-Test.img"
+
+ROOT_LV_PATH="/dev/mapper/PBX--vg-root"
+MOUNT_PATH="/mnt/debian"
+VGROUP="PBX-vg"
+
+main() {
+  root_check
+
+  trap 'echo "Status Code: $?"; cleanup;' EXIT
+
+  losetup -fP $IMG_FILE
+  LOOP_DEVICE=$(losetup -l | grep $IMG_FILE | cut -d ' ' -f1)
+  echo $LOOP_DEVICE
+
+  vgchange -a y $VGROUP
+
+  mkdir -p $MOUNT_PATH
+
+  mount $ROOT_LV_PATH $MOUNT_PATH
+  mount "${LOOP_DEVICE}p2" "$MOUNT_PATH/boot"
+  mount "${LOOP_DEVICE}p1" "$MOUNT_PATH/boot/efi"
+
+  KERNEL_VERSION=$(get_kernel_version)
+
+  tar -I zstd -c -C "${MOUNT_PATH}" --warning=no-file-ignored . | pv >"PBX-Image-${KERNEL_VERSION}.tar.zst"
+}
+
+root_check() {
+  if [[ $EUID -ne 0 ]]; then
+    echo -e "${RED}You must be root to do this." 1>&2
+    exit 77
+  fi
+}
+
+get_kernel_version() {
+  local kernel_file=$(ls -1 "$MOUNT_PATH/boot/vmlinuz-"* 2>/dev/null | head -n1)
+  if [[ -n "$kernel_file" ]]; then
+    basename "$kernel_file" | sed 's/vmlinuz-//'
+  else
+    echo "unknown"
+  fi
+}
+
+cleanup() {
+  if [[ $NO_CLEANUP = true ]]; then
+    echo -e "${YELLOW}No cleanup specified. Make sure to manually clean mounts.${RESET}" 1>&2
+    exit 100
+  fi
+
+  echo "Cleaning Mounts"
+
+  umount -lf "${MOUNT_PATH}/boot/efi" 2>/dev/null || true
+  umount -lf "${MOUNT_PATH}/boot" 2>/dev/null || true
+  umount -lf "${MOUNT_PATH}" 2>/dev/null || true
+
+  vgchange -a n $VGROUP
+  echo -e "${GREEN}Clean.${RESET}"
+  losetup -D
+}
+
+main