OXware Hypervisor Documentation

Version 2.6.3 — Latest (full enterprise roadmap)

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 — all accessible from a dark-themed single-page application 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 (recommended)

One command installs OXware and all dependencies on Ubuntu 22.04+ or Debian 12+. Requires root.

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

The script detects your distribution, installs all dependencies (KVM, libvirt, qemu-utils, noVNC, Nginx, Python packages), configures systemd services, and generates a self-signed TLS certificate. Takes 5–10 minutes depending on network speed. After completion, navigate to https://<server-ip>:8006.

Method 1 — Bootable ISO (recommended for bare-metal)

The ISO method installs a complete, pre-configured Ubuntu 22.04 LTS base with OXware baked in. The Calamares graphical installer guides disk partitioning, locale, and network setup.

# Build the ISO on any Ubuntu 22.04 machine with 8 GB+ free space
cd /path/to/oxware-hypervisor/build
sudo bash build-iso.sh

# Flash to USB (replace /dev/sdX with your USB device)
sudo dd if=oxware-2.3.iso of=/dev/sdX bs=4M status=progress conv=fsync

Boot the target machine from USB and follow the Calamares installer. OXware services start automatically on first boot.

Method 2 — Manual install (git clone) on Ubuntu 22.04 LTS

Alternative if you prefer to inspect the source before running, or need to use a specific branch.

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

The script installs all dependencies (KVM, libvirt, qemu-utils, noVNC, Nginx, Python packages), configures systemd services, and generates a self-signed TLS certificate. The process takes 5–10 minutes depending on network speed.

Method 3 — Script on existing Debian 12 (Bookworm) Supported

OXware fully supports Debian 12 Bookworm. The installer auto-detects the distribution and adjusts package names accordingly.

# Gerekli ön paketler
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

# KVM doğrulama (Debian 12)
sudo apt-get install -y cpu-checker
kvm-ok
# "KVM acceleration can be used" görünmezse BIOS'ta VT-x / SVM'i aktif edin

Repair

# Restart all OXware services and repair broken symlinks
sudo bash repair.sh

# Reset the admin account password
sudo bash repair.sh --reset-password

First Login & Setup Wizard

After installation, navigate to https://<server-ip>:8006. Accept the self-signed certificate warning (or skip it by configuring Let's Encrypt in Settings → SSL).

The setup wizard runs automatically on first boot and walks you through:

1. Admin password — set the password for the built-in admin account.
2. Hostname — set the server hostname (used in notifications and the UI title).
3. Network mode — choose NAT (simpler) or bridge networking (gives VMs routable IPs).
4. IP pool — optionally define the first CIDR block for VM IP allocation.
5. Notifications — optionally configure a Telegram bot token or Discord webhook.
6. 2FA — optionally enable TOTP two-factor authentication for the admin account immediately.

VM Management

The main dashboard lists all virtual machines in a table with live status badges. From here you can perform single-VM and bulk operations.

Creating a VM

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

Lifecycle Operations

Bulk Operations

Select multiple VMs using the checkboxes in the list, then choose an action from the Bulk Actions dropdown: Start All, Stop All, Delete Selected, Tag Selected, or Assign to User.

VM Scheduling

From VM Detail → Overview → Schedule, set automatic start and stop times using a cron-like picker. Useful for dev/test environments that should only run during business hours.

VM Tagging & Grouping

Tags are free-form labels (e.g., production, web, backup). The dashboard can be filtered and grouped by tag. Tags are also used by alert rules to target subsets of VMs.

Notes & Credentials Vault

Each VM has a Notes tab for free-text documentation and a Credentials Vault for storing SSH keys, passwords, and API tokens associated with that VM. Vault entries are AES-encrypted at rest.

ESXi / OVA Import & Migration

OXware can import virtual machines from VMware ESXi, Proxmox, VirtualBox, and any other hypervisor that can export to standard formats. Disk conversion is handled automatically using qemu-img.

Supported Formats

Method 1 — Web UI (OVA Import button) Updated v2.4

