# 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:**
```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.