| blob | cc8970338a2300cd5505d7fe45c92d1173178290 |
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
36 An
37 .Nm
38 node performs network address translation (NAT) of packets
39 passing through it.
40 A
41 .Nm nat
42 node uses
43 .Xr libalias 3
44 engine for packet aliasing.
45 .Sh HOOKS
46 This node type has two hooks:
47 .Bl -tag -width indent
48 .It Va out
49 Packets received on this hook are considered outgoing and will be
50 masqueraded to a configured address.
51 .It Va in
52 Packets coming on this hook are considered incoming and will be
53 dealiased.
54 .El
55 .Sh CONTROL MESSAGES
56 This 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
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 Li setmode
63 Set node's operation mode using supplied
64 .Vt "struct ng_nat_mode".
65 .Bd -literal
66 struct 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
80 Configure target address for a node.
81 When an incoming packet not associated with any pre-existing aliasing
82 link arrives at the host machine, it will be sent to the specified address.
83 .It Dv NGM_NAT_REDIRECT_PORT Pq Li redirectport
84 Redirect incoming connections arriving to given port(s) to
85 another host and port(s).
86 The following
87 .Vt "struct ng_nat_redirect_port"
88 must be supplied as argument.
89 .Bd -literal
90 #define NG_NAT_DESC_LENGTH 64
91 struct 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
103 Redirection is assigned an unique ID which is returned as
104 response to this message, and
105 information about redirection added to
106 list of static redirects which later can be retrieved by
107 .Dv NGM_NAT_LIST_REDIRECTS
108 message.
109 .It Dv NGM_NAT_REDIRECT_ADDR Pq Li redirectaddr
110 Redirect traffic for public IP address to a machine on the
111 local network.
112 This function is known as
113 .Em static NAT .
114 The following
115 .Vt "struct ng_nat_redirect_addr"
116 must be supplied as argument.
117 .Bd -literal
118 struct 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
125 Unique ID for this redirection is returned as response to this message.
126 .It Dv NGM_NAT_REDIRECT_PROTO Pq Li redirectproto
127 Redirect incoming IP packets of protocol
128 .Va proto
129 (see
130 .Xr protocols 5 )
131 to a machine on the local network.
132 The following
133 .Vt "struct ng_nat_redirect_proto"
134 must be supplied as argument.
135 .Bd -literal
136 struct 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
145 Unique ID for this redirection is returned as response to this message.
146 .It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Li redirectdynamic
147 Mark redirection with specified ID as dynamic, i.e., it will serve
148 for exactly one next connection and then will be automatically
149 deleted from internal links table.
150 Only fully specified links can be made dynamic.
151 The redirection with this ID is also immediately deleted from
152 user-visible list of static redirects (available through
153 .Dv NGM_NAT_LIST_REDIRECTS
154 message).
155 .It Dv NGM_NAT_REDIRECT_DELETE Pq Li redirectdelete
156 Delete redirection with specified ID (currently active
157 connections are not affected).
158 .It Dv NGM_NAT_ADD_SERVER Pq Li addserver
159 Add another server to a pool.
160 This is used to transparently offload network load on a single server
161 and distribute the load across a pool of servers, also known as
162 .Em LSNAT
163 (RFC 2391).
164 The following
165 .Vt "struct ng_nat_add_server"
166 must be supplied as argument.
167 .Bd -literal
168 struct ng_nat_add_server {
169 uint32_t id;
170 struct in_addr addr;
171 uint16_t port;
172 };
173 .Ed
174 .Pp
175 First, the redirection is set up by
176 .Dv NGM_NAT_REDIRECT_PORT
177 or
178 .Dv NGM_NAT_REDIRECT_ADDR .
179 Then, ID of that redirection is used in multiple
180 .Dv NGM_NAT_ADD_SERVER
181 messages to add necessary number of servers.
182 For redirections created by
183 .Dv NGM_NAT_REDIRECT_ADDR ,
184 the
185 .Va port
186 is ignored and could have any value.
187 Original redirection's parameters
188 .Va local_addr
189 and
190 .Va local_port
191 are also ignored after
192 .Dv NGM_NAT_ADD_SERVER
193 was used (they are effectively replaced by server pool).
194 .It Dv NGM_NAT_LIST_REDIRECTS Pq Li listredirects
195 Return list of configured static redirects as
196 .Vt "struct ng_nat_list_redirects".
197 .Bd -literal
198 struct 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 };
210 struct 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
217 Entries of the
218 .Va redirects
219 array returned in the unified format for all redirect types.
220 Ports are meaningful only if protocol is either TCP or UDP
221 and
222 .Em static NAT
223 redirection (created by
224 .Dv NGM_NAT_REDIRECT_ADDR )
225 is indicated by
226 .Va proto
227 set to
228 .Dv NG_NAT_REDIRPROTO_ADDR .
229 If
230 .Va lsnat
231 servers counter is greater than zero, then
232 .Va local_addr
233 and
234 .Va local_port
235 are also meaningless.
236 .It Dv NGM_NAT_PROXY_RULE Pq Li proxyrule
237 Specify a transparent proxying rule (string must be
238 supplied as argument).
239 See
240 .Xr libalias 3
241 for details.
242 .El
243 .Pp
244 In all redirection messages
245 .Va local_addr
246 and
247 .Va local_port
248 mean address and port of target machine in the internal network,
249 respectively.
250 If
251 .Va alias_addr
252 is zero, then default aliasing address (set by
253 .Dv NGM_NAT_SET_IPADDR )
254 is used.
255 Connections can also be restricted to be accepted only
256 from specific external machines by using non-zero
257 .Va remote_addr
258 and/or
259 .Va remote_port .
260 Each redirection assigned an ID which can be later used for
261 redirection manipulation on individual basis (e.g., removal).
262 This ID guaranteed to be unique until the node shuts down
263 (it will not be reused after deletion), and is returned to
264 user after making each new redirection or can be found in
265 the stored list of all redirections.
266 The
267 .Va description
268 passed to and from node unchanged, together with ID providing
269 a way for several entities to concurrently manipulate
270 redirections in automated way.
271 .Sh SHUTDOWN
272 This node shuts down upon receipt of a
273 .Dv NGM_SHUTDOWN
274 control message, or when both hooks are disconnected.
275 .Sh EXAMPLES
276 In the following example, the packets are injected into a
277 .Nm nat
278 node using the
279 .Xr ng_ipfw 4
280 node.
281 .Bd -literal -offset indent
282 # Create NAT node
283 ngctl mkpeer ipfw: nat 60 out
284 ngctl name ipfw:60 nat
285 ngctl connect ipfw: nat: 61 in
286 ngctl msg nat: setaliasaddr x.y.35.8
288 # Divert traffic into NAT node
289 ipfw add 300 netgraph 61 all from any to any in via fxp0
290 ipfw add 400 netgraph 60 all from any to any out via fxp0
292 # Let packets continue with after being (de)aliased
293 sysctl net.inet.ip.fw.one_pass=0
294 .Ed
295 .Pp
296 The
297 .Nm
298 node can be inserted right after the
299 .Xr ng_iface 4
300 node in the graph.
301 In the following example, we perform masquerading on a
302 serial 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
311 SEQ
312 ifconfig 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
320 The
321 .Nm
322 node type was implemented in
323 .Fx 6.0 .
324 .Sh AUTHORS
325 .An Gleb Smirnoff Aq glebius@FreeBSD.org