diff --git a/CHANGELOG.md b/CHANGELOG.md
index a907108..86565c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,18 @@ All notable changes to PVEmanager will be documented in this file.
---
+## [Unreleased]
+
+### ✨ Network topology page
+
+- **New `/topology` page** — an interactive map of the infrastructure: panel → cluster → Proxmox node → VM/LXC, rendered with React Flow. Node cards carry live CPU/RAM meters, guests show status, IP, bridge/VLAN and tags
+- **Filters** — narrow the graph to one connection, filter guests by status (all / running / stopped), and collapse a node's guests into a single badge above a configurable threshold (remembered per browser); expand a collapsed node individually
+- **Canvas tools** — zoom, pan, fit-to-screen, fullscreen, minimap, legend and PNG/SVG export of the whole graph
+- **New API `GET /proxmox/api/network/topology`** — one aggregated request instead of fanning out over servers/nodes/SDN/VMs; gated on `network:view`, honours workspace scoping and per-owner VM isolation. Unreachable connections degrade to cached data plus a warning instead of failing the page
+- **`netN` parser** — guest NIC strings are now parsed (bridge, VLAN tag, MAC, model, firewall, rate, MTU) for both the QEMU and LXC dialects, available via `include_nics=true`
+
+---
+
## [v1.16.1] - 2026-08-17
### 🎨 UI
diff --git a/CHANGELOG.ru.md b/CHANGELOG.ru.md
index 798837c..e8f7324 100644
--- a/CHANGELOG.ru.md
+++ b/CHANGELOG.ru.md
@@ -4,6 +4,18 @@
---
+## [Не выпущено]
+
+### ✨ Страница «Топология сети»
+
+- **Новая страница `/topology`** — интерактивная карта инфраструктуры: панель → кластер → нода Proxmox → VM/LXC на базе React Flow. На карточках нод — живые индикаторы CPU/RAM, у гостей видны статус, IP, bridge/VLAN и теги
+- **Фильтры** — сужение графа до одного подключения, фильтр гостей по статусу (все / запущенные / остановленные) и схлопывание гостей ноды в один узел при превышении настраиваемого порога (запоминается в браузере); свернувшуюся ноду можно раскрыть по отдельности
+- **Инструменты холста** — зум, панорама, вписать в экран, полноэкранный режим, миникарта, легенда и экспорт всего графа в PNG/SVG
+- **Новый API `GET /proxmox/api/network/topology`** — один агрегированный запрос вместо обхода серверов/нод/SDN/VM; требует право `network:view`, учитывает рабочие области и изоляцию VM по владельцу. Недоступное подключение отдаёт данные из кэша с предупреждением, а не ломает страницу
+- **Парсер `netN`** — строки сетевых карт гостей теперь разбираются (bridge, VLAN-тег, MAC, модель, firewall, rate, MTU) для обоих диалектов, QEMU и LXC; доступно через `include_nics=true`
+
+---
+
## [v1.16.1] - 2026-08-17
### 🎨 Интерфейс
diff --git a/backend/app/api/proxmox/__init__.py b/backend/app/api/proxmox/__init__.py
index 3007ad8..ed499d0 100644
--- a/backend/app/api/proxmox/__init__.py
+++ b/backend/app/api/proxmox/__init__.py
@@ -15,6 +15,7 @@ from .pools import router as pools_router
from .disks import router as disks_router
from .access import router as access_router
from .node_admin import router as node_admin_router
+from .topology import router as topology_router
from ._helpers import get_next_vmid, save_vm_instance, get_vm_instance
router = APIRouter()
@@ -34,3 +35,4 @@ router.include_router(pools_router)
router.include_router(disks_router)
router.include_router(access_router)
router.include_router(node_admin_router)
+router.include_router(topology_router)
diff --git a/backend/app/api/proxmox/topology.py b/backend/app/api/proxmox/topology.py
new file mode 100644
index 0000000..60276c9
--- /dev/null
+++ b/backend/app/api/proxmox/topology.py
@@ -0,0 +1,486 @@
+"""Aggregated network topology: panel -> cluster -> node -> guest.
+
+One endpoint feeds the whole /topology page so the frontend makes a single
+request instead of fanning out over servers/nodes/sdn/vms. Everything the graph
+draws - plus the bridge/VLAN/MAC data the planned "group by VLAN" view will
+need - is collected here.
+
+Kept separate from ``cluster.py``'s ``/api/cluster/topology``, which answers a
+different question (which servers form which cluster) and is consumed by the
+Cluster page.
+"""
+
+import asyncio
+import threading
+import time as time_lib
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from loguru import logger
+from sqlalchemy.orm import Session, joinedload
+
+from ...auth import PermissionChecker
+from ...db import get_db
+from ...models import IPAMAllocation, IPAMNetwork, ProxmoxServer, User, VMInstance
+from ...proxmox import _run_in_executor, parse_guest_nics
+from ...schemas import (NetworkTopologyResponse, TopologyBridge, TopologyCluster,
+ TopologyGuest, TopologyNic, TopologyNode,
+ TopologyPanelSummary, TopologyWarning)
+from ._helpers import _get_proxmox_client, can_view_all_instances, get_visible_server_ids
+
+router = APIRouter()
+
+# Live cluster/resources + node networks, keyed by server id. Short TTL: the
+# page auto-refreshes every 30s and several users may watch it at once.
+_topo_cache: Dict[int, Dict[str, Any]] = {}
+_topo_lock = threading.Lock()
+TOPO_TTL = 15
+
+# Guest configs change rarely, and reading them costs one HTTP call per guest.
+_nic_cache: Dict[Tuple[int, int], Dict[str, Any]] = {}
+_nic_lock = threading.Lock()
+NIC_TTL = 300
+NIC_MAX_WORKERS = 8
+NIC_MAX_FETCHES = 300 # hard ceiling so a huge cluster cannot hang the request
+
+
+def _truthy(value: Any) -> bool:
+ """Proxmox returns flags as 1/0, "1"/"0" or bools depending on the field."""
+ return str(value).strip().lower() in ("1", "true", "yes", "on")
+
+
+# ==================== Live collection (runs off the request thread) ====================
+
+def _collect_server(server: ProxmoxServer, include_bridges: bool) -> Dict[str, Any]:
+ """Everything one Proxmox connection can tell us, in as few calls as possible."""
+ client = _get_proxmox_client(server)
+
+ # A single /cluster/resources call carries both node and guest metrics.
+ resources = client.get_cluster_resources() or []
+ nodes = [r for r in resources if r.get("type") == "node"]
+ guests = [r for r in resources if r.get("type") in ("qemu", "lxc")]
+
+ bridges: Dict[str, List[Dict[str, Any]]] = {}
+ if include_bridges:
+ # Zones/vnets are cluster-wide; fetch once and filter per node below.
+ try:
+ zones = {z.get("zone"): z for z in (client.get_sdn_zones() or [])}
+ vnets = client.get_sdn_vnets() or []
+ except Exception as exc: # SDN is optional and older PVE lacks it
+ logger.debug(f"SDN unavailable on {server.name}: {exc}")
+ zones, vnets = {}, []
+
+ for node_res in nodes:
+ node_name = node_res.get("node")
+ if not node_name:
+ continue
+ entries: List[Dict[str, Any]] = []
+ try:
+ for iface in client.get_node_networks(node_name) or []:
+ name = iface.get("iface") or iface.get("name")
+ if not name:
+ continue
+ cidr = iface.get("cidr")
+ if not cidr and iface.get("address") and iface.get("netmask"):
+ cidr = "{0}/{1}".format(iface["address"], iface["netmask"])
+ entries.append({
+ "name": name,
+ "type": iface.get("type"),
+ "cidr": cidr,
+ "vlan_aware": _truthy(iface.get("bridge_vlan_aware")),
+ "ports": iface.get("bridge_ports") or iface.get("slaves"),
+ "active": _truthy(iface.get("active")),
+ })
+ except Exception as exc:
+ logger.debug(f"Could not read networks of {server.name}/{node_name}: {exc}")
+
+ # SDN vnets are attachable as bridges but never appear in /network.
+ for vnet in vnets:
+ vnet_name = vnet.get("vnet")
+ if not vnet_name:
+ continue
+ zone_name = vnet.get("zone", "")
+ zone_nodes = (zones.get(zone_name, {}).get("nodes") or "").replace(" ", "")
+ if zone_nodes and node_name not in zone_nodes.split(","):
+ continue
+ entries.append({
+ "name": vnet_name,
+ "type": "vnet",
+ "zone": zone_name,
+ "active": True,
+ })
+ bridges[node_name] = entries
+
+ return {"nodes": nodes, "guests": guests, "bridges": bridges}
+
+
+def _fetch_nics(server: ProxmoxServer, targets: List[Tuple[str, int, str]]) -> Dict[int, List[Dict[str, Any]]]:
+ """``netN`` cards for the given guests. ``targets`` = [(node, vmid, type)]."""
+ if not targets:
+ return {}
+ client = _get_proxmox_client(server)
+
+ def _one(node: str, vmid: int, vm_type: str) -> Tuple[int, List[Dict[str, Any]]]:
+ getter = client.get_vm_config if vm_type == "qemu" else client.get_container_config
+ config = getter(node, vmid) or {}
+ return vmid, [nic.to_dict() for nic in parse_guest_nics(config)]
+
+ result: Dict[int, List[Dict[str, Any]]] = {}
+ with ThreadPoolExecutor(max_workers=min(NIC_MAX_WORKERS, len(targets))) as pool:
+ futures = [pool.submit(_one, *target) for target in targets]
+ for future in as_completed(futures):
+ try:
+ vmid, nics = future.result()
+ except Exception as exc:
+ logger.debug(f"Could not read guest config on {server.name}: {exc}")
+ continue
+ result[vmid] = nics
+ return result
+
+
+# ==================== Helpers ====================
+
+def _split_tags(raw: Optional[str]) -> List[str]:
+ """Proxmox stores tags as a ``;``-separated string; the graph wants a list."""
+ if not raw:
+ return []
+ return [t.strip() for t in str(raw).replace(",", ";").split(";") if t.strip()]
+
+
+def _to_int(value: Any) -> Optional[int]:
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _to_float(value: Any) -> Optional[float]:
+ try:
+ return float(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _empty_response() -> NetworkTopologyResponse:
+ return NetworkTopologyResponse(
+ generated_at=datetime.now(timezone.utc),
+ panel=TopologyPanelSummary(),
+ clusters=[],
+ warnings=[],
+ )
+
+
+# ==================== Endpoint ====================
+
+@router.get("/api/network/topology", response_model=NetworkTopologyResponse)
+async def get_network_topology(
+ request: Request,
+ server_id: Optional[int] = Query(None, description="Limit to a single connection"),
+ include_stopped: bool = Query(True),
+ include_templates: bool = Query(False),
+ include_bridges: bool = Query(True),
+ include_nics: bool = Query(False, description="Read every guest config for bridge/VLAN/MAC - one call per guest"),
+ db: Session = Depends(get_db),
+ current_user: User = Depends(PermissionChecker("network:view")),
+):
+ """Infrastructure tree for the topology page.
+
+ Always answers 200 (bar a permission denial): an unreachable server
+ degrades to cached rows plus a warning rather than failing the page.
+ """
+ warnings: List[TopologyWarning] = []
+
+ # -- Visibility ----------------------------------------------------------
+ # None means "no restriction" and is NOT the same as an empty set.
+ visible_ids = get_visible_server_ids(request, db, current_user)
+ if visible_ids is not None and not visible_ids:
+ return _empty_response()
+
+ servers_q = db.query(ProxmoxServer)
+ if visible_ids is not None:
+ servers_q = servers_q.filter(ProxmoxServer.id.in_(visible_ids))
+ if server_id is not None:
+ if visible_ids is not None and server_id not in visible_ids:
+ # 404 rather than 403 so the response cannot confirm the server exists.
+ raise HTTPException(status_code=404, detail="Proxmox server not found")
+ servers_q = servers_q.filter(ProxmoxServer.id == server_id)
+ servers = servers_q.order_by(ProxmoxServer.name).all()
+ if not servers:
+ return _empty_response()
+ server_map = {s.id: s for s in servers}
+
+ # -- Ownership: live Proxmox data carries no owner, the DB does ----------
+ see_all = can_view_all_instances(current_user)
+
+ db_q = (
+ db.query(VMInstance)
+ .options(joinedload(VMInstance.owner))
+ .filter(VMInstance.deleted_at.is_(None), VMInstance.server_id.in_(server_map.keys()))
+ )
+ if not see_all:
+ db_q = db_q.filter(VMInstance.owner_id == current_user.id)
+ db_guests = db_q.all()
+ db_by_key: Dict[Tuple[int, int], VMInstance] = {(g.server_id, g.vmid): g for g in db_guests}
+ # Pair-scoped, not vmid-scoped: the same vmid on two servers is two guests.
+ owned_keys = set(db_by_key.keys())
+
+ # -- IP addresses from IPAM, falling back to the cached instance row ------
+ ipam_by_key: Dict[Tuple[int, int], str] = {}
+ for alloc in (
+ db.query(IPAMAllocation)
+ .filter(IPAMAllocation.status.in_(["allocated", "reserved"]))
+ .all()
+ ):
+ if alloc.proxmox_server_id and alloc.proxmox_vmid and alloc.ip_address:
+ ipam_by_key[(alloc.proxmox_server_id, alloc.proxmox_vmid)] = alloc.ip_address
+
+ ipam_nets = db.query(IPAMNetwork).filter(
+ IPAMNetwork.proxmox_server_id.in_(server_map.keys())
+ ).all()
+ ipam_by_bridge: Dict[Tuple[int, str], IPAMNetwork] = {
+ (n.proxmox_server_id, n.proxmox_bridge): n for n in ipam_nets if n.proxmox_bridge
+ }
+
+ # -- Live data, in parallel: one dead cluster must not stall the rest -----
+ live: Dict[int, Dict[str, Any]] = {}
+ stale_servers: List[ProxmoxServer] = []
+ now = time_lib.time()
+ with _topo_lock: # guards the dict only, never a network call
+ for server in servers:
+ cached = _topo_cache.get(server.id)
+ if cached and (now - cached["time"]) < TOPO_TTL:
+ live[server.id] = cached["data"]
+ elif server.is_online is False:
+ # Offline servers contribute nothing but a connection timeout.
+ continue
+ else:
+ stale_servers.append(server)
+
+ if stale_servers:
+ tasks = [_run_in_executor(_collect_server, s, include_bridges) for s in stale_servers]
+ results = await asyncio.gather(*tasks, return_exceptions=True)
+ for server, result in zip(stale_servers, results):
+ if isinstance(result, HTTPException):
+ warnings.append(TopologyWarning(
+ server_id=server.id, server_name=server.name,
+ code="no_credentials", message=str(result.detail),
+ ))
+ continue
+ if isinstance(result, BaseException):
+ logger.warning(f"Topology collection failed for {server.name}: {result}")
+ warnings.append(TopologyWarning(
+ server_id=server.id, server_name=server.name,
+ code="error", message=str(result),
+ ))
+ continue
+ live[server.id] = result
+ with _topo_lock:
+ _topo_cache[server.id] = {"time": time_lib.time(), "data": result}
+
+ for server in servers:
+ if server.id not in live and not any(w.server_id == server.id for w in warnings):
+ warnings.append(TopologyWarning(
+ server_id=server.id, server_name=server.name,
+ code="offline", message=f"'{server.name}' is unreachable - showing cached data",
+ ))
+
+ # -- NICs (opt-in): bridge / VLAN / MAC straight from the guest configs ---
+ nics_by_key: Dict[Tuple[int, int], List[Dict[str, Any]]] = {}
+ if include_nics:
+ pending: Dict[int, List[Tuple[str, int, str]]] = {}
+ budget = NIC_MAX_FETCHES
+ truncated = False
+ now = time_lib.time()
+ for sid, data in live.items():
+ for guest in data["guests"]:
+ vmid = _to_int(guest.get("vmid"))
+ node = guest.get("node")
+ if vmid is None or not node:
+ continue
+ if not see_all and (sid, vmid) not in owned_keys:
+ continue
+ with _nic_lock:
+ cached = _nic_cache.get((sid, vmid))
+ if cached and (now - cached["time"]) < NIC_TTL:
+ nics_by_key[(sid, vmid)] = cached["data"]
+ continue
+ if budget <= 0:
+ truncated = True
+ continue
+ budget -= 1
+ pending.setdefault(sid, []).append((node, vmid, guest.get("type", "qemu")))
+
+ if truncated:
+ warnings.append(TopologyWarning(
+ code="nics_truncated",
+ message=f"Network card details limited to {NIC_MAX_FETCHES} guests per request",
+ ))
+
+ if pending:
+ server_ids = list(pending.keys())
+ tasks = [_run_in_executor(_fetch_nics, server_map[sid], pending[sid]) for sid in server_ids]
+ results = await asyncio.gather(*tasks, return_exceptions=True)
+ stamp = time_lib.time()
+ for sid, result in zip(server_ids, results):
+ if isinstance(result, BaseException):
+ logger.debug(f"NIC collection failed for server {sid}: {result}")
+ continue
+ for vmid, nics in result.items():
+ nics_by_key[(sid, vmid)] = nics
+ with _nic_lock:
+ _nic_cache[(sid, vmid)] = {"time": stamp, "data": nics}
+
+ # -- Assemble ------------------------------------------------------------
+ def _build_guest(sid: int, node_name: str, res: Optional[Dict[str, Any]],
+ row: Optional[VMInstance]) -> Optional[TopologyGuest]:
+ res = res or {}
+ vmid = _to_int(res.get("vmid"))
+ if vmid is None and row is not None:
+ vmid = row.vmid
+ if vmid is None:
+ return None
+
+ vm_type = res.get("type") or (row.vm_type if row else None) or "qemu"
+ is_template = _truthy(res.get("template")) or bool(row and row.is_template)
+ if is_template and not include_templates:
+ return None
+ status = res.get("status") or (row.status if row else None) or "unknown"
+ if not include_stopped and status != "running":
+ return None
+
+ tags = _split_tags(res.get("tags")) or _split_tags(row.tags if row else None)
+ name = res.get("name") or (row.name if row else None) or f"vm-{vmid}"
+
+ return TopologyGuest(
+ id=f"guest:{sid}:{vmid}",
+ server_id=sid,
+ node=node_name,
+ vmid=vmid,
+ type=vm_type,
+ name=name,
+ status=status,
+ is_template=is_template,
+ lock=res.get("lock"),
+ cpu=_to_float(res.get("cpu")),
+ cores=_to_int(res.get("maxcpu")) or (row.cores if row else None),
+ mem=_to_int(res.get("mem")),
+ maxmem=_to_int(res.get("maxmem")) or (row.memory if row else None),
+ disk=_to_int(res.get("disk")),
+ maxdisk=_to_int(res.get("maxdisk")),
+ uptime=_to_int(res.get("uptime")),
+ tags=tags,
+ owner_id=row.owner_id if row else None,
+ owner_username=(row.owner.username if row and row.owner else None),
+ ip=ipam_by_key.get((sid, vmid)) or (row.ip_address if row else None),
+ nics=[
+ TopologyNic(**{k: v for k, v in nic.items() if k in TopologyNic.model_fields})
+ for nic in nics_by_key.get((sid, vmid), [])
+ ],
+ )
+
+ # cluster_name groups connections; a server without one stands alone.
+ cluster_buckets: Dict[str, Dict[str, Any]] = {}
+ for server in servers:
+ key = f"cluster:{server.cluster_name}" if server.cluster_name else f"cluster:server:{server.id}"
+ bucket = cluster_buckets.setdefault(key, {
+ "id": key,
+ "name": server.cluster_name or server.name,
+ "kind": "cluster" if server.cluster_name else "standalone",
+ "server_ids": [],
+ "online": False,
+ "nodes": {}, # node name -> TopologyNode, deduplicated per cluster
+ })
+ bucket["server_ids"].append(server.id)
+ if server.id in live:
+ bucket["online"] = True
+
+ data = live.get(server.id)
+ if data is None:
+ # Rebuild from the 10s VM cache so an offline server still shows up.
+ by_node: Dict[str, List[VMInstance]] = {}
+ for row in db_guests:
+ if row.server_id != server.id:
+ continue
+ by_node.setdefault(row.node or server.name, []).append(row)
+ for node_name, node_rows in by_node.items():
+ if node_name in bucket["nodes"]:
+ continue
+ guests = [g for g in (_build_guest(server.id, node_name, None, r) for r in node_rows) if g]
+ guests.sort(key=lambda g: g.vmid)
+ bucket["nodes"][node_name] = TopologyNode(
+ id=f"node:{server.id}:{node_name}",
+ server_id=server.id, server_name=server.name, node=node_name,
+ status="unknown", stale=True, guests=guests,
+ )
+ continue
+
+ guests_by_node: Dict[str, List[Dict[str, Any]]] = {}
+ for res in data["guests"]:
+ node_name = res.get("node")
+ vmid = _to_int(res.get("vmid"))
+ if not node_name or vmid is None:
+ continue
+ if not see_all and (server.id, vmid) not in owned_keys:
+ continue
+ guests_by_node.setdefault(node_name, []).append(res)
+
+ for node_res in data["nodes"]:
+ node_name = node_res.get("node")
+ if not node_name or node_name in bucket["nodes"]:
+ continue # same PVE cluster reachable through two connections
+ bridges = []
+ for entry in data["bridges"].get(node_name, []):
+ ipam_net = ipam_by_bridge.get((server.id, entry["name"]))
+ bridges.append(TopologyBridge(
+ **entry,
+ ipam_network_id=ipam_net.id if ipam_net else None,
+ ipam_cidr=ipam_net.network if ipam_net else None,
+ ipam_name=ipam_net.name if ipam_net else None,
+ ))
+ guests = [
+ g for g in (
+ _build_guest(server.id, node_name, res,
+ db_by_key.get((server.id, _to_int(res.get("vmid")))))
+ for res in guests_by_node.get(node_name, [])
+ ) if g
+ ]
+ guests.sort(key=lambda g: g.vmid)
+ bucket["nodes"][node_name] = TopologyNode(
+ id=f"node:{server.id}:{node_name}",
+ server_id=server.id,
+ server_name=server.name,
+ node=node_name,
+ status=node_res.get("status") or "unknown",
+ stale=False,
+ cpu=_to_float(node_res.get("cpu")),
+ maxcpu=_to_int(node_res.get("maxcpu")),
+ mem=_to_int(node_res.get("mem")),
+ maxmem=_to_int(node_res.get("maxmem")),
+ uptime=_to_int(node_res.get("uptime")),
+ bridges=bridges,
+ guests=guests,
+ )
+
+ clusters = [
+ TopologyCluster(
+ id=b["id"], name=b["name"], kind=b["kind"],
+ server_ids=b["server_ids"], online=b["online"],
+ nodes=sorted(b["nodes"].values(), key=lambda n: n.node),
+ )
+ for b in cluster_buckets.values()
+ ]
+ clusters.sort(key=lambda c: (c.kind != "cluster", c.name.lower()))
+
+ node_count = sum(len(c.nodes) for c in clusters)
+ guest_count = sum(len(n.guests) for c in clusters for n in c.nodes)
+
+ return NetworkTopologyResponse(
+ generated_at=datetime.now(timezone.utc),
+ panel=TopologyPanelSummary(
+ cluster_count=len(clusters), node_count=node_count, guest_count=guest_count,
+ ),
+ clusters=clusters,
+ warnings=warnings,
+ )
diff --git a/backend/app/proxmox/__init__.py b/backend/app/proxmox/__init__.py
index 0ebafd3..7483d26 100644
--- a/backend/app/proxmox/__init__.py
+++ b/backend/app/proxmox/__init__.py
@@ -1,9 +1,13 @@
from .client import ProxmoxClient, get_proxmox_resources, _run_in_executor, clear_all_cache, clear_server_cache
+from .net_parser import ParsedNic, parse_net_string, parse_guest_nics
__all__ = [
'ProxmoxClient',
'get_proxmox_resources',
'_run_in_executor',
'clear_all_cache',
- 'clear_server_cache'
+ 'clear_server_cache',
+ 'ParsedNic',
+ 'parse_net_string',
+ 'parse_guest_nics',
]
diff --git a/backend/app/proxmox/net_parser.py b/backend/app/proxmox/net_parser.py
new file mode 100644
index 0000000..af52ca3
--- /dev/null
+++ b/backend/app/proxmox/net_parser.py
@@ -0,0 +1,139 @@
+"""Parser for Proxmox ``netN`` guest NIC strings.
+
+Proxmox stores every guest network card as one comma-separated key=value
+string in the guest config (``net0``, ``net1``, …). Two dialects exist:
+
+* QEMU — ``virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=100,firewall=1``
+ The NIC model is itself the key holding the MAC address.
+* LXC — ``name=eth0,bridge=vmbr0,hwaddr=AA:BB:CC:DD:EE:FF,ip=10.0.0.5/24,``
+ ``gw=10.0.0.1,type=veth,firewall=1``
+
+The repository only ever *builds* these strings (``api/proxmox/lxc.py``,
+``proxmox/mixins/vm.py``); this module reads them back so callers can learn
+which bridge/VLAN a guest actually sits on.
+
+Deliberately free of any ``proxmoxer`` import so both the API layer and the
+client mixins can use it. Parsing never raises: an unparsable token is skipped
+rather than failing the whole request.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+import re
+
+# NIC models QEMU accepts. The model name doubles as the key carrying the MAC,
+# which is the only way to tell "virtio=AA:.." from an ordinary option.
+QEMU_MODELS = {
+ "virtio", "e1000", "e1000e", "e1000-82540em", "e1000-82544gc",
+ "e1000-82545em", "rtl8139", "vmxnet3", "ne2k_pci", "ne2k_isa",
+ "pcnet", "i82551", "i82557b", "i82559er",
+}
+
+_NET_KEY_RE = re.compile(r"^net(\d+)$")
+
+
+@dataclass
+class ParsedNic:
+ """One guest network interface, normalised across the QEMU/LXC dialects."""
+
+ key: str # "net0"
+ index: int # 0
+ model: Optional[str] = None # virtio / e1000 / … (QEMU only)
+ mac: Optional[str] = None # uppercase, from model= or hwaddr=
+ bridge: Optional[str] = None # vmbr0 or an SDN vnet
+ vlan_tag: Optional[int] = None
+ trunks: List[int] = field(default_factory=list)
+ firewall: bool = False
+ link_down: bool = False
+ name: Optional[str] = None # LXC: name=eth0
+ ip: Optional[str] = None # LXC: "10.0.0.5/24" or "dhcp"
+ ip6: Optional[str] = None
+ gw: Optional[str] = None
+ gw6: Optional[str] = None
+ rate: Optional[float] = None # MB/s
+ mtu: Optional[int] = None
+ queues: Optional[int] = None
+ raw: str = ""
+
+ def to_dict(self) -> Dict[str, Any]:
+ return asdict(self)
+
+
+def _as_int(value: str) -> Optional[int]:
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _as_float(value: str) -> Optional[float]:
+ try:
+ return float(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _as_bool(value: str) -> bool:
+ return str(value).strip().lower() in ("1", "true", "yes", "on")
+
+
+def parse_net_string(key: str, value: str) -> ParsedNic:
+ """Parse a single ``netN`` value. Never raises."""
+ match = _NET_KEY_RE.match(key or "")
+ nic = ParsedNic(key=key or "", index=int(match.group(1)) if match else 0, raw=value or "")
+
+ for token in (value or "").split(","):
+ token = token.strip()
+ if not token or "=" not in token:
+ # Bare tokens (rare, e.g. a stray flag) carry nothing we need.
+ continue
+ opt, _, raw_val = token.partition("=")
+ opt = opt.strip().lower()
+ raw_val = raw_val.strip()
+
+ if opt in QEMU_MODELS:
+ nic.model = opt
+ nic.mac = raw_val.upper() or None
+ elif opt == "hwaddr":
+ nic.mac = raw_val.upper() or None
+ elif opt == "bridge":
+ nic.bridge = raw_val or None
+ elif opt == "tag":
+ nic.vlan_tag = _as_int(raw_val)
+ elif opt == "trunks":
+ nic.trunks = [v for v in (_as_int(p) for p in raw_val.split(";")) if v is not None]
+ elif opt == "firewall":
+ nic.firewall = _as_bool(raw_val)
+ elif opt == "link_down":
+ nic.link_down = _as_bool(raw_val)
+ elif opt == "name":
+ nic.name = raw_val or None
+ elif opt == "ip":
+ nic.ip = raw_val or None
+ elif opt == "ip6":
+ nic.ip6 = raw_val or None
+ elif opt == "gw":
+ nic.gw = raw_val or None
+ elif opt == "gw6":
+ nic.gw6 = raw_val or None
+ elif opt == "rate":
+ nic.rate = _as_float(raw_val)
+ elif opt == "mtu":
+ nic.mtu = _as_int(raw_val)
+ elif opt == "queues":
+ nic.queues = _as_int(raw_val)
+
+ return nic
+
+
+def parse_guest_nics(config: Dict[str, Any]) -> List[ParsedNic]:
+ """Every ``netN`` entry of a QEMU/LXC config, ordered by interface index."""
+ nics: List[ParsedNic] = []
+ for key, value in (config or {}).items():
+ if not isinstance(key, str) or not _NET_KEY_RE.match(key):
+ continue
+ if not isinstance(value, str):
+ continue
+ nics.append(parse_net_string(key, value))
+ nics.sort(key=lambda n: n.index)
+ return nics
diff --git a/backend/app/schemas.py b/backend/app/schemas.py
index e7cabed..510dd47 100644
--- a/backend/app/schemas.py
+++ b/backend/app/schemas.py
@@ -861,3 +861,115 @@ class WorkspaceResponse(BaseModel):
class WorkspaceDetail(WorkspaceResponse):
servers: List[WorkspaceServerItem] = []
users: List[WorkspaceUserItem] = []
+
+
+# ==================== Network topology ====================
+# Response shape for GET /proxmox/api/network/topology. Deliberately a domain
+# hierarchy (panel → cluster → node → guest) rather than ready-made graph
+# nodes/edges: the frontend derives edges from nesting, and the grouping
+# threshold changes the rendered node count client-side without a round-trip.
+# Fields the graph does not draw yet (bridges, nic.bridge/vlan_tag, tags) are
+# the groundwork for the planned "group by VLAN / by tag" views.
+
+
+class TopologyNic(BaseModel):
+ """One guest network card, parsed out of its ``netN`` config string."""
+
+ key: str
+ model: Optional[str] = None
+ mac: Optional[str] = None
+ bridge: Optional[str] = None
+ vlan_tag: Optional[int] = None
+ trunks: List[int] = []
+ firewall: bool = False
+ link_down: bool = False
+ name: Optional[str] = None
+ ip: Optional[str] = None
+ gw: Optional[str] = None
+ rate: Optional[float] = None
+ mtu: Optional[int] = None
+
+
+class TopologyBridge(BaseModel):
+ """A bridge / bond / SDN vnet a guest can be attached to."""
+
+ name: str
+ type: Optional[str] = None
+ cidr: Optional[str] = None
+ vlan_aware: bool = False
+ ports: Optional[str] = None
+ active: bool = False
+ zone: Optional[str] = None
+ ipam_network_id: Optional[int] = None
+ ipam_cidr: Optional[str] = None
+ ipam_name: Optional[str] = None
+
+
+class TopologyGuest(BaseModel):
+ id: str
+ server_id: int
+ node: str
+ vmid: int
+ type: str # "qemu" | "lxc"
+ name: str
+ status: str # running | stopped | paused | unknown
+ is_template: bool = False
+ lock: Optional[str] = None
+ cpu: Optional[float] = None
+ cores: Optional[int] = None
+ mem: Optional[int] = None
+ maxmem: Optional[int] = None
+ disk: Optional[int] = None
+ maxdisk: Optional[int] = None
+ uptime: Optional[int] = None
+ tags: List[str] = []
+ owner_id: Optional[int] = None
+ owner_username: Optional[str] = None
+ ip: Optional[str] = None
+ nics: List[TopologyNic] = []
+
+
+class TopologyNode(BaseModel):
+ id: str
+ server_id: int
+ server_name: str
+ node: str
+ status: str # online | offline | unknown
+ stale: bool = False # True → rebuilt from cache, server unreachable
+ cpu: Optional[float] = None
+ maxcpu: Optional[int] = None
+ mem: Optional[int] = None
+ maxmem: Optional[int] = None
+ uptime: Optional[int] = None
+ bridges: List[TopologyBridge] = []
+ guests: List[TopologyGuest] = []
+
+
+class TopologyCluster(BaseModel):
+ id: str
+ name: str
+ kind: str # "cluster" | "standalone"
+ server_ids: List[int] = []
+ online: bool = False
+ nodes: List[TopologyNode] = []
+
+
+class TopologyWarning(BaseModel):
+ server_id: Optional[int] = None
+ server_name: Optional[str] = None
+ code: str # offline | no_credentials | error | nics_truncated
+ message: str
+
+
+class TopologyPanelSummary(BaseModel):
+ name: str = "PVEmanager"
+ cluster_count: int = 0
+ node_count: int = 0
+ guest_count: int = 0
+
+
+class NetworkTopologyResponse(BaseModel):
+ generated_at: datetime
+ panel: TopologyPanelSummary
+ clusters: List[TopologyCluster] = []
+ warnings: List[TopologyWarning] = []
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 00783d1..e82ad39 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -18,8 +18,10 @@
"@xterm/addon-fit": "^0.11.0",
"@xterm/addon-web-links": "^0.12.0",
"@xterm/xterm": "^6.0.0",
+ "@xyflow/react": "^12.8.0",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
+ "html-to-image": "^1.11.13",
"i18next": "^26.0.3",
"i18next-browser-languagedetector": "^8.2.1",
"lucide-react": "^1.7.0",
@@ -2033,6 +2035,15 @@
"integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
"license": "MIT"
},
+ "node_modules/@types/d3-drag": {
+ "version": "3.0.7",
+ "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
+ "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-selection": "*"
+ }
+ },
"node_modules/@types/d3-ease": {
"version": "3.0.2",
"resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
@@ -2063,6 +2074,12 @@
"@types/d3-time": "*"
}
},
+ "node_modules/@types/d3-selection": {
+ "version": "3.0.11",
+ "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.11.tgz",
+ "integrity": "sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==",
+ "license": "MIT"
+ },
"node_modules/@types/d3-shape": {
"version": "3.1.8",
"resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.8.tgz",
@@ -2084,6 +2101,25 @@
"integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==",
"license": "MIT"
},
+ "node_modules/@types/d3-transition": {
+ "version": "3.0.9",
+ "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
+ "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-selection": "*"
+ }
+ },
+ "node_modules/@types/d3-zoom": {
+ "version": "3.0.8",
+ "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.8.tgz",
+ "integrity": "sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-interpolate": "*",
+ "@types/d3-selection": "*"
+ }
+ },
"node_modules/@types/debug": {
"version": "4.1.13",
"resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz",
@@ -2162,7 +2198,7 @@
"version": "19.2.3",
"resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.2.3.tgz",
"integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==",
- "dev": true,
+ "devOptional": true,
"license": "MIT",
"peerDependencies": {
"@types/react": "^19.2.0"
@@ -2540,6 +2576,76 @@
"addons/*"
]
},
+ "node_modules/@xyflow/react": {
+ "version": "12.11.3",
+ "resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.11.3.tgz",
+ "integrity": "sha512-G3jogHz2GWUtIOkhavUGno2YzY9u6fILIJBttfsBendb0/HWB90JG+sOTAvlIMEwyvq9zgy9V9ZQSwyQjR5QzQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@xyflow/system": "0.0.80",
+ "classcat": "^5.0.3",
+ "zustand": "^4.4.0"
+ },
+ "peerDependencies": {
+ "@types/react": ">=17",
+ "@types/react-dom": ">=17",
+ "react": ">=17",
+ "react-dom": ">=17"
+ },
+ "peerDependenciesMeta": {
+ "@types/react": {
+ "optional": true
+ },
+ "@types/react-dom": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/@xyflow/react/node_modules/zustand": {
+ "version": "4.5.7",
+ "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz",
+ "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==",
+ "license": "MIT",
+ "dependencies": {
+ "use-sync-external-store": "^1.2.2"
+ },
+ "engines": {
+ "node": ">=12.7.0"
+ },
+ "peerDependencies": {
+ "@types/react": ">=16.8",
+ "immer": ">=9.0.6",
+ "react": ">=16.8"
+ },
+ "peerDependenciesMeta": {
+ "@types/react": {
+ "optional": true
+ },
+ "immer": {
+ "optional": true
+ },
+ "react": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/@xyflow/system": {
+ "version": "0.0.80",
+ "resolved": "https://registry.npmjs.org/@xyflow/system/-/system-0.0.80.tgz",
+ "integrity": "sha512-ywc3ZqG91brzWrH1WlwMdIX4goOfrpBy6AbLdVSaof/Xx9l138ijIKRExM6EkMro2F+OImGmSiA/WKcXvKVcfA==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-drag": "^3.0.7",
+ "@types/d3-interpolate": "^3.0.4",
+ "@types/d3-selection": "^3.0.10",
+ "@types/d3-transition": "^3.0.8",
+ "@types/d3-zoom": "^3.0.8",
+ "d3-drag": "^3.0.0",
+ "d3-interpolate": "^3.0.1",
+ "d3-selection": "^3.0.0",
+ "d3-zoom": "^3.0.0"
+ }
+ },
"node_modules/accepts": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -2956,6 +3062,12 @@
"url": "https://polar.sh/cva"
}
},
+ "node_modules/classcat": {
+ "version": "5.0.5",
+ "resolved": "https://registry.npmjs.org/classcat/-/classcat-5.0.5.tgz",
+ "integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==",
+ "license": "MIT"
+ },
"node_modules/cli-cursor": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz",
@@ -3269,6 +3381,28 @@
"node": ">=12"
}
},
+ "node_modules/d3-dispatch": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
+ "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
+ "license": "ISC",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-drag": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
+ "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
+ "license": "ISC",
+ "dependencies": {
+ "d3-dispatch": "1 - 3",
+ "d3-selection": "3"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
"node_modules/d3-ease": {
"version": "3.0.1",
"resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
@@ -3324,6 +3458,15 @@
"node": ">=12"
}
},
+ "node_modules/d3-selection": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
+ "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
+ "license": "ISC",
+ "engines": {
+ "node": ">=12"
+ }
+ },
"node_modules/d3-shape": {
"version": "3.2.0",
"resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
@@ -3369,6 +3512,41 @@
"node": ">=12"
}
},
+ "node_modules/d3-transition": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
+ "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
+ "license": "ISC",
+ "dependencies": {
+ "d3-color": "1 - 3",
+ "d3-dispatch": "1 - 3",
+ "d3-ease": "1 - 3",
+ "d3-interpolate": "1 - 3",
+ "d3-timer": "1 - 3"
+ },
+ "engines": {
+ "node": ">=12"
+ },
+ "peerDependencies": {
+ "d3-selection": "2 - 3"
+ }
+ },
+ "node_modules/d3-zoom": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
+ "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
+ "license": "ISC",
+ "dependencies": {
+ "d3-dispatch": "1 - 3",
+ "d3-drag": "2 - 3",
+ "d3-interpolate": "1 - 3",
+ "d3-selection": "2 - 3",
+ "d3-transition": "2 - 3"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
"node_modules/data-uri-to-buffer": {
"version": "4.0.1",
"resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
@@ -4716,6 +4894,12 @@
"void-elements": "3.1.0"
}
},
+ "node_modules/html-to-image": {
+ "version": "1.11.13",
+ "resolved": "https://registry.npmjs.org/html-to-image/-/html-to-image-1.11.13.tgz",
+ "integrity": "sha512-cuOPoI7WApyhBElTTb9oqsawRvZ0rHhaHwghRLlTuffoD1B2aDemlCruLeZrUIIdvG7gs9xeELEPm6PhuASqrg==",
+ "license": "MIT"
+ },
"node_modules/html-url-attributes": {
"version": "3.0.1",
"resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index 22e9e90..b613ce4 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -21,8 +21,10 @@
"@xterm/addon-fit": "^0.11.0",
"@xterm/addon-web-links": "^0.12.0",
"@xterm/xterm": "^6.0.0",
+ "@xyflow/react": "^12.8.0",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
+ "html-to-image": "^1.11.13",
"i18next": "^26.0.3",
"i18next-browser-languagedetector": "^8.2.1",
"lucide-react": "^1.7.0",
diff --git a/frontend/src/components/ui/slider.tsx b/frontend/src/components/ui/slider.tsx
new file mode 100644
index 0000000..67e9ef7
--- /dev/null
+++ b/frontend/src/components/ui/slider.tsx
@@ -0,0 +1,20 @@
+import { Slider as SliderPrimitive } from "@base-ui/react/slider"
+
+import { cn } from "@/lib/utils"
+
+function Slider({ className, ...props }: SliderPrimitive.Root.Props) {
+ return (
+ {t('topology.empty', 'No servers available')}
+ {t('topology.subtitle', 'Hierarchical map of clusters, nodes and guests')} +
+{t('topology.too_many', 'Too many objects; grouping enabled')}
+ ) : null} + + {/* Above the canvas normally; in fullscreen it moves inside, where it is + the only way to reach the filters. */} + {isFullscreen ? null : toolbar} + +