Migrating to 0.2.0

What changed

vmsan 0.2.0 replaces the iptables firewall backend with nftables. This is a significant change to how network isolation rules are applied and managed.

iptables to nftables

All firewall rules are now applied atomically via a single nftables Flush() call instead of ~38 sequential iptables commands. Each VM gets its own nftables table (vmsan_<vmId>) containing all rules, and cleanup is a single table deletion instead of rule-by-rule removal.

ICMP blocked by default

All ICMP traffic from VMs is now blocked. This prevents ICMP tunneling attacks. ICMP type 3 (destination unreachable) is still accepted via ct state related for established connections, preserving Path MTU Discovery.

UDP blocked by default

All UDP traffic is now blocked except DNS (port 53). This prevents UDP-based data exfiltration. Applications relying on UDP (QUIC/HTTP3, game servers, streaming) will not work from inside VMs. NTP (UDP 123) is also blocked -- Firecracker VMs use kvm-clock for time sync from the host.

Reserved port ranges

Ports 10053-10307, 10443-10697, and 10080-10334 are reserved for future DNS/SNI proxy and can no longer be used as published ports.

Migration steps

1. Stop all running VMs

sudo vmsan list --json | jq -r '.[] | select(.status == "running") | .id' | xargs -I{} sudo vmsan stop {}

2. Upgrade vmsan to 0.2.0

curl -fsSL https://vmsan.dev/install | bash

This also installs the new vmsan-nftables binary to ~/.vmsan/bin/.

3. Start VMs

sudo vmsan start <vmId>

nftables rules are applied automatically. No manual configuration is needed.

4. Old iptables rules

Legacy iptables rules from 0.1.0 are cleaned up automatically on the first vmsan stop with 0.2.0. You do not need to remove them manually.

5. If issues occur

If nftables does not work on your system, fall back to the legacy iptables backend:

VMSAN_LEGACY_IPTABLES=1 sudo vmsan start <vmId>

This is a temporary escape hatch. The iptables fallback will be removed in 0.3.0.

Breaking changes

ICMP blocked

ping from VMs no longer works. This is intentional to prevent ICMP tunneling. Note that --allowed-cidr does not re-enable ICMP -- it is a destination filter, not a protocol filter.

UDP blocked (except DNS)

Applications using QUIC, HTTP/3, game protocols, or other UDP-based transports will break. DNS continues to work via DNAT to the configured resolvers.

nftables required on host

The host kernel must support nftables (kernel 5.10 or later). The nf_tables kernel module must be loaded or built-in. Run sudo vmsan doctor to verify. Firecracker already requires kernel 5.10+, so this should not be a practical issue.

Reserved port ranges

The following port ranges are reserved and rejected by --publish-port validation:

• 10053-10307 (DNS proxy)
• 10443-10697 (SNI proxy)
• 10080-10334 (HTTP proxy)

Host firewall interaction

If the host runs ufw or firewalld, their FORWARD chains may interfere with vmsan nftables rules. In 0.1.0, vmsan inserted rules at position 1 in the shared iptables chain. In 0.2.0, vmsan uses separate nftables tables where any table's chain can independently drop a packet.

Run sudo vmsan doctor to detect active host firewalls. See the networking guide for workarounds.