1. Go to Virtual Machines dashboard.
2. Click ↑ OVA Import button (top-right area, next to New VM).
3. Select your .ova, .vmdk, or supported file.
4. Select the target libvirt network from the dropdown (default, bridge, custom).
5. OXware extracts the archive, converts the disk to qcow2, auto-deduplicates the VM name on conflict, defines the VM in libvirt connected to the chosen network.

Firmware (UEFI/BIOS), CPU, and RAM are auto-detected from VMX/OVF metadata when available. Adjust from VM Detail → Hardware after import.

Method 2 — SFTP Browser (ESXi direct) New v2.4

1. Go to Settings → Backup → SFTP/ESXi Yedek.
2. Enter your ESXi host IP, SSH username, password or private key path.
3. Select the import network from the dropdown.
4. Click Dosyaları Listele — OXware connects via SFTP and lists the remote filesystem.
5. Navigate to your datastore directory (e.g. /vmfs/volumes/datastore1/myvm/).
6. Click İndir+Import on any .vmdk, .ova, or .qcow2 file.
7. OXware downloads the file in the background, converts it with qemu-img, and registers it in libvirt. Track progress in the Tasks panel.

Method 3 — Direct SCP + Convert (fastest for huge disks)

Skip the browser upload for very large disks (50 GB+). Copy the VMDK directly to the OXware host, convert manually, then register:

# 1. Copy VMDK from ESXi host
scp root@esxi-host:/vmfs/volumes/datastore/myvm/myvm.vmdk \
 /var/lib/oxware/imports/

# 2. Convert to qcow2
qemu-img convert -p -O qcow2 \
 /var/lib/oxware/imports/myvm.vmdk \
 /var/lib/libvirt/images/myvm.qcow2

# 3. Register via API
curl -X POST https://localhost:8006/api/import/ova \
 -H "Authorization: Bearer <token>" \
 -F "file=@/var/lib/oxware/imports/myvm.qcow2"

KVM → KVM Live Migration (between OXware nodes)

Zero-downtime migration between two OXware servers running KVM. Both nodes must have SSH access to each other and shared or compatible storage.

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

This calls virsh migrate --live --persistent under the hood. The VM keeps running during transfer; downtime is typically < 1 second at final memory sync.

Downtime Summary

Export from OXware

From VM Detail → Overview → Export, download the VM as a .tar.gz (qcow2 disk + libvirt XML). Use this to move VMs between OXware nodes or keep an offline backup.

POST /api/vms/{vm_id}/export

VM Detail Page

Click any VM name in the dashboard to open its detail page. The detail page has six tabs:

Overview

Shows current status, IP address, vCPU / RAM / disk allocation, uptime counter, tags, schedule, assigned users (vm-user), notes, and lifecycle action buttons.

Console

Embedded noVNC viewer. Opens a dedicated browser window for a full-resolution VNC session. See the Console section for details.

Hardware

Live-edit vCPUs (hot-plug if the guest OS supports virtio-balloon / hotplug), RAM allocation, disk list (attach/detach/resize qcow2 images), and network interfaces (add/remove VirtIO NICs, set IP, QoS bandwidth limit). CPU pinning configuration is also here.

Monitoring

Real-time charts for CPU%, RAM%, disk read/write IOPS, and network tx/rx. History shows the last 60 seconds of rolling data. Longer-term history is available via the Prometheus endpoint or the global Monitoring page.

Snapshots

Create, revert to, or delete disk snapshots. Each snapshot stores the VM's full qcow2 state at that point in time. Snapshots are listed with timestamp, size, and description. Revert requires the VM to be stopped.

Firewall

Per-VM nftables rules. Add inbound/outbound rules specifying protocol (TCP/UDP/ICMP), port range, source CIDR, and action (ACCEPT/DROP). Rules are applied immediately without restarting the VM.

VM Console

OXware embeds noVNC to provide a browser-based VNC console for each VM. No client software is required.

Opening the Console

From the VM detail page, click the Console tab, then Open Console. A new browser window opens with a full-resolution VNC session.

Features

