Skip to content

Filter and translate traffic

This page shows how to filter what a router forwards and accepts, and how to translate addresses. A router without firewall documents forwards everything and accepts the node API and the traffic chalkos protects. The router's firewall explains the chains these documents add to.

Before you begin

The examples extend the router r1 of Set up a router, with its WAN on eth0, its LAN on eth1 and the VLAN interfaces vlan*, and its node API on eth1.

Group the interfaces into zones

A zone names the interfaces whose traffic the policies treat alike:

apiVersion: router.chalkos.dev/v1alpha1
kind: FirewallZone
metadata: {name: wan}
spec: {interfaces: [eth0]}
---
apiVersion: router.chalkos.dev/v1alpha1
kind: FirewallZone
metadata: {name: lan}
spec: {interfaces: [eth1, "vlan*"]}

Give each interface one zone. chalkctl refuses a name or glob that two zones hold, but it does not compare a glob with the names it matches: eth* in one zone and eth0 in another pass, and the policy whose name sorts first then takes eth0's connections. The zone local is the router itself and needs no document.

Put VRFs into zones

On a router with VRFs, a zone can hold a whole VRF in vrfs. The links that join the VRF later belong to the zone too:

apiVersion: router.chalkos.dev/v1alpha1
kind: FirewallZone
metadata: {name: tenant}
spec: {vrfs: [tenant]}

To split one VRF's links into several zones, name the links in interfaces and leave the VRF out of vrfs. A zone needs interfaces, vrfs or both, and a VRF is in one zone. A link of a VRF that a zone holds is in no other zone. The validator router refuses a zone that names a link, or a glob that may match one, of a VRF that another zone holds. It also refuses an interface or glob that matches a VRF's device, such as ten* beside the VRF tenant:

FirewallZone/x: spec.interfaces[0]: ten* matches tenant, the device of VRF tenant; name the VRF in vrfs

It refuses an interface of a VRF's own name, such as tenant, the same way. chalkctl validate and chalkctl config apply run the validator before chalkctl sends anything, and the router runs it again at the delivery.

Policies and NAT rules name these zones as any other. A policy between the zones of two VRFs forwards only what the VRFs' tables route, and importing routes puts the routes there. A NAT rule's in.interface and out.interface name links: the validator refuses one that matches a VRF's device and no link, such as internet or inter*, while * translates on every link.

Let the LAN reach the WAN

Without a policy between two zones, the router forwards everything. Once one policy goes between zones, the router forwards only what a policy accepts. It drops traffic between zones without a policy, and from or to an interface in no zone. Let the LAN reach the WAN:

apiVersion: router.chalkos.dev/v1alpha1
kind: FirewallPolicy
metadata: {name: lan-wan}
spec: {from: lan, to: wan, default: accept}

Replies to the LAN's connections pass, because the firewall accepts established connections. Nothing from the WAN reaches the LAN, since no policy goes from wan to lan.

The policy also stops the router forwarding between eth1 and the VLANs, which share the zone lan. Let them reach each other with a policy from the zone to itself:

apiVersion: router.chalkos.dev/v1alpha1
kind: FirewallPolicy
metadata: {name: lan-lan}
spec: {from: lan, to: lan, default: accept}

Allow connections to the router

A policy whose to is local filters connections to the router itself. Its rules match in order, and the first that matches decides. default takes the rest, and is drop unless the policy says otherwise:

apiVersion: router.chalkos.dev/v1alpha1
kind: FirewallPolicy
metadata: {name: wan-local}
spec:
  from: wan
  to: local
  rules:
    - {protocol: tcp, destinationPorts: [8080], source: {set: monitoring}, action: accept}
    - {protocol: tcp, destinationPorts: ["8443-8444"], source: {cidrs: [198.51.100.0/24, "2001:db8:3::/48"]}, action: accept}
---
apiVersion: router.chalkos.dev/v1alpha1
kind: AddressSet
metadata: {name: monitoring}
spec: {family: ipv6, prefixes: ["2001:db8:2::/64"]}

An AddressSet holds ranges of one family. A rule's source or destination names one in set, or lists address ranges in cidrs, one of the two; a rule without it matches every address. A port is a number from 1 to 65535, or a range "<first>-<last>" of two such numbers whose first is no higher than its last. A policy cannot drop what the firewall accepts before it: chalkd's port on the management interfaces, pings, ICMP errors, neighbour discovery and established connections. Nor does it filter DHCPv4 on the links a DHCPSubnet serves: the DHCP server reads it ahead of the firewall. DHCPv6 on an IPv6 subnet's link and DHCP on a relay's links pass openings that the firewall adds before the policies, as Lease addresses with DHCP describes.

Masquerade and forward ports

NATRule documents translate addresses, with or without policies. Masquerade the LAN's IPv4 out of the WAN, and forward the WAN's port 8443 to a server on the LAN:

