PBX-Image-Script/README.md

PBX Image Script

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:

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:

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:

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

./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.

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.