• Pointer lock — click inside the canvas to capture the mouse cursor. Press Escape to release.
• Ctrl+Alt+Del — the toolbar provides a dedicated button to send this key combination to the guest.
• Fullscreen — expands the console to fill the entire browser window.
• Clipboard — copy/paste text between host and guest (requires clipboard permissions in the browser).
• SPICE info — the info panel shows the SPICE/VNC connection parameters if you need to connect with a native client.

Console Types

OXware supports three console types, selectable from the VM Console tab:

Paste Support

• noVNC: Click Yapıştır toolbar button or press Ctrl+Shift+V
• xterm.js / Shell: Ctrl+Shift+V, right-click, or the Paste button

Browser clipboard API requires HTTPS and explicit permission. Chrome/Edge: allow clipboard access in the address bar lock icon.

Host Shell Console

The Shell Console page gives a root PTY shell directly on the hypervisor host — useful for emergency access and diagnostics.

Role-Based Access Control

OXware uses four built-in roles. Roles are assigned per user and cannot be combined (one role per user).

vm-user Assignment

The vm-user role is designed for end users (e.g., hosting customers) who should only see their own VMs.

• Go to VM Detail → Overview → Assigned Users and click Assign User.
• Alternatively, go to Users → Edit User → Assigned VMs to manage all assignments for a user at once.
• A vm-user sees only the summary dashboard and their assigned VMs. They can start, stop, reboot, and access the console of their VMs, but cannot create or delete VMs, manage networking, or access system settings.

Managing Users

Navigate to Settings → Users (administrator only). Create, edit, or delete users, assign roles, force-reset passwords, and revoke active JWT sessions.

LDAP / Active Directory

OXware can authenticate users against an LDAP server or Microsoft Active Directory instead of (or alongside) the local user database.

Configuration

Go to Settings → LDAP and fill in:

After saving, LDAP users can log in with their domain credentials. Local accounts still work as fallback.

Networking

Network Stat Cards v2.5

The top of the Network page shows four colour-coded gradient stat cards: Sanal Ağlar (blue), Aktif Ağlar (green), Host Arayüzleri (purple), and Aktif Arayüzler (orange). Values update every time the page is loaded.

IP Pool Management

Navigate to Network → IP Pools. Define one or more CIDR blocks (e.g., 10.10.0.0/24). OXware allocates IPs from the pool when creating VMs and tracks usage. You can also pin a static IP to a VM from the pool.

Network Modes

Network QoS

From VM Detail → Hardware → Network, set per-interface bandwidth limits (inbound/outbound in Mbps). OXware uses libvirt's built-in bandwidth filter to enforce limits.

libvirt DHCP Static Entries

OXware writes static DHCP leases into the libvirt network XML so VMs always receive their assigned IP regardless of renewal cycles.

DNS Watchdog

A background service checks DNS resolution from the host every 60 seconds. If resolution fails, it automatically restarts the libvirt DHCP/DNS service and sends an alert. Configurable under Settings → DNS Watchdog.

HAProxy Load Balancer

Navigate to Network → Load Balancer to create HAProxy frontend/backend configurations. Changes are written to /etc/haproxy/haproxy.cfg and reloaded without downtime.

Per-VM Firewall

See VM Detail → Firewall tab. Rules use nftables and take effect immediately.

Bridge IP Isolation v2.4

Navigate to Network → Bridge & IP İzolasyonu. Enter a bridge name (e.g. oxbr0), select the physical NIC, and click Kur. OXware will:

1. Create the Linux bridge device with ip link add oxbr0 type bridge
2. Attach the physical NIC as a bridge member
3. Bring the bridge up
4. Define a libvirt forward mode='bridge' network

cloud-init Static IP v2.4

When creating a VM (advanced options), set Static IP / Gateway / Netmask / DNS. OXware generates a cloud-init network-config v2 YAML and injects it via a NoCloud seed ISO. The VM configures its interface at first boot — no DHCP dependency.

# Generated network-config v2
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]

Network DHCP Live Edit v2.4

Click the button on any virtual network to open the edit modal. You can modify Gateway, Netmask, DHCP Start, and DHCP End. OXware stops the network, redefines it with updated XML, then restarts it — matching the virsh net-destroy / net-define / net-start workflow.

Subnet Calculator v2.4

