Pathbox installation guide

Install the Swift Fox Pathbox inline appliance on your own hardware: NIC and BIOS requirements, the VPP and pathbox apt repositories, preflight checks, and web-UI provisioning for line-rate per-subscriber fq_codel shaping.

This guide walks through installing Swift Fox Pathbox on an ISP-managed Linux host. At the end you’ll have a transparent L2 bridge shaping customer traffic with per-subscriber fq_codel, as well as optional captive disconnects, MPLS/TE balancing, bandwidth accounting and TCP latency monitoring.

If you’d rather buy pre-configured hardware from Swift Fox, contact us — the pre-flashed appliance is shipped ready-to-use.

Pathbox uses VPP (Vector Packet Processor) with custom in-house plugins to be able to handle millions of packets per second and line-rate throughput using commodity hardware.

1. Hardware requirements

Minimum specs

Validated NIC families

These are the NICs Swift Fox has tested end-to-end with VPP 26.02. Others may work if a compatible DPDK PMD exists, but Swift Fox cannot guarantee reliably performance outside these models.

The pathbox-ui preflight tool (installed with pathbox) detects your NICs against this list and warns if nothing matches.

Recommended by speed tier

2. BIOS configuration

Three settings matter. Names and locations vary by vendor; these are the most common.

• Intel VT-d (or AMD IOMMU / AMD-Vi): enable. Usually under Advanced → CPU Configuration, or Advanced → Chipset Configuration. Without this, VPP can’t bind NICs via vfio-pci.

• Hyper-Threading: disable. HT pairs two threads on a single physical core that contend for the same execution units, which adds jitter to VPP worker performance — DPDK’s recommendation is HT-off for deterministic latency.

• C-states / power management: for best latency, disable aggressive C-states (C1E, C3, C6, etc.). On a server this rarely matters, but on small fanless boxes some ship with deep C-states enabled by default that add several µs of jitter. Set “max performance” / “max power” profile if in doubt.

You don’t need to enable PXE, serial console, or anything network-related in BIOS for pathbox.

3. OS installation

Supported Linux distributions

Pathbox is published for all three of:

• Ubuntu 22.04 LTS (Jammy)
• Ubuntu 24.04 LTS (Noble)
• Debian 12 (Bookworm)

The same install process works for all three, the scripts below detect which one you’re running and configure the apt sources for you.

Install one of the other supported distros from the standard installer. Default partitioning is fine. Network setup at first can be whatever gets the server online to download packages — we’ll configure pathbox networking via the web UI later.

Pick the right network interface for install. If your machine has more than two NICs (e.g. two 10 G ports for the customer bridge plus an on-board 1 G management port), do the OS install on the spare port — not on one of the NICs you plan to bridge with pathbox. If your machine only has the two bridge NICs (no spare), you may want to use a USB ethernet adapter, console, or IPMI to maintain access during setup.

VPP also requires a few kernel boot parameters (IOMMU, hugepages, CPU isolation), but the exact values depend on hardware preflight has yet to inspect — we’ll set them in Step 8 once preflight has emitted a hardware-tuned recommendation.

4. Add the fd.io VPP apt repository

Pathbox is built against, and pinned to, VPP 26.02, which is published by the fd.io project. Add fd.io’s 26.02 release repo before installing pathbox:

curl -s https://packagecloud.io/install/repositories/fdio/2602/script.deb.sh | sudo bash

sudo apt-get update

Use exactly this repo — not fd.io’s rolling release repo. The rolling repo moves to newer VPP series on fd.io’s schedule, and a VPP release pathbox wasn’t built against will refuse to install (and wouldn’t be supported if forced). When pathbox moves to a newer VPP series, the release notes will include the updated repo step.

If you get an error about missing curl, you can install it with apt-get install curl

5. Add the Swift Fox pathbox apt repository

curl -fsSL https://deb.swift-fox.net/install.sh | sudo sh

This script adds the appropriate Swift Fox repo for your distribution.

6. Install pathbox

sudo apt-get install swiftfox-pathbox

This pulls in VPP and its plugin packages from fd.io, then installs the Swift Fox Pathbox runtime.

Only the pathbox-ui service is started at this point — the data-plane services (pathbox-apply, pathbox-rsvpd) are dormant until you finish the setup process. If you get an error about missing libmosquitto1, you may need to enable the universe repository for your Ubuntu/Debian repos.

7. Run preflight

pathbox-ui preflight

This surveys your system (CPU, RAM, IOMMU status, hugepages, NIC compatibility) and prints two things:

