Running as a Virtual Machine

AthenaBNG is a standard Debian 13 userspace stack on top of the Linux data plane — it makes no assumption about running on bare metal, so it runs equally well inside a hypervisor. This page covers Proxmox VE (KVM/QEMU); the same principles apply to plain libvirt/KVM, VMware, or Hyper-V.

A VM is a good fit for labs, PoCs, smaller deployments, and HA setups where you want to snapshot/migrate the BNG. For line-rate production forwarding, give the data-plane NIC to the guest directly (SR-IOV or PCI passthrough) — see Network configuration.

VM sizing

Resource	Minimum	Recommended	Notes
vCPU	2	4+	Scale with subscriber count and throughput. Set CPU type = host.
RAM	4 GB	8 GB+	Session DB + accel-ppp + FRR.
Disk	50 GB	50 GB+	Logs and the session database. virtio-scsi, SSD-backed.
NICs	2	3	Management + subscriber trunk + core/uplink (trunk and uplink may share one NIC via VLANs).

Network topology

Provisioning the guest

Two paths — the cloud image is fastest; the ISO install mirrors a physical build.

Option A — Debian 13 cloud image (cloud-init)

Fastest, unattended. Run these on the Proxmox host shell:

# 1. Fetch the Debian 13 (Trixie) generic cloud image
wget https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2

# 2. Create the VM (id 9000). host CPU + NUMA for data-plane performance.
qm create 9000 --name athenabng --memory 8192 --cores 4 --cpu host --numa 1 \
  --net0 virtio,bridge=vmbr0

# 3. Import the cloud image as the VM's system disk
qm set 9000 --scsihw virtio-scsi-single \
  --scsi0 local-lvm:0,import-from=$PWD/debian-13-genericcloud-amd64.qcow2,discard=on,ssd=1

# 4. Grow the disk to 50G (cloud images ship small; cloud-init auto-expands the FS)
qm disk resize 9000 scsi0 50G

# 5. Cloud-init drive + serial console (cloud images expect a serial console)
qm set 9000 --ide2 local-lvm:cloudinit \
  --boot order=scsi0 --serial0 socket --vga serial0

# 6. Cloud-init: login user, SSH key, and management addressing
qm set 9000 --ciuser athena \
  --sshkeys ~/.ssh/id_ed25519.pub \
  --ipconfig0 ip=10.0.0.20/24,gw=10.0.0.1

# 7. Boot
qm start 9000

Then attach the data-plane NIC(s) — see Network configuration — and continue with Installation (install the .deb).

Option B — Debian 13 ISO install

1. Upload the Debian 13 (Trixie) netinst ISO to a Proxmox storage.
2. Create a VM: 4 cores, 8192 MB, CPU type host, BIOS OVMF (UEFI) or SeaBIOS, machine q35, SCSI controller VirtIO SCSI single, a 50G disk with Discard + SSD emulation, and the ISO on the CD drive.
3. Install a minimal Debian 13 (standard system utilities + SSH server; no desktop).
4. Continue with Installation.

Disk configuration

• Controller: VirtIO SCSI single (--scsihw virtio-scsi-single).
• Options: enable Discard (discard=on) so freed blocks return to thin storage, and SSD emulation (ssd=1) on SSD/NVMe-backed storage.
• Size: 50 GB+ — logs and the session database live under /opt/athena-bng and /var.

Network configuration

This is the part that matters for a BNG. AthenaBNG performs dynamic VLAN (QinQ) demux inside the guest — the subscriber-facing interface must receive the fully tagged trunk, with the outer and inner tags intact, so abng-demux can create per-subscriber sub-interfaces. How you present that NIC decides both correctness and performance.

Management NIC

Standard: a virtio adapter on vmbr0. Nothing special.

# already added as net0 above; equivalently:
qm set 9000 --net0 virtio,bridge=vmbr0

Data-plane NIC (subscriber trunk + uplink)

Choose one of two approaches.

Recommended for production — SR-IOV or PCI passthrough

Give the physical NIC (or an SR-IOV Virtual Function) straight to the guest. The VM sees the real hardware, so QinQ, checksum/segmentation offloads, and throughput all behave exactly like bare metal — this is the only way to reach line rate at 10G+.

# PCI passthrough of a physical NIC (find the ID with: lspci | grep -i ethernet)
qm set 9000 --hostpci0 0000:01:00.1,pcie=1

# — or — attach a pre-created SR-IOV VF the same way (0000:01:10.0, etc.)

Requires IOMMU enabled on the host (intel_iommu=on / amd_iommu=on in the kernel cmdline, vfio-pci bound to the device). Inside the guest the NIC appears as a normal interface (e.g. enp6s0) — point your trunk/upstream interface config at it.

Simple (lab / lower throughput) — a dedicated bridge

Use a plain, non-VLAN-aware Linux bridge that owns the physical data NIC, and attach the VM NIC to it with no VLAN tag. A non-VLAN-aware bridge forwards frames untouched, so stacked 802.1ad (S-tag) + 802.1Q (C-tag) frames reach the guest intact.

Do not make the data-plane bridge VLAN-aware. A VLAN-aware bridge processes/filters the outer tag as 802.1Q, which collides with the guest doing its own QinQ demux. VLAN-aware bridges are fine for the management NIC, not the subscriber trunk.

On the Proxmox host, /etc/network/interfaces:

auto vmbr1
iface vmbr1 inet manual
    bridge-ports enp1s0f1      # the physical data-plane NIC
    bridge-stp off
    bridge-fd 0
    # NOT vlan-aware — pass all tags through untouched
    mtu 9000

Attach it to the guest with the per-NIC firewall off (so tagged frames aren't filtered) and multiqueue matching the vCPU count:

qm set 9000 --net1 virtio,bridge=vmbr1,queues=4,firewall=0,mtu=1

mtu=1 tells the virtio NIC to inherit the bridge MTU (9000 here) rather than the default 1500.

MTU / overhead

PPPoE (8 bytes) and QinQ (two 4-byte tags) push subscriber frames past the classic 1500-byte payload. Size the whole path — physical NIC, bridge, VM NIC, and the guest's trunk interface — to at least 1540 ("baby jumbo") so a full 1500-byte customer payload survives, or 9000 (jumbo) if your access/core network supports it. A too-small MTU anywhere on the path shows up as PPPoE sessions that establish but fail on large packets.

Offloads

With a dedicated bridge + virtio, if stacked-VLAN (QinQ) frames arrive malformed, disable VLAN offload on the host physical NIC:

ethtool -K enp1s0f1 rxvlan off txvlan off

Passthrough/SR-IOV guests manage offloads inside the VM and generally need no host-side changes.

After the guest is up

1. Install the software — follow Installation (the .deb is the quickest path).
2. Map your interface config to the VM's NICs — mgmt0 on net0, the trunk/uplink on the passthrough/bridged NIC. See Interfaces.
3. For throughput tuning (CPU pinning, queues, hugepages), see Performance Tuning.

Snapshots, HA & migration

Because the whole BNG is one VM, you get hypervisor snapshots, live migration, and Proxmox HA for free. Two caveats:

• Passthrough/SR-IOV disables live migration — the VM is tied to that host's hardware. Use a bridged data NIC if live migration matters more than peak throughput, or plan for cold migration.
• Snapshot before major config commits; the running/candidate config model already gives you rollback, but a VM snapshot is a cheap extra safety net.