Available in Network → IPAM at the bottom of the page. Enter any CIDR (e.g. 10.0.1.0/22) to instantly see: Network address, Broadcast, First/Last host, Host count, Subnet mask, Wildcard, IP class, RFC1918 status, and binary representation. No server round-trip.

Storage & Snapshots

Disk Image Management

OXware uses qcow2 as the default disk format. From VM Detail → Hardware → Disks you can:

• Add a new virtual disk (specify size in GB).
• Detach and re-attach disks between VMs (VM must be stopped).
• Resize a disk online (requires the guest OS to recognize the new size).
• View SMART health status for physical drives backing the storage pool.

Snapshots

From VM Detail → Snapshots:

• Create snapshot — enter a description; snapshot is created instantly using qcow2 internal snapshots.
• Revert — restores the VM disk to the snapshot state. VM must be stopped before reverting.
• Delete — removes the snapshot and reclaims disk space.

Auto-Snapshot Scheduler

Navigate to Storage → Snapshot Scheduler. Set a cron-like schedule (e.g., daily at 02:00) and retention count (e.g., keep last 7). The scheduler creates and prunes snapshots automatically.

Backup to MinIO or Local Path

Configure backup targets under Settings → Backup:

• MinIO / S3-compatible — provide endpoint URL, bucket name, access key, and secret key. Backups are compressed qcow2 exports uploaded directly to the bucket.
• Local path — specify a directory on the host or a mounted NAS share.

Schedule backups per-VM or globally. Each backup run creates a timestamped archive.

Security

TOTP Two-Factor Authentication

All accounts can enable TOTP 2FA. Navigate to Profile → Security → Enable 2FA, scan the QR code with any TOTP app (Google Authenticator, Authy, etc.), and verify a code. Once enabled, login requires both password and a time-based code.

Administrators can force 2FA for all accounts globally under Settings → Security → Require 2FA.

JWT Authentication

Sessions use short-lived JWT access tokens (default 15 minutes) paired with longer-lived refresh tokens (7 days). Active sessions are visible and revocable under Settings → Sessions. Tokens are stored in httpOnly cookies to prevent XSS theft.

CSRF Protection

All state-changing API requests require a CSRF token sent as both a cookie and a request header (double-submit pattern). The SPA handles this transparently.

IP Allowlist

Navigate to Settings → Security → IP Allowlist. Add CIDRs or individual IPs that are permitted to access the web UI. Requests from unlisted IPs receive a 403 response before authentication is attempted.

nftables Firewall

OXware manages nftables rules for both global (host-level) and per-VM traffic. The Network → Firewall page provides a UI to manage global rules. Per-VM rules are managed from the VM detail page's Firewall tab.

IDS Integration

OXware can forward auth events (login failures, unusual access patterns) to an external IDS. Configure the IDS webhook URL under Settings → Security → IDS. Brute-force detection is built in: accounts are temporarily locked after 5 failed login attempts.

Security Score Dashboard

The Security page shows a composite score based on: 2FA coverage, IP allowlist status, outdated packages, open ports, and audit log anomalies. Each factor links to the relevant settings page.

Audit Log

All user actions (logins, VM operations, settings changes, failed auth attempts) are recorded in an immutable audit log. Navigate to Settings → Audit Log to search and export logs.

Machine-ID Independent Credentials v2.5

OXware credentials are encrypted with a key derived from /etc/machine-id. If the machine-id changes (kernel update, disk clone, VM migration), admin login would fail. To prevent this:

• The admin username is additionally saved in plaintext to /etc/oxware/.username (mode 600).
• If the encrypted .auth file cannot be decrypted, OXware reads the username fallback and logs a critical warning — the setup wizard does not re-open.

Password Reset File v2.5

If you lose access, a root user can reset credentials without reinstalling:

# 1. Create the 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 the service — reset is applied on startup, file is deleted
sudo systemctl restart oxware

Monitoring

Unified Monitoring Page v2.5

The İzleme page consolidates all observability in one view: system metrics, SMART disk health, HA cluster status, IDS/IPS alerts, VM uptime history, trend analysis, and cost estimation. Heavy sections load only when manually triggered — preventing the browser-freeze issue present in earlier versions.