1. A pass/warn/fail report for each check.
2. A suggested configuration block at the bottom: the exact GRUB_CMDLINE_LINUX line for your hardware, and a pointer to pathbox-ui preflight --apply for the matching VPP startup.conf (covered in Step 9).

Some checks (IOMMU, hugepages, isolcpus) are expected to FAIL on a fresh box that hasn’t had its kernel boot parameters set yet. Other FAILs (e.g. nics_supported) are hardware issues and should be sorted out first:

8. Apply kernel boot parameters

VPP needs IOMMU, hugepages, and CPU isolation set in the kernel cmdline before it can run. The exact values depend on your CPU layout and which NUMA node your NIC lives on, which is why we waited until preflight had inspected the hardware.

Open /etc/default/grub in an editor, find the GRUB_CMDLINE_LINUX="..." line, and paste in the cmdline preflight emitted in its SUGGESTED CONFIGURATION block. A typical line looks like:

intel_iommu=on iommu=pt default_hugepagesz=2M hugepagesz=2M hugepages=1024 isolcpus=1-3 nohz_full=1-3 rcu_nocbs=1-3

What each parameter does:

• intel_iommu=on iommu=pt — binds the IOMMU for DPDK’s vfio-pci driver. (On AMD hardware preflight uses amd_iommu=on iommu=pt.)
• default_hugepagesz=2M hugepagesz=2M hugepages=1024 — pre-allocates 1024 × 2 MiB hugepages (~2 GiB) at boot. VPP uses these for its DPDK buffer pool.
• isolcpus=1-3 — reserves CPUs 1, 2, 3 for VPP worker threads; remaining cores run the kernel scheduler + our management daemons. Preflight picks the exact CPU range based on your NIC’s NUMA node.
• nohz_full=1-3 rcu_nocbs=1-3 — further isolates those cores from kernel ticks and RCU callbacks. Latency-determinism improvement.

NUMA affinity (what preflight does for you)

On single-socket boxes (one CPU package, one NUMA node), preflight just isolates the cores that aren’t reserved for management.

On multi-socket boxes or AMD EPYC with multiple NUMA nodes per CCD, VPP workers must run on the same NUMA node as the NIC — cross-node memory traffic goes over the inter-socket link (UPI/Infinity Fabric) and tanks throughput. Preflight reads /sys/bus/pci/devices/<addr>/numa_node for each supported NIC and emits an isolcpus/corelist-workers set drawn from that node’s CPUs, with the main thread parked on a different node when possible so kernel scheduling never contends with VPP workers.

Apply and reboot

sudo nano /etc/default/grub      # paste into GRUB_CMDLINE_LINUX
sudo update-grub
sudo reboot

After the reboot, re-run pathbox-ui preflight. The IOMMU, hugepages, and isolcpus checks should now be green.

9. Configure VPP for your hardware

The fastest path is to let preflight write /etc/vpp/startup.conf for you, based on the hardware it just detected:

sudo pathbox-ui preflight --apply

This generates a stripped-down startup.conf with the cpu, dpdk, memory, and buffers config tuned for your box (NIC PCI addresses, NIC NUMA node, worker CPU set). If /etc/vpp/startup.conf already exists, the command refuses unless you pass --force (the previous file is renamed to startup.conf.bak.<timestamp> first).

You don’t need to restart VPP after this — the next step (web UI network configuration) restarts the data plane stack automatically when you click Apply.

10. Finish setup via the web UI

Open https://<your-pathbox-ip>/ in a browser. You’ll get a TLS certificate warning (self-signed cert for the host IP) — accept it.

1. Sign in with admin / admin. You’ll be forced to change the password before anything else.

2. Go to Network and configure:

   • Pathbox IP / prefix — this pathbox’s IP on the bridge subnet. This should be a /29 or higher as it must be able to reach both the upstream and (if used) downstream routers, and it should be different from any other IP bound to the device
   • Upstream router IP — your bgp/gateway-facing router
   • Downstream router IP (optional) — your aggregation/customer-facing router. Only needed if this pathbox will participate in MPLS/TE routing — used by the Swift Fox cloud to place it in the routing graph. Leave blank for shaping / latency / netflow / captive disconnect-only deployments (which is most pathboxes).
   • Upstream / Downstream port — pick the interfaces from the dropdown (populated from VPP’s detected interfaces). These will be bridged together and is where customer traffic will flow.
   • MTUs — leave 0 to use the interface default shown, or set explicitly (see the notes about MPLS framing below)

3. Go to Provisioning and paste your Swift Fox provisioning key (can be found from the “Routing Analysis -> Configure” menu in Swift Fox, once the pathbox device has been added to your netmap).

