Translate to IPv4 and resolve names¶
This page shows how a router gives IPv6-only clients the IPv4 internet. A NAT64 translates their
connections to addresses of a NAT64 prefix into IPv4 connections. A Resolver answers their DNS
queries. With DNS64 it answers for a name that has only A records with AAAA records in that
prefix. Both work in the default VRF and in each other VRF.
NAT64 and DNS64 on a router explains how chalkos runs
both.
Before you begin¶
You need a router set up as Set up a router describes, and the secrets file. Its
image must carry Jool for NAT64 and Unbound for the resolver. Router images do unless their
modules set the image option
chalkos.router.nat64.enable or
chalkos.router.resolver.enable
to false. An image without one refuses its documents: chalkctl validate reports that it
does not accept kind "NAT64" or does not accept kind "Resolver". A resolver's dns64 does
not need a NAT64 on the same router; it may synthesise addresses for a NAT64 another router runs.
The examples configure the fabric edge r1 of Route with BGP:
- Its IPv6-only clients are in
2001:db8::/32, behindeth1andeth2. - Its uplink
eth0reaches the IPv4 internet. - It announces
192.0.2.0/24to its transit provider, so the provider routes those addresses to it.
A NAT64's connections leave from IPv4 addresses that the uplink routes to the router. With an
empty pool4 they leave from the address of the uplink they leave through. The firewall's NAT
rules leave them alone either way.
Add a NAT64¶
A NAT64 is one translator. It takes the well-known prefix 64:ff9b::/96 unless prefix says
otherwise:
apiVersion: router.chalkos.dev/v1alpha1
kind: NAT64
metadata: {name: edge}
spec:
pool4: [{prefix: 192.0.2.252/30}]
A client's connection to 64:ff9b::c633:6402 leaves the router as a connection to
198.51.100.2, the IPv4 address that the last 32 bits embed. It leaves from an address and port
of pool4. Each entry of pool4 gives:
prefix: IPv4 addresses, 65536 at most.ports: a port or a range<first>-<last>, by default61001-65535. For ICMP they are the identifiers of echo requests. How many ports each address has bounds how many connections it carries for a protocol.protocols:tcp,udpandicmpby default.
An empty pool4, the default, takes the address of the link a connection leaves through, with
the ports 61001 to 65535. The router masquerades the NAT64's own address to it. That suits an
uplink whose address comes from DHCP. Several NAT64s may have an empty pool4.
An entry of pool4 holds addresses that the uplink routes to the router, never an address of
the router's own links. The router answers its own addresses itself, so their replies never
reach the NAT64. The rules refuse an entry that holds an address a Network document gives a
link, such as 192.0.2.253/24 on the uplink of 10-wan, so chalkctl validate reports it:
NAT64 edge: the pool entry 192.0.2.252/30 holds 192.0.2.253, an address a Network document gives a link; the router answers it itself, so leave pool4 empty to take the address of the link the connections leave through
An address that DHCP gives the uplink is not in any document, so the rules cannot refuse it.
chalkos-nat64.service checks the router's addresses instead. When a pool holds one, the unit
fails before it changes any instance and names the link:
chalkos-nat64: NAT64 edge: the pool entry 192.0.2.252/30 holds 192.0.2.253, an address of the link eth0, which the router answers itself; leave pool4 empty to take the address of the link the connections leave through; no instance changed
Give such an uplink an empty pool4.
Each address of a pool belongs to its NAT64 alone. No Network gives a link one of them, and no
NAT rule translates to one or matches a destination among them. The
validator router refuses such a rule, and
chalkctl validate reports it:
chalkctl: r1: the config is refused: NATRule/web: spec.to.address: to.address 192.0.2.253 lies in 192.0.2.252/30, the pool of NAT64 edge, whose addresses belong to the NAT64 whole; translate to an address outside the pool
The router's own connections take the kernel's ephemeral ports, 32768 to 60999, and Jool refuses them in a pool. A range that touches them is refused:
chalkctl: r1: the config is refused: NAT64/edge: spec.pool4: a pool entry takes the ports 1-65535, which touch the kernel's ephemeral ports, 32768 to 60999, which Jool refuses; give ports from 1 to 32767 or from 61000 to 65535
To give the pool's addresses most of their ports, give them two entries:
spec:
pool4:
- {prefix: 192.0.2.252/30, ports: "1-32767"}
- {prefix: 192.0.2.252/30, ports: "61000-65535"}
A node may hold several NAT64 documents, each with a prefix and a pool of its own. A NAT64's
name has 11 characters at most, because its link n64-<name> is an interface name, which has 15.
Prefixes are 32, 40, 48, 56, 64 or 96 bits long, as RFC 6052 gives them. Two entries of one pool
that share an address, a protocol and a port are refused. The validator router refuses two
NAT64s of one VRF whose prefixes overlap and two NAT64s whose pools share an address:
chalkctl: r1: the config is refused: NAT64/lab: spec.prefix: NAT64 lab and NAT64 edge both translate addresses of 64:ff9b::/96 in VRF default; give each NAT64 of a VRF a prefix of its own
A delivery that changes a NAT64's pool keeps its connections. One that changes its prefix, or renames it, replaces the translator, and the connections it carried end.
Each translated connection takes two entries in the router's connection table, one per side.
Raise Router.spec.conntrackMax when the NAT64s carry many connections.
Keep 169.254.64.0/18 free¶
Each NAT64 joins the router through a link of its own, whose two ends take a /30 of
169.254.64.0/18. The /30 follows from a hash of the NAT64's name alone, so a NAT64 keeps its
link's addresses while others come and go. While the node has a NAT64, the rules refuse a static
address in that range on any other link:
a Network document gives a link the address 169.254.96.241, which lies in 169.254.64.0/18, the range of the NAT64s' links; give the link another address
networkd's IPv4 link-local addressing picks an address of 169.254.0.0/16 by itself, which may
lie in the NAT64s' range, and no document names it. Leave it off on a router with NAT64s: it is
off unless a Network sets linkLocalAddressing to ipv4 or yes.
Two names may hash to the same /30. Among 10 NAT64s the chance is about 1%, and among 20 about
4.5%. The validator router then refuses the later name:
chalkctl: r1: the config is refused: NAT64/nat8: metadata.name: NAT64 nat8 and NAT64 nat282 both take the link addresses 169.254.120.112/30, which the hashes of their names pick; rename NAT64 nat8
Rename the NAT64 you are adding, even when the message names the other one. The running NAT64 then keeps its link's addresses and the connections that its masquerade tracks.
Announce the prefix¶
The router routes each NAT64's prefix to the NAT64's link, a route of the protocol nat64 that
exists while the NAT64 runs. An explicit pool's prefixes get such a route too. chalkctl node
routes lists them:
DESTINATION TYPE PROTOCOL TABLE METRIC NEXT HOPS
192.0.2.252/30 unicast nat64 254 0 169.254.96.242 on n64-edge
64:ff9b::/96 unicast nat64 254 1024 fe80::2 on n64-edge
BGP announces a network while the router's table holds a route to it, so the prefix belongs in
the networks of the BGP document. The clients' routers then send its traffic to this router.
r1's BGP of Route with BGP lists it already, with the routing policy nat64, which
tags its announcement with a community:
apiVersion: router.chalkos.dev/v1alpha1
kind: BGP
metadata: {name: bgp}
spec:
asn: 64512
routerID: 192.0.2.1
multipath: {ebgp: 64, asPathRelax: true}
networks:
- {prefix: "2001:db8:ffff::1/128"}
- {prefix: "64:ff9b::/96", policy: nat64}
- {prefix: 192.0.2.0/24}
A router without BGP needs routes to the prefix on the clients' side, such as a static route of a
Network document on their router.
The zones' policies do not filter the connections a NAT64 translates: any host whose packets to the prefix reach the router in the NAT64's VRF uses it. Limit who routes the prefix to the router, by the routes you announce and by the reverse-path filter.
Resolve names with DNS64¶
A Resolver runs a DNS resolver of the router. A VRF has one at most, and a Resolver without
vrf, or with vrf: default, serves the default VRF:
apiVersion: router.chalkos.dev/v1alpha1
kind: Resolver
metadata: {name: resolver}
spec:
listen: ["2001:db8:ffff::1"]
allow: ["2001:db8::/32"]
dns64: {prefix: "64:ff9b::/96"}
The resolver answers on port 53 of each address of listen, over UDP and TCP, to the clients of
allow. It refuses every other client. The firewall accepts DNS from allow to listen by
itself, ahead of the policies to local. listen holds addresses of the router, such as the
address of a loopback or a dummy interface, or of an interface to the clients. A config whose
listen and allow share no family is refused, as the resolver would answer no one.
A range of a whole family opens the resolver to the internet
An allow of ::/0 or 0.0.0.0/0 answers whoever reaches an address of listen. When one
of them faces the internet, the router is an open resolver, which others use for
amplification attacks. Give allow the clients' ranges alone.
dns64 synthesises an AAAA record in its prefix from each A record of a name that has no AAAA
record, so clients reach IPv4-only names through the NAT64. Give it the prefix of a NAT64 that the
clients route to the router; the rules do not compare the two. The resolver also answers
ipv4only.arpa with RFC 8880's addresses in the prefix, from which clients learn the prefix
itself.
Without forwarders the resolver looks names up itself, from the root servers. To send queries
to other resolvers instead, list them:
dnssec, true by default, validates the answers with the root's trust anchor of the image.
Forwarders must then pass DNSSEC records on. Turn validation off with dnssec: false when they
do not.
Translate and resolve in a VRF¶
A NAT64 and a Resolver with vrf serve the clients of that VRF alone. The VRF guest of
Separate routing with VRFs holds a guest LAN on eth3,
with the address 2001:db8:3::1/64, and an uplink of its own on eth4. Its guests get a NAT64
and a resolver of their own:
apiVersion: router.chalkos.dev/v1alpha1
kind: NAT64
metadata: {name: guest}
spec: {vrf: guest}
---
apiVersion: router.chalkos.dev/v1alpha1
kind: Resolver
metadata: {name: guest}
spec:
vrf: guest
listen: ["2001:db8:3::1"]
allow: ["2001:db8:3::/64"]
dns64: {prefix: "64:ff9b::/96"}
The NAT64 guest has an empty pool4, so its connections leave eth4 from the uplink's
address. The router routes its prefix to its link in guest's table, where the guests reach it,
and no other VRF does:
DESTINATION TYPE PROTOCOL TABLE METRIC NEXT HOPS
64:ff9b::/96 unicast nat64 300 1024 fe80::2 on n64-guest
A NAT64 of another VRF may translate the same prefix. Each VRF's table routes the prefix to its
own NAT64, so the NAT64s never see each other's clients. Two NAT64s' pools share no address,
whatever their VRFs. To announce a VRF's prefix, name it in networks of the VRF's BGP
document.
The resolver of guest answers on the VRF's links alone and sends its own queries out through
them, so the VRF's table needs routes to the root servers or to the forwarders. listen holds
addresses of the VRF's links. The validator router refuses an address that Network documents
give only to links of other VRFs, such as 2001:db8:ffff::1 on the management link of 10-mgmt:
chalkctl: r1: the config is refused: Resolver/guest: spec.listen[0]: the address 2001:db8:ffff::1 of listen belongs to links of Network 10-mgmt in VRF default alone, so the resolver of VRF guest never receives its queries; listen on an address of the VRF's links
The firewall opens the resolver's port 53 on the VRF's links alone. Each VRF has one Resolver
at most, and a NAT64 or Resolver that names a VRF no VRF document declares is refused.
Answer local names¶
localZones answers the names of zones from records of the document:
spec:
localZones:
- name: lan.example.org
records:
- {name: router.lan.example.org, type: AAAA, value: "2001:db8:1::1"}
- {name: lan.example.org, type: MX, value: 10 mail.lan.example.org}
- {name: _imaps._tcp.lan.example.org, type: SRV, value: 0 1 993 mail.lan.example.org}
- {name: lan.example.org, type: TXT, value: v=spf1 -all, ttl: 300}
- {name: ads.example.net, type: always_nxdomain}
Names are in lower case, without the root's dot, and a record's name is the zone's or one below
it. A zone of type static, the default, answers from its records alone. transparent looks up
the names its records lack, and always_nxdomain answers that no name exists.
Config kinds lists the other types and each record type's
value.
The rules refuse local zones that break one of these:
- A record's value is data of its type: an address of its family for
AandAAAA, a name forCNAMEandPTR,<preference> <name>forMXand<priority> <weight> <port> <name>forSRV, each number from 0 to 65535. It holds up to 255 printable ASCII characters, without quotes or backslashes. - A
redirectzone holds records of its own name alone, which it answers for every name below it. - With
dns64, no zone isipv4only.arpa, below it or above it, such asarpa. The resolver would answer such a zone before DNS64 does.
The output unbound refuses a record that appears twice and a CNAME record beside another record
of its name, in any zone. It checks when the router renders its config, at a delivery or at
chalkctl config apply --dry-run, and chalkctl validate does not:
chalkctl: r1: the config is refused: Resolver/resolver: spec.localZones[0].records[1]: www.lan.example.org holds a CNAME record and another record; a CNAME's name holds it alone
DNS64 synthesises no AAAA record from a local zone's A records.
Tell the clients¶
The clients learn the resolver and the NAT64 prefix from the router advertisements on their
link. On a router that sends them, such as the LAN router of the clients, set both in the LAN's
Network document:
apiVersion: networkd.chalkos.dev/v1alpha1
kind: Network
metadata: {name: 20-lan}
spec:
match: {name: lan0}
network: {address: ["2001:db8:1::1/64"], ipv6SendRA: true}
ipv6Prefix: {prefix: "2001:db8:1::/64"}
ipv6SendRA: {dns: ["2001:db8:ffff::1"]}
ipv6PREF64Prefix: {prefix: "64:ff9b::/96"}
ipv6SendRA.dns announces the resolver. ipv6PREF64Prefix announces the NAT64 prefix to clients
that synthesise addresses themselves.
Deliver and check¶
Validate the files and deliver them:
The delivery applies the NAT64s and reloads the resolvers, which keep their caches. A Resolver
added starts its resolver, and one removed stops it. The rules and the validator router check
the documents before chalkctl sends anything. The renderers' checks run on the router, as
Fix a refused delivery describes.
chalkos-nat64.service and chalkos-resolvers.service are units of the boot, so when either
fails on an upgrade's first boot, the router falls back to the image it ran, as
Boot, health and rollback describes.
chalkctl status shows the NAT64s and the resolvers after the BGP sessions:
nat64:
INSTANCE SESSIONS BINDINGS POOL TCP POOL UDP POOL ICMP
edge 1 1 18140 18140 18140
resolver: running
Each NAT64 whose instance runs has a line. SESSIONS counts the connections it translates, over
all protocols. BINDINGS counts the IPv4 addresses and ports that those connections hold. The
POOL columns count the addresses and ports of each protocol's pool: 4 addresses of 4535 ports
each here. A protocol that the pool leaves out shows -. An empty pool shows 4535 ports per
protocol, the ports 61001 to 65535 of the NAT64's own address.
The resolver of a VRF has a line of its own after the default VRF's. The VRF example's router prints:
nat64:
INSTANCE SESSIONS BINDINGS POOL TCP POOL UDP POOL ICMP
guest 3 3 4535 4535 4535
resolver guest: running
A NAT64 whose instance did not load has no line. After a boot the status then lists
failed unit chalkos-nat64.service, and a delivery fails with the unit's error. A VRF's resolver
that does not run shows its unit's state, such as
resolver guest: not running: unbound@guest.service is failed. One whose unit runs but whose
sockets are bound to a device the VRF no longer has shows
resolver guest: not running: unbound@guest.service is active, but it is bound to a removed device of the VRF.
chalkos-resolvers.service restarts such a resolver when a delivery recreates its VRF, so the
line points to a delivery whose effects failed.
nat64: unknown: gives jool's error when chalkd could not read the NAT64s' state.
resolver: not running: gives unbound-control's error. A router without NAT64 documents prints
no nat64: line, and one without a Resolver no resolver line. A node in maintenance mode
runs neither.
The diagnostic dns-query asks the resolver from the router:
chalkctl node diag r1 --secrets secrets.age dns-query name=ipv4only.arpa type=AAAA server=2001:db8:ffff::1
;; ->>HEADER<<- opcode: QUERY, rcode: NOERROR, id: 28595
;; flags: qr rd ra ; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;; ipv4only.arpa. IN AAAA
;; ANSWER SECTION:
ipv4only.arpa. 3600 IN AAAA 64:ff9b::c000:ab
ipv4only.arpa. 3600 IN AAAA 64:ff9b::c000:aa
The query comes from the router's own address in the default VRF, which allow must hold. It
cannot ask a VRF's resolver. nat64-sessions lists a NAT64's connections, for TCP, then UDP,
then ICMP. Each shows the remote host's and the client's address and port, then the pool's
address and port and the address the client connected to:
---------------------------------
(V4_FIN_V6_FIN_RCV) Expires in 0:03:59.285
Remote: 198.51.100.2#443 2001:db8:1::2#41784
Local: 192.0.2.253#62646 64:ff9b::c633:6402#443
---------------------------------
---------------------------------
---------------------------------
For a NAT64 with an empty pool, Local: shows the NAT64's own address, such as
169.254.111.206#62646 for guest, which the router masquerades to the uplink's address. The
diagnostic runs in the NAT64's network namespace, so an instance that does not run fails with
failed_precondition: diagnostic nat64-sessions: the network namespace nat64-guest does not exist.
Both diagnostics need an operator client: nat64-sessions shows who connects where. The status
needs a reader.
Fix a refused delivery¶
The rules check each document and what one document's fields say of another's. The
validator router compares the NAT64s in pairs and
checks the listen addresses against the Network documents. chalkctl validate and
chalkctl config apply run it before chalkctl sends anything, and the router runs it again at
the delivery. It checks the VRFs' links first, and the listen addresses only once the
links pass. Within each step it reports every fault it finds at once.
chalkctl prints the refusals after the config is refused:, as it prints a rule's, with the
document and the field each is about:
chalkctl: r1: the config is refused: NAT64/lab: spec.prefix: NAT64 lab and NAT64 edge both translate addresses of 64:ff9b::/96 in VRF default; give each NAT64 of a VRF a prefix of its own
| Message | Fix |
|---|---|
NAT64/lab: spec.prefix: NAT64 lab and NAT64 edge both translate addresses of 64:ff9b::/96 in VRF default; give each NAT64 of a VRF a prefix of its own |
Give one of the NAT64s another prefix, or move it to another VRF. |
NAT64/lab: spec.pool4[0]: the entry shares addresses with the pool of NAT64 edge; give each NAT64 a pool of its own |
Split the addresses between the pools. |
NAT64/nat8: metadata.name: NAT64 nat8 and NAT64 nat282 both take the link addresses 169.254.120.112/30, which the hashes of their names pick; rename NAT64 nat8 |
Rename the NAT64 you are adding. |
Resolver/guest: spec.listen[0]: the address 2001:db8:ffff::1 of listen belongs to links of Network 10-mgmt in VRF default alone, so the resolver of VRF guest never receives its queries; listen on an address of the VRF's links |
Listen on an address of the resolver's VRF. |
The renderer of the output unbound compares the records in pairs when the router renders its
config, at a delivery or at chalkctl config apply --dry-run. chalkctl validate does not run
it. Its refusal fails the delivery, and chalkctl prints it in the same form:
| Message | Fix |
|---|---|
Resolver/resolver: spec.localZones[0].records[1]: a.lan.example.org. AAAA 2001:db8::1 appears twice; Unbound keeps one, so drop the other |
Drop one of the records. |
Resolver/resolver: spec.localZones[0].records[1]: www.lan.example.org holds a CNAME record and another record; a CNAME's name holds it alone |
Drop the other records of the name, or the CNAME record. |
What next¶
- NAT64 and DNS64 on a router explains the translator, its namespace and link, the resolver's config and their limits.
- Separate routing with VRFs sets up the VRFs.
- Route with BGP announces the NAT64 prefix.
- Config kinds describes each field.