Live Metrics

The global Monitoring page shows a grid of live metric cards for all VMs: CPU%, RAM usage, disk I/O, and network I/O. Data refreshes every 30 seconds (optimised from 8 s to prevent cluster overload).

Per-VM metrics are also available via the REST API:

Performance History Graphs v2.5

CPU and RAM trend charts with a range picker: 1h, 6h, 24h, 7d, 30d. A background collector stores metric samples every 60 seconds in a local SQLite database. For longer retention, export to Prometheus (see below).

Alert Rules

Navigate to Monitoring → Alert Rules to create threshold-based rules. Each rule specifies:

• Metric (CPU%, RAM%, disk I/O, network I/O, uptime)
• Condition (above / below threshold for N consecutive samples)
• Target (all VMs, a tag group, or a specific VM)
• Notification channel (Telegram, Discord, email)

Anomaly Detection

OXware computes a rolling baseline for each VM's CPU and RAM usage. When a metric deviates more than 2 standard deviations from the baseline, an anomaly alert is triggered. Sensitivity is adjustable per-rule.

Prometheus Endpoint

All VM metrics are exposed in Prometheus text format at:

Scrape this endpoint with Prometheus and visualize in Grafana for long-term retention and advanced dashboards.

Uptime Tracker

The dashboard displays per-VM uptime percentage over the last 7 and 30 days. Downtime incidents are logged with cause (manual stop, crash, host reboot) for SLA reporting.

Network Speedtest

The built-in speedtest measures latency (ICMP ping) and download throughput (HTTP) from the hypervisor to known test servers. Accessible from Monitoring+ → Ağ Hız Testi.

Test Servers

Metrics

• Latency (ms) — avg RTT from 3 ICMP pings
• Packet Loss — % of ping packets dropped
• Download (Mbps) — measured with curl (10 MB HTTP download, Mbps = bytes/s × 8 / 1M)
• Test Duration — total download test time in seconds

Requirements

• curl and ping must be available on the host (usually pre-installed)
• Outbound HTTP/HTTPS access to the test server is required
• Only admin and operator roles can run tests (prevents abuse)

Results measure server-to-internet bandwidth, not client-to-server bandwidth. Use for diagnosing upstream connectivity issues.

BGP Tunneling

OXware includes BGP peer management for advanced networking setups. Configure under Settings → Ağ → BGP.

API Endpoints

Backup & SFTP

OXware supports scheduled VM backups and remote transfer via SFTP/SSH. Configure under Settings → Zamanlama → Yedekleme.

Backup Types

• Disk backup — copies VM disk image (.qcow2) to a local path; optionally transfers via SFTP
• Snapshot — QEMU internal snapshot (no downtime)

SFTP Configuration

Settings → Ağ → SFTP Test card. Required fields:

• host — remote server hostname or IP
• port — SSH port (default 22)
• username — SSH user
• private_key_path — absolute path to SSH private key on the host

Use Test Connection to verify before scheduling.

Backup destination paths are validated against an allowlist (/var/lib/libvirt/images, /var/lib/oxware/backups) to prevent path traversal.

Disk Format & Wipe

The Format sub-tab in VM detail provides disk backup and secure wipe operations.

Disk Backup

Copies the VM's disk file to a destination path. The VM should be stopped or paused for a consistent snapshot.

Disk Wipe

Irreversible. Overwrites the disk with zeros using dd then deletes the file. Confirm by typing the disk device name before proceeding.

Security

• Destination paths are resolved with os.path.realpath() and validated against an allowlist — prevents symlink traversal attacks
• Disk wipe requires explicit double confirmation in the UI

Notifications

OXware supports three notification channels. Configure them under Settings → Notifications.

Telegram

Create a Telegram bot via @BotFather, copy the bot token, and paste it into Settings. Add your chat ID (get it from @userinfobot). Test the connection with the Send Test button.

Discord Webhook

In Discord, go to Server Settings → Integrations → Webhooks, create a webhook, and copy the URL into OXware Settings. Alert messages are sent as embeds with color-coded severity.

Email

