A YANG Module for Network Address Translation (NAT) and Network Prefix Translation (NPT)
Extracted elements (29)
Dynamic explicit mappings (PCP, RFC 6887; Diameter, RFC 6736; RFC 8045) are out of scope; the module covers only static explicit mappings (CLI-configured) and dynamic implicit mappings (packet-triggered). This separation cleanly decouples the signaling protocol from the NAT data model.
Logging configuration (what to log and where to send logs, REQ-12 of RFC 6888 and Section 2.3 of RFC 6908) is intentionally excluded from the module scope. These are deployment-specific operational concerns whose standardization is deferred to separate documents.
No mapping table is maintained for stateless NAT variants: NPTv6 (stateless and transport-agnostic), EAM (no per-flow mapping), SIIT (internal nodes use IPv4-translatable IPv6 addresses), and CLAT when a dedicated /64 prefix is provided. Keeping the mapping-table optional avoids imposing stateful overhead on inherently stateless mechanisms.
Port-set assignment (port-range-allocation) is offered alongside single-port allocation to reduce NAT logging volume, since one log entry can cover an entire port set. This addresses REQ-14 of RFC 6888 and the logging optimization problem identified in Section 12 of RFC 6269.
All parameters that NATV2-MIB (RFC 7659) requires to be configured 'by some means not specified' — address realms, subscriber info, NAT instance identification, port/filtering/pooling/fragment behaviors, address pools, and static mappings — are configurable via this YANG module. Unlike NATV2-MIB, the YANG module additionally supports multiple policies per NAT instance.
DS-Lite (Dual-Stack Lite) support is defined as an extension to this YANG module in RFC 8513 rather than here. The napt44 feature description notes that an IPv6 address (DS-Lite softwire) may serve as an extra attribute to disambiguate NAPT44 mappings beyond the five-tuple.
SCTP NAT support (NAT-SUPP) is identified as requiring future extension; the mapping-entry would need two optional SCTP-specific fields (Internal Verification Tag and External Verification Tag). TCP-specific timers are not generalized to other connection-oriented protocols pending a standards document specifying such behavior.
A CGN must implement a protocol giving subscribers explicit control over NAT mappings (REQ-9 of RFC 6888); that protocol should be PCP (RFC 6887). Dynamic explicit mappings via PCP are out of scope of this module but must be supported at the device level.
It must be possible to administratively turn off translation for specific destination addresses and/or ports using nat-pass-through entries, per REQ-6 of RFC 6888.
NAT behavioral recommendations for UDP (RFC 4787), TCP (RFC 5382), and ICMP (RFC 5508) are assumed to be enabled by default; the module also relies on recommendations from RFC 6888 and RFC 7857.
The end-port-number leaf in the port-number grouping must be greater than or equal to start-port-number, enforced by a YANG must constraint with error-message 'The end-port-number must be greater than or equal to start-port-number.'
The NAT function SHOULD be able to assign port sets to optimize logging volume (REQ-14 of RFC 6888). The port-allocation-type leaf selects between single-port and port-range-allocation, and port-set-size specifies the number of ports per assignment.
When any configured resource limit is reached, packets that would normally trigger new port mappings or be translated against existing mappings MUST be dropped by the translator.
Eight YANG features gate translation modes: basic-nat44, napt44, dst-nat, nat64, siit, clat, eam, and nptv6 (Table 1). Additional combination modes (port-restricted NAT, simultaneous stateful/stateless NAT64, NAT64+EAM) are realized by composing feature-guarded parameters rather than defining extra features.
NAT state is organized under /nat/instances/instance (keyed by uint32 id, must be >= 1), where each instance carries an optional name, enable boolean, read-only capabilities container, a policy list, a mapping-table, and a statistics subtree. Multiple instances and multiple policies per instance are independently supported.
Resource limits are structured in four configurable groups: port-quota (max ports per subscriber, optionally per-protocol), fragments-limit (uint32, max out-of-order fragments), mapping-limits (limit-subscribers, limit-address-mappings, limit-port-mappings, limit-per-protocol), and connection-limits (rate limits per-subscriber, per-instance, per-protocol). Packets exceeding any limit are dropped.
The external-ip-address-pool list (feature: basic-nat44 or napt44 or nat64) specifies pools of external IPv4 prefixes (inet:ipv4-prefix, mandatory) identified by pool-id (uint32, must >= 1). Multiple non-contiguous blocks are supported, aligning with RFC 6888's requirement that the NAT external address pool have no size or contiguity limitations.
The ietf-nat YANG module (namespace urn:ietf:params:xml:ns:yang:ietf-nat, prefix nat, revision 2019-01-10) provides a data model covering NAT44, NAPT, NAT64, CLAT, SIIT, EAM, NPTv6, and Destination NAT. Translation modes are gated by YANG feature statements so only relevant data nodes are instantiated per device.
The mapping-entry grouping defines per-flow NAT state with fields: index (uint32), type (static/dynamic-implicit/dynamic-explicit), transport-protocol (uint8 from IANA Protocol Numbers), internal-src-address/port, external-src-address/port, internal-dst-address/port, external-dst-address/port, and lifetime (uint32, seconds). Both IPv4 and IPv6 addresses are supported as internal addresses to cover NAT44 and NAT64.
The nat-pass-through list (feature: basic-nat44 or napt44 or dst-nat) allows specifying IP prefixes and optional port numbers whose traffic must bypass translation, implementing REQ-6 of RFC 6888. If no prefix is specified, the port-based bypass applies to any destination address.
The port-set grouping offers a choice (default port-range) between a simple contiguous range (start-port-number, end-port-number) and the MAP-E PSID algorithm (psid-offset uint8 0..15, psid-len uint8 0..15 mandatory, psid uint16 mandatory) per RFC 7597. This grouping is reused for port-set-restrict and for internal/external port fields in mapping-entry.
The read-only capabilities container advertises per-instance NAT behavior: supported nat-flavor identityrefs, transport-protocols, mapping behavior (endpoint-independent, address-dependent, address-and-port-dependent), filtering behavior (three analogous options), port features (randomization, range-allocation, preservation, parity-preservation, round-robin, paired-address-pooling), and fragment-behavior (unsupported/in-order/out-of-order).
The statistics subtree provides read-only counters using yang:zero-based-counter64 for traffic (sent/received/dropped packets and bytes, with separate dropped-address-limit, dropped-port-limit, and dropped-subscriber-limit counters), yang:gauge32 for mapping statistics (total active subscribers, address mappings, port mappings per-protocol), and yang:gauge32 gauge values for per-pool address and port allocation/free counts.
The timers container (feature: napt44 or nat64) provides configurable timeout values for UDP (udp-timeout), TCP (tcp-idle-timeout, tcp-trans-open-timeout, tcp-trans-close-timeout, tcp-in-syn-timeout), ICMP (icmp-timeout), fragments (fragment-min-timeout), and a per-port-timeout list. Additional hold-down-timeout and hold-down-max leaves support hairpinning or port reuse scenarios.
Two YANG notifications are defined: nat-pool-event (carries instance id, policy-id, pool-id, notify-pool-threshold percent) triggers on per-pool address utilization crossing high- or low-threshold; nat-instance-event (carries instance id, notify-subscribers-threshold uint32, notify-addresses-threshold percent, notify-ports-threshold percent) triggers on instance-wide resource thresholds. Both support rate-limiting via notify-interval (minimum seconds between successive notifications).
IANA registered the YANG module in the 'YANG Module Names' registry with name 'ietf-nat', namespace 'urn:ietf:params:xml:ns:yang:ietf-nat', prefix 'nat', and reference RFC 8512.
Connection-limits and mapping-limits controls prevent a single subscriber from exhausting NAT CPU and memory resources, enforcing fairness among subscribers and protecting the NAT implementation from resource exhaustion attacks. Rate-limit thresholds are configurable per subscriber, per instance, and per protocol.
The fragments-limit parameter is provided to prevent DoS attacks caused by out-of-order IP fragments that exhaust NAT reassembly buffer resources; operators must configure an appropriate bound to limit fragment state maintained per translator.
The ietf-nat module exposes sensitive operational data (subscriber addresses, active port mappings, external address pools) and security-relevant configuration. NACM (RFC 8341) MUST be used to restrict access, and NETCONF or RESTCONF sessions MUST run over a secure transport (TLS or SSH) to prevent eavesdropping or tampering.