girginos
Documentation · v0.9 beta

Everything to run girginos in production.

Install the agent, promote a Center, wire up HA with DRBD, drive the REST API or thegirginosvmCLI. Every command, endpoint and env var, in one place.

Quick installREST API reference
home

Welcome

Welcome to the girginos documentation. This guide walks you from a fresh AlmaLinux host to a multi-node cluster with synchronous DRBD replication, live migration and VM-level high availability — using only two binaries and a single installer.

Start here
Quick install →

One-liner installer with 3 roles.

Operate
CLI reference →

Every girginosvm subcommand.

Resilience
HA + DRBD →

~1.5 s failover, RPO = 0.

What you will learn

  • › Install Node + Center, join a cluster.
  • › Drive VMs through CLI and REST.
  • › Wire up IPAM pools and routed bridges.
  • › Promote VMs to DRBD-backed HA.
  • › Tune VDS plans (NUMA, hugepages, vhost).
  • › Back up, self-update, troubleshoot.
New here? Follow Quick install, then CLI reference, then HA + DRBD. Each section is self-contained — jump around freely.
overview

Overview

girginos is a self-hosted virtualization platform built around two Go binaries: girginosvm (per-node agent + local operator panel on port 1996) andgirginosvm-center (cluster control plane on port 1997). Both share the same embedded web UI; the menu adapts to scope.

Node agent
:1996

libvirt/QEMU, IPAM, DRBD, local panel.

Center
:1997

Inventory, HA engine, scheduler, alerts.

Tenant portal
:1998

End-customer self-service portal.

The platform is fully closed-source under an enterprise license. Heartbeat lives athttps://girginos.net/api/public/license/verify and reports counters only — never PII.
install

Quick install

One-liner installer. Aşağıdaki formu doldur, sana özel kurulum komutu otomatik oluşur. Center (control plane) tek komutla kurulur; node'lar daha sonra Center panelinden eklenir.

Install command builder
curl -fsSL https://update.girginos.net/install.sh -o /tmp/i.sh && \
  GIRGINOSVM_CENTER_PUBLIC_URL=https://center.yourdomain.com:1997 \
  bash /tmp/i.sh --mode=center \
    --admin-email='admin@yourdomain.com' \
    --admin-password='ChangeMe-StrongPass!' \
    --non-interactive

System requirements

RoleOSRAMCPUDisk
Center (control plane)AlmaLinux 108 GB4 cores50 GB SSD
Node (hypervisor)AlmaLinux 1016 GB (min)8 cores (min)240 GB SSD (min)

İşletim sistemi olarak AlmaLinux 10 destekleniyor (RHEL 10 uyumlu). Node değerleri minimumdur — üzerinde çalıştıracağınız VM'lerin toplam vCPU / RAM / disk ihtiyacına göre ölçeklendirin.

Required ports

PortDirectionPurpose
1996/tcpNode ← operatorLocal panel + REST API (TLS)
1997/tcpCenter ← node/operatorCluster panel + control plane (TLS)
1998/tcpTenant ← end-userCustomer self-service portal
7789/tcpNode ↔ NodeDRBD9 replication
49152-49215/tcpNode ↔ NodeLive-migration NBD streams
cli

CLI reference

The girginosvm binary is both daemon and admin CLI. Center adds girginosvm-center.

Node — VM lifecycle

# List, inspect
girginosvm vm list
girginosvm vm show <vm-id>

# Create from image catalog
girginosvm vm create --name web01 --image almalinux-10 \
  --vcpu 4 --memory 8192 --disk 80 --network br-vsw

# Power control
girginosvm vm start    <vm-id>
girginosvm vm stop     <vm-id> --graceful
girginosvm vm reboot   <vm-id>
girginosvm vm destroy  <vm-id> --purge

# Snapshots
girginosvm vm snapshot create <vm-id> --name pre-upgrade
girginosvm vm snapshot revert <vm-id> --name pre-upgrade

