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 1, 2008 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 indent 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 indent 58.It Dv NGM_NAT_SET_IPADDR Pq Li 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 Li 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 Li 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 Li 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 Li 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 Li 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 Li 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 Li redirectdelete 156Delete redirection with specified ID (currently active 157connections are not affected). 158.It Dv NGM_NAT_ADD_SERVER Pq Li 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 Li 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 Li proxyrule 237Specify a transparent proxying rule (string must be 238supplied as argument). 239See 240.Xr libalias 3 241for details. 242.El 243.Pp 244In all redirection messages 245.Va local_addr 246and 247.Va local_port 248mean address and port of target machine in the internal network, 249respectively. 250If 251.Va alias_addr 252is zero, then default aliasing address (set by 253.Dv NGM_NAT_SET_IPADDR ) 254is used. 255Connections can also be restricted to be accepted only 256from specific external machines by using non-zero 257.Va remote_addr 258and/or 259.Va remote_port . 260Each redirection assigned an ID which can be later used for 261redirection manipulation on individual basis (e.g., removal). 262This ID guaranteed to be unique until the node shuts down 263(it will not be reused after deletion), and is returned to 264user after making each new redirection or can be found in 265the stored list of all redirections. 266The 267.Va description 268passed to and from node unchanged, together with ID providing 269a way for several entities to concurrently manipulate 270redirections in automated way. 271.Sh SHUTDOWN 272This node shuts down upon receipt of a 273.Dv NGM_SHUTDOWN 274control message, or when both hooks are disconnected. 275.Sh EXAMPLES 276In the following example, the packets are injected into a 277.Nm nat 278node using the 279.Xr ng_ipfw 4 280node. 281.Bd -literal -offset indent 282# Create NAT node 283ngctl mkpeer ipfw: nat 60 out 284ngctl name ipfw:60 nat 285ngctl connect ipfw: nat: 61 in 286ngctl msg nat: setaliasaddr x.y.35.8 287 288# Divert traffic into NAT node 289ipfw add 300 netgraph 61 all from any to any in via fxp0 290ipfw add 400 netgraph 60 all from any to any out via fxp0 291 292# Let packets continue with after being (de)aliased 293sysctl net.inet.ip.fw.one_pass=0 294.Ed 295.Pp 296The 297.Nm 298node can be inserted right after the 299.Xr ng_iface 4 300node in the graph. 301In the following example, we perform masquerading on a 302serial line with HDLC encapsulation. 303.Bd -literal -offset indent 304/usr/sbin/ngctl -f- <<-SEQ 305 mkpeer cp0: cisco rawdata downstream 306 name cp0:rawdata hdlc 307 mkpeer hdlc: nat inet in 308 name hdlc:inet nat 309 mkpeer nat: iface out inet 310 msg nat: setaliasaddr x.y.8.35 311SEQ 312ifconfig ng0 x.y.8.35 x.y.8.1 313.Ed 314.Sh SEE ALSO 315.Xr libalias 3 , 316.Xr ng_ipfw 4 , 317.Xr natd 8 , 318.Xr ngctl 8 319.Sh HISTORY 320The 321.Nm 322node type was implemented in 323.Fx 6.0 . 324.Sh AUTHORS 325.An Gleb Smirnoff Aq glebius@FreeBSD.org 326