4. Click Apply network configuration. This enables pathbox-apply + pathbox-rsvpd, restarts the data plane, and fetches your ISP’s config from the Swift Fox cloud.

5. After apply, visit the Dashboard. You should see:

   • Network configuration populated
   • Last apply timestamp set to “just now”
   • (Within ~60 seconds) the Shaper page populates with your subscribers if configured

11. Verify

• Shaper page should show per-CPE rates after the first cloud sync (usually within 60 seconds), if queue syncing is enabled in Swift Fox.
• Disconnect page should show a captive IP (the Swift Fox captive server) and any disconnected customers, if captive disconnect is enabled in Swift Fox.
• Network page should show an MTU probe result after ~30 seconds. If the probe reports “too low”, your downstream router’s port MTU needs to be ≥ 1508 (or ≥ 1512 with VLAN tags) to accept post-MPLS-label frame sizes.
• Customer speed test from a provisioned CPE should measure close to their plan rate. If it’s significantly below (say, 47 Mbps on a 50 Mbps plan), see the “Shaper” page’s rate multiplier — the default of 1.046 compensates for VLAN + TCP framing overhead, but extra headers (MPLS stacks, PPPoE, GRE) or non-standard MTUs may need tuning.

12. Routine operations

Checking for updates

Updates appear as a blue banner in the pathbox-ui when available. Click it to open the Updates page, review the version diff, then click Apply upgrade during a maintenance window. This runs apt-get update and apt-get install --only-upgrade swiftfox-pathbox. VPP restarts; ~30 seconds of traffic interruption.

You can also check / apply from the CLI:

sudo apt-get update
sudo apt-get install --only-upgrade swiftfox-pathbox

Reading logs

sudo journalctl -u pathbox-ui    -f
sudo journalctl -u pathbox-apply -f
sudo journalctl -u pathbox-rsvpd -f
sudo journalctl -u vpp           -f

Restarting services

The three pathbox services are linked by systemd’s PartOf so restarting VPP cascades down:

sudo systemctl restart vpp
# also restarts pathbox-apply + pathbox-rsvpd + pathbox-ui

Restart an individual service if needed:

sudo systemctl restart pathbox-rsvpd

13. Troubleshooting

”I clicked Apply but customer traffic still isn’t flowing”

1. Check journalctl -u pathbox-apply -b -0 for errors bringing up VPP.
2. Check journalctl -u pathbox-rsvpd -b -0 for MQTT connection errors — if the provision key is wrong, rsvpd will fail to connect.
3. On the Shaper page, confirm subscribers are populated. If the page says “Awaiting first shaper sync”, the cloud hasn’t pushed anything yet — contact Swift Fox if you have issues with provisioning.

”Speed tests measure way below plan”

See the Shaper page’s rate multiplier setting. If your network uses MPLS, PPPoE, or double VLAN tags, your effective framing overhead is higher than the default 4.6%. Bump the multiplier up (e.g. 1.08) until your speed tests land at plan rate.

”MTU probe says ‘too low’”

The downstream router’s port MTU is below 1508 (or below 1512 with VLANs). bridge_mpls adds a 4-byte label, pushing frames past the port’s L2 MTU. On MikroTik, set /interface ethernet set mtu=1508 on the port facing pathbox.

”pathbox-ui won’t start”

sudo journalctl -u pathbox-ui -b -0 | tail -50

pathbox-ui is designed to start on a fresh box with no config — it boots into a setup wizard and binds to whatever IP the kernel currently has. If it’s failing anyway, common causes:

• Port 443/80 already in use (some other web server installed?). Stop the conflicting service or change pathbox-ui’s flags in /lib/systemd/system/pathbox-ui.service.
• /etc/pathbox/ not writable (TLS cert generation fails). Check ownership: should be root:root 0755.

”Setup wizard not reachable”

The first boot’s journal prints the URLs to use, e.g.:

HTTPS listening on :443
  Setup wizard reachable at:
    https://192.168.1.42/
    https://10.0.0.5/

Browsers will warn about the self-signed cert — click through. After you set pathbox_ip and apply, the cert is regenerated to include the new IP and you can reach the UI on either the old kernel-leased IP or the new pathbox IP.

”Need to start over”

sudo apt-get purge swiftfox-pathbox
# wipes /etc/pathbox/ and /var/lib/pathbox/
sudo apt-get install swiftfox-pathbox
# fresh setup

Getting help

• Hardware compatibility questions: pathbox-ui preflight output
• Cloud-side provisioning: contact Swift Fox support
• Data plane bugs / unexpected behavior: collect sudo journalctl -u pathbox-rsvpd --since "1 hour ago" and the output of sudo vppctl show runtime, send to Swift Fox support.