OXware Hypervisor Documentation

v2.8.1  Latest GA

OXware is an open-source hypervisor management platform built on KVM/QEMU and Ubuntu/Debian. It provides a complete web-based control plane for virtual machine lifecycle, role-based access, networking, storage, security, monitoring, and an AI assistant — accessible at https://<server-ip>:8006.

Architecture

Browser (SPA — dark theme, PWA, multi-language)
  ├── REST API Flask 3.x + Flask-SocketIO (real-time events)
  ├── JWT auth middleware + RBAC layer
  ├── libvirt / QEMU-KVM (VM lifecycle, XML domain management)
  ├── noVNC WebSocket proxy (browser VNC console)
  ├── nftables (per-VM and global firewall rules)
  └── Nginx (TLS termination, reverse proxy, Let's Encrypt)

Requirements

Installation

Quick Install

# Ubuntu 22.04+ or Debian 12+, requires root
curl -sSL https://oxware.top/install.sh | sudo bash

Installs all dependencies, configures systemd services, generates self-signed TLS cert. Takes 5-10 minutes. Navigate to https://<server-ip>:8006.

Method 1 — Bootable ISO

cd /path/to/oxware-hypervisor/build
sudo bash build-iso.sh
sudo dd if=oxware-2.7.iso of=/dev/sdX bs=4M status=progress conv=fsync

Method 2 — Git Clone

git clone https://github.com/ShinnAsukha/oxware-hypervisor.git /opt/oxware-src
cd /opt/oxware-src && sudo bash install.sh

Method 3 — Debian 12 Supported

sudo apt-get update && sudo apt-get install -y git curl python3-venv
git clone https://github.com/ShinnAsukha/oxware-hypervisor.git /opt/oxware-src
cd /opt/oxware-src && sudo bash install.sh

Repair

sudo bash repair.sh               # restart all services
sudo bash repair.sh --reset-password  # reset admin password

First Login & Setup Wizard

Navigate to https://<server-ip>:8006. Accept the self-signed cert warning (or configure Let's Encrypt in Settings). Setup wizard runs on first boot:

1. Admin password — set the password for the built-in admin account.
2. Hostname — set the server hostname.
3. Network mode — NAT (simpler) or bridge networking.
4. IP pool — optional CIDR block for VM IP allocation.
5. Notifications — optional Telegram bot token or Discord webhook.
6. 2FA — optional TOTP two-factor authentication.

VM Management

Creating a VM

1. Click New VM in the dashboard top-right.
2. Choose a template (OS image) or upload a custom ISO.
3. Configure vCPUs, RAM, disk size, and network interface.
4. Set optional: CPU pinning, memory ballooning, auto-start, tags.
5. Click Create. VM appears in the list within seconds.

Lifecycle Operations

Bulk Operations

Select multiple VMs via checkboxes, then choose from Bulk Actions: Start All, Stop All, Delete Selected, Tag Selected, or Assign to User.

Notes & Credentials Vault

Each VM has a Notes tab and a Credentials Vault for SSH keys, passwords, API tokens. Vault entries are AES-encrypted at rest.

VM Detail Page

• Overview — status, IP, vCPU/RAM/disk, uptime, tags, schedule, assigned users, notes, lifecycle buttons.
• Console — embedded noVNC viewer.
• Hardware — live-edit vCPUs, RAM, disks, network interfaces, CPU pinning.
• Monitoring — real-time CPU%, RAM%, disk IOPS, network tx/rx (60s rolling window).
• Snapshots — create, revert, or delete disk snapshots.
• Firewall — per-VM nftables rules applied immediately.

VM Console

Features: pointer lock (Escape to release), Ctrl+Alt+Del button, fullscreen, clipboard copy/paste. Host shell console gives root PTY on the hypervisor for emergency access.

ESXi / OVA Import & Migration

KVM Live Migration

POST /api/vms/migrate
{
  "vm_id": "myvm",
  "target_host": "192.168.1.20",
  "protocol": "qemu+ssh"
}

Calls virsh migrate --live --persistent. Downtime typically <1 second at final memory sync.

Role-Based Access Control

Assign a vm-user: VM Detail → Overview → Assigned Users → Assign User or Users → Edit User → Assigned VMs. vm-users can start, stop, reboot, and access console of their assigned VMs only.

LDAP / Active Directory

Navigate to Settings → LDAP.

Networking

Network Modes

HAProxy Load Balancer

Navigate to Network → Load Balancer. Changes write to /etc/haproxy/haproxy.cfg and reload gracefully.

Bridge IP Isolation v2.4

cloud-init Static IP v2.4

version: 2
ethernets:
  eth0:
    addresses: [203.0.113.10/24]
    gateway4: 203.0.113.1
    nameservers:
      addresses: [8.8.8.8, 1.1.1.1]

Subnet Calculator v2.4

Available at Network → IPAM. Enter any CIDR to see: network address, broadcast, first/last host, host count, mask, wildcard, IP class, RFC1918 status.

Storage & Snapshots

OXware uses qcow2 as the default disk format. From VM Detail → Hardware → Disks: add, detach, resize disks, view SMART health.

Snapshots: create (instantaneous qcow2 internal), revert (VM must be stopped), delete. Auto-snapshot scheduler at Storage → Snapshot Scheduler.

Backup: Settings → Backup — MinIO/S3-compatible endpoint or local path, per-VM or global schedule.

Security

TOTP Two-Factor Authentication

Navigate to Profile → Security → Enable 2FA, scan QR code, verify. Administrators can force 2FA globally at Settings → Security → Require 2FA.

JWT & Session Security

Short-lived JWT access tokens (15 min default) + refresh tokens (7 days). As of v2.7.0: stored in httpOnly cookies to prevent XSS theft. All state-changing requests require a CSRF token (double-submit pattern).

Audit Log

All user actions recorded in immutable audit log. Navigate to Settings → Audit Log to search and export.

Password Reset File v2.5

# 1. Create reset file (root only, mode 600 required)
printf 'USERNAME=admin\nPASSWORD=new_secure_pass\n' \
  | sudo tee /etc/oxware/.passwd_reset
sudo chmod 600 /etc/oxware/.passwd_reset
# 2. Restart — reset applied on startup, file auto-deleted
sudo systemctl restart oxware

Monitoring

Global Monitoring page shows live metric grid: CPU%, RAM, disk I/O, network I/O. Refreshes every 30 seconds.

Alert rules: Monitoring → Alert Rules. Anomaly detection uses z-score rolling baseline; deviations >2σ trigger alerts.

Network Speedtest

Accessible from Monitoring+ → Ağ Hız Testi. Measures latency (ICMP ping), packet loss, and download throughput to test servers across Turkey, Europe, Americas, and Asia-Pacific.

BGP Tunneling

Configure under Settings → Ağ → BGP.

Backup & SFTP

Configure under Settings → Zamanlama → Yedekleme. Types: disk backup (copy VM disk to local path, optional SFTP transfer) and snapshot (QEMU internal, no downtime).

Disk Format & Wipe

Destination paths resolved via os.path.realpath() and validated against an allowlist to prevent symlink traversal.

Notifications

Configure under Settings → Notifications. Three channels: Telegram (bot token + chat ID), Discord Webhook, Email (SMTP).

Events: alert threshold breached, VM crash, host resource exhaustion, backup failure, cert expiry, 2FA bypass attempt, IDS alert.

AI Assistant (OXY)

Access via AI tab or Ctrl+Shift+A.

• Natural-language VM creation — describe a VM in plain English; OXY creates it.
• Capacity forecasting — analyzes CPU/RAM trends, projects resource exhaustion at 80% and 95% capacity.
• Auto-Scaler — CPU thresholds that trigger vCPU hot-plug or memory balloon adjustments.

Hosting Integration

• DiyoCP Module v2.5 — download from Settings → Integrations → DiyoCP, copy to modules/servers/oxware/.
• WiseCP Module — provision VMs directly from WiseCP billing panel.
• WHMCS Module — install from integrations/whmcs/.
• Terraform Provider — community provider in integrations/terraform/.

Enterprise Features

v2.7.0 brings 27+ datacenter-grade modules to open-source KVM.

Confidential VMs

• AMD SEV / SEV-ES / SEV-SNP / Intel TDX — CPU-enforced memory encryption; hypervisor cannot read guest RAM.
• vTPM 2.0 — per-VM virtual TPM for BitLocker, LUKS2, measured boot.
• UEFI Secure Boot — signed OVMF loader + SMM; blocks unsigned kernels at boot.
• Attestation — launch measurement captured via virsh domlaunchsecinfo (SEV) or TDREPORT (TDX).

Auto-Remediation Runbooks

• Anomaly-driven — fires when z-score detector raises event matching runbook metric regex.
• Step types: notify, shell (timeout-bounded), api_call, vm_action.
• Safety — per-runbook cooldown_sec and max_runs_per_hour. approval: manual forces operator confirmation before execution.
• Audit — every execution appended to /var/lib/oxware/runbook_history.jsonl.

Managed Cluster Federation

• Single control plane — federate multiple OXware controllers into one inventory.
• Parallel health — all members probed concurrently with per-member latency.
• VM inventory — /api/vms aggregated across members; rows carry _member_id, _member_label, _region.
• Roles: leader, follower, observer. TLS verification per member.

Compute & Scheduling

DRS (cluster-wide VM rebalancing), Affinity/Anti-Affinity rules, EVC (CPU masking for cross-generation migration), Maintenance Mode (auto-evacuate), NUMA-aware scheduling + HugePages.

Security & Compliance

SAML/OIDC SSO (Okta, Azure AD, Google) with fail-closed signature verification. SIEM integration (Splunk, Elastic, Wazuh). Session recording. CIS / NIST / PCI-DSS / HIPAA / ISO27001 compliance scanner.

v2.8.1 — Cloud-Native & Hardening

v2.8.1 Latest GA — Five new security patches plus eight new feature modules covering Kubernetes, GitOps, microVMs, SSO presets, audit retention, SBOM, PWA offline, and SSH known-hosts hardening.

Kubernetes CSI Driver

OXware storage pools surface as Kubernetes PersistentVolumes via a CSI 1.8 driver. Provision, snapshot, expand, and delete VMs from the cluster's PVC API. Supported filesystems: ext4, xfs, btrfs.

KubeVirt Bridge

Register a Kubernetes cluster running KubeVirt and have OXware serve as the underlying hypervisor for its VirtualMachine CRs. The bridge translates VMI specs into native libvirt domains.

GitOps Manager

Manifest-driven infra: register a git repository, OXware reconciles VM and network manifests on a schedule. Compatible with ArgoCD and Flux directory layouts (vms/<name>.yaml, networks/<name>.yaml). Optional auto_apply closes the loop; otherwise drift is reported for manual sync.

Firecracker microVM Runtime

Second-tier VM runtime alongside QEMU/KVM. Firecracker microVMs boot in <125 ms with <5 MB host overhead — ideal for serverless, CI runners, and per-request VMs.

OAuth2 Provider Presets

One-click discovery URL builders for the most common identity providers: Keycloak, Authentik, Okta, Microsoft Entra ID, Google Workspace, GitLab. The operator supplies only base URL + client credentials; OXware fills scopes and claim mappings.

Audit-Log Retention Policy

Default policy keeps 90 days of entries per file with a 200 MB hard cap. Tracks audit_chain, runbook_history, bulk_audit. Rotation is on-demand or scheduled; old entries are dropped, not compressed (compress flag planned).

CycloneDX SBOM

Per-release Software Bill of Materials in CycloneDX 1.5 JSON. Includes every installed Python distribution with purl, license, and project URLs. Auto-generated by CI on every push to main and uploaded as a build artifact.

PWA Offline Mode

Panel registers a service worker that pre-caches static assets and last-known /api/vms, /api/hosts, /api/networks responses. When the network drops, the dashboard switches to a read-only fallback view rather than a blank page.

SSH Known-Hosts & First-Contact Approval

Outbound SSH (SFTP backup, ESXi import) used to trust whatever key the peer presented. v2.8.1 ships ssh_known_hosts: a persistent /var/lib/oxware/known_hosts file plus a panel queue of pending fingerprint approvals. Trust-on-first-use is opt-in via OXWARE_SSH_TOFU=1 for migration.

Security Patches (SEC-029..033)

• SEC-029 (HIGH) Safe archive extraction — safe_tar_extract / safe_zip_extract reject path traversal, symlink escape, device-file members. Replaces both tarfile.extractall() sites in app.py (Bandit B202).
• SEC-030 (MEDIUM) DNS rebinding mitigation — security_utils.resolve_safe_host() resolves once, validates against the SSRF block list, returns IP literal for direct connect.
• SEC-031 (MEDIUM) FTP backup target deprecated — ftplib only imported when OXWARE_ENABLE_INSECURE_FTP=1; otherwise _upload_ftp aborts and recommends SFTP (Bandit B321/B402).
• SEC-032 (MEDIUM) SSH known-hosts replaces paramiko.AutoAddPolicy with a persistent known_hosts file and operator approval queue (Bandit B507).
• SEC-033 (LOW) make security runs Bandit + pip-audit; CI publishes the SBOM and audit results as artifacts.

Six-Language Panel + CI Gate

French (FR) joins TR, EN, ES, DE, ZH for a total of six interface languages with full parity. Each lang dict carries 2200+ entries covering every UI string. A CI workflow (.github/workflows/i18n-and-sbom.yml) fails the build if any untranslated TR string appears in HTML body or JS literals. A pre-commit hook auto-runs the i18n pipeline whenever index.html is staged.

v2.8.1 — AI & Advanced

v2.8.1 Latest GA — Six innovations not found in vSphere/Proxmox/Nutanix, plus a vDS-class network panel and quality-of-life additions. Every new string is translated across all five languages.

VM Flight Recorder + AI Post-Mortem

An aircraft-style black box for every VM. It assembles the last N minutes of a VM's metric history (from the existing perf_history collector — no extra sampling load) and its events into a single timeline. On demand, the configured AI agent generates a root-cause post-mortem (e.g. "CPU spike → memory pressure → OOM → kernel panic") with prevention advice. Open it from the VM detail page → Kara Kutu. API: GET /api/v2/vms/<id>/flightrec, POST /api/v2/vms/<id>/post-mortem.

Telegram ChatOps (two-way + AI)

Manage the datacenter from Telegram: ask "why is vm-3 slow?", "create a new ubuntu VM", "cluster status" and the AI answers and acts through the same tool layer the panel uses. Competitors only push one-way alerts. Disabled by default; whitelisted chat IDs only; mutating operations are opt-in (otherwise read-mostly operator authority). Uses the Telegram bot token from Notifications. Configure under Settings → ChatOps.

What-If Capacity Simulator

"What happens if I add 10 VMs with 2 vCPU / 4 GB each?" — projects the impact on CPU, RAM, power, cost and CO₂ before you act, from live usage + host capacity + the Green Mode power profile. A pre-flight sandbox, not just a recommendation. VMs → What-If.

Live Heat Map

Every VM's load at a glance as a colour grid (green→red by CPU). Spot busy VMs instantly and click through to detail. VMs → Isı Haritası.

Cluster Time-Machine

Point-in-time snapshots of the whole cluster configuration (VMs, networks, DVS, vApps) plus a git-style diff between any two points — see exactly what changed and when. Restore is advisory (shows the delta to re-apply). Settings → Zaman Makinesi.

Distributed vSwitch (vDS-class)

A VMware vDS-style panel: a cluster-wide virtual switch with VLAN-tagged port groups, uplink/NIC-teaming (active-backup / balance-slb / balance-tcp / LACP), VXLAN spanning across nodes, and a one-screen visual topology (Control plane → DVS → port groups → uplinks → physical trunk). Networks → DVS.

Also new on the network side: SDN VXLAN overlays, a built-in L4 load balancer (isolated HAProxy instance), federation mTLS identity, and a Network Mode & IP tab that detects NAT/bridge/routed networks and surfaces each VM's real guest-agent IP (fixing the bridge/DHCP "wrong IP" problem).

Golden Images · OVA · vApp · QoS · more

Golden-image marketplace (one-click cloud-init Ubuntu/Debian/Rocky/Alma), OVA/OVF export, vApp boot orchestration (ordered start/stop with delays), per-VM disk I/O QoS, snapshot-chain analysis, Vault→VM secret injection, measured-boot attestation, AI runbook generator (natural language → automation rule), AI Ops Insights, carbon/energy report, live VM thumbnails, firmware boot splash, an onboarding tour, 14 selectable themes, and AI tool gating (sensitive queries restricted to the primary administrator).

Plugin SDK

Plugins are single .py files loaded at runtime. No restart required. Three optional hooks:

• register_routes(app) — adds Flask routes.
• on_vm_event(event) — VM lifecycle events: vm.created, vm.started, vm.stopped, vm.deleted.
• on_load() / on_unload() — called when plugin is enabled/disabled.

Example Plugin

PLUGIN_META = {
    "id": "my-plugin",
    "name": "My Plugin",
    "version": "1.0",
    "author": "Your Name",
    "description": "Adds /api/plugin/hello endpoint.",
    "api_version": "1.0",
}

def register_routes(app):
    @app.route("/api/plugin/hello")
    def _hello():
        from flask import jsonify
        return jsonify({"message": "Hello from my plugin!"})

def on_vm_event(event):
    pass

Security Validator

AST scan before upload. Blocked: os/subprocess shell invocation, eval/exec/__import__. Direct socket use flagged as warning.

API Reference

Authentication

# 1. Obtain token
curl -k -X POST https://host:8006/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpass"}'

# 2. Use token
curl -k https://host:8006/api/vms \
  -H "Authorization: Bearer <token>"

Virtual Machines

Users & RBAC

Networking

Storage

Monitoring & Alerts

Provisioning & ISO

Enterprise — Compute (v2.5+)

Enterprise — Security (v2.5+)

Confidential VMs (v2.7.0)

Runbooks (v2.7.0)

Federation (v2.7.0)

Bulk Operations (v2.7.0)

Multi-Region / Cloud Burst / OAuth2 (v2.7.0)

Green Mode (v2.6.2)

Configuration

Main config: /opt/oxware/config.ini. Requires sudo systemctl restart oxware after changes.

Troubleshooting

Service won't start

sudo journalctl -u oxware -n 100 --no-pager
sudo systemctl status oxware

KVM not available

sudo apt-get install -y cpu-checker && kvm-ok
# Enable VT-x / SVM in BIOS if unavailable

Can't connect to panel

• Verify port 8006 is open in the firewall.
• Run sudo bash repair.sh to restart all services.
• Accept the self-signed certificate warning in your browser.

Reset admin password

sudo bash repair.sh --reset-password

Lost credentials entirely

printf 'USERNAME=admin\nPASSWORD=new_secure_pass\n' \
  | sudo tee /etc/oxware/.passwd_reset
sudo chmod 600 /etc/oxware/.passwd_reset
sudo systemctl restart oxware

Still stuck?

Open an issue on GitHub Issues or ask in Discord. Include OS version, OXware version (cat /opt/oxware/version), and relevant journal output.