# Live migration
girginosvm vm migrate <vm-id> --target node-b.local --detect-zeroes

Networking & IPAM

girginosvm net list
girginosvm net pool add --name pub-eu --cidr 49.12.158.176/29 \
  --gateway 49.12.158.177 --vlan 4001 --bridge br-vsw

girginosvm ipam leases
girginosvm ipam sync                 # reconcile reservations
girginosvm ipam repair --dry-run
girginosvm net arp-flush --vm <id>   # cluster-wide GARP burst

HA & DRBD

# Promote single-disk VM to HA storage
girginosvm ha prepare <vm-id>

# Maintenance
girginosvm ha pause   <vm-id>
girginosvm ha resume  <vm-id>
girginosvm ha unflap  <vm-id>        # clear anti-flap hold
girginosvm ha drill   <vm-id>        # read-only failover dry-run

# Inspect
girginosvm ha history --limit 200
girginosvm ha summary  --window 1h

Center promote / membership

girginosvm center promote --bind 0.0.0.0:1997 \
  --public-url https://center.example.net:1997 \
  --admin-password "$ADMIN_PW"
girginosvm center status
girginosvm center demote --confirm

# From a node, join a Center
girginosvm membership join \
  --center https://center.example.net:1997 \
  --token  ops-xxxxxxxx
girginosvm membership drain   # graceful exit for rolling reboot
girginosvm membership status

Images & cloud-init

# Image catalog (qcow2 templates pulled from update.girginos.net)
girginosvm image list
girginosvm image pull almalinux-10
girginosvm image rm   debian-12

# Per-VM cloud-init draft (applied on next rebuild)
girginosvm vm cloud-init get  <vm-id>
girginosvm vm cloud-init set  <vm-id> --file user-data.yaml
girginosvm vm rebuild         <vm-id> --confirm

# Inject SSH keys into a running VM
girginosvm vm inject-ssh-key  <vm-id> --key-file ~/.ssh/id_ed25519.pub

# Network reset (rewrite netplan/NM/ifcfg from IPAM truth)
girginosvm vm network-reset   <vm-id> --snapshot

Firewall (per-VM nftables)

girginosvm fw show   <vm-id>
girginosvm fw set    <vm-id> --file rules.json
girginosvm fw apply  <vm-id>
girginosvm fw preset <vm-id> --name web      # web / db / ssh-only / locked

Modules & licensing

girginosvm module list
girginosvm module enable   ha-vm
girginosvm module disable  vpc
girginosvm module license  ha-vm --file ha-vm.lic
girginosvm module license  ha-vm --remove
girginosvm module audit    --limit 50

Storage & DRBD

girginosvm storage pool list
girginosvm storage pool add  --name fast --path /var/lib/girginosvm/storage
girginosvm storage health                       # SMART + statfs + dmesg I/O scan
girginosvm storage disk list

# DRBD inspection / recovery
girginosvm drbd status
girginosvm drbd promote   <resource> --force
girginosvm drbd recover                         # boot-time auto-resolve

Backup, update, diagnostics

# Center backup (config + DB + secrets → local / FTP / SFTP / S3 / WebDAV / GDrive)
girginosvm-center backup run     --destination s3-prod
girginosvm-center backup list
girginosvm-center restore        /var/backups/center-2026-05-18.tar.zst

# Self-update (pre-flight, mandatory backup, rollback)
girginosvm update check
girginosvm update apply   --backup
girginosvm update rollback

# Diagnostics
girginosvm doctor                                # full health bundle
girginosvm quorum                                # witness reachability
girginosvm run-script ovmf-refresh               # encrypted scriptvault entry
/usr/local/bin/error-correlate.sh --since "1h ago"

DCIM, ARP guard, scheduler

# DCIM (sites / rooms / rows / racks)
girginosvm dcim site   list
girginosvm dcim rack   add --site dc1 --row r1 --name R03 --units 47

# ARP guard — pin authoritative gateway MAC per bridge
girginosvm arpguard status
girginosvm arpguard pin    --bridge br-routed --ip 49.12.158.177 --mac aa:bb:cc:dd:ee:ff
girginosvm arpguard unpin  --bridge br-routed --ip 49.12.158.177

# Per-VM power schedules (5-field cron, UTC)
girginosvm schedule list <vm-id>
girginosvm schedule add  <vm-id> --action stop --cron "0 22 * * *"

# Customer / project / quota
girginosvm customer list
girginosvm customer create --name acme --email ops@acme.io
girginosvm project  list   --customer acme
girginosvm quota    set    --customer acme --vcpu 64 --memory 256GiB --disk 4TiB
modules

Modules & licensing

Features are toggled per cluster through the Module Catalog. License envelopes are Ed25519-signed and verified offline by the Center.

# List modules
curl -sS -H "Authorization: Bearer $TOKEN" \
  https://center.example.net:1997/v1/modules | jq

# Toggle
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  https://center.example.net:1997/v1/modules/ha-vm/enable

# Install signed license
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  --data-binary @ha-vm.lic \
  https://center.example.net:1997/v1/modules/ha-vm/license

# Audit log
curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://center.example.net:1997/v1/modules/audit?limit=50" | jq
Module keyWhat it unlocks
ha-vmVM-level high availability + DRBD orchestration
live-migrateOnline migration with detect-zeroes optimisation
ipamCluster-wide IPAM with peer-aware leases
dcimSites, rooms, racks, cable topology
vpcVXLAN tenant networks (preview)
converterP2V / V2V import wizard (preview)
api

REST API

Bearer-authenticated JSON API. Use Idempotency-Key on POSTs to retry safely. Full endpoint catalog lives on the API page.

curl -sS -H "Authorization: Bearer $TOKEN" \
  https://center.example.net:1997/v1/admin/inventory | jq

curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"web01","image":"almalinux-10","vcpu":4,"memory_mb":8192}' \
  https://node-a.local:1996/v1/vms
ha

High availability (HA + DRBD)

VM-level HA combines DRBD9 synchronous replication with an active TCP probe, witness quorum and an anti-flap budget. Failover orchestration completes in ~1.5 s; guest downtime depends on boot.

Promote to HA

# 1. Snapshot + stop + DRBD create + qcow2→raw + XML rewrite
girginosvm ha prepare <vm-id>

# 2. Verify replication is UpToDate on both peers
drbdadm status

# 3. (Optional) Drill a failover from Center
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  https://center.example.net:1997/v1/admin/ha/vm/<vm-id>/drill | jq

Useful env vars

VariableDefaultPurpose
GIRGINOSVM_HA_VM_LIVEfalseMaster switch for live failover
GIRGINOSVM_STALE_AFTER20sHeartbeat staleness threshold
GIRGINOSVM_HA_FLAP_THRESHOLD3Triggers within window to engage hold
GIRGINOSVM_HA_FLAP_COOLDOWN1hAnti-flap maintenance hold duration
GIRGINOSVM_QUORUM_REQUIREDtrueBlock promote if Center witness is gone
GIRGINOSVM_HA_GLOBAL_MAX_PER_MIN10Cluster-wide failover rate limit
DRBD live-migrate requires allow-two-primaries yes in the resource netblock, or QEMU on the target will exit with "process exited while connecting to monitor".
network

Networking & IPAM

NAT (libvirt default) and routed bridges (Hetzner / OVH style) both work. IPAM is the single source of truth for pool allocation; IPPoolPickFree unions local leases with peer-node bound leases to prevent duplicate IPs across the cluster.

# Example: routed /29 subnet on br-routed
- name: pub-eu
  cidr: 188.40.14.232/29
  gateway: 188.40.14.233
  bridge: br-routed
  vlan: 0
  range:
    start: 188.40.14.234
    end:   188.40.14.238
