Networking Guide

Complete guide to QuantaVirt virtual networking — network modes, VirtIO-net and legacy NIC emulation, vhost acceleration, VLANs, PQC-encrypted tunnels, and firewall configuration. QuantaVirt provides flexible networking through software bridges, NAT, and direct physical NIC bridging.

Networking Overview #

Each VM connects to one or more virtual networks through emulated network interfaces. QuantaVirt manages virtual switches (bridges), DHCP, DNS forwarding, and NAT. Network traffic between VMs on the same bridge stays within the hypervisor; external traffic is routed through the host's physical NICs.

Virtual Networks #

# List all virtual networks
quantavirt network list
# NAME        MODE      BRIDGE    SUBNET            ACTIVE VMs
# default     nat       qvbr0     10.0.100.0/24     3
# internal    isolated  qvbr1     10.0.200.0/24     2
# office      bridge    qvbr2     (external DHCP)   5

# Show detailed network info
quantavirt network show default
# Name:       default
# Mode:       NAT
# Bridge:     qvbr0
# Subnet:     10.0.100.0/24
# Gateway:    10.0.100.1
# DHCP Range: 10.0.100.100 – 10.0.100.254
# DNS:        10.0.100.1 (forwarding to host resolv.conf)
# Attached:   ubuntu-server (52:54:00:a1:b2:c3 → 10.0.100.101)

# Delete a network (must have no attached VMs)
quantavirt network delete internal

NAT Mode #

NAT networks provide outbound internet connectivity for VMs while hiding them behind the host's IP address. QuantaVirt runs a built-in DHCP server and DNS forwarder on the bridge interface. Inbound connections require explicit port forwarding rules.

# Create a NAT network
quantavirt network create \
  --name devnet \
  --mode nat \
  --subnet 10.0.50.0/24 \
  --dhcp-start 10.0.50.100 \
  --dhcp-end 10.0.50.200

# Port forwarding: host:8080 → VM:80
quantavirt network forward devnet \
  --protocol tcp \
  --host-port 8080 \
  --guest-ip 10.0.50.101 \
  --guest-port 80

# List port forwards
quantavirt network forward-list devnet

Bridge Mode #

Bridged networking connects VMs directly to a physical network interface. VMs receive IP addresses from the physical network's DHCP server and appear as independent hosts on the LAN. This is the recommended mode for production server workloads.

# Create a bridged network attached to physical eth0
quantavirt network create \
  --name production \
  --mode bridge \
  --interface eth0

# Create bridged network with specific bridge name
quantavirt network create \
  --name dmz \
  --mode bridge \
  --interface eth1 \
  --bridge-name qvbr-dmz

Isolated Mode #

Isolated networks have no route to the host or external networks. VMs on an isolated network can only communicate with each other. This is ideal for backend database tiers, internal microservices, and testing environments.

# Create an isolated network
quantavirt network create \
  --name db-internal \
  --mode isolated \
  --subnet 10.0.200.0/24

Virtual NIC Types #

vhost Acceleration #

vhost moves the VirtIO data plane processing from the hypervisor's main loop into a dedicated kernel thread or userspace process, significantly improving network throughput and latency.

# In VM configuration JSON — vhost is enabled by default
"network": [{
  "type": "virtio-net",
  "network": "production",
  "queues": 4,
  "vhost": true,
  "offload": {
    "tso4": true,
    "tso6": true,
    "gso": true,
    "gro": true,
    "csum": true
  }
}]

VLANs #

QuantaVirt supports IEEE 802.1Q VLAN tagging on virtual networks. VMs can be placed on specific VLANs for network segmentation without requiring multiple physical NICs.

# Create a VLAN-tagged network on physical interface eth0
quantavirt network create \
  --name engineering \
  --mode bridge \
  --interface eth0 \
  --vlan 100

quantavirt network create \
  --name finance \
  --mode bridge \
  --interface eth0 \
  --vlan 200

# Attach VM to VLAN network
# In config: "network": [{ "type": "virtio-net", "network": "engineering" }]

PQC-Encrypted Tunnels #

QuantaVirt can encrypt all VM network traffic with post-quantum cryptography. PQC tunnels create point-to-point encrypted channels between hypervisor hosts, protecting VM-to-VM traffic from quantum-capable adversaries performing traffic capture.

# Create a PQC-encrypted tunnel network between two hosts
quantavirt network create \
  --name pqc-overlay \
  --mode tunnel \
  --tunnel-peer 192.168.1.20 \
  --tunnel-kem ML-KEM-768 \
  --tunnel-aead AES-256-GCM \
  --subnet 10.0.250.0/24

# Per-VM tunnel (encrypt only specific VM traffic)
"network": [{
  "type": "virtio-net",
  "network": "production",
  "pqc_tunnel": true
}]

# Check tunnel status
quantavirt network tunnel-status pqc-overlay
# Peer:        192.168.1.20
# State:       ESTABLISHED
# KEM:         ML-KEM-768 (QUAC 100 hardware)
# AEAD:        AES-256-GCM
# Session Key: rotated 2m ago (next rotation in 58m)
# Packets TX:  1,234,567  (encrypted)
# Packets RX:  1,234,401  (verified)

Firewall Rules #

QuantaVirt includes a built-in packet filter for virtual networks. Rules are applied at the bridge level and can filter by protocol, port, source/destination IP, and direction.

# Allow SSH to a specific VM
quantavirt network rule add default \
  --direction in \
  --protocol tcp \
  --dest-port 22 \
  --dest-ip 10.0.100.101 \
  --action accept

# Block all outbound traffic from a VM
quantavirt network rule add default \
  --direction out \
  --source-ip 10.0.100.105 \
  --action drop

# List firewall rules
quantavirt network rule list default

# Default policy: ACCEPT (all traffic allowed unless explicitly denied)
# Change default policy to DROP
quantavirt network rule set-policy default --default drop

Advanced Networking #

Jumbo Frames

# Set MTU on virtual network
quantavirt network set production --mtu 9000

# Per-VM MTU override in config
"network": [{ "type": "virtio-net", "network": "production", "mtu": 9000 }]

SR-IOV Passthrough

For maximum network performance, QuantaVirt supports SR-IOV passthrough. Physical NIC Virtual Functions (VFs) are assigned directly to VMs via IOMMU, bypassing the virtual switch entirely.

# Enable SR-IOV VFs on physical NIC
quantavirt system sriov enable --interface eth0 --num-vfs 8

# Assign VF to VM via PCI passthrough
quantavirt vm set myvm --pci-add 0000:05:02.0  # VF BDF address

Multi-NIC Configuration

# VM with three NICs on different networks
"network": [
  { "type": "virtio-net", "network": "management", "mac": "52:54:00:00:01:01" },
  { "type": "virtio-net", "network": "production", "mac": "52:54:00:00:01:02", "queues": 8 },
  { "type": "virtio-net", "network": "storage-net", "mac": "52:54:00:00:01:03", "mtu": 9000 }
]

Network Troubleshooting #