Print this page
10522 Convert ipnat(7I) to mandoc
@@ -1,9 +1,7 @@
IPNAT(7I) Ioctl Requests IPNAT(7I)
-
-
NAME
ipnat - IP Filter/NAT module interface
DESCRIPTION
The ipnat device provides interfaction with the NAT features of the
@@ -14,22 +12,23 @@
Filter and is accessed via the NAT device file /dev/ipnat. Opening the
device for reading or writing determines which ioctl calls can be
successfully made.
IOCTLS
- The caller must construct a ipfobj structure when issuing a SIOCGNATL
- or SIOCSTPUT. The ipfobj structure is then passed to the ioctl call and
- is filled out with ipfo_type set to IPFOBJ_value. IPFOBJ_ value
- provides a matching name for the structure, while ipfo_size is set to
- the total size of the structure being passed and ipfo_ptr is set to the
+ The caller must construct a ipfobj structure when issuing a SIOCGNATL or
+ SIOCSTPUT ioctl. The ipfobj structure is then passed to the ioctl call
+ and is filled out with ipfo_type set to IPFOBJ_value. IPFOBJ_value
+ provides a matching name for the structure, while ipfo_size is set to the
+ total size of the structure being passed and ipfo_ptr is set to the
structure address. The ipfo_rev structure should be set to the current
value of IPFILTER_VERSION, while ipfo_offset and ipfo_xxxpad should be
set to 0.
/*
* 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) */
@@ -42,41 +41,33 @@
#define IPFILTER_VERSION 4010901 /* IPFilter version */
#define IPFOBJ_NATSAVE 8 /* struct nat_save */
#define IPFOBJ_NATLOOKUP 9 /* struct natlookup */
-
-
- The following ioctl() calls may be used to manipulate the ipnat sub-
+ The following ioctl(2) calls may be used to manipulate the ipnat sub-
system inside of ipf. Note that the ipnat 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 EINVAL.
- SIOCSTLCK
- Set or clear the NAT lock to prevent table updates
+ SIOCSTLCK Set or clear the NAT lock to prevent table updates
attributable to packet flow-through.
-
- SIOCGNATL
- Search the NAT table for the rdr entry that matches the
- fields in the natlookup structure. The caller must
- populate the structure with the address/port information
- of the accepted TCP connection (nl_inip, nl_inport) and
- the address/port information of the peer (nl_outip,
- nl_outport). The nl_flags field must have the IPN_TCP
- option set. All other fields must be set to 0. If the
- call succeeds, nl_realip and nl_realport are set to the
- real destination address and port, respectively. The
- nl_inport and nl_outport fields must be in host byte
- order.
-
- If IPN_FINDFORWARD is set in nl_flags, a check is made to
- see if it is possible to create an outgoing NAT session by
- checking if a packet coming from (nl_realip,nl_realport)
- and destined for (nl_outip,nl_outport) can be translated.
- If translation is possible, the flag remains set,
+ SIOCGNATL Search the NAT table for the rdr entry that matches the fields
+ in the natlookup structure. The caller must populate the
+ structure with the address/port information of the accepted
+ TCP connection (nl_inip, nl_inport) and the address/port
+ information of the peer (nl_outip, nl_outport). The nl_flags
+ field must have the IPN_TCP option set. All other fields must
+ be set to 0. If the call succeeds, nl_realip and nl_realport
+ are set to the real destination address and port,
+ respectively. The nl_inport and nl_outport fields must be in
+ host byte order. If IPN_FINDFORWARD is set in nl_flags, a
+ check is made to see if it is possible to create an outgoing
+ NAT session by checking if a packet coming from (nl_realip,
+ nl_realport) and destined for (nl_outip, nl_outport) can be
+ translated. If translation is possible, the flag remains set,
otherwise it is cleared in the structure returned to the
caller.
/*
* Structure used with SIOCGNATL.
@@ -103,36 +94,40 @@
* Accepted values for nl_flags
*/
#define IPN_TCP 0x00001
#define IPN_FINDFORWARD 0x400000
+ SIOCSTPUT Move a NAT mapping structure from user space into the kernel.
+ This ioctl is used by ipfs(1M) to restore NAT sessions saved
+ in /var/db/ipf/ipnat.ipf. The nat_save structure must have
+ its ipn_nat and ipn_ipnat structures filled out correctly.
+ Fields not assigned a value must be initialised to 0. All
+ pointer fields are adjusted, as appropriate, once the
+ structure is passed into the kernel and none are preserved.
+ To create a translation, the following fields must be set:
- SIOCSTPUT
- Move a NAT mapping structure from user space into the
- kernel. This ioctl is used by ipfs(1M) to restore NAT
- sessions saved in /var/db/ipf/ipnat.ipf. The nat_save
- structure must have its ipn_nat and ipn_ipnat structures
- filled out correctly. Fields not assigned a value must be
- initialised to 0. All pointer fields are adjusted, as
- appropriate, once the structure is passed into the kernel
- and none are preserved.
+ Interface name
+ The interface name on which the host is to be exited must
+ be set in nat_ifnames[0].
- To create a translation, the following fields must be set:
- Interface name - The interface name on which the host is
- to be exited must be set in nat_ifnames[0].
- Local IP address and port number - The connection's
- local IP address and port number are stored in network
- byte order using nat_inip/nat_inport.
- Destination address/port - The destination address/port
- are stored in nat_oip/nat_oport.
- Target address/port - The translation's target
- address/port is stored in nat_outip/nat_outport.
+ Local IP address and port number
+ The connection's local IP address and port number are
+ stored in network byte order using nat_inip/nat_inport.
+
+ Destination address/port
+ The destination address/port are stored in
+ nat_oip/nat_oport.
+
+ Target address/port
+ The translation's target address/port is stored in
+ nat_outip/nat_outport.
+
The caller must also precalculate the checksum adjustments
- necessary to complete the translation and store those
- values in nat_sumd (delta required for TCP header) and
- nat_ipsumd (delta required for IP header).
+ necessary to complete the translation and store those values
+ in nat_sumd (delta required for TCP header) and nat_ipsumd
+ (delta required for IP header).
/*
* Structures used with SIOCSTPUT.
*/
typedef struct nat_save {
@@ -199,28 +194,23 @@
/*
* Definitions for nat_flags
*/
#define NAT_TCP 0x0001 /* IPN_TCP */
-
-
EXAMPLES
- The following example shows how to prepare and use SIOCSTPUT to insert
- a NAT session directly into the table. Note that the usual TCP/IP code
- is omitted is this example.
+ The following example shows how to prepare and use SIOCSTPUT to insert a
+ NAT session directly into the table. Note that the usual TCP/IP code is
+ omitted is this example.
-
In the code segment below, incoming_fd is the TCP connection file
descriptor that is accepted as part of the redirect process, while
remote_fd is the outgoing TCP connection to the remote server being
translated back to the original IP address/port pair.
- Note -
+ Note -- The following ipnat headers must be included before you can use
+ the code shown in this example:
- The following ipnat headers must be included before you can use the
- code shown in this example:
-
#include <netinet/in.h>
#include <arpa/inet.h>
#include <net/if.h>
#include <netinet/ipl.h>
#include <netinet/ip_compat.h>
@@ -227,16 +217,13 @@
#include <netinet/ip_fil.h>
#include <netinet/ip_nat.h>
#include <string.h>
#include <fcntl.h>
+ Note -- In the example below, various code fragments have been excluded
+ to enhance clarity.
- Note -
-
- In the example below, various code fragments have been excluded to
- enhance clarity.
-
int
translate_connection(int incoming_fd)
{
struct sockaddr_in usin;
struct natlookup nlp;
@@ -316,68 +303,44 @@
onoff = 1;
if (ioctl(nat_fd, SIOCSTPUT, &obj) != 0)
fprintf(stderr, "Error occurred\n");
- return connect(rem_fd, (struct sockaddr ) &usin, sizeof(usin));
+ return connect(rem_fd, (struct sockaddr)&usin, sizeof(usin));
}
-
ERRORS
- EPERM
- 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 {PRIV_SYS_NET_CONFIG} in the
- effective set.
+ EPERM 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
+ {PRIV_SYS_NET_CONFIG} in the effective set.
+ ENOMEM 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.
- ENOMEM
- 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.
+ EFAULT The calling process specified an invalid pointer in
+ the ipfobj structure.
+ EINVAL The calling process detected a parameter or field set
+ to an unacceptable value.
- EFAULT
- The calling process specified an invalid pointer in the
- ipfobj structure.
+ EEXIST The calling process, via SIOCSTPUT, attempted to add a
+ NAT entry that already exists in the NAT table.
+ ESRCH The calling process called SIOCSTPUT before setting
+ the SI_NEWFR flag and providing a pointer in the
+ nat_fr field that cannot be found in the current rule
+ set.
- EINVAL
- The calling process detected a parameter or field set to an
- unacceptable value.
+ EACESS The calling process issued a SIOCSTPUT before issuing
+ a SIOCSTLCK.
+INTERFACE STABILITY
+ Committed
- EEXIST
- The calling process, via SIOCSTPUT, attempted to add a NAT
- entry that already exists in the NAT table.
-
-
- ESRCH
- The calling process called SIOCSTPUT before setting the
- SI_NEWFR flag and providing a pointer in the nat_fr field
- that cannot be found in the current rule set.
-
-
- EACESS
- The calling process issued a SIOCSTPUT before issuing a
- SIOCSTLCK.
-
-
-ATTRIBUTES
- See attributes(5) for descriptions of the following attributes:
-
-
-
-
- +--------------------+-----------------+
- | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
- +--------------------+-----------------+
- |Interface Stability | Committed |
- +--------------------+-----------------+
-
SEE ALSO
ipfs(1M), ipnat(1M), ioctl(2), attributes(5)
-
-
- May 22, 2008 IPNAT(7I)
+illumos October 23, 2017 illumos