Routed pools require a gateway inside the CIDR — otherwise install/reinstall leaves the VM with a broken default route.
storage

Storage layout & permissions

QEMU runs as the qemu user. The agent enforces directory + file ownership automatically; if you drop files in manually, replicate these modes.

PathOwnerMode
/var/lib/girginosvmroot:root0751
/var/lib/girginosvm/storageroot:qemu0755
…/storage/*.qcow2root:qemu0640
…/iso/*root:qemu0644
vds

VDS performance tuning

The vds-* plan family auto-enables CPU pinning, NUMA-strict placement, 1 GiB hugepages (≥ 64 GiB RAM), guest NUMA topology (≥ 8 vCPU + 16 GiB) and backend-aware disk IO (io_uring for qcow2, native for DRBD/LVM). All knobs are env-tunable.

VariableDefaultPurpose
GIRGINOSVM_VDS_HUGEPAGE_AUTO_MIB65536Memory ≥ this → enable 1 GiB hugepages (0 = off)
GIRGINOSVM_VDS_NUMA_NODES_AUTO2Guest NUMA cell count (0 = off)
GIRGINOSVM_VDS_DISK_IOautoForce <CMD>io_uring</CMD> or <CMD>native</CMD>
GIRGINOSVM_NET_VHOST1Enable vhost-net offload on virtio NICs
GIRGINOSVM_NET_RX_QUEUE_SIZE1024RX queue (256/512/1024)
auth

Authentication & tokens

Center supports both email/password sessions (8 h TTL by default, refreshable) and static operator tokens. Nodes always accept the cluster bearer token.

# Issue session
curl -sS -X POST -H "Content-Type: application/json" \
  -d '{"email":"admin@local","password":"$PW"}' \
  https://center.example.net:1997/v1/auth/login | jq -r .token

# Refresh (rotation, ≤5min before expiry)
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  https://center.example.net:1997/v1/auth/refresh | jq
When advertising the panel from a node, GIRGINOSVM_ADVERTISE_PANEL_TOKEN MUST equalGIRGINOSVM_TOKEN (admin bearer). The installer wires this automatically.
ops

Day-2 operations

Backups

# Center self-backup (config + DB + secrets)
girginosvm-center backup run --destination s3-prod
girginosvm-center backup list

# Restore (auto pre-restore snapshot, path-traversal guarded)
girginosvm-center restore /var/backups/center-2026-05-18.tar.zst

Self-update

girginosvm update check
girginosvm update apply --backup   # mandatory backup + integrity scan
girginosvm update rollback         # restore previous binary

Healthcheck timer

# Detect artifact drift between Center bundle and installed binary
/usr/local/bin/worker-artifact-healthcheck.sh --check --json

# Auto-resync (run by systemd timer every 15min)
/usr/local/bin/worker-artifact-healthcheck.sh --sync
troubleshoot

Troubleshooting

Correlate logs to known root causes

# Walk journal + /var/log + Center events, match against signature catalog
/usr/local/bin/error-correlate.sh --since "1h ago"
# Exit codes: 0 clean, 1 error-class, 2 critical-class

DRBD vermagic mismatch after kernel upgrade

# Symptom: ha-prepare drbd_create exits 10, "Invalid argument" on drbd_transport_tcp
rmmod drbd_transport_tcp drbd
modprobe drbd_transport_tcp
systemctl restart girginosvm

HA flap hold engaged

# Inspect, then clear after fixing root cause
curl -sS -H "Authorization: Bearer $TOKEN" \
  https://center.example.net:1997/v1/admin/ha/vm/flaps | jq
girginosvm ha unflap <vm-id>
Never run pkill -STOP qemu-kvm for crash simulation — the pattern matches every VM on the host. Use targeted pkill -STOP -f "guest=<vm>" and always pair with -CONT.