NexaFabric

NexaFabric is an open-source SDN-like network and security control plane for Proxmox VE environments. It runs as an external web application and provides inventory, IPAM, security groups, policy simulation, firewall previews, audit trails, and automation without patching Proxmox itself.

What Is Included

• FastAPI backend with SQLAlchemy 2, Alembic-ready models, JWT auth, RBAC primitives, audit logging, and provider interfaces.
• React + TypeScript frontend with Vite, Tailwind CSS, TanStack Query, React Router, Zustand, dark/light mode, and production-oriented pages.
• PostgreSQL, Redis, worker, API, frontend, and reverse proxy through Docker Compose.
• Optional demo seed data for clusters, nodes, workloads, networks, tenants, policies, IPAM, jobs, and audit events.
• Tests, lint/type-check scripts, CI workflow, and operational documentation.

Quick Start

cp .env.example .env
docker compose up --build

Then open:

• Frontend: http://localhost:8080
• API docs: http://localhost:8080/api/docs

On a fresh database NexaFabric opens the setup wizard first. The wizard creates the first Super Admin user and registers the first Proxmox or demo provider.

To start from scratch during testing:

docker compose down -v
docker compose up --build

Demo data is disabled by default. Enable it only for lab screenshots or UI testing:

SEED_DEMO_DATA=true

Proxmox Preparation

NexaFabric can read inventory from the Proxmox VE API immediately after you add a cluster, but IPAM and flow visibility depend on what Proxmox and the guests expose. Use this checklist before expecting full data in the UI.

1. Create A Dedicated API Token

In Proxmox VE, create a dedicated user and API token instead of using a personal admin token.

Recommended UI path:

1. Datacenter -> Permissions -> Users
2. Create a user such as nexafabric@pve or another realm you manage.
3. Datacenter -> Permissions -> API Tokens
4. Add a token such as nexafabric@pve!control-plane.
5. Keep privilege separation enabled unless you intentionally want the token to inherit all user privileges.

NexaFabric accepts both token formats:

PVEAPIToken=nexafabric@pve!control-plane=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
nexafabric@pve!control-plane=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The installer stores the token with the cluster and starts in read_only mode by default.

2. Assign Minimum Read Permissions

For inventory, IP discovery, policy preview, and dashboard data, assign the token read access at the Datacenter level or the narrowest paths that contain your nodes and guests.

Minimum practical read privileges:

• Sys.Audit for cluster and node inventory.
• VM.Audit for VM and container inventory/config visibility.
• SDN.Audit if you use Proxmox SDN zones, VNets, EVPN, or related network objects.

For write-enabled firewall orchestration, create a separate token or role and do not reuse the read-only token. Only enable write mode after previews and audit logging have been verified in your environment.

Minimum practical write privileges for VM/LXC-level firewall rules:

• VM.Audit so NexaFabric can resolve guests and inspect existing rules.
• VM.Config.Options so NexaFabric can enable the guest firewall option before writing rules.
• VM.Config.Network on /vms or on the narrow VM/LXC paths you want NexaFabric to manage, so NexaFabric can set firewall=1 on guest network interfaces before writing rules.

NexaFabric writes only rules that carry a NexaFabric policy=... comment marker. During apply it removes and replaces its own marked rules for the selected policy, leaving manually created Proxmox firewall rules untouched.

3. Enable QEMU Guest Agent For VM IP Discovery

For QEMU VMs, Proxmox only exposes guest interface/IP details reliably when the QEMU Guest Agent is installed in the VM and enabled in Proxmox.

Per VM:

1. Install the guest agent inside the VM.
   • Debian/Ubuntu: apt install qemu-guest-agent
   • RHEL/Rocky/Alma: dnf install qemu-guest-agent
   • Windows: install the VirtIO guest tools including the QEMU guest agent.
2. Enable and start the service in the guest.
   • Linux: systemctl enable --now qemu-guest-agent
3. In Proxmox UI, open the VM:
   • Options -> QEMU Guest Agent -> Enabled
4. Reboot the VM or fully stop/start it if Proxmox does not immediately report the agent.

NexaFabric uses the Proxmox guest-agent network interface endpoint to discover IPv4 addresses for IPAM. If the guest agent is missing, the VM can still appear in inventory, but IPAM may not learn its IP address.

4. LXC IP Discovery

For LXC containers, NexaFabric reads static IPs from the Proxmox container network config when available.

Works best when container interfaces are configured with explicit IPs, for example:

net0: name=eth0,bridge=vmbr0,ip=10.10.10.50/24,gw=10.10.10.1

If the container uses DHCP, Proxmox may not always have a stable IP value in config. In that case, use a DHCP lease source, static reservations, or a future NexaFabric node-agent/flow-source integration.

5. Sync Cluster Inventory

After adding the cluster in NexaFabric:

1. Open Clusters.
2. Click the cluster row/name.
3. Use Test to validate the token.
4. Use Sync to import nodes, VMs/LXCs, networks, and discoverable IP addresses.
5. Open IPAM -> Discover from Proxmox if you want to rerun IP discovery later.

