NG_NAT(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NG_NAT(4) — the ng_nat NAT netgraph node type 💖

okay bestie, sit down, hydrate, because we're about to talk about network address translation and it's genuinely so good. this is the manual page for ng_nat, a netgraph node type, straight from the Kernel Interfaces Manual. it's giving kernel-adjacent, it's giving packets, it's giving ✨infrastructure✨. let's GO.

✨ SYNOPSIS ✨

#include <netgraph/ng_nat.h>

that's it. that's the whole incantation. put that include in your file and the universe opens up. 🦋

🌸 DESCRIPTION 🌸

so. an ng_nat node does network address translation (NAT) on IPv4 packets that pass through it. that's its whole personality and honestly? iconic.

a nat node uses the libalias(3) engine for packet aliasing. so like, the node is the vibe, libalias(3) is the muscle. 💪

🎀 HOOKS 🎀

this node type has two hooks. only two. two little doorways. and they are:

  • out — packets received on this hook are considered outgoing and will be masqueraded to a configured address. bye bestie, you're getting a new face. 💅
  • in — packets coming on this hook are considered incoming and will be dealiased. welcome home, let's take that mask off. 🫶

👑 CONTROL MESSAGES 👑

this node type supports the generic control messages, plus all of the following. yes, all. every single one. we're not skipping anything, that's not the energy here.

  • NGM_NAT_SET_IPADDR (setaliasaddr) — configure the aliasing address for a node. once both hooks are connected AND the aliasing address is configured, the node is ready for aliasing operation. that's the "we're so back" moment. 🔥
  • NGM_NAT_SET_MODE (setmode) — set the node's operation mode using the supplied struct ng_nat_mode.
struct ng_nat_mode {
        uint32_t        flags;
        uint32_t        mask;
};
/* Supported flags: */
#define NG_NAT_LOG                      0x01
#define NG_NAT_DENY_INCOMING            0x02
#define NG_NAT_SAME_PORTS               0x04
#define NG_NAT_UNREGISTERED_ONLY        0x10
#define NG_NAT_RESET_ON_ADDR_CHANGE     0x20
#define NG_NAT_PROXY_ONLY               0x40
#define NG_NAT_REVERSE                  0x80

look at all those flags. each one a little mood. 🌈

  • NGM_NAT_SET_TARGET (settarget) — configure the target address for a node. when an incoming packet that is not associated with any pre-existing aliasing link arrives at the host machine, it will be sent to the specified address. like a little greeter at the door going "you? over there." 🚪
  • NGM_NAT_REDIRECT_PORT (redirectport) — redirect incoming connections arriving to given port(s) to another host and port(s). the following struct ng_nat_redirect_port must be supplied as the argument.
#define NG_NAT_DESC_LENGTH      64
struct ng_nat_redirect_port {
        struct in_addr  local_addr;
        struct in_addr  alias_addr;
        struct in_addr  remote_addr;
        uint16_t        local_port;
        uint16_t        alias_port;
        uint16_t        remote_port;
        uint8_t         proto;
        char            description[NG_NAT_DESC_LENGTH];
};

redirection gets assigned a unique ID which is returned as the response to this message, and info about the redirection gets added to the list of static redirects — which you can later retrieve with the NGM_NAT_LIST_REDIRECTS message. so it's not lost, it's filed. organized queen. 🗂️

  • NGM_NAT_REDIRECT_ADDR (redirectaddr) — redirect traffic for a public IP address to a machine on the local network. this function is known as static NAT. the following struct ng_nat_redirect_addr must be supplied as the argument.
struct ng_nat_redirect_addr {
        struct in_addr  local_addr;
        struct in_addr  alias_addr;
        char            description[NG_NAT_DESC_LENGTH];
};

a unique ID for this redirection is returned as the response to this message. one ID, one redirection, no cap. 💫

  • NGM_NAT_REDIRECT_PROTO (redirectproto) — redirect incoming IP packets of protocol proto (see protocols(5)) to a machine on the local network. the following struct ng_nat_redirect_proto must be supplied as the argument.
struct ng_nat_redirect_proto {
        struct in_addr  local_addr;
        struct in_addr  alias_addr;
        struct in_addr  remote_addr;
        uint8_t         proto;
        char            description[NG_NAT_DESC_LENGTH];
};

unique ID for this redirection is returned as the response to this message. same deal, different struct, still slaying. ✨

  • NGM_NAT_REDIRECT_DYNAMIC (redirectdynamic) — mark the redirection with the specified ID as dynamic, i.e. it will serve for exactly one next connection and then will be automatically deleted from the internal links table. only fully specified links can be made dynamic. the redirection with this ID is also immediately deleted from the user-visible list of static redirects (the one you get through the NGM_NAT_LIST_REDIRECTS message). so like — it's still doing its job, it's just off the grid now. ghosted but functional. 👻
  • NGM_NAT_REDIRECT_DELETE (redirectdelete) — delete the redirection with the specified ID. currently active connections are not affected. so it's a "no new friends" situation, not a "get out" situation. 🚫
  • NGM_NAT_ADD_SERVER (addserver) — add another server to a pool. this is used to transparently offload network load on a single server and distribute the load across a pool of servers, also known as LSNAT (RFC 2391). the following struct ng_nat_add_server must be supplied as the argument.
struct ng_nat_add_server {
        uint32_t        id;
        struct in_addr  addr;
        uint16_t        port;
};

here's the flow, bestie, listen closely: first, the redirection is set up by NGM_NAT_REDIRECT_PORT or NGM_NAT_REDIRECT_ADDR. then, the ID of that redirection is used in multiple NGM_NAT_ADD_SERVER messages to add the necessary number of servers. for redirections created by NGM_NAT_REDIRECT_ADDR, the port is ignored and could have any value. and after NGM_NAT_ADD_SERVER was used, the original redirection's local_addr and local_port parameters are also ignored — they are effectively replaced by the server pool. the group chat has spoken, the old settings are out. 💀

  • NGM_NAT_LIST_REDIRECTS (listredirects) — return the list of configured static redirects as struct ng_nat_list_redirects.
struct ng_nat_listrdrs_entry {
        uint32_t        id;             /* Anything except zero */
        struct in_addr  local_addr;
        struct in_addr  alias_addr;
        struct in_addr  remote_addr;
        uint16_t        local_port;
        uint16_t        alias_port;
        uint16_t        remote_port;
        uint16_t        proto;          /* Valid proto or NG_NAT_REDIRPROTO_ADDR */
        uint16_t        lsnat;          /* LSNAT servers count */
        char            description[NG_NAT_DESC_LENGTH];
};
struct ng_nat_list_redirects {
        uint32_t                total_count;
        struct ng_nat_listrdrs_entry redirects[];
};
#define NG_NAT_REDIRPROTO_ADDR  (IPPROTO_MAX + 3)

entries of the redirects array come back in a unified format for all redirect types — one format to rule them all, we love consistency. ports are meaningful only if the protocol is either TCP or UDP, and static NAT redirection (created by NGM_NAT_REDIRECT_ADDR) is indicated by proto set to NG_NAT_REDIRPROTO_ADDR. and if the lsnat servers counter is greater than zero, then local_addr and local_port are also meaningless. read the fields, bestie, don't assume. 🙈

  • NGM_NAT_PROXY_RULE (proxyrule) — specify a transparent proxying rule (a string must be supplied as the argument). see libalias(3) for details. the details live over there, go visit them. 🧚
  • NGM_NAT_LIBALIAS_INFO (libaliasinfo) — return internal statistics of the libalias(3) instance as struct ng_nat_libalias_info.
struct ng_nat_libalias_info {
        uint32_t        icmpLinkCount;
        uint32_t        udpLinkCount;
        uint32_t        tcpLinkCount;
        uint32_t        sctpLinkCount;
        uint32_t        pptpLinkCount;
        uint32_t        protoLinkCount;
        uint32_t        fragmentIdLinkCount;
        uint32_t        fragmentPtrLinkCount;
        uint32_t        sockCount;
};

in case ng_nat failed to retrieve a certain counter from its libalias instance, the corresponding field is returned as UINT32_MAX. so if you see that, it's not a flex, it's a "couldn't get it". 😭

  • NGM_NAT_SET_DLT (setdlt) — sets the data link type on the in and out hooks. currently, the supported types are DLT_RAW (raw IP datagrams, no offset applied, the default) and DLT_EN10MB (Ethernet). DLT_ definitions can be found in <net/bpf.h>. if you want to work on the ipfw(8) level you must use no additional offset by specifying DLT_RAW. if, however, you attach ng_nat to a network interface directly and EN10MB is specified, then the extra offset will be applied to take into account the link-level header. in this mode the ng_nat would also inspect the appropriate type field in the Ethernet header and pass-through any datagrams that are not IP packets. it's got range, it's got manners. 👑
  • NGM_NAT_GET_DLT (getdlt) — this control message returns the current data link type of the in and out hooks. no arguments, just vibes and an answer. 💅

okay and now the big unifying paragraph about redirection messages in general, because it applies to all of them and it's important:

in all redirection messages, local_addr and local_port mean the address and port of the target machine in the internal network, respectively. if alias_addr is zero, then the default aliasing address (set by NGM_NAT_SET_IPADDR) is used. connections can also be restricted to be accepted only from specific external machines by using non-zero remote_addr and/or remote_port.

each redirection is assigned an ID which can later be used for redirection manipulation on an individual basis (e.g., removal). this ID is guaranteed to be unique until the node shuts down — it will not be reused after deletion — and is returned to the user after making each new redirection, or it can be found in the stored list of all redirections. the description is passed to and from the node unchanged, and together with the ID it provides a way for several entities to concurrently manipulate redirections in an automated way. teamwork, but make it kernel. 🫶

💀 SHUTDOWN 💀

this node shuts down upon receipt of an NGM_SHUTDOWN control message, or when both hooks are disconnected. that's it. that's the end of the node. it saw everything, it did its job, it logged off. 😭

okay we are NOT done yet bestie, there's more of this page coming — part 2 is right around the corner, don't you dare close the tab 💖✨

✨ EXAMPLES ✨

okay bestie, here's where it gets fun. let's see this thing actually work 💅

💖 Example 1: injecting packets with ng_ipfw(4)

in this one, the packets get injected into a nat node using the ng_ipfw(4) node. it's giving teamwork, fr fr.

# Create NAT node
ngctl mkpeer ipfw: nat 60 out
ngctl name ipfw:60 nat
ngctl connect ipfw: nat: 61 in
ngctl msg nat: setaliasaddr x.y.35.8

# Divert traffic into NAT node
ipfw add 300 netgraph 61 all from any to any in via fxp0
ipfw add 400 netgraph 60 all from any to any out via fxp0

# Let packets continue with after being (de)aliased
sysctl net.inet.ip.fw.one_pass=0

so like — make the node, name it, connect the other hook, set the alias addr, then shove traffic at it with ipfw, and finally tell the firewall to not stop at the first match so the packets can keep flowing after being (de)aliased. slay 🔥

🦋 Example 2: right after ng_iface(4), HDLC serial line realness

the ng_nat node can be inserted right after the ng_iface(4) node in the graph. here we're doing masquerading on a serial line with HDLC encapsulation. vintage but iconic 💜

/usr/sbin/ngctl -f- <<-SEQ
        mkpeer cp0: cisco rawdata downstream
        name cp0:rawdata hdlc
        mkpeer hdlc: nat inet in
        name hdlc:inet nat
        mkpeer nat: iface out inet
        msg nat: setaliasaddr x.y.8.35
SEQ
ifconfig ng0 x.y.8.35 x.y.8.1

the way that ngctl just eats a whole heredoc script and builds your entire graph in one go?? obsessed. 😭✨

🌸 Example 3: attaching straight to a physical interface via ng_ether(4)

the ng_nat node can also be attached directly to the physical interface via the ng_ether(4) node in the graph. this time we're doing masquerading on an Ethernet interface connected to a public network. main character energy, no cap 👑

ifconfig igb0 inet x.y.8.35 netmask 0xfffff000
route add default x.y.0.1
/usr/sbin/ngctl -f- <<-SEQ
        mkpeer igb0: nat lower in
        name igb0:lower igb0_NAT
        connect igb0: igb0_NAT: upper out
        msg igb0_NAT: setdlt 1
        msg igb0_NAT: setaliasaddr x.y.8.35
SEQ

note the setdlt 1 in there — that's the vibe check for this setup, don't skip it bestie 💅

👀 SEE ALSO

go read these, they're the group chat:

📜 HISTORY

the ng_nat node type was implemented in FreeBSD 6.0. an elder. a legend. still eating. 💖

🫶 AUTHORS

Gleb Smirnoff <glebius@FreeBSD.org>

thank you for your service king 🫡✨

and that's the whole page, bestie!! this version came from the Debian packaging, dated December 12, 2018, and it lives at section NG_NAT(4). go forth and NAT responsibly 💅🌸🦋

📦 where this page comes from