apiVersion: router.chalkos.dev/v1alpha1
kind: NATRule
metadata: {name: masquerade}
spec:
  type: masquerade
  out: {zone: wan}
  match: {source: [192.0.2.0/24]}
---
apiVersion: router.chalkos.dev/v1alpha1
kind: NATRule
metadata: {name: web}
spec:
  type: dnat
  in: {zone: wan}
  match: {protocol: tcp, destinationPorts: [8443]}
  to: {address: 192.0.2.10, port: 443}

A rule translates IPv4 unless its family is ipv6. snat translates the source to to.address instead of the interface's address. The router forwards what a dnat rule translated without a policy of its own.

NAT rules leave the connections of a NAT64 alone: they leave from the addresses of its pool, or an empty pool's own masquerade translates them. The forward chain accepts a NAT64's translated traffic ahead of the policies, so no policy filters it. A NAT rule may not translate to an address of a NAT64's pool, nor a dnat rule match a destination in a pool or a NAT64 prefix. No zone holds a NAT64's link n64-<name>: the validator router refuses a zone whose interfaces name or glob one, such as *, and a NAT rule whose interface matches NAT64 links alone. Translate to IPv4 and resolve names sets a NAT64 up.

Deliver and check the firewall

Validate the files and deliver them as for any config:

chalkctl validate
chalkctl config apply r1 --secrets secrets.age

The node checks the rendered ruleset with nft before it changes anything, and loads it in one transaction. Show what it loaded:

chalkctl node diag r1 --secrets secrets.age nft-ruleset

When nft refuses the rendered ruleset at boot, the router loads the fallback ruleset instead, which accepts chalkd's port on every interface and forwards nothing. The firewall's journal then reads nft refused /run/chalkos/outputs/router-nftables/ruleset.nft; loading the fallback ruleset, which forwards nothing:

chalkctl logs r1 --secrets secrets.age --unit=chalkos-firewall.service

The next delivery that changes the firewall documents loads the rendered ruleset again.

Fix a refused delivery

chalkctl refuses documents before it sends anything: a value the kind's schema does not take, such as a range of ports that runs backwards, a field that names a document the config lacks, a value that two documents share where the kind takes it once, what the rules of the router kinds refuse, and what the validator router refuses. Each message names the document.

The schemas, the references and the rules refuse these:

Message Fix
FirewallPolicy "wan-local": - at '/spec/rules/1/destinationPorts/0': '8444-8443' is not valid port-range: a range of ports is "<first>-<last>", each from 1 to 65535, and the first no higher than the last Write the lower port first.
FirewallPolicy/lan-dmz: spec.to: FirewallZone "dmz" does not exist Add the zone, or name one that exists.
FirewallZone/lan: spec.interfaces[0], FirewallZone/wan: spec.interfaces[1]: "eth1" is not unique; give each interface one zone Keep the interface in one zone.
FirewallZone/guest: spec.vrfs[0]: VRF "guest" does not exist Add the VRF document, or fix the name in vrfs.
FirewallZone/guest, FirewallZone/lan: spec.vrfs[0] "tenant" is not unique; give each VRF one zone Keep the VRF in one zone, or name its links in the zones instead.
FirewallPolicy/lan-wan, FirewallPolicy/web: (spec.from, spec.to) ("lan", "wan") is not unique; give each pair of zones one policy Merge the policies' rules into one.
FirewallPolicy/wan-local: spec.rules[0].source.set: AddressSet "monitoring" does not exist Add the AddressSet, or fix the name in set.
NATRule web has addresses of another family than ipv4 Set family: ipv6, or give IPv4 addresses.

Built-ins lists every rule of the router kinds.

The validator router checks the zones and NAT rules against the links that the Network, VRF and NAT64 documents give. It reports every fault it finds at once, after the config is refused:, and the router runs it again at the delivery:

Message Fix
FirewallZone/x: spec.interfaces[0]: ten* matches tenant, the device of VRF tenant; name the VRF in vrfs Put the VRF into the zone's vrfs, or name its links.
FirewallZone/x: spec.interfaces[0]: FirewallZone x names eth2, which may be a link of VRF tenant, which FirewallZone tenant holds; give each link one zone Take the VRF out of the other zone's vrfs and name its links in each zone, or drop the link here.
FirewallZone/lan: spec.interfaces[0]: * matches n64-guest, the link of NAT64 guest, which no zone holds; name other links Name the zone's links without a glob that matches n64-<name>.
NATRule/n: spec.out.interface: inter* matches no link, only internet, the device of VRF internet; name the VRF's links or a zone of the VRF Name the VRF's links, or a zone that holds the VRF.
NATRule/n: spec.out.zone: the zone x holds no link Give the zone links, or name another zone.
NATRule/web: spec.to.address: to.address 203.0.113.5 lies in 203.0.113.0/28, the pool of NAT64 edge, whose addresses belong to the NAT64 whole; translate to an address outside the pool Translate to an address outside every NAT64's pool.

Separate routing with VRFs lists its other refusals of zones and VRFs.

What next