Skip to content

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, behind eth1 and eth2.
  • Its uplink eth0 reaches the IPv4 internet.
  • It announces 192.0.2.0/24 to 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 default 61001-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, udp and icmp by 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:

chalkctl node routes r1 --protocol nat64 --secrets secrets.age
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:

spec:
  forwarders: ["2001:db8:2::53", 198.51.100.53]

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:

chalkctl node routes r1 --vrf guest --protocol nat64 --secrets secrets.age
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 A and AAAA, a name for CNAME and PTR, <preference> <name> for MX and <priority> <weight> <port> <name> for SRV, each number from 0 to 65535. It holds up to 255 printable ASCII characters, without quotes or backslashes.
  • A redirect zone holds records of its own name alone, which it answers for every name below it.
  • With dns64, no zone is ipv4only.arpa, below it or above it, such as arpa. 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:

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

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:

chalkctl status r1 --secrets secrets.age
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:

chalkctl node diag r1 --secrets secrets.age nat64-sessions instance=edge
---------------------------------
(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