All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
$FreeBSD: releng/10.2/share/man/man4/ng_nat.4 248582 2013-03-21 13:02:43Z glebius $
.Dd March 21, 2013 .Dt NG_NAT 4 .Os .Sh NAME .Nm ng_nat .Nd "NAT netgraph node type" .Sh SYNOPSIS n netgraph/ng_nat.h .Sh DESCRIPTION An .Nm node performs network address translation (NAT) of packets passing through it. A .Nm nat node uses .Xr libalias 3 engine for packet aliasing. .Sh HOOKS This node type has two hooks: l -tag -width ".Va out" t Va out Packets received on this hook are considered outgoing and will be masqueraded to a configured address. t Va in Packets coming on this hook are considered incoming and will be dealiased. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: l -tag -width foo t Dv NGM_NAT_SET_IPADDR Pq Ic setaliasaddr Configure aliasing address for a node. After both hooks have been connected and aliasing address was configured, a node is ready for aliasing operation. t Dv NGM_NAT_SET_MODE Pq Ic setmode Set node's operation mode using supplied .Vt "struct ng_nat_mode" . d -literal struct ng_nat_mode { uint32_t flags; uint32_t mask; }; /* Supported flags: */ #define NG_NAT_LOG 0x01 #define NG_NAT_DENY_INCOMING 0x02 #define NG_NAT_SAME_PORTS 0x04 #define NG_NAT_UNREGISTERED_ONLY 0x10 #define NG_NAT_RESET_ON_ADDR_CHANGE 0x20 #define NG_NAT_PROXY_ONLY 0x40 #define NG_NAT_REVERSE 0x80 .Ed t Dv NGM_NAT_SET_TARGET Pq Ic settarget Configure target address for a node. When an incoming packet not associated with any pre-existing aliasing link arrives at the host machine, it will be sent to the specified address. t Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport Redirect incoming connections arriving to given port(s) to another host and port(s). The following .Vt "struct ng_nat_redirect_port" must be supplied as argument. d -literal #define NG_NAT_DESC_LENGTH 64 struct ng_nat_redirect_port { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed
p Redirection is assigned an unique ID which is returned as response to this message, and information about redirection added to list of static redirects which later can be retrieved by .Dv NGM_NAT_LIST_REDIRECTS message. t Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr Redirect traffic for public IP address to a machine on the local network. This function is known as .Em static NAT . The following .Vt "struct ng_nat_redirect_addr" must be supplied as argument. d -literal struct ng_nat_redirect_addr { struct in_addr local_addr; struct in_addr alias_addr; char description[NG_NAT_DESC_LENGTH]; }; .Ed
p Unique ID for this redirection is returned as response to this message. t Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto Redirect incoming IP packets of protocol .Va proto (see .Xr protocols 5 ) to a machine on the local network. The following .Vt "struct ng_nat_redirect_proto" must be supplied as argument. d -literal struct ng_nat_redirect_proto { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed
p Unique ID for this redirection is returned as response to this message. t Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic Mark redirection with specified ID as dynamic, i.e., it will serve for exactly one next connection and then will be automatically deleted from internal links table. Only fully specified links can be made dynamic. The redirection with this ID is also immediately deleted from user-visible list of static redirects (available through .Dv NGM_NAT_LIST_REDIRECTS message). t Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete Delete redirection with specified ID (currently active connections are not affected). t Dv NGM_NAT_ADD_SERVER Pq Ic addserver Add another server to a pool. This is used to transparently offload network load on a single server and distribute the load across a pool of servers, also known as .Em LSNAT (RFC 2391). The following .Vt "struct ng_nat_add_server" must be supplied as argument. d -literal struct ng_nat_add_server { uint32_t id; struct in_addr addr; uint16_t port; }; .Ed
p First, the redirection is set up by .Dv NGM_NAT_REDIRECT_PORT or .Dv NGM_NAT_REDIRECT_ADDR . Then, ID of that redirection is used in multiple .Dv NGM_NAT_ADD_SERVER messages to add necessary number of servers. For redirections created by .Dv NGM_NAT_REDIRECT_ADDR , the .Va port is ignored and could have any value. Original redirection's parameters .Va local_addr and .Va local_port are also ignored after .Dv NGM_NAT_ADD_SERVER was used (they are effectively replaced by server pool). t Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects Return list of configured static redirects as .Vt "struct ng_nat_list_redirects" . d -literal struct ng_nat_listrdrs_entry { uint32_t id; /* Anything except zero */ struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint16_t proto; /* Valid proto or NG_NAT_REDIRPROTO_ADDR */ uint16_t lsnat; /* LSNAT servers count */ char description[NG_NAT_DESC_LENGTH]; }; struct ng_nat_list_redirects { uint32_t total_count; struct ng_nat_listrdrs_entry redirects[]; }; #define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3) .Ed
p Entries of the .Va redirects array returned in the unified format for all redirect types. Ports are meaningful only if protocol is either TCP or UDP and .Em static NAT redirection (created by .Dv NGM_NAT_REDIRECT_ADDR ) is indicated by .Va proto set to .Dv NG_NAT_REDIRPROTO_ADDR . If .Va lsnat servers counter is greater than zero, then .Va local_addr and .Va local_port are also meaningless. t Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule Specify a transparent proxying rule (string must be supplied as argument). See .Xr libalias 3 for details. t Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo Return internal statistics of .Xr libalias 3 instance as .Vt "struct ng_nat_libalias_info" . d -literal struct ng_nat_libalias_info { uint32_t icmpLinkCount; uint32_t udpLinkCount; uint32_t tcpLinkCount; uint32_t sctpLinkCount; uint32_t pptpLinkCount; uint32_t protoLinkCount; uint32_t fragmentIdLinkCount; uint32_t fragmentPtrLinkCount; uint32_t sockCount; }; .Ed In case of .Nm failed to retreive a certain counter from its .Xr libalias instance, the corresponding field is returned as .Va UINT32_MAX . .El
p In all redirection messages .Va local_addr and .Va local_port mean address and port of target machine in the internal network, respectively. If .Va alias_addr is zero, then default aliasing address (set by .Dv NGM_NAT_SET_IPADDR ) is used. Connections can also be restricted to be accepted only from specific external machines by using non-zero .Va remote_addr and/or .Va remote_port . Each redirection assigned an ID which can be later used for redirection manipulation on individual basis (e.g., removal). This ID guaranteed to be unique until the node shuts down (it will not be reused after deletion), and is returned to user after making each new redirection or can be found in the stored list of all redirections. The .Va description passed to and from node unchanged, together with ID providing a way for several entities to concurrently manipulate redirections in automated way. .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when both hooks are disconnected. .Sh EXAMPLES In the following example, the packets are injected into a .Nm nat node using the .Xr ng_ipfw 4 node. d -literal -offset indent # Create NAT node ngctl mkpeer ipfw: nat 60 out ngctl name ipfw:60 nat ngctl connect ipfw: nat: 61 in ngctl msg nat: setaliasaddr x.y.35.8 # Divert traffic into NAT node ipfw add 300 netgraph 61 all from any to any in via fxp0 ipfw add 400 netgraph 60 all from any to any out via fxp0 # Let packets continue with after being (de)aliased sysctl net.inet.ip.fw.one_pass=0 .Ed
p The .Nm node can be inserted right after the .Xr ng_iface 4 node in the graph. In the following example, we perform masquerading on a serial line with HDLC encapsulation. d -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer cp0: cisco rawdata downstream name cp0:rawdata hdlc mkpeer hdlc: nat inet in name hdlc:inet nat mkpeer nat: iface out inet msg nat: setaliasaddr x.y.8.35 SEQ ifconfig ng0 x.y.8.35 x.y.8.1 .Ed .Sh SEE ALSO .Xr libalias 3 , .Xr ng_ipfw 4 , .Xr natd 8 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 6.0 . .Sh AUTHORS .An Gleb Smirnoff Aq glebius@FreeBSD.org