Masquerade — dynamic source NAT for the WAN interface

Masquerade is a special form of source NAT that uses the egress interface’s current IP address at translation time. The operator does not specify the translation address; the kernel uses whatever address is currently assigned to the egress interface.

The masquerade pattern is the production default for dynamic WAN IP scenarios:

• DHCP — the WAN IP is assigned by the ISP’s DHCP server. The IP can change at any lease renewal.
• PPPoE — the WAN IP is assigned by the PPPoE server. The IP can change at any reconnect.
• Mobile broadband — the WAN IP is assigned by the mobile carrier. The IP can change frequently.

For these scenarios, static SNAT (which requires a specific translation address) is fragile: if the WAN IP changes, the SNAT rule’s translation address is wrong, and the outbound traffic is translated to an address that is not assigned to any interface. The reply traffic cannot reach the router; the connection fails.

This lesson covers the masquerade pattern, the conntrack interaction, the masquerade vs static SNAT tradeoff, and the production failure modes.

Configuring masquerade

The masquerade rule is a SNAT rule whose translation address is the keyword masquerade rather than a literal address:

# Masquerade outbound traffic on eth0 (the WAN interface)
set nat source rule 10 outbound-interface name eth0
set nat source rule 10 source address 192.168.1.0/24
set nat source rule 10 translation address 'masquerade'

commit

The translation address clause is required, and masquerade is what makes it dynamic: the kernel substitutes the current primary address of the outbound interface at translation time, so the rule survives a DHCP lease change without being rewritten.

Leaving the clause out does not give you masquerade. It gives you a rule that matches traffic and translates nothing, so packets leave the router with their RFC 1918 source addresses intact and the return traffic never comes back. That failure is the subject of the break/fix scenario vyos-bf-nat-wrong, and it is silent from the router’s own point of view - the router’s own traffic is unaffected, so ping from the CLI still works.

The conntrack entry reflects this:

tcp 6 300 ESTABLISHED src=192.168.1.100 dst=198.51.100.5
  sport=52012 dport=443 packets=12 bytes=1844 [ASSURED]
  src=198.51.100.5 dst=<current-WAN-IP> sport=443 dport=52012
  packets=8 bytes=4096

The reply direction has the current WAN IP, not a specific address. If the WAN IP changes, the existing conntrack entries still have the old WAN IP — they will not work after the change.

Masquerade vs static SNAT

The masquerade and static SNAT patterns have different tradeoffs:

The performance difference is small (a single interface address lookup per NEW packet). For most production routers, the difference is in the noise.

The functional difference is significant: masquerade adapts to WAN IP changes; static SNAT requires manual update.

flowchart LR
  P["Outbound packet"]
  SA["Static SNAT<br/>translation address: 203.0.113.10<br/>(fixed)"]
  MA["Masquerade<br/>translation address: current eth0 IP<br/>(dynamic)"]
  CT["conntrack entry<br/>with translated source"]
  NET["Packet leaves on eth0"]

  P --> SA
  P --> MA
  SA --> CT
  MA --> CT
  CT --> NET

For dynamic WAN IP scenarios, masquerade is the only safe choice. For static WAN IP scenarios, either pattern works; static SNAT is slightly faster but masquerade is more robust against operator error (the operator does not have to remember the WAN IP).

The WAN IP change scenario

The production scenario: the WAN IP changes (DHCP lease renewal, PPPoE reconnect, ISP-side change). The masquerade rule continues to work for new connections; existing connections break.

# Before WAN IP change
eth0: 203.0.113.10
conntrack: src=192.168.1.100 -> dst=198.51.100.5, reply dst=203.0.113.10

# After WAN IP change
eth0: 203.0.113.20
# Existing flows: conntrack entry still has reply dst=203.0.113.10
# Reply arrives at 203.0.113.10 (no longer our IP) — packet dropped by ISP
# Reply arrives at 203.0.113.20 (our new IP) — no conntrack entry, packet dropped by firewall
# New flows: masquerade uses 203.0.113.20, work correctly

The existing flows are silently broken. The new flows work. The operator sees a partial outage: existing SSH sessions work (if the WAN IP did not change for the SSH flow) but HTTP requests break.

Production discipline

Multiple WAN interfaces

The multi-WAN scenario (covered in Part XXXIX) uses masquerade on each WAN interface:

# Masquerade on WAN1
set nat source rule 10 outbound-interface name eth0
set nat source rule 10 source address 192.168.1.0/24
set nat source rule 10 translation address 'masquerade'

# Masquerade on WAN2
set nat source rule 20 outbound-interface name eth1
set nat source rule 20 source address 192.168.1.0/24
set nat source rule 20 translation address 'masquerade'

Each WAN interface has its own masquerade rule. The translation address is the current IP of the egress interface, so traffic on eth0 uses eth0’s IP and traffic on eth1 uses eth1’s IP.

The conntrack entries for traffic on eth0 have the reply direction with eth0’s IP; traffic on eth1 has the reply direction with eth1’s IP. The two are independent; a WAN IP change on eth0 does not affect eth1’s flows.

Operational commands

The masquerade state is exercised through the standard VyOS operational commands:

# Show the NAT rules
show nat source

# Show a specific rule
show nat source rule 10

# Show the current WAN IP
show interfaces ethernet eth0
sudo ip addr show eth0

# Show the conntrack entries
sudo conntrack -L
sudo conntrack -L -n

# Live event stream
sudo conntrack -E

# Flush the conntrack table
sudo conntrack -F

# Live packet capture
sudo tcpdump -ni eth0 'src net 192.168.1.0/24'

Rollback

The masquerade changes are rolled back the same way as any VyOS configuration change:

# Show the candidate diff
compare

# Revert to a previous revision
rollback 1
commit
save

# Or delete the rule and re-commit
delete nat source rule 10
commit
save

# Flush the conntrack table
sudo conntrack -F

The discipline: every masquerade change is followed by a conntrack flush.

Production discipline

Cross-course references

• Part XXXVIII-01 (XXXVIII-VyOS-NAT / SNAT vs DNAT concept) covers the underlying NAT primitives.
• Part XXXVIII-04 (XXXVIII-VyOS-NAT / one-to-one) covers the 1:1 static NAT pattern.
• Part XXXIX-02 (XXXIX-VyOS-MultiWAN / failover) covers the multi-WAN failover with masquerade.
• Part XXXIX-06 (XXXIX-VyOS-MultiWAN / troubleshoot) covers the diagnostic method for NAT issues.

Quiz