Imported IPs are placed into an automatically created discovered-ipam network if NexaFabric cannot map them to an existing subnet.

6. Firewall And Policy Requirements

NexaFabric policy preview does not require Proxmox firewall writes. It compiles NexaFabric policies into provider-specific preview output and records audit events.

Before enabling real firewall apply workflows:

• Ensure Proxmox firewall is enabled intentionally at the Datacenter, node, and guest level where you want enforcement.
• Ensure the firewall checkbox is enabled on the relevant VM/LXC network interfaces, otherwise Proxmox may store rules without enforcing them for that interface.
• Keep NexaFabric clusters in read_only mode until previews are reviewed.
• Use audit mode policies first to see what would be allowed or blocked.
• Confirm that Proxmox API token permissions match the exact write operations you plan to allow.
• Keep backups of Proxmox firewall configuration before enabling automation.

Live apply currently supports VM/LXC-level rules where the enforcement side is a concrete workload:

• ingress policies apply to the destination VM/LXC.
• egress policies apply to the source VM/LXC.
• The opposite side can be any, an IP/CIDR, or another workload with an assigned IP in IPAM.
• Security group and network-wide targets remain preview-only until they can be expanded safely.
• audit mode does not write blocking Proxmox rules; it records the intended result without enforcement.

NexaFabric is designed to read first, simulate second, and only apply after explicit confirmation.

7. Network Flow Visibility

Proxmox inventory and guest agent data are enough for:

• Cluster, node, VM, LXC inventory.
• Network object visibility.
• IPAM discovery for VMs with QEMU Guest Agent.
• Static LXC IP discovery.
• Policy matching and firewall previews.

Actual traffic flow visibility, top talkers, byte counters, and per-workload traffic history require the NexaFabric node agent or another telemetry source. Proxmox VE does not provide full flow telemetry for every VM through the basic inventory API.

Supported options:

• NexaFabric node agent on Proxmox nodes to read VM/LXC interface hints, host interface counters, real IPv4 TCP/UDP/ICMP flows from Linux VM interfaces, conntrack flows when available, nftables ruleset state, and pve-firewall status.
• Open vSwitch with sFlow/NetFlow/IPFIX exported to a collector.
• Router/firewall flow exports from pfSense, OPNsense, FRR/BGP edge devices, or physical switches.

Until such a source is configured, NexaFabric will show No flow telemetry collected yet instead of fake traffic. If the node agent can see VM interface counters but no packet flows, NexaFabric displays the counters as an explicitly marked fallback.

8. Install The Node Agent

After a Proxmox cluster sync has imported nodes:

1. Open Nodes.
2. Click the agent icon on the node row.
3. Copy the installer command.
4. Run it as root on the matching Proxmox node.

The installer creates:

• /opt/nexafabric-agent/nexafabric-agent.py
• /etc/nexafabric-agent/config.json
• nexafabric-agent.service

The agent sends a heartbeat every 30 seconds to NexaFabric. It uses a node-specific enrollment token generated by the UI and does not need your Proxmox API token.

Useful commands on the Proxmox node:

systemctl status nexafabric-agent
journalctl -u nexafabric-agent -f
systemctl restart nexafabric-agent

Agent version 0.2.1 reports host/interface counters, VMID hints from Proxmox interface names, real packet-derived IPv4 TCP/UDP/ICMP flows from VM interfaces, conntrack flow records when available, recent kernel firewall log drops/rejects, pve-firewall status, and an nftables ruleset hash. NexaFabric maps flow source/destination IPs back to workloads through IPAM, so VM/LXC details can show observed and blocked traffic once guest IPs have been discovered. Blocked traffic visibility depends on Proxmox/kernel firewall logging being enabled for the rule or default drop that rejected the packet. The agent does not enforce policies itself; Proxmox firewall rule apply remains API-driven through NexaFabric.

The default agent config enables the packet flow collector:

{
  "packet_flow_collector": true,
  "packet_flow_window_seconds": 10,
  "flow_limit": 500
}

The collector runs as root through the Linux AF_PACKET interface and attaches to Proxmox VM interfaces such as tap100i0 and fwln100i0. It aggregates locally before sending data to NexaFabric; packet payloads are not stored or uploaded.

9. Troubleshooting Proxmox Integration

401 No ticket or Provider sync failed usually means:

• The API token format is wrong.
• The token was copied without the secret value after =.
• The token lacks the required ACLs.
• Privilege separation is enabled but no permissions were assigned to the token.
• The wrong realm/user/token ID was used.

TLS errors usually mean:

• Proxmox uses a self-signed certificate.
• The hostname in Cluster API URL does not match the certificate.
• Disable Verify TLS certificate only for trusted lab systems, or install a valid certificate on Proxmox.

Repository Layout

backend/       FastAPI API, models, services, worker entrypoint, tests
frontend/      React application, API client, pages, component tests
docs/          Architecture, operations, security, provider and API docs
nginx/         Reverse proxy example

Safety Model

NexaFabric never applies firewall changes without a preview, validation, and audit record. The included Proxmox provider is designed around read-only inventory first, then explicit dry-run and apply workflows for concrete VM/LXC firewall rules.