xref: /freebsd/share/man/man4/ng_nat.4 (revision 7447ca0eb235974642312b9555caec00b57d8fc1)
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