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