1 .\" Copyright (c) 2005 Gleb Smirnoff <glebius@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd "NAT netgraph node type"
38 node performs network address translation (NAT) of IPv4 packets
44 engine for packet aliasing.
46 This node type has two hooks:
47 .Bl -tag -width ".Va out"
49 Packets received on this hook are considered outgoing and will be
50 masqueraded to a configured address.
52 Packets coming on this hook are considered incoming and will be
56 This node type supports the generic control messages, plus the following:
58 .It Dv NGM_NAT_SET_IPADDR Pq Ic setaliasaddr
59 Configure aliasing address for a node.
60 After both hooks have been connected and aliasing address was configured,
61 a node is ready for aliasing operation.
62 .It Dv NGM_NAT_SET_MODE Pq Ic setmode
63 Set node's operation mode using supplied
64 .Vt "struct ng_nat_mode" .
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
81 The corresponding libalias flags can be found by replacing the
85 .It Dv NGM_NAT_SET_TARGET Pq Ic settarget
86 Configure target address for a node.
87 When an incoming packet not associated with any pre-existing aliasing
88 link arrives at the host machine, it will be sent to the specified address.
89 .It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport
90 Redirect incoming connections arriving to given port(s) to
91 another host and port(s).
93 .Vt "struct ng_nat_redirect_port"
94 must be supplied as argument.
96 #define NG_NAT_DESC_LENGTH 64
97 struct ng_nat_redirect_port {
98 struct in_addr local_addr;
99 struct in_addr alias_addr;
100 struct in_addr remote_addr;
103 uint16_t remote_port;
105 char description[NG_NAT_DESC_LENGTH];
109 Redirection is assigned an unique ID which is returned as
110 response to this message, and
111 information about redirection added to
112 list of static redirects which later can be retrieved by
113 .Dv NGM_NAT_LIST_REDIRECTS
115 .It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr
116 Redirect traffic for public IP address to a machine on the
118 This function is known as
121 .Vt "struct ng_nat_redirect_addr"
122 must be supplied as argument.
124 struct ng_nat_redirect_addr {
125 struct in_addr local_addr;
126 struct in_addr alias_addr;
127 char description[NG_NAT_DESC_LENGTH];
131 Unique ID for this redirection is returned as response to this message.
132 .It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto
133 Redirect incoming IP packets of protocol
137 to a machine on the local network.
139 .Vt "struct ng_nat_redirect_proto"
140 must be supplied as argument.
142 struct ng_nat_redirect_proto {
143 struct in_addr local_addr;
144 struct in_addr alias_addr;
145 struct in_addr remote_addr;
147 char description[NG_NAT_DESC_LENGTH];
151 Unique ID for this redirection is returned as response to this message.
152 .It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic
153 Mark redirection with specified ID as dynamic, i.e., it will serve
154 for exactly one next connection and then will be automatically
155 deleted from internal links table.
156 Only fully specified links can be made dynamic.
157 The redirection with this ID is also immediately deleted from
158 user-visible list of static redirects (available through
159 .Dv NGM_NAT_LIST_REDIRECTS
161 .It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete
162 Delete redirection with specified ID (currently active
163 connections are not affected).
164 .It Dv NGM_NAT_ADD_SERVER Pq Ic addserver
165 Add another server to a pool.
166 This is used to transparently offload network load on a single server
167 and distribute the load across a pool of servers, also known as
171 .Vt "struct ng_nat_add_server"
172 must be supplied as argument.
174 struct ng_nat_add_server {
181 First, the redirection is set up by
182 .Dv NGM_NAT_REDIRECT_PORT
184 .Dv NGM_NAT_REDIRECT_ADDR .
185 Then, ID of that redirection is used in multiple
186 .Dv NGM_NAT_ADD_SERVER
187 messages to add necessary number of servers.
188 For redirections created by
189 .Dv NGM_NAT_REDIRECT_ADDR ,
192 is ignored and could have any value.
193 Original redirection's parameters
197 are also ignored after
198 .Dv NGM_NAT_ADD_SERVER
199 was used (they are effectively replaced by server pool).
200 .It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects
201 Return list of configured static redirects as
202 .Vt "struct ng_nat_list_redirects" .
204 struct 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;
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];
216 struct ng_nat_list_redirects {
217 uint32_t total_count;
218 struct ng_nat_listrdrs_entry redirects[];
220 #define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3)
225 array returned in the unified format for all redirect types.
226 Ports are meaningful only if protocol is either TCP or UDP
229 redirection (created by
230 .Dv NGM_NAT_REDIRECT_ADDR )
234 .Dv NG_NAT_REDIRPROTO_ADDR .
237 servers counter is greater than zero, then
241 are also meaningless.
242 .It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule
243 Specify a transparent proxying rule (string must be
244 supplied as argument).
248 .It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo
249 Return internal statistics of
252 .Vt "struct ng_nat_libalias_info" .
254 struct 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;
268 failed to retrieve a certain counter
271 instance, the corresponding field is returned as
273 .It Dv NGM_NAT_SET_DLT Pq Ic setdlt
274 Sets the data link type on the
279 Currently, supported types are
281 (raw IP datagrams , no offset applied, the default) and
283 (Ethernet). DLT_ definitions can be found in
285 If you want to work on the
287 level you must use no additional offset by specifying
289 If, however, you attach
291 to a network interface directly and
293 is specified, then the extra offset will be applied to take into account
297 would also inspect appropriate type field in the Ethernet header and
298 pass-through any datagrams that are not IP packets.
299 .It Dv NGM_NAT_GET_DLT Pq Ic getdlt
300 This control message returns the current data link type of the
307 In all redirection messages
311 mean address and port of target machine in the internal network,
315 is zero, then default aliasing address (set by
316 .Dv NGM_NAT_SET_IPADDR )
318 Connections can also be restricted to be accepted only
319 from specific external machines by using non-zero
323 Each redirection assigned an ID which can be later used for
324 redirection manipulation on individual basis (e.g., removal).
325 This ID guaranteed to be unique until the node shuts down
326 (it will not be reused after deletion), and is returned to
327 user after making each new redirection or can be found in
328 the stored list of all redirections.
331 passed to and from node unchanged, together with ID providing
332 a way for several entities to concurrently manipulate
333 redirections in automated way.
335 This node shuts down upon receipt of a
337 control message, or when both hooks are disconnected.
339 In the following example, the packets are injected into a
344 .Bd -literal -offset indent
346 ngctl mkpeer ipfw: nat 60 out
347 ngctl name ipfw:60 nat
348 ngctl connect ipfw: nat: 61 in
349 ngctl msg nat: setaliasaddr x.y.35.8
351 # Divert traffic into NAT node
352 ipfw add 300 netgraph 61 all from any to any in via fxp0
353 ipfw add 400 netgraph 60 all from any to any out via fxp0
355 # Let packets continue with after being (de)aliased
356 sysctl net.inet.ip.fw.one_pass=0
361 node can be inserted right after the
364 In the following example, we perform masquerading on a
365 serial 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
372 mkpeer nat: iface out inet
373 msg nat: setaliasaddr x.y.8.35
375 ifconfig ng0 x.y.8.35 x.y.8.1
380 node can also be attached directly to the physical interface
384 In the following example, we perform masquerading on a
385 Ethernet interface connected to a public network.
386 .Bd -literal -offset indent
387 ifconfig igb0 inet x.y.8.35 netmask 0xfffff000
388 route 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
406 node type was implemented in
409 .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org