share/man/man4/ng_nat.4

   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
  36 An
  37 .Nm
  38 node performs network address translation (NAT) of packets
  39 passing through it.
  40 A
  41 .Nm nat
  42 node uses
  43 .Xr libalias 3
  44 engine for packet aliasing.
  45 .Sh HOOKS
  46 This node type has two hooks:
  47 .Bl -tag -width ".Va out"
  48 .It Va out
  49 Packets received on this hook are considered outgoing and will be
  50 masqueraded to a configured address.
  51 .It Va in
  52 Packets coming on this hook are considered incoming and will be
  53 dealiased.
  54 .El
  55 .Sh CONTROL MESSAGES
  56 This 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
  59 Configure aliasing address for a node.
  60 After both hooks have been connected and aliasing address was configured,
  61 a node is ready for aliasing operation.
  62 .It Dv NGM_NAT_SET_MODE Pq Ic setmode
  63 Set node's operation mode using supplied
  64 .Vt "struct ng_nat_mode" .
  65 .Bd -literal
  66 struct 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
  80 Configure target address for a node.
  81 When an incoming packet not associated with any pre-existing aliasing
  82 link arrives at the host machine, it will be sent to the specified address.
  83 .It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport
  84 Redirect incoming connections arriving to given port(s) to
  85 another host and port(s).
  86 The following
  87 .Vt "struct ng_nat_redirect_port"
  88 must be supplied as argument.
  89 .Bd -literal
  90 #define NG_NAT_DESC_LENGTH      64
  91 struct 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
 103 Redirection is assigned an unique ID which is returned as
 104 response to this message, and
 105 information about redirection added to
 106 list of static redirects which later can be retrieved by
 107 .Dv NGM_NAT_LIST_REDIRECTS
 108 message.
 109 .It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr
 110 Redirect traffic for public IP address to a machine on the
 111 local network.
 112 This function is known as
 113 .Em static NAT .
 114 The following
 115 .Vt "struct ng_nat_redirect_addr"
 116 must be supplied as argument.
 117 .Bd -literal
 118 struct 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
 125 Unique ID for this redirection is returned as response to this message.
 126 .It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto
 127 Redirect incoming IP packets of protocol
 128 .Va proto
 129 (see
 130 .Xr protocols 5 )
 131 to a machine on the local network.
 132 The following
 133 .Vt "struct ng_nat_redirect_proto"
 134 must be supplied as argument.
 135 .Bd -literal
 136 struct 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
 145 Unique ID for this redirection is returned as response to this message.
 146 .It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic
 147 Mark redirection with specified ID as dynamic, i.e., it will serve
 148 for exactly one next connection and then will be automatically
 149 deleted from internal links table.
 150 Only fully specified links can be made dynamic.
 151 The redirection with this ID is also immediately deleted from
 152 user-visible list of static redirects (available through
 153 .Dv NGM_NAT_LIST_REDIRECTS
 154 message).
 155 .It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete
 156 Delete redirection with specified ID (currently active
 157 connections are not affected).
 158 .It Dv NGM_NAT_ADD_SERVER Pq Ic addserver
 159 Add another server to a pool.
 160 This is used to transparently offload network load on a single server
 161 and distribute the load across a pool of servers, also known as
 162 .Em LSNAT
 163 (RFC 2391).
 164 The following
 165 .Vt "struct ng_nat_add_server"
 166 must be supplied as argument.
 167 .Bd -literal
 168 struct ng_nat_add_server {
 169         uint32_t        id;
 170         struct in_addr  addr;
 171         uint16_t        port;
 172 };
 173 .Ed
 174 .Pp
 175 First, the redirection is set up by
 176 .Dv NGM_NAT_REDIRECT_PORT
 177 or
 178 .Dv NGM_NAT_REDIRECT_ADDR .
 179 Then, ID of that redirection is used in multiple
 180 .Dv NGM_NAT_ADD_SERVER
 181 messages to add necessary number of servers.
 182 For redirections created by
 183 .Dv NGM_NAT_REDIRECT_ADDR ,
 184 the
 185 .Va port
 186 is ignored and could have any value.
 187 Original redirection's parameters
 188 .Va local_addr
 189 and
 190 .Va local_port
 191 are also ignored after
 192 .Dv NGM_NAT_ADD_SERVER
 193 was used (they are effectively replaced by server pool).
 194 .It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects
 195 Return list of configured static redirects as
 196 .Vt "struct ng_nat_list_redirects" .
 197 .Bd -literal
 198 struct 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 };
 210 struct 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
 217 Entries of the
 218 .Va redirects
 219 array returned in the unified format for all redirect types.
 220 Ports are meaningful only if protocol is either TCP or UDP
 221 and
 222 .Em static NAT
 223 redirection (created by
 224 .Dv NGM_NAT_REDIRECT_ADDR )
 225 is indicated by
 226 .Va proto
 227 set to
 228 .Dv NG_NAT_REDIRPROTO_ADDR .
 229 If
 230 .Va lsnat
 231 servers counter is greater than zero, then
 232 .Va local_addr
 233 and
 234 .Va local_port
 235 are also meaningless.
 236 .It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule
 237 Specify a transparent proxying rule (string must be
 238 supplied as argument).
 239 See
 240 .Xr libalias 3
 241 for details.
 242 .It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo
 243 Return internal statistics of
 244 .Xr libalias 3
 245 instance as
 246 .Vt "struct ng_nat_libalias_info" .
 247 .Bd -literal
 248 struct 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
 260 In case of
 261 .Nm
 262 failed to retreive a certain counter
 263 from its
 264 .Xr libalias
 265 instance, the corresponding field is returned as
 266 .Va UINT32_MAX .
 267 .El
 268 .Pp
 269 In all redirection messages
 270 .Va local_addr
 271 and
 272 .Va local_port
 273 mean address and port of target machine in the internal network,
 274 respectively.
 275 If
 276 .Va alias_addr
 277 is zero, then default aliasing address (set by
 278 .Dv NGM_NAT_SET_IPADDR )
 279 is used.
 280 Connections can also be restricted to be accepted only
 281 from specific external machines by using non-zero
 282 .Va remote_addr
 283 and/or
 284 .Va remote_port .
 285 Each redirection assigned an ID which can be later used for
 286 redirection manipulation on individual basis (e.g., removal).
 287 This ID guaranteed to be unique until the node shuts down
 288 (it will not be reused after deletion), and is returned to
 289 user after making each new redirection or can be found in
 290 the stored list of all redirections.
 291 The
 292 .Va description
 293 passed to and from node unchanged, together with ID providing
 294 a way for several entities to concurrently manipulate
 295 redirections in automated way.
 296 .Sh SHUTDOWN
 297 This node shuts down upon receipt of a
 298 .Dv NGM_SHUTDOWN
 299 control message, or when both hooks are disconnected.
 300 .Sh EXAMPLES
 301 In the following example, the packets are injected into a
 302 .Nm nat
 303 node using the
 304 .Xr ng_ipfw 4
 305 node.
 306 .Bd -literal -offset indent
 307 # Create NAT node
 308 ngctl mkpeer ipfw: nat 60 out
 309 ngctl name ipfw:60 nat
 310 ngctl connect ipfw: nat: 61 in
 311 ngctl msg nat: setaliasaddr x.y.35.8
 312
 313 # Divert traffic into NAT node
 314 ipfw add 300 netgraph 61 all from any to any in via fxp0
 315 ipfw add 400 netgraph 60 all from any to any out via fxp0
 316
 317 # Let packets continue with after being (de)aliased
 318 sysctl net.inet.ip.fw.one_pass=0
 319 .Ed
 320 .Pp
 321 The
 322 .Nm
 323 node can be inserted right after the
 324 .Xr ng_iface 4
 325 node in the graph.
 326 In the following example, we perform masquerading on a
 327 serial 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
 336 SEQ
 337 ifconfig 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
 345 The
 346 .Nm
 347 node type was implemented in
 348 .Fx 6.0 .
 349 .Sh AUTHORS
 350 .An Gleb Smirnoff Aq glebius@FreeBSD.org