Configure SMTP settings (host, port, username, password, TLS mode) and a recipient list. OXware sends HTML-formatted alert emails.

Notification Events

Events that trigger notifications: alert rule threshold breached, VM crash detected, host resource exhaustion, backup failure, certificate expiry warning, 2FA bypass attempt, IDS alert.

AI Assistant

The AI assistant is accessible from the AI tab in the sidebar or by pressing Ctrl+Shift+A.

Natural-Language VM Creation

Describe the VM you need in plain English. For example:

"Create a Ubuntu 22.04 VM with 4 vCPUs, 8 GB RAM, 100 GB disk,
 in the production tag, auto-start enabled"

OXware parses the description, shows a configuration preview, and creates the VM on confirmation.

Capacity Forecasting

The AI analyzes historical CPU and RAM usage trends across all VMs and projects resource exhaustion dates. A forecast chart shows when the host is expected to reach 80% and 95% capacity. This helps plan hardware upgrades before you run out of resources.

Auto-Scaler

Define auto-scaling policies for eligible VMs: specify CPU thresholds that trigger vCPU hot-plug or memory balloon adjustments. The auto-scaler checks metrics every 60 seconds and applies changes within libvirt's hot-plug capabilities.

Hosting Integration

DiyoCP Module v2.5

OXware includes a native provisioning module for DiyoCP, a Turkish hosting control panel. Download the module from Settings → Integrations → DiyoCP and copy it to your DiyoCP server's modules/servers/oxware/ directory.

Package config options: cpu, ram_mb, disk_gb, os_template, network. Supports: Create, Suspend, Unsuspend, Terminate, Resize, Status, Test Connection.

WiseCP Module

The WiseCP module allows hosting providers to provision OXware VMs directly from the WiseCP billing panel. Customers order a VPS product, WiseCP calls the OXware Provisioning API to create the VM, and credentials are delivered automatically.

WHMCS Module

A WHMCS server module is included under integrations/whmcs/. Install it to your WHMCS modules/servers/ directory and configure the OXware API URL and credentials in WHMCS server settings.

Provisioning API

Both modules use the dedicated provisioning endpoint:

This endpoint accepts a JSON body describing the VM spec and returns VM ID, IP, and console credentials. Use an API key with the provision scope (generated in Settings → API Keys).

Terraform Provider

A community Terraform provider is available for infrastructure-as-code VM management. See integrations/terraform/ for the provider source and usage examples.

Nginx + Let's Encrypt

Navigate to Settings → SSL / Domains to add a custom domain and issue a Let's Encrypt certificate. OXware uses certbot and reconfigures Nginx automatically.

Enterprise Features (v2.6.3)

The v2.6.3 Enterprise release brings 23+ datacenter-grade modules to open-source KVM, closing the gap with VMware vSphere and Nutanix AHV — at zero licensing cost.

Compute & Scheduling

• DRS (Distributed Resource Scheduler) — cluster-wide automatic VM rebalancing by CPU/RAM load.
• Affinity / Anti-Affinity Rules — keep VMs together or force them apart across hosts.
• EVC (Enhanced vMotion Compatibility) — CPU masking for migration across CPU generations.
• Maintenance Mode — auto-evacuate VMs to other hosts before host maintenance.
• NUMA-aware scheduling — pin VMs to physical NUMA nodes, HugePages tuning.
• Right-Sizing Recommendations — detect over/under-provisioned VMs automatically.
• Predictive Failure Analysis — SMART/ECC monitoring → proactive VM evacuation.
• Compute Tuning — KSM (kernel same-page merging), memory ballooning, hugepages.

Storage

• Linked Clones — 100 VMs from 1 base image plus thin diffs.
• Application-consistent snapshots — DB-aware quiesce (flush + freeze).
• Snapshot orphan cleanup — automatic stale snapshot detection & removal.
• Storage Advanced — ZFS, tiering, dedup/compression hooks, SPBM, iSCSI targets.
• Backup Encryption — AES-256 encrypted archives with passphrase.

Network

• NIOC (Network I/O Control) — per-VM bandwidth guarantees & QoS.
• Network Advanced — VXLAN overlay, IPv6 dual-stack, service chaining hooks.

