1.\" Copyright (c) 2005 Gleb Smirnoff <glebius@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd December 6, 2024 26.Dt NG_NAT 4 27.Os 28.Sh NAME 29.Nm ng_nat 30.Nd "NAT netgraph node type" 31.Sh SYNOPSIS 32.In netgraph/ng_nat.h 33.Sh DESCRIPTION 34An 35.Nm 36node performs network address translation (NAT) of IPv4 packets 37passing through it. 38A 39.Nm nat 40node uses 41.Xr libalias 3 42engine for packet aliasing. 43.Sh HOOKS 44This node type has two hooks: 45.Bl -tag -width ".Va out" 46.It Va out 47Packets received on this hook are considered outgoing and will be 48masqueraded to a configured address. 49.It Va in 50Packets coming on this hook are considered incoming and will be 51dealiased. 52.El 53.Sh CONTROL MESSAGES 54This node type supports the generic control messages, plus the following: 55.Bl -tag -width foo 56.It Dv NGM_NAT_SET_IPADDR Pq Ic setaliasaddr 57Configure aliasing address for a node. 58After both hooks have been connected and aliasing address was configured, 59a node is ready for aliasing operation. 60.It Dv NGM_NAT_SET_MODE Pq Ic setmode 61Set node's operation mode using supplied 62.Vt "struct ng_nat_mode" . 63.Bd -literal 64struct ng_nat_mode { 65 uint32_t flags; 66 uint32_t mask; 67}; 68/* Supported flags: */ 69#define NG_NAT_LOG 0x01 70#define NG_NAT_DENY_INCOMING 0x02 71#define NG_NAT_SAME_PORTS 0x04 72#define NG_NAT_UNREGISTERED_ONLY 0x10 73#define NG_NAT_RESET_ON_ADDR_CHANGE 0x20 74#define NG_NAT_PROXY_ONLY 0x40 75#define NG_NAT_REVERSE 0x80 76#define NG_NAT_UNREGISTERED_CGN 0x100 77#define NG_NAT_UDP_EIM 0x200 78.Ed 79.Pp 80The corresponding libalias flags can be found by replacing the 81.Vt "NG_NAT" 82prefix with 83.Vt "PKT_ALIAS" . 84.It Dv NGM_NAT_SET_TARGET Pq Ic settarget 85Configure target address for a node. 86When an incoming packet not associated with any pre-existing aliasing 87link arrives at the host machine, it will be sent to the specified address. 88.It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport 89Redirect incoming connections arriving to given port(s) to 90another host and port(s). 91The following 92.Vt "struct ng_nat_redirect_port" 93must be supplied as argument. 94.Bd -literal 95#define NG_NAT_DESC_LENGTH 64 96struct ng_nat_redirect_port { 97 struct in_addr local_addr; 98 struct in_addr alias_addr; 99 struct in_addr remote_addr; 100 uint16_t local_port; 101 uint16_t alias_port; 102 uint16_t remote_port; 103 uint8_t proto; 104 char description[NG_NAT_DESC_LENGTH]; 105}; 106.Ed 107.Pp 108Redirection is assigned an unique ID which is returned as 109response to this message, and 110information about redirection added to 111list of static redirects which later can be retrieved by 112.Dv NGM_NAT_LIST_REDIRECTS 113message. 114.It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr 115Redirect traffic for public IP address to a machine on the 116local network. 117This function is known as 118.Em static NAT . 119The following 120.Vt "struct ng_nat_redirect_addr" 121must be supplied as argument. 122.Bd -literal 123struct ng_nat_redirect_addr { 124 struct in_addr local_addr; 125 struct in_addr alias_addr; 126 char description[NG_NAT_DESC_LENGTH]; 127}; 128.Ed 129.Pp 130Unique ID for this redirection is returned as response to this message. 131.It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto 132Redirect incoming IP packets of protocol 133.Va proto 134(see 135.Xr protocols 5 ) 136to a machine on the local network. 137The following 138.Vt "struct ng_nat_redirect_proto" 139must be supplied as argument. 140.Bd -literal 141struct ng_nat_redirect_proto { 142 struct in_addr local_addr; 143 struct in_addr alias_addr; 144 struct in_addr remote_addr; 145 uint8_t proto; 146 char description[NG_NAT_DESC_LENGTH]; 147}; 148.Ed 149.Pp 150Unique ID for this redirection is returned as response to this message. 151.It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic 152Mark redirection with specified ID as dynamic, i.e., it will serve 153for exactly one next connection and then will be automatically 154deleted from internal links table. 155Only fully specified links can be made dynamic. 156The redirection with this ID is also immediately deleted from 157user-visible list of static redirects (available through 158.Dv NGM_NAT_LIST_REDIRECTS 159message). 160.It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete 161Delete redirection with specified ID (currently active 162connections are not affected). 163.It Dv NGM_NAT_ADD_SERVER Pq Ic addserver 164Add another server to a pool. 165This is used to transparently offload network load on a single server 166and distribute the load across a pool of servers, also known as 167.Em LSNAT 168(RFC 2391). 169The following 170.Vt "struct ng_nat_add_server" 171must be supplied as argument. 172.Bd -literal 173struct ng_nat_add_server { 174 uint32_t id; 175 struct in_addr addr; 176 uint16_t port; 177}; 178.Ed 179.Pp 180First, the redirection is set up by 181.Dv NGM_NAT_REDIRECT_PORT 182or 183.Dv NGM_NAT_REDIRECT_ADDR . 184Then, ID of that redirection is used in multiple 185.Dv NGM_NAT_ADD_SERVER 186messages to add necessary number of servers. 187For redirections created by 188.Dv NGM_NAT_REDIRECT_ADDR , 189the 190.Va port 191is ignored and could have any value. 192Original redirection's parameters 193.Va local_addr 194and 195.Va local_port 196are also ignored after 197.Dv NGM_NAT_ADD_SERVER 198was used (they are effectively replaced by server pool). 199.It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects 200Return list of configured static redirects as 201.Vt "struct ng_nat_list_redirects" . 202.Bd -literal 203struct ng_nat_listrdrs_entry { 204 uint32_t id; /* Anything except zero */ 205 struct in_addr local_addr; 206 struct in_addr alias_addr; 207 struct in_addr remote_addr; 208 uint16_t local_port; 209 uint16_t alias_port; 210 uint16_t remote_port; 211 uint16_t proto; /* Valid proto or NG_NAT_REDIRPROTO_ADDR */ 212 uint16_t lsnat; /* LSNAT servers count */ 213 char description[NG_NAT_DESC_LENGTH]; 214}; 215struct ng_nat_list_redirects { 216 uint32_t total_count; 217 struct ng_nat_listrdrs_entry redirects[]; 218}; 219#define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3) 220.Ed 221.Pp 222Entries of the 223.Va redirects 224array returned in the unified format for all redirect types. 225Ports are meaningful only if protocol is either TCP or UDP 226and 227.Em static NAT 228redirection (created by 229.Dv NGM_NAT_REDIRECT_ADDR ) 230is indicated by 231.Va proto 232set to 233.Dv NG_NAT_REDIRPROTO_ADDR . 234If 235.Va lsnat 236servers counter is greater than zero, then 237.Va local_addr 238and 239.Va local_port 240are also meaningless. 241.It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule 242Specify a transparent proxying rule (string must be 243supplied as argument). 244See 245.Xr libalias 3 246for details. 247.It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo 248Return internal statistics of 249.Xr libalias 3 250instance as 251.Vt "struct ng_nat_libalias_info" . 252.Bd -literal 253struct ng_nat_libalias_info { 254 uint32_t icmpLinkCount; 255 uint32_t udpLinkCount; 256 uint32_t tcpLinkCount; 257 uint32_t sctpLinkCount; 258 uint32_t pptpLinkCount; 259 uint32_t protoLinkCount; 260 uint32_t fragmentIdLinkCount; 261 uint32_t fragmentPtrLinkCount; 262 uint32_t sockCount; 263}; 264.Ed 265In case of 266.Nm 267failed to retrieve a certain counter 268from its 269.Xr libalias 3 270instance, the corresponding field is returned as 271.Va UINT32_MAX . 272.It Dv NGM_NAT_SET_DLT Pq Ic setdlt 273Sets the data link type on the 274.Va in 275and 276.Va out 277hooks. 278Currently, supported types are 279.Cm DLT_RAW 280(raw IP datagrams , no offset applied, the default) and 281.Cm DLT_EN10MB 282(Ethernet). DLT_ definitions can be found in 283.In net/bpf.h . 284If you want to work on the 285.Xr ipfw 8 286level you must use no additional offset by specifying 287.Cm DLT_RAW . 288If, however, you attach 289.Nm 290to a network interface directly and 291.Cm EN10MB 292is specified, then the extra offset will be applied to take into account 293link-level header. 294In this mode the 295.Nm 296would also inspect appropriate type field in the Ethernet header and 297pass-through any datagrams that are not IP packets. 298.It Dv NGM_NAT_GET_DLT Pq Ic getdlt 299This control message returns the current data link type of the 300.Va in 301and 302.Va out 303hooks. 304.El 305.Pp 306In all redirection messages 307.Va local_addr 308and 309.Va local_port 310mean address and port of target machine in the internal network, 311respectively. 312If 313.Va alias_addr 314is zero, then default aliasing address (set by 315.Dv NGM_NAT_SET_IPADDR ) 316is used. 317Connections can also be restricted to be accepted only 318from specific external machines by using non-zero 319.Va remote_addr 320and/or 321.Va remote_port . 322Each redirection assigned an ID which can be later used for 323redirection manipulation on individual basis (e.g., removal). 324This ID guaranteed to be unique until the node shuts down 325(it will not be reused after deletion), and is returned to 326user after making each new redirection or can be found in 327the stored list of all redirections. 328The 329.Va description 330passed to and from node unchanged, together with ID providing 331a way for several entities to concurrently manipulate 332redirections in automated way. 333.Sh SHUTDOWN 334This node shuts down upon receipt of a 335.Dv NGM_SHUTDOWN 336control message, or when both hooks are disconnected. 337.Sh EXAMPLES 338In the following example, the packets are injected into a 339.Nm nat 340node using the 341.Xr ng_ipfw 4 342node. 343.Bd -literal -offset indent 344# Create NAT node 345ngctl mkpeer ipfw: nat 60 out 346ngctl name ipfw:60 nat 347ngctl connect ipfw: nat: 61 in 348ngctl msg nat: setaliasaddr x.y.35.8 349 350# Divert traffic into NAT node 351ipfw add 300 netgraph 61 all from any to any in via fxp0 352ipfw add 400 netgraph 60 all from any to any out via fxp0 353 354# Let packets continue with after being (de)aliased 355sysctl net.inet.ip.fw.one_pass=0 356.Ed 357.Pp 358The 359.Nm 360node can be inserted right after the 361.Xr ng_iface 4 362node in the graph. 363In the following example, we perform masquerading on a 364serial line with HDLC encapsulation. 365.Bd -literal -offset indent 366/usr/sbin/ngctl -f- <<-SEQ 367 mkpeer cp0: cisco rawdata downstream 368 name cp0:rawdata hdlc 369 mkpeer hdlc: nat inet in 370 name hdlc:inet nat 371 mkpeer nat: iface out inet 372 msg nat: setaliasaddr x.y.8.35 373SEQ 374ifconfig ng0 x.y.8.35 x.y.8.1 375.Ed 376.Pp 377The 378.Nm 379node can also be attached directly to the physical interface 380via 381.Xr ng_ether 4 382node in the graph. 383In the following example, we perform masquerading on a 384Ethernet interface connected to a public network. 385.Bd -literal -offset indent 386ifconfig igb0 inet x.y.8.35 netmask 0xfffff000 387route add default x.y.0.1 388/usr/sbin/ngctl -f- <<-SEQ 389 mkpeer igb0: nat lower in 390 name igb0:lower igb0_NAT 391 connect igb0: igb0_NAT: upper out 392 msg igb0_NAT: setdlt 1 393 msg igb0_NAT: setaliasaddr x.y.8.35 394SEQ 395.Ed 396.Sh SEE ALSO 397.Xr libalias 3 , 398.Xr ng_ipfw 4 , 399.Xr natd 8 , 400.Xr ng_ether 8 , 401.Xr ngctl 8 402.Sh HISTORY 403The 404.Nm 405node type was implemented in 406.Fx 6.0 . 407.Sh AUTHORS 408.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org 409