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:
The node checks the rendered ruleset with nft before it changes anything, and loads it in one transaction. Show what it loaded:
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:
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¶
- The router's firewall shows the chains these documents render.
- Config kinds lists every field.