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 January 24, 2021 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.Ed 78.Pp 79The corresponding libalias flags can be found by replacing the 80.Vt "NG_NAT" 81prefix with 82.Vt "PKT_ALIAS" . 83.It Dv NGM_NAT_SET_TARGET Pq Ic settarget 84Configure target address for a node. 85When an incoming packet not associated with any pre-existing aliasing 86link arrives at the host machine, it will be sent to the specified address. 87.It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport 88Redirect incoming connections arriving to given port(s) to 89another host and port(s). 90The following 91.Vt "struct ng_nat_redirect_port" 92must be supplied as argument. 93.Bd -literal 94#define NG_NAT_DESC_LENGTH 64 95struct ng_nat_redirect_port { 96 struct in_addr local_addr; 97 struct in_addr alias_addr; 98 struct in_addr remote_addr; 99 uint16_t local_port; 100 uint16_t alias_port; 101 uint16_t remote_port; 102 uint8_t proto; 103 char description[NG_NAT_DESC_LENGTH]; 104}; 105.Ed 106.Pp 107Redirection is assigned an unique ID which is returned as 108response to this message, and 109information about redirection added to 110list of static redirects which later can be retrieved by 111.Dv NGM_NAT_LIST_REDIRECTS 112message. 113.It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr 114Redirect traffic for public IP address to a machine on the 115local network. 116This function is known as 117.Em static NAT . 118The following 119.Vt "struct ng_nat_redirect_addr" 120must be supplied as argument. 121.Bd -literal 122struct ng_nat_redirect_addr { 123 struct in_addr local_addr; 124 struct in_addr alias_addr; 125 char description[NG_NAT_DESC_LENGTH]; 126}; 127.Ed 128.Pp 129Unique ID for this redirection is returned as response to this message. 130.It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto 131Redirect incoming IP packets of protocol 132.Va proto 133(see 134.Xr protocols 5 ) 135to a machine on the local network. 136The following 137.Vt "struct ng_nat_redirect_proto" 138must be supplied as argument. 139.Bd -literal 140struct ng_nat_redirect_proto { 141 struct in_addr local_addr; 142 struct in_addr alias_addr; 143 struct in_addr remote_addr; 144 uint8_t proto; 145 char description[NG_NAT_DESC_LENGTH]; 146}; 147.Ed 148.Pp 149Unique ID for this redirection is returned as response to this message. 150.It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic 151Mark redirection with specified ID as dynamic, i.e., it will serve 152for exactly one next connection and then will be automatically 153deleted from internal links table. 154Only fully specified links can be made dynamic. 155The redirection with this ID is also immediately deleted from 156user-visible list of static redirects (available through 157.Dv NGM_NAT_LIST_REDIRECTS 158message). 159.It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete 160Delete redirection with specified ID (currently active 161connections are not affected). 162.It Dv NGM_NAT_ADD_SERVER Pq Ic addserver 163Add another server to a pool. 164This is used to transparently offload network load on a single server 165and distribute the load across a pool of servers, also known as 166.Em LSNAT 167(RFC 2391). 168The following 169.Vt "struct ng_nat_add_server" 170must be supplied as argument. 171.Bd -literal 172struct ng_nat_add_server { 173 uint32_t id; 174 struct in_addr addr; 175 uint16_t port; 176}; 177.Ed 178.Pp 179First, the redirection is set up by 180.Dv NGM_NAT_REDIRECT_PORT 181or 182.Dv NGM_NAT_REDIRECT_ADDR . 183Then, ID of that redirection is used in multiple 184.Dv NGM_NAT_ADD_SERVER 185messages to add necessary number of servers. 186For redirections created by 187.Dv NGM_NAT_REDIRECT_ADDR , 188the 189.Va port 190is ignored and could have any value. 191Original redirection's parameters 192.Va local_addr 193and 194.Va local_port 195are also ignored after 196.Dv NGM_NAT_ADD_SERVER 197was used (they are effectively replaced by server pool). 198.It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects 199Return list of configured static redirects as 200.Vt "struct ng_nat_list_redirects" . 201.Bd -literal 202struct ng_nat_listrdrs_entry { 203 uint32_t id; /* Anything except zero */ 204 struct in_addr local_addr; 205 struct in_addr alias_addr; 206 struct in_addr remote_addr; 207 uint16_t local_port; 208 uint16_t alias_port; 209 uint16_t remote_port; 210 uint16_t proto; /* Valid proto or NG_NAT_REDIRPROTO_ADDR */ 211 uint16_t lsnat; /* LSNAT servers count */ 212 char description[NG_NAT_DESC_LENGTH]; 213}; 214struct ng_nat_list_redirects { 215 uint32_t total_count; 216 struct ng_nat_listrdrs_entry redirects[]; 217}; 218#define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3) 219.Ed 220.Pp 221Entries of the 222.Va redirects 223array returned in the unified format for all redirect types. 224Ports are meaningful only if protocol is either TCP or UDP 225and 226.Em static NAT 227redirection (created by 228.Dv NGM_NAT_REDIRECT_ADDR ) 229is indicated by 230.Va proto 231set to 232.Dv NG_NAT_REDIRPROTO_ADDR . 233If 234.Va lsnat 235servers counter is greater than zero, then 236.Va local_addr 237and 238.Va local_port 239are also meaningless. 240.It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule 241Specify a transparent proxying rule (string must be 242supplied as argument). 243See 244.Xr libalias 3 245for details. 246.It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo 247Return internal statistics of 248.Xr libalias 3 249instance as 250.Vt "struct ng_nat_libalias_info" . 251.Bd -literal 252struct ng_nat_libalias_info { 253 uint32_t icmpLinkCount; 254 uint32_t udpLinkCount; 255 uint32_t tcpLinkCount; 256 uint32_t sctpLinkCount; 257 uint32_t pptpLinkCount; 258 uint32_t protoLinkCount; 259 uint32_t fragmentIdLinkCount; 260 uint32_t fragmentPtrLinkCount; 261 uint32_t sockCount; 262}; 263.Ed 264In case of 265.Nm 266failed to retrieve a certain counter 267from its 268.Xr libalias 269instance, the corresponding field is returned as 270.Va UINT32_MAX . 271.It Dv NGM_NAT_SET_DLT Pq Ic setdlt 272Sets the data link type on the 273.Va in 274and 275.Va out 276hooks. 277Currently, supported types are 278.Cm DLT_RAW 279(raw IP datagrams , no offset applied, the default) and 280.Cm DLT_EN10MB 281(Ethernet). DLT_ definitions can be found in 282.In net/bpf.h . 283If you want to work on the 284.Xr ipfw 8 285level you must use no additional offset by specifying 286.Cm DLT_RAW . 287If, however, you attach 288.Nm 289to a network interface directly and 290.Cm EN10MB 291is specified, then the extra offset will be applied to take into account 292link-level header. 293In this mode the 294.Nm 295would also inspect appropriate type field in the Ethernet header and 296pass-through any datagrams that are not IP packets. 297.It Dv NGM_NAT_GET_DLT Pq Ic getdlt 298This control message returns the current data link type of the 299.Va in 300and 301.Va out 302hooks. 303.El 304.Pp 305In all redirection messages 306.Va local_addr 307and 308.Va local_port 309mean address and port of target machine in the internal network, 310respectively. 311If 312.Va alias_addr 313is zero, then default aliasing address (set by 314.Dv NGM_NAT_SET_IPADDR ) 315is used. 316Connections can also be restricted to be accepted only 317from specific external machines by using non-zero 318.Va remote_addr 319and/or 320.Va remote_port . 321Each redirection assigned an ID which can be later used for 322redirection manipulation on individual basis (e.g., removal). 323This ID guaranteed to be unique until the node shuts down 324(it will not be reused after deletion), and is returned to 325user after making each new redirection or can be found in 326the stored list of all redirections. 327The 328.Va description 329passed to and from node unchanged, together with ID providing 330a way for several entities to concurrently manipulate 331redirections in automated way. 332.Sh SHUTDOWN 333This node shuts down upon receipt of a 334.Dv NGM_SHUTDOWN 335control message, or when both hooks are disconnected. 336.Sh EXAMPLES 337In the following example, the packets are injected into a 338.Nm nat 339node using the 340.Xr ng_ipfw 4 341node. 342.Bd -literal -offset indent 343# Create NAT node 344ngctl mkpeer ipfw: nat 60 out 345ngctl name ipfw:60 nat 346ngctl connect ipfw: nat: 61 in 347ngctl msg nat: setaliasaddr x.y.35.8 348 349# Divert traffic into NAT node 350ipfw add 300 netgraph 61 all from any to any in via fxp0 351ipfw add 400 netgraph 60 all from any to any out via fxp0 352 353# Let packets continue with after being (de)aliased 354sysctl net.inet.ip.fw.one_pass=0 355.Ed 356.Pp 357The 358.Nm 359node can be inserted right after the 360.Xr ng_iface 4 361node in the graph. 362In the following example, we perform masquerading on a 363serial line with HDLC encapsulation. 364.Bd -literal -offset indent 365/usr/sbin/ngctl -f- <<-SEQ 366 mkpeer cp0: cisco rawdata downstream 367 name cp0:rawdata hdlc 368 mkpeer hdlc: nat inet in 369 name hdlc:inet nat 370 mkpeer nat: iface out inet 371 msg nat: setaliasaddr x.y.8.35 372SEQ 373ifconfig ng0 x.y.8.35 x.y.8.1 374.Ed 375.Pp 376The 377.Nm 378node can also be attached directly to the physical interface 379via 380.Xr ng_ether 4 381node in the graph. 382In the following example, we perform masquerading on a 383Ethernet interface connected to a public network. 384.Bd -literal -offset indent 385ifconfig igb0 inet x.y.8.35 netmask 0xfffff000 386route add default x.y.0.1 387/usr/sbin/ngctl -f- <<-SEQ 388 mkpeer igb0: nat lower in 389 name igb0:lower igb0_NAT 390 connect igb0: igb0_NAT: upper out 391 msg igb0_NAT: setdlt 1 392 msg igb0_NAT: setaliasaddr x.y.8.35 393SEQ 394.Ed 395.Sh SEE ALSO 396.Xr libalias 3 , 397.Xr ng_ipfw 4 , 398.Xr natd 8 , 399.Xr ngctl 8 , 400.Xr ng_ether 8 401.Sh HISTORY 402The 403.Nm 404node type was implemented in 405.Fx 6.0 . 406.Sh AUTHORS 407.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org 408