proxmox-tools/README.md

# Proxmox Cloud Image Tool

Tool untuk membuat **template** di Proxmox menggunakan cloud image (Ubuntu, Debian, CentOS, dll) dengan Golang.

## Features

- Download cloud image dari URL **atau gunakan local file**
- Customize image (resize disk, inject SSH key)
- Otomatis create template di Proxmox
- Support konfigurasi via CLI flags atau YAML file
- Progress bar untuk download
- **QEMU Guest Agent support** (auto-enable)
- **Firewall configuration** (enable/disable + custom rules)
- **Batch mode** untuk create multiple templates sekaligus

## Tools

### 1. Linux Cloud Images (Main Tool)
Tool utama untuk Linux cloud images (Ubuntu, Debian, CentOS, Rocky, dll).

📁 **Location**: Root directory
📖 **Docs**: [README.md](README.md) (this file)

### 2. Windows Cloud Images
Tool terpisah untuk Windows cloud images (Windows Server, Windows 11).

📁 **Location**: `windows-tools/`
📖 **Docs**: [windows-tools/README.md](windows-tools/README.md)

**Key Differences:**
- Windows: UEFI + TPM 2.0 + Secure Boot
- Linux: BIOS/UEFI flexible
- Windows: Requires qcow2 image from [cloudbase/windows-imaging-tools](https://github.com/cloudbase/windows-imaging-tools)
- Linux: Download langsung dari official repos

## Requirements

- Go 1.19+
- SSH access ke Proxmox host
- `qemu-img` dan `virt-customize` (libguestfs-tools)

Install dependencies di Ubuntu/Debian:
```bash
sudo apt install qemu-utils libguestfs-tools
```

## Installation

### Quick Install (Recommended):

```bash
git clone <repo-url>
cd cloud-image
sudo ./install.sh
```

Installer akan otomatis:
- Install dependencies (qemu-utils, libguestfs-tools)
- Build binary
- Install ke `/usr/local/bin`

### Manual Build:

```bash
git clone <repo-url>
cd cloud-image
go build -o proxmox-cloud-image
sudo cp proxmox-cloud-image /usr/local/bin/
sudo chmod +x /usr/local/bin/proxmox-cloud-image
```

### Uninstall:

```bash
cd cloud-image
sudo ./uninstall.sh
```

Setelah install, bisa langsung dipanggil dari mana aja:
```bash
proxmox-cloud-image -h
```

### Windows (WSL2):

```bash
# Install WSL2 Ubuntu
wsl --install

# Masuk ke WSL
wsl

# Install dependencies
sudo apt update
sudo apt install qemu-utils libguestfs-tools golang-go

# Clone dan install
git clone <repo-url>
cd cloud-image
sudo ./install.sh
```

### Docker (Cross-platform):

Build image:
```bash
docker build -t proxmox-cloud-image .
```

Jalankan:
```bash
docker run --rm -v $(pwd)/configs:/workspace proxmox-cloud-image -config /workspace/config.yaml
```

Atau buat alias:
```bash
alias proxmox-cloud-image='docker run --rm -v $(pwd):/workspace proxmox-cloud-image'
proxmox-cloud-image -h
```

## Usage

### Menggunakan URL (download):

```bash
proxmox-cloud-image \
  -image-url "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -vm-id 9000 \
  -proxmox-host "192.168.1.100" \
  -proxmox-user "root@pam" \
  -storage "local-lvm" \
  -memory 2048 \
  -cores 2 \
  -disk-size "20G" \
  -bridge "vmbr0" \
  -ssh-key "/root/.ssh/id_rsa.pub" \
  -guest-agent \
  -firewall
```

### Menggunakan local file:

```bash
proxmox-cloud-image \
  -image-url "/path/to/ubuntu-22.04-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -vm-id 9000 \
  -proxmox-host "192.168.1.100" \
  -storage "local-lvm" \
  -guest-agent
```

### Auto-find VM ID (mulai dari 10000):

```bash
proxmox-cloud-image \
  -image-url "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -proxmox-host "192.168.1.100" \
  -guest-agent
```

### Dengan VLAN:

```bash
proxmox-cloud-image \
  -image-url "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" \
  -vm-name "ubuntu-template" \
  -vm-id 9000 \
  -proxmox-host "192.168.1.100" \
  -bridge "vmbr0" \
  -vlan-tag 100 \
  -guest-agent \
  -firewall
```

### Menggunakan config file:

```bash
proxmox-cloud-image -config config.yaml
```

Contoh `config.yaml` dengan URL:
```yaml
image_url: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
vm_name: "ubuntu-template"
vm_id: 0
storage: "local-lvm"
memory: 2048
cores: 2
disk_size: "20G"
bridge: "vmbr0"
vlan_tag: 100
ssh_key: "/root/.ssh/id_rsa.pub"
proxmox_host: "192.168.1.100"
proxmox_user: "root@pam"
proxmox_pass: ""
guest_agent: true
firewall: true
firewall_rules:
  - type: in
    action: accept
    protocol: tcp
    dport: "22"
    comment: "SSH"
  - type: in
    action: accept
    protocol: tcp
    dport: "80,443"
    comment: "HTTP/HTTPS"
```

Contoh `config.yaml` dengan local file:
```yaml
image_url: "/home/user/images/ubuntu-22.04-server-cloudimg-amd64.img"
vm_name: "ubuntu-template"
vm_id: 0
storage: "local-lvm"
memory: 2048
cores: 2
disk_size: "20G"
bridge: "vmbr0"
ssh_key: "/root/.ssh/id_rsa.pub"
proxmox_host: "192.168.1.100"
proxmox_user: "root@pam"
guest_agent: true
firewall: false
```

### Batch mode (multiple templates):

Buat file batch (contoh: `batch.txt`) dengan list config files:
```
# Ubuntu templates
configs/ubuntu-22.04.yaml
configs/ubuntu-20.04.yaml

# Debian templates
configs/debian-12.yaml
configs/debian-11.yaml
```

Jalankan batch:
```bash
proxmox-cloud-image -batch batch.txt
```

**Features:**
- Process multiple config files sekaligus
- Max 3 concurrent jobs (parallel)
- Auto-skip lines yang kosong atau comment (#)
- Summary report di akhir

## Cloud Image URLs

### Ubuntu
- Ubuntu 22.04 (Jammy): `https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img`
- Ubuntu 20.04 (Focal): `https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img`

### Debian
- Debian 12 (Bookworm): `https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2`
- Debian 11 (Bullseye): `https://cloud.debian.org/images/cloud/bullseye/latest/debian-11-generic-amd64.qcow2`

### CentOS Stream
- CentOS Stream 9: `https://cloud.centos.org/centos/9-stream/x86_64/images/CentOS-Stream-GenericCloud-9-latest.x86_64.qcow2`

## Flags

| Flag | Default | Description |
|------|---------|-------------|
| `-config` | - | Path ke config file (YAML) |
| `-image-url` | - | URL cloud image (required) |
| `-vm-name` | cloud-vm | Nama template |
| `-vm-id` | 0 | Template ID (0 = auto-find dari 10000+) |
| `-storage` | auto-detect | Nama storage Proxmox (auto-detect jika kosong) |
| `-memory` | 2048 | Memory dalam MB |
| `-cores` | 2 | Jumlah CPU cores |
| `-disk-size` | 20G | Ukuran disk |
| `-bridge` | vmbr0 | Network bridge |
| `-vlan-tag` | 0 | VLAN tag (0 = no VLAN) |
| `-guest-agent` | false | Enable QEMU guest agent |
| `-firewall` | false | Enable firewall |
| `-ssh-key` | - | Path ke SSH public key |
| `-proxmox-host` | - | IP/hostname Proxmox (required) |
| `-proxmox-user` | root@pam | Proxmox user |
| `-proxmox-pass` | - | Proxmox password |
| `-list-storage` | - | List semua storage yang tersedia |
| `-ls` | - | Shorthand untuk `-list-storage` |

## How It Works

1. **Prepare image** (download dari URL atau copy dari local file)
2. Customize image:
   - Resize disk (jika di-specify)
   - Inject SSH key (jika ada)
   - **Install qemu-guest-agent package** (jika guest-agent enabled)
3. Upload image ke Proxmox host via SCP
4. Create VM menggunakan `qm` commands
5. Import disk dan configure VM
6. Setup cloud-init
7. **Enable QEMU Guest Agent** (jika di-enable)
8. **Enable Proxmox firewall** (jika di-enable)
9. **Configure firewall rules** (jika ada rules yang di-define)
10. **Convert VM menjadi template** dengan `qm template`

## QEMU Guest Agent

QEMU Guest Agent adalah service yang berjalan di guest OS untuk:
- IP address discovery
- Graceful shutdown/reboot
- File system freeze/thaw
- Time synchronization

**Tool ini akan otomatis install qemu-guest-agent package** ke dalam image menggunakan `virt-customize` sebelum upload ke Proxmox.

Enable dengan flag `-guest-agent` atau di config file:
```yaml
guest_agent: true
```

**Note**: Guest agent di-enable by default. Package akan di-install otomatis saat customize image.

## Proxmox Firewall

Proxmox firewall bisa di-enable untuk template dengan flag `-firewall` atau di config file:
```yaml
firewall: true
```

### Firewall Rules

Kamu juga bisa define firewall rules langsung di config file:

```yaml
firewall: true
firewall_rules:
  - type: in
    action: accept
    protocol: tcp
    dport: "22"
    comment: "SSH"
  - type: in
    action: accept
    protocol: tcp
    dport: "80,443"
    comment: "HTTP/HTTPS"
  - type: in
    action: accept
    protocol: icmp
    comment: "ICMP/Ping"
  - type: in
    action: drop
    comment: "Drop all other incoming"
```

**Firewall Rule Fields:**
- `type`: `in` (incoming) atau `out` (outgoing)
- `action`: `accept`, `drop`, atau `reject`
- `protocol`: `tcp`, `udp`, `icmp`, dll (optional)
- `dport`: destination port atau port range, contoh: `22`, `80,443`, `8000:9000` (optional)
- `sport`: source port (optional)
- `source`: source IP/CIDR, contoh: `192.168.1.0/24` (optional)
- `dest`: destination IP/CIDR (optional)
- `comment`: komentar untuk rule (optional)

Rules akan ditulis ke `/etc/pve/firewall/<vmid>.fw` di Proxmox host.

Firewall akan di-enable di network interface VM.

## Clone Template

Setelah template dibuat, kamu bisa clone untuk membuat VM baru:

```bash
qm clone 9000 100 --name my-vm --full
qm set 100 --ipconfig0 ip=192.168.1.100/24,gw=192.168.1.1
qm set 100 --sshkeys /root/.ssh/id_rsa.pub
qm start 100
```

## Notes

- Tool ini menggunakan SSH untuk koneksi ke Proxmox
- Pastikan SSH key sudah di-setup untuk passwordless login
- Image akan di-download ke `/tmp` dan di-upload ke Proxmox
- Template tidak bisa di-start, harus di-clone dulu
- QEMU Guest Agent akan otomatis ter-install di guest OS yang support

## License

MIT License

Copyright (c) 2025 Othman Hendy Suseno

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.