'\" te .\" Copyright (c) 2008, 2011, Oracle and/or its affiliates. All rights reserved. .TH ipnat 7I "2 Aug 2011" "SunOS 5.11" "Ioctl Requests" .SH NAME ipnat \- IP Filter/NAT module interface .SH DESCRIPTION .sp .LP The \fBipnat\fR device provides interaction with the NAT features of the Oracle Solaris IPFilter. .SH APPLICATION PROGRAMMING INTERFACE .sp .LP The NAT features programming model is a component of the Oracle Solaris IP Filter and is accessed by way of the NAT device file \fB/dev/ipnat\fR. Opening the device for reading or writing determines which ioctl calls can be successfully made. .SH IOCTLS .sp .LP The caller must construct a \fBipfobj\fR structure when issuing a \fBSIOCGNATL\fR or \fBSIOCSTPUT\fR. The \fBipfobj\fR structure is then passed to the ioctl call and is filled out with \fBipfo_type\fR set to \fBIPFOBJ_value\fR. \fBIPFOBJ_ value\fR provides a matching name for the structure, while \fBipfo_size\fR is set to the total size of the structure being passed and \fBipfo_ptr\fR is set to the structure address. The \fBipfo_rev\fR structure should be set to the current value of \fBIPFILTER_VERSION\fR, while \fBipfo_offset\fR and \fBipfo_xxxpad\fR should be set to \fB0\fR. .sp .in +2 .nf /* * Structure used with SIOCGNATL/SIOCSTPUT. */ /* * Object structure description. For passing through in ioctls. */ typedef struct ipfobj { u_32_t ipfo_rev; /* IPFilter version (IPFILTER_VERSION) */ u_32_t ipfo_size; /* size of object at ipfo_ptr */ void *ipfo_ptr; /* pointer to object */ int ipfo_type; /* type of object being pointed to */ int ipfo_offset; /* bytes from ipfo_ptr where to start */ u_char ipfo_xxxpad[32]; /* reserved for future use */ } ipfobj_t; #define IPFILTER_VERSION 4010902 /* IPFilter version */ #define IPFOBJ_NATSAVE 8 /* struct nat_save */ #define IPFOBJ_NATLOOKUP 9 /* struct natlookup */ .fi .in -2 .sp .LP The following \fBioctl()\fR calls may be used to manipulate the \fBipnat\fR sub-system inside of \fBipf\fR. The \fBipnat\fR driver only accept calls from applications using the same data model as the kernel. In other words, 64-bit kernels can only accept calls from 64-bit applications. Calls from 32-bit applications fail with \fBEINVAL\fR. .sp .ne 2 .mk .na \fB\fBSIOCSTLCK\fR\fR .ad .RS 13n .rt Set or clear the NAT lock to prevent table updates attributable to packet flow-through. .RE .sp .ne 2 .mk .na \fB\fBSIOCGNATL\fR\fR .ad .RS 13n .rt Search the NAT table for the \fBrdr\fR entry that matches the fields in the \fBnatlookup\fR structure. The caller must populate the structure with the address/port information of the accepted TCP connection (\fBnl_inip, nl_inport\fR) and the address/port information of the peer (\fBnl_outip, nl_outport\fR). In case an application desires to look up NAT table for IPv6, then requested information must be passed using different members: \fBnl_inip6\fR and \fBnl_outip6\fR for IPv6. The \fBnl_flags\fR field must have the \fBIPN_TCP\fR option set. All other fields must be set to \fB0\fR. If the call succeeds, \fBnl_realip\fR (eventually \fBnl_realip6\fR in case look up is being performed in IPv6 NAT table) and \fBnl_realport\fR are set to the real destination address and port, respectively. The \fBnl_inport\fR and \fBnl_outport\fR fields must be in host byte order. If \fBIPN_FINDFORWARD\fR is set in \fBnl_flags\fR, a check is made to see if it is possible to create an outgoing NAT session by checking if a packet coming from (\fBnl_realip,nl_realport\fR) and destined for ( \fBnl_outip,nl_outport\fR) can be translated. If translation is possible, the flag remains set, otherwise it is cleared in the structure returned to the caller. .sp .in +2 .nf /* * Structure used with SIOCGNATL. */ typedef struct natlookup { i6addr_t nl_inipaddr; i6addr_t nl_outipaddr; i6addr_t nl_realipaddr; int nl_v; int nl_flags; u_short nl_inport; u_short nl_outport; u_short nl_realport; } natlookup_t #define nl_inip nl_inipaddr.in4 #define nl_outip nl_outipaddr.in4 #define nl_realip nl_realipaddr.in4 #define nl_inip6 nl_inipaddr.in6 #define nl_outip6 nl_outipaddr.in6 #define nl_realip6 nl_realipaddr.in6 /* * Accepted values for nl_flags */ #define IPN_TCP 0x00001 #define IPN_FINDFORWARD 0x400000 .fi .in -2 .RE .sp .ne 2 .mk .na \fB\fBSIOCSTPUT\fR\fR .ad .RS 13n .rt Move a NAT mapping structure from user space into the kernel. This ioctl is used by \fBipfs\fR(1M) to restore NAT sessions saved in \fB/var/db/ipf/ipnat.ipf\fR. The \fBnat_save\fR structure must have its \fBipn_nat\fR and \fBipn_ipnat\fR structures filled out correctly. Fields not assigned a value must be initialized to \fB0\fR. All pointer fields are adjusted, as appropriate, once the structure is passed into the kernel and none are preserved. .sp To create a translation, the following fields must be set: .br .in +2 Interface name - The interface name on which the host is to be exited must be set in \fBnat_ifnames[0]\fR. .in -2 .br .in +2 Local IP address and port number - The connection's local IP address and port number are stored in network byte order using \fBnat_inip/nat_inport\fR. .in -2 .br .in +2 Destination address/port - The destination address/port are stored in \fBnat_oip/nat_oport\fR. If you are using IPv6, you must use \fBnat_inip6.in6\fR member to pass local IPv6 address. .in -2 .br .in +2 Target address/port - The translation's target address/port is stored in \fBnat_outip/nat_outport\fR. If you are using IPv6, you must use \fBnat_outip6.in6\fR member to pass translation target address. .in -2 .sp .in +2 .nf /* * Structures used with SIOCSTPUT. */ typedef struct nat_save { void *ipn_next; struct nat ipn_nat; struct ipnat ipn_ipnat; struct frentry ipn_fr; int ipn_dsize; char ipn_data[4]; } nat_save_t; typedef struct nat { ipfmutex_t nat_lock; struct nat *nat_next; struct nat **nat_pnext; struct nat *nat_hnext[2]; struct nat **nat_phnext[2]; struct hostmap *nat_hm; void *nat_data; struct nat **nat_me; struct ipstate *nat_state; struct ap_session *nat_aps; frentry_t *nat_fr; struct ipnat *nat_ptr; void *nat_ifps[2]; void *nat_sync; ipftqent_t nat_tqe; u_32_t nat_flags; u_32_t nat_sumd[2]; u_32_t nat_ipsumd; u_32_t nat_mssclamp; i6addr_t nat_inip6; i6addr_t nat_outip6; i6addr_t nat_oip6; U_QUAD_T nat_pkts[2]; U_QUAD_T nat_bytes[2]; union { udpinfo_t nat_unu; tcpinfo_t nat_unt; icmpinfo_t nat_uni; greinfo_t nat_ugre; } nat_un; u_short nat_oport; u_short nat_use; u_char nat_p; int nat_dir; int nat_ref; int nat_hv[2]; char nat_ifnames[2][LIFNAMSIZ]; int nat_rev; int nat_v; int nat_redir; } nat_t; #define nat_inip nat_inip6.in4 #define nat_outip nat_outip6.in4 #define nat_oip nat_oip6.in4 #define nat_inport nat_un.nat_unt.ts_sport #define nat_outport nat_un.nat_unt.ts_dport /* * Values for nat_dir, nat_redir * both members have to be set to same value by proxy app. */ #define NAT_INBOUND 0 #define NAT_OUTBOUND 1 /* * Definitions for nat_flags */ #define NAT_TCP 0x0001 /* IPN_TCP */ .fi .in -2 .RE .SH EXAMPLES .sp .LP The following example shows how to prepare and use \fBSIOCSTPUT\fR to insert a NAT session directly into the table. The usual TCP/IP code is omitted is this example. .sp .LP In the code segment below, \fBincoming_fd\fR is the TCP connection file descriptor that is accepted as part of the redirect process, while \fBremote_fd\fR is the outgoing TCP connection to the remote server being translated back to the original IP address/port pair. .sp .LP The following \fBipnat\fR headers must be included before you can use the code shown in this example: .sp .in +2 .nf #include #include #include #include #include #include #include #include #include .fi .in -2 .sp .LP In the example below, various code fragments have been excluded to enhance clarity. .sp .in +2 .nf int translate_connection(int incoming_fd) { struct sockaddr_in usin; struct natlookup nlp; struct nat_save ns; struct ipfobj obj; struct nat *nat; int remote_fd; int nat_fd; int onoff; memset(&ns, 0, sizeof(ns)); nat = &ns.ipn_nat namelen = sizeof(usin); getsockname(remote_fd, (struct sockaddr *)&usin, &namelen); namelen = sizeof(sin); getpeername(incoming_fd, (struct sockaddr *) &sin, &namelen); namelen = sizeof(sloc); getsockname(incoming_fd, (struct sockaddr *) &sloc, &namelen); bzero((char *) &obj, sizeof(obj)); obj.ipfo_rev = IPFILTER_VERSION; obj.ipfo_size = sizeof(nlp); obj.ipfo_ptr = &nlp; obj.ipfo_type = IPFOBJ_NATLOOKUP; /* * Build up the NAT natlookup structure. */ bzero((char *) &nlp, sizeof(nlp)); nlp.nl_outip = sin.sin_addr; nlp.nl_inip = sloc.sin_addr; /* * In case your implementation uses IPv6, then you have to use * nlp.nl_outip6, nlp.nl_inip6 members instead of * nlp.nl_outip, nlp.nl_inip. */ nlp.nl_flags = IPN_TCP; nlp.nl_outport = ntohs(sin.sin_port); nlp.nl_inport = ntohs(sloc.sin_port); /* * Open the NAT device and lookup the mapping pair. */ nat_fd = open(IPNAT_NAME, O_RDWR); if (ioctl(nat_fd, SIOCGNATL, &obj) != 0) return -1; nat->nat_inip = usin.sin_addr; nat->nat_outip = nlp.nl_outip; nat->nat_oip = nlp.nl_realip; /* * Again in case you are using IPv6, you need to use a different * members here: * nat_inip6.in6 * nat_outip6.in6 * nat_oip6.in6 */ nat->nat_inport = usin.sin_port; nat->nat_outport = nlp.nl_outport; nat->nat_oport = nlp.nl_realport; nat->nat_v = 4; /* * Use nat->nat_v = 6, in case you are dealing with IPv6 */ nat->nat_flags = IPN_TCPUDP; /* * Prepare the ipfobj structure, accordingly. */ bzero((char *)&obj, sizeof(obj)); obj.ipfo_rev = IPFILTER_VERSION; obj.ipfo_size = sizeof(*nsp); obj.ipfo_ptr = nsp; obj.ipfo_type = IPFOBJ_NATSAVE; onoff = 1; if (ioctl(nat_fd, SIOCSTPUT, &obj) != 0) fprintf(stderr, "Error occurred\en"); return connect(rem_fd, (struct sockaddr ) &usin, sizeof(usin)); } .fi .in -2 .SH ERRORS .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 10n .rt The device has been opened for reading only. To succeed, the ioctl call must be opened for both reading and writing. The call may be returned if it is privileged and the calling process did not assert \fB{PRIV_SYS_NET_CONFIG}\fR in the effective set. .RE .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt More memory was allocated than the kernel can provide. The call may also be returned if the application inserts a NAT entry that exceeds the hash bucket chain's maximum length. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 10n .rt The calling process specified an invalid pointer in the \fBipfobj\fR structure. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt The calling process detected a parameter or field set to an unacceptable value. .RE .sp .ne 2 .mk .na \fB\fBEEXIST\fR\fR .ad .RS 10n .rt The calling process, by way of \fBSIOCSTPUT\fR, attempted to add a NAT entry that already exists in the NAT table. .RE .sp .ne 2 .mk .na \fB\fBESRCH\fR\fR .ad .RS 10n .rt The calling process called \fBSIOCSTPUT\fR before setting the \fBSI_NEWFR\fR flag and providing a pointer in the \fBnat_fr\fR field that cannot be found in the current rule set. .RE .sp .ne 2 .mk .na \fB\fBEACESS\fR\fR .ad .RS 10n .rt The calling process issued a \fBSIOCSTPUT\fR before issuing a \fBSIOCSTLCK\fR. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted .TE .SH SEE ALSO .sp .LP \fBipfs\fR(1M), \fBipnat\fR(1M), \fBioctl\fR(2), \fBattributes\fR(5)