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 March 21, 2013 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 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.El 268.Pp 269In all redirection messages 270.Va local_addr 271and 272.Va local_port 273mean address and port of target machine in the internal network, 274respectively. 275If 276.Va alias_addr 277is zero, then default aliasing address (set by 278.Dv NGM_NAT_SET_IPADDR ) 279is used. 280Connections can also be restricted to be accepted only 281from specific external machines by using non-zero 282.Va remote_addr 283and/or 284.Va remote_port . 285Each redirection assigned an ID which can be later used for 286redirection manipulation on individual basis (e.g., removal). 287This ID guaranteed to be unique until the node shuts down 288(it will not be reused after deletion), and is returned to 289user after making each new redirection or can be found in 290the stored list of all redirections. 291The 292.Va description 293passed to and from node unchanged, together with ID providing 294a way for several entities to concurrently manipulate 295redirections in automated way. 296.Sh SHUTDOWN 297This node shuts down upon receipt of a 298.Dv NGM_SHUTDOWN 299control message, or when both hooks are disconnected. 300.Sh EXAMPLES 301In the following example, the packets are injected into a 302.Nm nat 303node using the 304.Xr ng_ipfw 4 305node. 306.Bd -literal -offset indent 307# Create NAT node 308ngctl mkpeer ipfw: nat 60 out 309ngctl name ipfw:60 nat 310ngctl connect ipfw: nat: 61 in 311ngctl msg nat: setaliasaddr x.y.35.8 312 313# Divert traffic into NAT node 314ipfw add 300 netgraph 61 all from any to any in via fxp0 315ipfw add 400 netgraph 60 all from any to any out via fxp0 316 317# Let packets continue with after being (de)aliased 318sysctl net.inet.ip.fw.one_pass=0 319.Ed 320.Pp 321The 322.Nm 323node can be inserted right after the 324.Xr ng_iface 4 325node in the graph. 326In the following example, we perform masquerading on a 327serial line with HDLC encapsulation. 328.Bd -literal -offset indent 329/usr/sbin/ngctl -f- <<-SEQ 330 mkpeer cp0: cisco rawdata downstream 331 name cp0:rawdata hdlc 332 mkpeer hdlc: nat inet in 333 name hdlc:inet nat 334 mkpeer nat: iface out inet 335 msg nat: setaliasaddr x.y.8.35 336SEQ 337ifconfig ng0 x.y.8.35 x.y.8.1 338.Ed 339.Sh SEE ALSO 340.Xr libalias 3 , 341.Xr ng_ipfw 4 , 342.Xr natd 8 , 343.Xr ngctl 8 344.Sh HISTORY 345The 346.Nm 347node type was implemented in 348.Fx 6.0 . 349.Sh AUTHORS 350.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org 351