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