Security & Compliance

• SSO — SAML / OIDC (Okta, Azure AD, Google Workspace).
• LDAP / Active Directory — domain authentication, group → role mapping.
• SIEM Integration — Splunk, Elastic, Wazuh (CEF / syslog export).
• Session Recording — SSH and VNC console capture & replay.
• MFA enforcement per role — mandatory TOTP for admins.

Availability & Disaster Recovery

• Site Recovery Manager — automated DR runbooks, cross-site replication.
• RPO/RTO monitoring — SLA tracking with burn-rate awareness.
• Recovery drill automation — non-destructive failover testing.

Operations & Automation

• Lifecycle Manager — rolling host upgrades, configuration drift detection.
• Alert Correlation Engine — group related alerts into single incidents.
• Webhook System — VM events → custom HTTP POST (Zapier / n8n).
• Automation Engine — multi-step workflow orchestration.
• VNC Thumbnails — live VM previews in the dashboard list.

Roadmap — Coming Soon

Fault Tolerance (lockstep), Storage DRS, Microsegmentation (per-VM L7 firewall), vTPM & Secure Boot, AMD SEV / Intel TDX confidential VMs, HashiCorp Vault integration, audit log hash-chain, multi-tenancy hard isolation & chargeback, vGPU (NVIDIA GRID / MIG), SR-IOV passthrough, image-based bare-metal provisioning, capacity planning + what-if, distributed tracing (OpenTelemetry), topology + flow visualization, cross-site replication, Terraform / Ansible / Pulumi providers, Kubernetes CSI driver + Operator, KubeVirt integration, GitOps (ArgoCD / Flux), policy-as-code (OPA / Rego), mobile app (iOS + Android), desktop client (Electron), PWA, microVM (Firecracker), Kata Containers.

Plugin SDK

OXware includes a Python plugin SDK that lets you extend the panel with custom API endpoints, VM event handlers, and UI panels. Plugins are single .py files loaded at runtime by the plugin engine. No restart required — plugins can be enabled and disabled live from Settings → Plugins.

Plugin Structure

Every plugin must be a single .py file with a PLUGIN_META dict at the top. Three optional hook functions are recognised:

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

PLUGIN_META Fields

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):
 # event = {"type": "vm.started", "vm_id": "...", "name": "..."}
 pass

Developing a Plugin (in-panel)

1. Open Settings → Plugins → Develop tab.
2. Click Scaffold and pick a template: Basic, API, Event, or Panel.
3. Write your code in the browser editor.
4. Click Validate — runs an AST security scan, checks PLUGIN_META, and flags dangerous calls.
5. Click Upload from Editor to install the plugin on your system.
6. The plugin is disabled by default — enable it in the Installed tab.

Scaffold Templates

Download a scaffold template: GET /api/plugins/scaffold?kind=basic (or api, event, panel).

Security Scanner (Validate)

The in-panel validator runs a Python AST scan before upload. The following patterns are blocked or flagged:

Sharing Plugins

Plugins run locally on your own OXware install. To share: post on GitHub Discussions. Well-tested plugins may be added to the curated catalog at oxware.top/marketplace.

Plugin SDK API Endpoints

API Reference

OXware ships a built-in interactive API explorer at /api/docs. Open it in your browser to browse every endpoint, see required parameters, and fire live requests against your running instance — no external tools needed.

How the API works

Login via POST /api/auth/login to get a JWT token. Pass it as a Bearer header on every subsequent call, or rely on the session cookie set by the dashboard.

# 1. Get 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>"

All API requests require a JWT Bearer token in the Authorization header, or a valid session cookie.

Authorization: Bearer <token>

Authentication

Virtual Machines

Users & RBAC

Networking

Storage

Monitoring & Alerts

Provisioning & ISO

SSH Keys & Vault

Enterprise — Compute (v2.5.3–2.5.6)

Security & Compliance (v2.5.4–2.5.6)

Enterprise — Backup Advanced (v2.5.7)

Observability (v2.5.8)

Network Advanced 2 (v2.5.9)

️ Cloud / Kubernetes (v2.5.10)

