Bypass file

The bypass file of an agent lists what stays on the machine’s physical network while it is joined: addresses that keep their route through the physical gateway, and, with lockdown, firewall exceptions. The agent reads it from VNET_BYPASS_FILE at start and again on SIGHUP (systemctl reload vnet-agent). vnet-roster writes one per machine that has bypass lines, as machines/<name>.bypass, to install as /etc/vnet/bypass.conf.

Format

Blank lines and lines whose first non-blank character is # are ignored. Five kinds of lines:

route <a.b.c.d/n>

The prefix keeps going through the physical gateway instead of the TUN. With lockdown it is also allowed in both directions, any protocol and port. A bare address is a /32. The prefix must not be 0.0.0.0/0 and must not overlap the overlay prefix.

out <iptables arguments> and in <iptables arguments>

A rule appended to the lockdown chain VNET_OUT or VNET_IN, before the final drop, exactly as written. The words are passed to iptables without a shell, so quotes and variables are not interpreted. Without lockdown these lines do nothing, and the agent says so at start.

out6 <ip6tables arguments> and in6 <ip6tables arguments>

The same for IPv6, which lockdown otherwise blocks entirely.

Example

# VDI broker and the organizers' DNS stay on the LAN
route 192.0.2.10
route 192.0.2.53/32
# the VDI gateway connects in
in  -p tcp -s 198.51.100.0/24 --dport 3389 -j ACCEPT
# organizers' SSH, over IPv6 too
in  -p tcp -s 198.51.100.0/24 --dport 22 -j ACCEPT
in6 -p tcp -s 2001:db8:100::/48 --dport 22 -j ACCEPT

How a route line is applied

Once the default route points into the TUN, the agent pins each route prefix:

  • a prefix inside a subnet the machine is directly on needs nothing, since the subnet route already wins;

  • a prefix the machine already routes through another gateway is left to that route;

  • anything else gets a route through the physical gateway that was the default before the agent joined.

The agent logs one of <prefix> stays on the physical network via <gw> dev <if> or <prefix> already has a route via ... for each. When a reload removes a line, its route is removed (Route <prefix> no longer bypasses the TUN).

Errors

A file with an error is refused as a whole: at start the agent stops, on a reload the previous rules stay in force (Bypass file reload failed).

Message

Cause

Bypass file line N: expected 'route a.b.c.d/n'

a route line without a prefix, with more than one, or malformed

Bypass file line N: a route for 0.0.0.0/0 would undo the default route through the TUN

a /0 route

Bypass file line N: <prefix> overlaps the overlay <overlay>

a route inside, or containing, the overlay prefix

Bypass file line N: '<kind>' needs iptables arguments

an in/out line with nothing after it

Bypass file line N: unknown line kind '...'

a first word other than the five above

Cannot open bypass file <path>

wrong path or permissions

An in/out line that parses but that iptables rejects is reported when the chains are built: the iptables error, then Bypass rule not installed: in .... The other rules are installed.