Print this page
12315 errors in section 7i of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/ipnat.7i
+++ new/usr/src/man/man7i/ipnat.7i
1 1 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
2 2 .\" Copyright (c) 2017, Joyent, Inc.
3 3 .\" The contents of this file are subject to the terms of the
4 4 .\" Common Development and Distribution License (the "License").
5 5 .\" You may not use this file except in compliance with the License.
6 6 .\"
|
↓ open down ↓ |
6 lines elided |
↑ open up ↑ |
7 7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 8 .\" or http://www.opensolaris.org/os/licensing.
9 9 .\" See the License for the specific language governing permissions
10 10 .\" and limitations under the License.
11 11 .\"
12 12 .\" When distributing Covered Code, include this CDDL HEADER in each
13 13 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 14 .\" If applicable, add the following below this CDDL HEADER, with the
15 15 .\" fields enclosed by brackets "[]" replaced with your own identifying
16 16 .\" information: Portions Copyright [yyyy] [name of copyright owner]
17 -.Dd October 23, 2017
17 +.Dd February 17, 2020
18 18 .Dt IPNAT 7I
19 19 .Os
20 20 .Sh NAME
21 21 .Nm ipnat
22 22 .Nd IP Filter/NAT module interface
23 23 .Sh DESCRIPTION
24 24 The
25 25 .Sy ipnat
26 -device provides interfaction with the NAT features of the Solaris IPFilter.
26 +device provides interaction with the NAT features of the illumos IP Filter.
27 27 .Sh APPLICATION PROGRAMMING INTERFACE
28 -The NAT features programming model is a component of the Solaris IP Filter and
28 +The NAT features programming model is a component of the illumos IP Filter and
29 29 is accessed via the NAT device file
30 30 .Pa /dev/ipnat .
31 31 Opening the device for
32 32 reading or writing determines which ioctl calls can be successfully made.
33 33 .Sh IOCTLS
34 34 The caller must construct a
35 35 .Vt ipfobj
36 36 structure when issuing a
37 37 .Sy SIOCGNATL
38 38 or
39 39 SIOCSTPUT
40 40 ioctl.
41 41 The
42 42 .Vt ipfobj
43 43 structure is then passed
44 44 to the ioctl call and is filled out with
45 45 .Fa ipfo_type
46 46 set to
47 47 .Dv IPFOBJ_ Ns value .
48 48 .Dv IPFOBJ_ Ns value
49 49 provides a matching name for the structure, while
50 50 .Fa ipfo_size
51 51 is set to the total size of the structure being passed and
52 52 .Fa ipfo_ptr
53 53 is set to the structure address.
54 54 The
55 55 .Fa ipfo_rev
56 56 structure should be set to the current value of
57 57 .Dv IPFILTER_VERSION ,
58 58 while
59 59 .Fa ipfo_offset
60 60 and
61 61 .Fa ipfo_xxxpad
62 62 should be set to 0.
63 63 .Bd -literal -offset 2n
64 64 /*
65 65 * Structure used with SIOCGNATL/SIOCSTPUT.
66 66 */
67 67
68 68 /*
69 69 * Object structure description. For passing through in ioctls.
70 70 */
71 71 typedef struct ipfobj {
72 72 u_32_t ipfo_rev; /* IPFilter version (IPFILTER_VERSION) */
73 73 u_32_t ipfo_size; /* size of object at ipfo_ptr */
74 74 void *ipfo_ptr; /* pointer to object */
75 75 int ipfo_type; /* type of object being pointed to */
76 76 int ipfo_offset; /* bytes from ipfo_ptr where to start */
77 77 u_char ipfo_xxxpad[32]; /* reserved for future use */
78 78 } ipfobj_t;
79 79
80 80 #define IPFILTER_VERSION 4010901 /* IPFilter version */
81 81 #define IPFOBJ_NATSAVE 8 /* struct nat_save */
82 82 #define IPFOBJ_NATLOOKUP 9 /* struct natlookup */
83 83 .Ed
84 84 .Pp
85 85 The following
86 86 .Xr ioctl 2
87 87 calls may be used to manipulate the ipnat sub-system inside of ipf.
88 88 Note that the ipnat driver only accept calls from applications
89 89 using the same data model as the kernel.
90 90 In other words, 64-bit kernels can only accept calls from 64-bit applications.
91 91 Calls from 32-bit applications fail
92 92 with
93 93 .Er EINVAL .
94 94 .Bl -tag -width SIOCSTLCK
95 95 .It Dv SIOCSTLCK
96 96 Set or clear the NAT lock to prevent table updates attributable to packet
97 97 flow-through.
98 98 .It Dv SIOCGNATL
99 99 Search the NAT table for the rdr entry that matches the fields in the natlookup
100 100 structure.
101 101 The caller must populate the structure with the address/port
102 102 information of the accepted TCP connection
103 103 .Pq Fa nl_inip , Fa nl_inport
104 104 and the
105 105 address/port information of the peer
106 106 .Pq Fa nl_outip , Fa nl_outport .
107 107 The
108 108 .Fa nl_flags
109 109 field must have the
110 110 .Dv IPN_TCP
111 111 option set.
112 112 All other fields must be set to 0.
113 113 If the call succeeds,
114 114 .Fa nl_realip
115 115 and
116 116 .Fa nl_realport
117 117 are set to the real destination address and port, respectively.
118 118 The
119 119 .Fa nl_inport
120 120 and
121 121 .Fa nl_outport
122 122 fields must be in host byte order.
123 123 If
124 124 .Dv IPN_FINDFORWARD
125 125 is set in
126 126 .Fa nl_flags ,
127 127 a check is made to see if it is
128 128 possible to create an outgoing NAT session by checking if a packet coming from
129 129 .Pq Fa nl_realip , Fa nl_realport
130 130 and destined for
131 131 .Pq Fa nl_outip , Fa nl_outport
132 132 can be translated.
133 133 If translation is possible, the flag remains set, otherwise it is
134 134 cleared in the structure returned to the caller.
135 135 .Bd -literal -offset indent
136 136 /*
137 137 * Structure used with SIOCGNATL.
138 138 */
139 139 typedef struct natlookup {
140 140 i6addr_t nl_inipaddr;
141 141 i6addr_t nl_outipaddr;
142 142 i6addr_t nl_realipaddr;
143 143 int nl_v;
144 144 int nl_flags;
145 145 u_short nl_inport;
146 146 u_short nl_outport;
147 147 u_short nl_realport;
148 148 } natlookup_t
149 149
150 150 #define nl_inip nl_inipaddr.in4
151 151 #define nl_outip nl_outipaddr.in4
152 152 #define nl_realip nl_realipaddr.in4
153 153 #define nl_inip6 nl_inipaddr.in6
154 154 #define nl_outip6 nl_outipaddr.in6
155 155 #define nl_realip6 nl_realipaddr.in6
156 156
157 157 /*
158 158 * Accepted values for nl_flags
159 159 */
160 160 #define IPN_TCP 0x00001
161 161 #define IPN_FINDFORWARD 0x400000
162 162 .Ed
163 163 .It Dv SIOCSTPUT
164 164 Move a NAT mapping structure from user space into the kernel.
165 165 This ioctl is used by
166 166 .Xr ipfs 1M
167 167 to restore NAT sessions saved in
168 168 .Pa /var/db/ipf/ipnat.ipf .
169 169 The
170 170 .Vt nat_save
171 171 structure must have its
172 172 .Fa ipn_nat
173 173 and
174 174 .Fa ipn_ipnat
175 175 structures filled out correctly.
176 176 Fields not assigned a value must be initialised to 0.
177 177 All pointer fields are adjusted, as appropriate, once the
178 178 structure is passed into the kernel and none are preserved.
179 179 .Pp
180 180 To create a translation, the following fields must be set:
181 181 .\" Force item bodies to next line using 2n width
182 182 .Bl -tag -width 2n
183 183 .It "Interface name"
184 184 The interface name on which the host is to be exited must be
185 185 set in
186 186 .Fa nat_ifnames[0] .
187 187 .It "Local IP address and port number"
188 188 The connection's local IP address and port
189 189 number are stored in network byte order using
190 190 .Fa nat_inip Ns / Ns Fa nat_inport .
191 191 .It "Destination address/port"
192 192 The destination address/port are stored in
193 193 .Fa nat_oip Ns / Ns Fa nat_oport .
194 194 .It "Target address/port"
195 195 The translation's target address/port is stored in
196 196 .Fa nat_outip Ns / Ns Fa nat_outport .
197 197 .El
198 198 .Pp
199 199 The caller must also precalculate the checksum adjustments necessary to
200 200 complete the translation and store those values in
201 201 .Fa nat_sumd
202 202 (delta required for TCP header) and
203 203 .Fa nat_ipsumd
204 204 (delta required for IP header).
205 205 .Bd -literal -offset indent
206 206 /*
207 207 * Structures used with SIOCSTPUT.
208 208 */
209 209 typedef struct nat_save {
210 210 void *ipn_next;
211 211 struct nat ipn_nat;
212 212 struct ipnat ipn_ipnat;
213 213 struct frentry ipn_fr;
214 214 int ipn_dsize;
215 215 char ipn_data[4];
216 216 } nat_save_t;
217 217
218 218 typedef struct nat {
219 219 ipfmutex_t nat_lock;
220 220 struct nat *nat_next;
221 221 struct nat **nat_pnext;
222 222 struct nat *nat_hnext[2];
223 223 struct nat **nat_phnext[2];
224 224 struct hostmap *nat_hm;
225 225 void *nat_data;
226 226 struct nat **nat_me;
227 227 struct ipstate *nat_state;
228 228 struct ap_session *nat_aps;
229 229 frentry_t *nat_fr;
230 230 struct ipnat *nat_ptr;
231 231 void *nat_ifps[2];
232 232 void *nat_sync;
233 233 ipftqent_t nat_tqe;
234 234 u_32_t nat_flags;
235 235 u_32_t nat_sumd[2];
236 236 u_32_t nat_ipsumd;
237 237 u_32_t nat_mssclamp;
238 238 i6addr_t nat_inip6;
239 239 i6addr_t nat_outip6;
240 240 i6addr_t nat_oip6;
241 241 U_QUAD_T nat_pkts[2];
242 242 U_QUAD_T nat_bytes[2];
243 243 union {
244 244 udpinfo_t nat_unu;
245 245 tcpinfo_t nat_unt;
246 246 icmpinfo_t nat_uni;
247 247 greinfo_t nat_ugre;
248 248 } nat_un;
249 249 u_short nat_oport;
250 250 u_short nat_use;
251 251 u_char nat_p;
252 252 int nat_dir;
253 253 int nat_ref;
254 254 int nat_hv[2];
255 255 char nat_ifnames[2][LIFNAMSIZ];
256 256 int nat_rev;
257 257 int nat_v;
258 258 } nat_t;
259 259
260 260 #define nat_inip nat_inip6.in4
261 261 #define nat_outip nat_outip6.in4
262 262 #define nat_oip nat_oip6.in4
263 263 #define nat_inport nat_un.nat_unt.ts_sport
264 264 #define nat_outport nat_un.nat_unt.ts_dport
265 265 /*
266 266 * Values for nat_dir
267 267 */
268 268 #define NAT_INBOUND 0
269 269 #define NAT_OUTBOUND 1
270 270 /*
271 271 * Definitions for nat_flags
272 272 */
273 273 #define NAT_TCP 0x0001 /* IPN_TCP */
274 274 .Ed
275 275 .El
276 276 .Sh EXAMPLES
277 277 The following example shows how to prepare and use
278 278 .Fa SIOCSTPUT
279 279 to insert a NAT session directly into the table.
280 280 Note that the usual TCP/IP code is omitted is this example.
281 281 .Pp
282 282 In the code segment below,
283 283 .Fa incoming_fd
284 284 is the TCP connection file descriptor
285 285 that is accepted as part of the redirect process, while
286 286 .Fa remote_fd
287 287 is the outgoing TCP connection to the remote server being translated back to the
288 288 original IP address/port pair.
289 289 .Pp
290 290 Note \(em
291 291 The following ipnat headers must be included before you can use the code shown
292 292 in this example:
293 293 .Bd -literal -offset 2n
294 294 #include <netinet/in.h>
295 295 #include <arpa/inet.h>
296 296 #include <net/if.h>
297 297 #include <netinet/ipl.h>
298 298 #include <netinet/ip_compat.h>
299 299 #include <netinet/ip_fil.h>
300 300 #include <netinet/ip_nat.h>
301 301 #include <string.h>
302 302 #include <fcntl.h>
303 303 .Ed
304 304 .Pp
305 305 Note \(em
306 306 In the example below, various code fragments have been excluded to enhance
307 307 clarity.
308 308 .Bd -literal -offset 2n
309 309 int
310 310 translate_connection(int incoming_fd)
311 311 {
312 312 struct sockaddr_in usin;
313 313 struct natlookup nlp;
314 314 struct nat_save ns;
315 315 struct ipfobj obj;
316 316 struct nat *nat;
317 317 int remote_fd;
318 318 int nat_fd;
319 319 int onoff;
320 320
321 321 memset(&ns, 0, sizeof(ns));
322 322 nat = &ns.ipn_nat
323 323
324 324 namelen = sizeof(usin);
325 325 getsockname(remote_fd, (struct sockaddr *)&usin, &namelen);
326 326
327 327 namelen = sizeof(sin);
328 328 getpeername(incoming_fd, (struct sockaddr *) &sin, &namelen);
329 329
330 330 namelen = sizeof(sloc);
331 331 getsockname(incoming_fd, (struct sockaddr *) &sloc, &namelen);
332 332
333 333 bzero((char *) &obi, sizeof(obj));
334 334 obj.ipfo_rev = IPFILTER_VERSION;
335 335 obj.ipfo_size = sizeof(nlp);
336 336 obj.ipfo_ptr = &nip;
337 337 obj.ipfo_type = IPFOBJ_NATLOOKUP;
338 338
339 339 /*
340 340 * Build up the NAT natlookup structure.
341 341 */
342 342 bzero((char *) &nlp, sizeof(nlp));
343 343 nlp.nl_outip = sin.sin_addr;
344 344 nlp.nl_inip = sloc.sin_addr;
345 345 nlp.nl_flags = IPN_TCP;
346 346 nlp.nl_outport = ntohs(sin.sin_port);
347 347 nlp.nl_inport = ntohs(sloc.sin_port);
348 348
349 349 /*
350 350 * Open the NAT device and lookup the mapping pair.
351 351 */
352 352 nat_fd = open(IPNAT_NAME, O_RDWR);
353 353 if (ioctl(nat_fd, SIOCGNATL, &obj) != 0)
354 354 return -1;
355 355
356 356 nat->nat_inip = usin.sin_addr;
357 357 nat->nat_outip = nlp.nl_outip;
358 358 nat->nat_oip = nlp.nl_realip;
359 359
360 360 sum1 = LONG_SUM(ntohl(usin.sin_addr.s_addr)) +
361 361 ntohs(usin.sin_port);
362 362 sum2 = LONG_SUM(ntohl(nat->nat_outip.s_addr)) +
363 363 ntohs(nlp.nl_outport);
364 364 CALC_SUMD(sum1, sum2, sumd);
365 365 nat->nat_sumd[0] = (sumd & 0xffff) + (sumd >> 16);
366 366 nat->nat_sumd[1] = nat->nat_sumd[0];
367 367
368 368 sum1 = LONG_SUM(ntohl(usin.sin_addr.s_addr));
369 369 sum2 = LONG_SUM(ntohl(nat->nat_outip.s_addr));
370 370 CALC_SUMD(sum1, sum2, sumd);
371 371 nat->nat_ipsumd = (sumd & 0xffff) + (sumd >> 16);
372 372
373 373 nat->nat_inport = usin.sin_port;
374 374 nat->nat_outport = nlp.nl_outport;
375 375 nat->nat_oport = nlp.nl_realport;
376 376
377 377 nat->nat_flags = IPN_TCPUDP;
378 378
379 379 /*
380 380 * Prepare the ipfobj structure, accordingly.
381 381 */
382 382 bzero((char *)&obi, sizeof(obj));
383 383 obj.ipfo_rev = IPFILTER_VERSION;
384 384 obj.ipfo_size = sizeof(*nsp);
385 385 obj.ipfo_ptr = nsp;
386 386 obj.ipfo_type = IPFOBJ_NATSAVE;
387 387
388 388 onoff = 1;
389 389 if (ioctl(nat_fd, SIOCSTPUT, &obj) != 0)
390 390 fprintf(stderr, "Error occurred\en");
391 391
392 392 return connect(rem_fd, (struct sockaddr)&usin, sizeof(usin));
393 393 }
394 394 .Ed
395 395 .Sh ERRORS
396 396 .Bl -tag -width Er
397 397 .It Er EPERM
398 398 The device has been opened for reading only.
399 399 To succeed, the ioctl call must be opened for both reading and writing.
400 400 The call may be returned if it is
401 401 privileged and the calling process did not assert
402 402 .Brq Sy PRIV_SYS_NET_CONFIG
403 403 in the effective set.
404 404 .It Er ENOMEM
405 405 More memory was allocated than the kernel can provide.
406 406 The call may also be returned if the application inserts a NAT entry that
407 407 exceeds the hash bucket chain's maximum length.
408 408 .It Er EFAULT
409 409 The calling process specified an invalid pointer in the ipfobj structure.
410 410 .It Er EINVAL
411 411 The calling process detected a parameter or field set to an unacceptable value.
412 412 .It Er EEXIST
413 413 The calling process, via
|
↓ open down ↓ |
375 lines elided |
↑ open up ↑ |
414 414 .Dv SIOCSTPUT ,
415 415 attempted to add a NAT entry that already exists in the NAT table.
416 416 .It Er ESRCH
417 417 The calling process called
418 418 .Dv SIOCSTPUT
419 419 before setting the
420 420 .Dv SI_NEWFR
421 421 flag and providing a pointer in the
422 422 .Fa nat_fr
423 423 field that cannot be found in the current rule set.
424 -.It Er EACESS
424 +.It Er EACCES
425 425 The calling process issued a
426 426 .Dv SIOCSTPUT
427 427 before issuing a
428 428 .Dv SIOCSTLCK .
429 429 .El
430 430 .Sh INTERFACE STABILITY
431 431 Committed
432 432 .Sh SEE ALSO
433 433 .Xr ipfs 1M ,
434 434 .Xr ipnat 1M ,
435 435 .Xr ioctl 2 ,
436 436 .Xr attributes 5
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX