eBPF-based Endpoint-Independent NAT

This eBPF application implements an "Endpoint-Independent Mapping" and "Endpoint-Independent Filtering" NAT(network address translation) on TC egress and ingress hooks.

Features

• eBPF: IPv4 to IPv4 NAPT(Network Address Port Translation)
• eBPF: IPv6 to IPv6 NAPT
• eBPF: Endpoint-Independent(Full Cone) NAT for TCP, UDP and ICMP
• eBPF: Partial external port range usage, allows reserving external ports for other usage
• Frontend: Automatic reconfiguration on interface address changes
• Frontend: Automatic IP rule and route setup for hairpinning, see #4

See example use cases for what can be achieved with EIM + EIF and other features einat provides.

For implementation details, see documentations under reference.

Requirement

• Linux kernel >= 5.15 (compiled with BPF and BTF support) on target machine
• libelf from elfutils
• zlib
• clang for bindgen and compiling BPF C code
• cargo and rustfmt for building

It's also required the eBPF JIT implementation for target architecture in kernel has implemented support for BPF-to-BPF calls, which is not the case for MIPS and other architectures have less interests. This application is only tested to work on x86-64 or aarch64.

See also OpenWrt guide for pitfalls running this on OpenWrt.

Installation

cargo install --git https://github.com/EHfive/einat-ebpf.git

You can also enable IPv6 NAT66 feature with --features ipv6 flag, however it would increase load time of eBPF programs to about 4 times.

Or build static binaries with Nix flakes we provide, run nix flake show to list all available packages.

nix build "github:EHfive/einat-ebpf#static-x86_64-unknown-linux-musl"
nix build "github:EHfive/einat-ebpf#ipv6-static-x86_64-unknown-linux-musl"
# Cross compile for aarch64
nix build "github:EHfive/einat-ebpf#static-aarch64-unknown-linux-musl"

For NixOS, you can use module github:EHfive/einat-ebpf#nixosModules.default.

See also cross-compilation guide for cross-compilation on Debian/Debian-based distros.

Usage

einat - An eBPF-based Endpoint-Independent NAT

USAGE:
  einat [OPTIONS]

OPTIONS:
  -h, --help                   Print this message
  -c, --config <file>          Path to configuration file
  -i, --ifname <name>          External network interface name, e.g. eth0
      --nat44                  Enable NAT44/NAPT44 for specified network interface
      --nat66                  Enable NAT66/NAPT66 for specified network interface
      --ports <range> ...      External TCP/UDP port ranges, defaults to 20000-29999
      --hairpin-if <name> ...  Hairpin internal network interface names, e.g. lo, lan0
      --bpf-log <level>        BPF tracing log level, 0 to 5, defaults to 0, disabled
  -v, --version                Print einat version

You would only need to specify external interface name in a minimal setup, and einat would select an external IP address on specified interface and reconfigures automatically.

# Enable IP forwarding if not already
sudo sysctl net.ipv4.ip_forward=1
# With simplified CLI options,
# this setup NAT for traffic forwarding to and from wan0 and setup hairpin
# routing for traffic forwarding from lo or lan0 to wan0
sudo einat --ifname wan0 --hairpin-if lo lan0
# With config file
sudo einat --config /path/to/config.toml

See config.sample.toml for more configuration options. This program requires cap_sys_admin for passing eBPF verification and cap_net_admin for attaching eBPF program to TC hooks on network interface.

Also make sure nftables/iptables masquerading rule is not set and forwarding of inbound traffic from external interface to internal interfaces for port ranges einat uses is allowed.

To test if this works, you can use tools below on internal network behind NAT. Notice you could only got "Full Cone" NAT if your external network is already "Full Cone" NAT or has a public IP.

• stunclient from stuntman
• stun-nat-behaviour
• go-stun
• NatTypeTester on Windows

Alternatives

• netfilter-full-cone-nat
• nft-fullcone

Instead of relying on existing Netfilter conntrack system like these out-of-tree kernel modules did, we implement a fully functional Endpoint Independent NAT engine on eBPF TC hook from scratch thus avoiding hassles dealing with "Address and Port-Dependent" Netfilter conntrack system and being slim and efficient.

And einat utilizes libbpf's CO-RE(Compile Once – Run Everywhere) capabilities that hugely simplifies distribution and deployment.

Recommended Reading

• How NAT traversal works, by David Anderson https://tailscale.com/blog/how-nat-traversal-works
• RFC 4787, Network Address Translation (NAT) Behavioral Requirements for Unicast UDP, https://datatracker.ietf.org/doc/html/rfc4787
• [Chinese] einat-ebpf，用 eBPF 从头写一个 Full Cone NAT, https://eh5.me/zh-cn/blog/einat-introduction/

COPYING

Sources under ./src/bpf/kernel are derived from Linux kernel, hence they are GPL-2.0-only licensed. For other files under this project, unless specified, they are GPL-2.0-or-later licensed.

Notice our BPF program calls into GPL-licensed kernel functions so you need to choose GPL-2.0-only license to distribute it.