Modern Workloads (v2.5.11)

IaC + Clients (v2.5.12)

Security & Compliance (v2.5.4–2.5.6)

Enterprise Expansion (v2.6.3)

8 new backend modules · 40+ endpoints · 8 security CVEs patched (SEC-001..008)

Fault Tolerance — checkpoint-based VM protection

Storage DRS — auto disk rebalance across pools

VM Console Recording — ffmpeg VNC→WebM

2FA Recovery Codes — single-use backup codes

Plugin SDK — dynamic Python plugin loader

See the Plugin SDK section for full documentation.

VM Disk Hot-Extend — live resize

Bulk VM Operations — parallel ops on N VMs

Network Mode & IP Fix — NAT/Bridge detection

Kernel Hardening — AppArmor/seccomp/cgroups/eBPF

Power & OS (v2.6.2)

Green Mode — AI-driven power optimization

Green Mode — AI power optimization

Multi-Region, Marketplace, Cloud Burst, Bare-Metal, OAuth2 (v2.6.3)

5 new backend modules · ~40 endpoints · geo-aware placement, app marketplace, cloud overflow, PXE provisioning, PKCE SSO

Multi-Region — geo-aware VM placement

App Marketplace — community app catalog

Cloud Burst — AWS/GCP/Azure overflow

Bare-Metal Provisioning — PXE/iPXE

OAuth 2.0 SSO — PKCE flow

Security Patches (v2.6.3)

8 CVEs patched without downtime:

• SEC-001 — AI API keys at-rest Fernet encryption (was plaintext)
• SEC-002 — AI_CONFIG_FILE path traversal guard (allowed-roots whitelist)
• SEC-003 — ai_agent threading.RLock + atomic file write + threading.Event stop
• SEC-004 — AI agent add/delete/update → admin-only (was operator)
• SEC-005 — 2FA invalid code = generic "Geçersiz kimlik bilgileri" (was specific)
• SEC-006 — vm_id XSS: {{ vm_id | tojson }} + server regex validation
• SEC-007 — postMessage '*' → location.origin + receiver origin check
• SEC-008 — WS auth: raw JWT in URL → one-time 60s vnc_token (no log leakage)

Full interactive API explorer with all ~270 endpoints (auto-generated, always current): https://<your-host>:8006/api/docs

Configuration

OXware reads its main configuration from /opt/oxware/config.ini. Changes require a service restart: sudo systemctl restart oxware.

Troubleshooting

oxupdate syntax error / update fails

If sudo oxupdate prints a syntax error (e.g. line N: syntax error near unexpected token `fi') or command not found, the CLI script got corrupted. Recover with:

cd /opt/oxware && git pull
sudo bash repair.sh --fix-cli
sudo systemctl restart oxware

repair.sh --fix-cli regenerates /usr/local/bin/ox and /usr/local/bin/oxupdate from a clean template. After that, sudo oxupdate works normally again.

Services won't start after reboot

sudo bash repair.sh

This restarts oxware, nginx, libvirtd, and novnc, and re-applies nftables rules.

Cannot access web UI

• Check that Nginx is running: sudo systemctl status nginx
• Check that the OXware service is running: sudo systemctl status oxware
• Check firewall: sudo nft list ruleset | grep 8006
• Ensure you are using https:// (not http) and accepting the certificate.

KVM not available

kvm-ok
# If it reports KVM not available, check BIOS virtualization settings
lscpu | grep Virtualization

VM stuck in starting state

Check libvirt logs:

sudo journalctl -u libvirtd -n 50 --no-pager

Reset admin password

sudo bash repair.sh --reset-password

Check OXware logs

sudo journalctl -u oxware -f
# Or the log file:
tail -f /var/log/oxware/app.log

Certificate errors

The default install uses a self-signed certificate. To issue a proper certificate, go to Settings → SSL → Let's Encrypt and enter your domain. Ensure ports 80 and 443 are open and the domain resolves to your server's IP.

LDAP login fails

Test LDAP connectivity from the server:

ldapsearch -x -H ldap://<ldap-server> -D "<bind-dn>" -w <password> -b "<base-dn>"