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 January 24, 2021
  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 IPv4 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 #define NG_NAT_UNREGISTERED_CGN         0x100
  79 .Ed
  80 .Pp
  81 The corresponding libalias flags can be found by replacing the
  82 .Vt "NG_NAT"
  83 prefix with
  84 .Vt "PKT_ALIAS" .
  85 .It Dv NGM_NAT_SET_TARGET Pq Ic settarget
  86 Configure target address for a node.
  87 When an incoming packet not associated with any pre-existing aliasing
  88 link arrives at the host machine, it will be sent to the specified address.
  89 .It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport
  90 Redirect incoming connections arriving to given port(s) to
  91 another host and port(s).
  92 The following
  93 .Vt "struct ng_nat_redirect_port"
  94 must be supplied as argument.
  95 .Bd -literal
  96 #define NG_NAT_DESC_LENGTH      64
  97 struct ng_nat_redirect_port {
  98         struct in_addr  local_addr;
  99         struct in_addr  alias_addr;
 100         struct in_addr  remote_addr;
 101         uint16_t        local_port;
 102         uint16_t        alias_port;
 103         uint16_t        remote_port;
 104         uint8_t         proto;
 105         char            description[NG_NAT_DESC_LENGTH];
 106 };
 107 .Ed
 108 .Pp
 109 Redirection is assigned an unique ID which is returned as
 110 response to this message, and
 111 information about redirection added to
 112 list of static redirects which later can be retrieved by
 113 .Dv NGM_NAT_LIST_REDIRECTS
 114 message.
 115 .It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr
 116 Redirect traffic for public IP address to a machine on the
 117 local network.
 118 This function is known as
 119 .Em static NAT .
 120 The following
 121 .Vt "struct ng_nat_redirect_addr"
 122 must be supplied as argument.
 123 .Bd -literal
 124 struct ng_nat_redirect_addr {
 125         struct in_addr  local_addr;
 126         struct in_addr  alias_addr;
 127         char            description[NG_NAT_DESC_LENGTH];
 128 };
 129 .Ed
 130 .Pp
 131 Unique ID for this redirection is returned as response to this message.
 132 .It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto
 133 Redirect incoming IP packets of protocol
 134 .Va proto
 135 (see
 136 .Xr protocols 5 )
 137 to a machine on the local network.
 138 The following
 139 .Vt "struct ng_nat_redirect_proto"
 140 must be supplied as argument.
 141 .Bd -literal
 142 struct ng_nat_redirect_proto {
 143         struct in_addr  local_addr;
 144         struct in_addr  alias_addr;
 145         struct in_addr  remote_addr;
 146         uint8_t         proto;
 147         char            description[NG_NAT_DESC_LENGTH];
 148 };
 149 .Ed
 150 .Pp
 151 Unique ID for this redirection is returned as response to this message.
 152 .It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic
 153 Mark redirection with specified ID as dynamic, i.e., it will serve
 154 for exactly one next connection and then will be automatically
 155 deleted from internal links table.
 156 Only fully specified links can be made dynamic.
 157 The redirection with this ID is also immediately deleted from
 158 user-visible list of static redirects (available through
 159 .Dv NGM_NAT_LIST_REDIRECTS
 160 message).
 161 .It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete
 162 Delete redirection with specified ID (currently active
 163 connections are not affected).
 164 .It Dv NGM_NAT_ADD_SERVER Pq Ic addserver
 165 Add another server to a pool.
 166 This is used to transparently offload network load on a single server
 167 and distribute the load across a pool of servers, also known as
 168 .Em LSNAT
 169 (RFC 2391).
 170 The following
 171 .Vt "struct ng_nat_add_server"
 172 must be supplied as argument.
 173 .Bd -literal
 174 struct ng_nat_add_server {
 175         uint32_t        id;
 176         struct in_addr  addr;
 177         uint16_t        port;
 178 };
 179 .Ed
 180 .Pp
 181 First, the redirection is set up by
 182 .Dv NGM_NAT_REDIRECT_PORT
 183 or
 184 .Dv NGM_NAT_REDIRECT_ADDR .
 185 Then, ID of that redirection is used in multiple
 186 .Dv NGM_NAT_ADD_SERVER
 187 messages to add necessary number of servers.
 188 For redirections created by
 189 .Dv NGM_NAT_REDIRECT_ADDR ,
 190 the
 191 .Va port
 192 is ignored and could have any value.
 193 Original redirection's parameters
 194 .Va local_addr
 195 and
 196 .Va local_port
 197 are also ignored after
 198 .Dv NGM_NAT_ADD_SERVER
 199 was used (they are effectively replaced by server pool).
 200 .It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects
 201 Return list of configured static redirects as
 202 .Vt "struct ng_nat_list_redirects" .
 203 .Bd -literal
 204 struct ng_nat_listrdrs_entry {
 205         uint32_t        id;             /* Anything except zero */
 206         struct in_addr  local_addr;
 207         struct in_addr  alias_addr;
 208         struct in_addr  remote_addr;
 209         uint16_t        local_port;
 210         uint16_t        alias_port;
 211         uint16_t        remote_port;
 212         uint16_t        proto;          /* Valid proto or NG_NAT_REDIRPROTO_ADDR */
 213         uint16_t        lsnat;          /* LSNAT servers count */
 214         char            description[NG_NAT_DESC_LENGTH];
 215 };
 216 struct ng_nat_list_redirects {
 217         uint32_t                total_count;
 218         struct ng_nat_listrdrs_entry redirects[];
 219 };
 220 #define NG_NAT_REDIRPROTO_ADDR  (IPPROTO_MAX + 3)
 221 .Ed
 222 .Pp
 223 Entries of the
 224 .Va redirects
 225 array returned in the unified format for all redirect types.
 226 Ports are meaningful only if protocol is either TCP or UDP
 227 and
 228 .Em static NAT
 229 redirection (created by
 230 .Dv NGM_NAT_REDIRECT_ADDR )
 231 is indicated by
 232 .Va proto
 233 set to
 234 .Dv NG_NAT_REDIRPROTO_ADDR .
 235 If
 236 .Va lsnat
 237 servers counter is greater than zero, then
 238 .Va local_addr
 239 and
 240 .Va local_port
 241 are also meaningless.
 242 .It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule
 243 Specify a transparent proxying rule (string must be
 244 supplied as argument).
 245 See
 246 .Xr libalias 3
 247 for details.
 248 .It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo
 249 Return internal statistics of
 250 .Xr libalias 3
 251 instance as
 252 .Vt "struct ng_nat_libalias_info" .
 253 .Bd -literal
 254 struct ng_nat_libalias_info {
 255         uint32_t        icmpLinkCount;
 256         uint32_t        udpLinkCount;
 257         uint32_t        tcpLinkCount;
 258         uint32_t        sctpLinkCount;
 259         uint32_t        pptpLinkCount;
 260         uint32_t        protoLinkCount;
 261         uint32_t        fragmentIdLinkCount;
 262         uint32_t        fragmentPtrLinkCount;
 263         uint32_t        sockCount;
 264 };
 265 .Ed
 266 In case of
 267 .Nm
 268 failed to retrieve a certain counter
 269 from its
 270 .Xr libalias
 271 instance, the corresponding field is returned as
 272 .Va UINT32_MAX .
 273 .It Dv NGM_NAT_SET_DLT Pq Ic setdlt
 274 Sets the data link type on the
 275 .Va in
 276 and
 277 .Va out
 278 hooks.
 279 Currently, supported types are
 280 .Cm DLT_RAW
 281 (raw IP datagrams , no offset applied, the default) and
 282 .Cm DLT_EN10MB
 283 (Ethernet). DLT_ definitions can be found in
 284 .In net/bpf.h .
 285 If you want to work on the
 286 .Xr ipfw 8
 287 level you must use no additional offset by specifying
 288 .Cm DLT_RAW .
 289 If, however, you attach
 290 .Nm
 291 to a network interface directly and
 292 .Cm EN10MB
 293 is specified, then the extra offset will be applied to take into account
 294 link-level header.
 295 In this mode the
 296 .Nm
 297 would also inspect appropriate type field in the Ethernet header and
 298 pass-through any datagrams that are not IP packets.
 299 .It Dv NGM_NAT_GET_DLT Pq Ic getdlt
 300 This control message returns the current data link type of the
 301 .Va in
 302 and
 303 .Va out
 304 hooks.
 305 .El
 306 .Pp
 307 In all redirection messages
 308 .Va local_addr
 309 and
 310 .Va local_port
 311 mean address and port of target machine in the internal network,
 312 respectively.
 313 If
 314 .Va alias_addr
 315 is zero, then default aliasing address (set by
 316 .Dv NGM_NAT_SET_IPADDR )
 317 is used.
 318 Connections can also be restricted to be accepted only
 319 from specific external machines by using non-zero
 320 .Va remote_addr
 321 and/or
 322 .Va remote_port .
 323 Each redirection assigned an ID which can be later used for
 324 redirection manipulation on individual basis (e.g., removal).
 325 This ID guaranteed to be unique until the node shuts down
 326 (it will not be reused after deletion), and is returned to
 327 user after making each new redirection or can be found in
 328 the stored list of all redirections.
 329 The
 330 .Va description
 331 passed to and from node unchanged, together with ID providing
 332 a way for several entities to concurrently manipulate
 333 redirections in automated way.
 334 .Sh SHUTDOWN
 335 This node shuts down upon receipt of a
 336 .Dv NGM_SHUTDOWN
 337 control message, or when both hooks are disconnected.
 338 .Sh EXAMPLES
 339 In the following example, the packets are injected into a
 340 .Nm nat
 341 node using the
 342 .Xr ng_ipfw 4
 343 node.
 344 .Bd -literal -offset indent
 345 # Create NAT node
 346 ngctl mkpeer ipfw: nat 60 out
 347 ngctl name ipfw:60 nat
 348 ngctl connect ipfw: nat: 61 in
 349 ngctl msg nat: setaliasaddr x.y.35.8
 350
 351 # Divert traffic into NAT node
 352 ipfw add 300 netgraph 61 all from any to any in via fxp0
 353 ipfw add 400 netgraph 60 all from any to any out via fxp0
 354
 355 # Let packets continue with after being (de)aliased
 356 sysctl net.inet.ip.fw.one_pass=0
 357 .Ed
 358 .Pp
 359 The
 360 .Nm
 361 node can be inserted right after the
 362 .Xr ng_iface 4
 363 node in the graph.
 364 In the following example, we perform masquerading on a
 365 serial line with HDLC encapsulation.
 366 .Bd -literal -offset indent
 367 /usr/sbin/ngctl -f- <<-SEQ
 368         mkpeer cp0: cisco rawdata downstream
 369         name cp0:rawdata hdlc
 370         mkpeer hdlc: nat inet in
 371         name hdlc:inet nat
 372         mkpeer nat: iface out inet
 373         msg nat: setaliasaddr x.y.8.35
 374 SEQ
 375 ifconfig ng0 x.y.8.35 x.y.8.1
 376 .Ed
 377 .Pp
 378 The
 379 .Nm
 380 node can also be attached directly to the physical interface
 381 via
 382 .Xr ng_ether 4
 383 node in the graph.
 384 In the following example, we perform masquerading on a
 385 Ethernet interface connected to a public network.
 386 .Bd -literal -offset indent
 387 ifconfig igb0 inet x.y.8.35 netmask 0xfffff000
 388 route add default x.y.0.1
 389 /usr/sbin/ngctl -f- <<-SEQ
 390         mkpeer igb0: nat lower in
 391         name igb0:lower igb0_NAT
 392         connect igb0: igb0_NAT: upper out
 393         msg igb0_NAT: setdlt 1
 394         msg igb0_NAT: setaliasaddr x.y.8.35
 395 SEQ
 396 .Ed
 397 .Sh SEE ALSO
 398 .Xr libalias 3 ,
 399 .Xr ng_ipfw 4 ,
 400 .Xr natd 8 ,
 401 .Xr ngctl 8 ,
 402 .Xr ng_ether 8
 403 .Sh HISTORY
 404 The
 405 .Nm
 406 node type was implemented in
 407 .Fx 6.0 .
 408 .Sh AUTHORS
 409 .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org