sbin/natd/natd.8

   1 .\" $FreeBSD: src/sbin/natd/natd.8,v 1.27.2.13 2003/02/23 21:17:43 trhodes Exp $
   2 .Dd September 29, 2016
   3 .Dt NATD 8
   4 .Os
   5 .Sh NAME
   6 .Nm natd
   7 .Nd Network Address Translation daemon
   8 .Sh SYNOPSIS
   9 .Nm
  10 .Bk -words
  11 .Op Fl unregistered_only | u
  12 .Op Fl log | l
  13 .Op Fl proxy_only
  14 .Op Fl reverse
  15 .Op Fl deny_incoming | d
  16 .Op Fl use_sockets | s
  17 .Op Fl same_ports | m
  18 .Op Fl verbose | v
  19 .Op Fl dynamic
  20 .Op Fl in_port | i Ar port
  21 .Op Fl out_port | o Ar port
  22 .Op Fl port | p Ar port
  23 .Op Fl alias_address | a Ar address
  24 .Op Fl target_address | t Ar address
  25 .Op Fl interface | n Ar interface
  26 .Op Fl proxy_rule Ar proxyspec
  27 .Op Fl redirect_port Ar linkspec
  28 .Op Fl redirect_proto Ar linkspec
  29 .Op Fl redirect_address Ar linkspec
  30 .Op Fl config | f Ar configfile
  31 .Op Fl log_denied
  32 .Op Fl log_facility Ar facility_name
  33 .Op Fl punch_fw Ar firewall_range
  34 .Op Fl log_ipfw_denied
  35 .Op Fl exit_delay | P Ar ms
  36 .Ek
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 utility provides a Network Address Translation facility for use
  41 with
  42 .Xr divert 4
  43 sockets under
  44 .Dx .
  45 It is intended for use with NICs - if you want to do NAT on a PPP link,
  46 use the
  47 .Fl nat
  48 switch to
  49 .Xr ppp 8 .
  50 .Pp
  51 The
  52 .Nm
  53 utility normally runs in the background as a daemon.
  54 It is passed raw IP packets as they travel into and out of the machine,
  55 and will possibly change these before re-injecting them back into the
  56 IP packet stream.
  57 .Pp
  58 It changes all packets destined for another host so that their source
  59 IP number is that of the current machine.
  60 For each packet changed in this manner, an internal table entry is
  61 created to record this fact.
  62 The source port number is also changed to indicate the table entry
  63 applying to the packet.
  64 Packets that are received with a target IP of the current host are
  65 checked against this internal table.
  66 If an entry is found, it is used to determine the correct target IP
  67 number and port to place in the packet.
  68 .Pp
  69 The following command line options are available:
  70 .Bl -tag -width Fl
  71 .It Fl log | l
  72 Log various aliasing statistics and information to the file
  73 .Pa /var/log/alias.log .
  74 This file is truncated each time
  75 .Nm
  76 is started.
  77 .It Fl deny_incoming | d
  78 Do not pass incoming packets that have no
  79 entry in the internal translation table.
  80 .Pp
  81 If this option is not used, then such a packet will be altered
  82 using the rules in
  83 .Fl target_address
  84 below, and the entry will be made in the internal translation table.
  85 .It Fl log_denied
  86 Log denied incoming packets via
  87 .Xr syslog 3
  88 (see also
  89 .Fl log_facility ) .
  90 .It Fl log_facility Ar facility_name
  91 Use specified log facility when logging information via
  92 .Xr syslog 3 .
  93 Argument
  94 .Ar facility_name
  95 is one of the keywords specified in
  96 .Xr syslog.conf 5 .
  97 .It Fl use_sockets | s
  98 Allocate a
  99 .Xr socket 2
 100 in order to establish an FTP data or IRC DCC send connection.
 101 This option uses more system resources, but guarantees successful
 102 connections when port numbers conflict.
 103 .It Fl same_ports | m
 104 Try to keep the same port number when altering outgoing packets.
 105 With this option, protocols such as RPC will have a better chance
 106 of working.
 107 If it is not possible to maintain the port number, it will be silently
 108 changed as per normal.
 109 .It Fl verbose | v
 110 Do not call
 111 .Xr daemon 3
 112 on startup.
 113 Instead, stay attached to the controlling terminal and display all packet
 114 alterations to the standard output.
 115 This option should only be used for debugging purposes.
 116 .It Fl unregistered_only | u
 117 Only alter outgoing packets with an
 118 .Em unregistered
 119 source address.
 120 According to RFC 1918, unregistered source addresses are 10.0.0.0/8,
 121 172.16.0.0/12 and 192.168.0.0/16.
 122 .It Fl redirect_port Ar proto Xo
 123 .Ar targetIP Ns : Ns Ar targetPORT Ns Op \- Ns Ar targetPORT
 124 .Op Ar aliasIP Ns : Ns Ar aliasPORT Ns Op \- Ns Ar aliasPORT
 125 .Op Ar remoteIP Ns Op : Ns Ar remotePORT Ns Op \- Ns Ar remotePORT
 126 .Xc
 127 Redirect incoming connections arriving to given port(s) to another host
 128 and port(s).
 129 Argument
 130 .Ar proto
 131 is either
 132 .Ar tcp
 133 or
 134 .Ar udp ,
 135 .Ar targetIP
 136 is the desired target IP number,
 137 .Ar targetPORT
 138 is the desired target port number or range,
 139 .Ar aliasPORT
 140 is the requested port number or range, and
 141 .Ar aliasIP
 142 is the aliasing address.
 143 Arguments
 144 .Ar remoteIP
 145 and
 146 .Ar remotePORT
 147 can be used to specify the connection more accurately if necessary.
 148 The
 149 .Ar targetPORT
 150 range and
 151 .Ar aliasPORT
 152 range need not be the same numerically, but must have the same size.
 153 If
 154 .Ar remotePORT
 155 is not specified, it is assumed to be all ports.
 156 If
 157 .Ar remotePORT
 158 is specified, it must match the size of
 159 .Ar targetPORT ,
 160 or be 0 (all ports).
 161 For example, the argument
 162 .Pp
 163 .Dl Ar tcp inside1:telnet 6666
 164 .Pp
 165 means that incoming TCP packets destined for port 6666 on this machine
 166 will be sent to the telnet port on the inside1 machine.
 167 .Pp
 168 .Dl Ar tcp inside2:2300-2399 3300-3399
 169 .Pp
 170 will redirect incoming connections on ports 3300-3399 to host
 171 inside2, ports 2300-2399.
 172 The mapping is 1:1 meaning port 3300 maps to 2300, 3301 maps to 2301, etc.
 173 .It Fl redirect_proto Ar proto localIP Oo
 174 .Ar publicIP Op Ar remoteIP
 175 .Oc
 176 Redirect incoming IP packets of protocol
 177 .Ar proto
 178 (see
 179 .Xr protocols 5 )
 180 destined for
 181 .Ar publicIP
 182 address to a
 183 .Ar localIP
 184 address and vice versa.
 185 .Pp
 186 If
 187 .Ar publicIP
 188 is not specified, then the default aliasing address is used.
 189 If
 190 .Ar remoteIP
 191 is specified, then only packets coming from/to
 192 .Ar remoteIP
 193 will match the rule.
 194 .It Fl redirect_address Ar localIP publicIP
 195 Redirect traffic for public IP address to a machine on the local
 196 network.
 197 This function is known as
 198 .Em static NAT .
 199 Normally static NAT is useful if your ISP has allocated a small block
 200 of IP addresses to you, but it can even be used in the case of single
 201 address:
 202 .Pp
 203 .Dl Ar redirect_address 10.0.0.8 0.0.0.0
 204 .Pp
 205 The above command would redirect all incoming traffic
 206 to machine 10.0.0.8.
 207 .Pp
 208 If several address aliases specify the same public address
 209 as follows
 210 .Bd -literal -offset indent
 211 .Ar redirect_address 192.168.0.2 public_addr
 212 .Ar redirect_address 192.168.0.3 public_addr
 213 .Ar redirect_address 192.168.0.4 public_addr
 214 .Ed
 215 .Pp
 216 the incoming traffic will be directed to the last
 217 translated local address (192.168.0.4), but outgoing
 218 traffic from the first two addresses will still be aliased
 219 to appear from the specified
 220 .Ar public_addr .
 221 .It Fl redirect_address Xo
 222 .Ar localIP Ns Oo , Ns
 223 .Ar localIP Ns Oo , Ns
 224 .Ar ...\&
 225 .Oc Oc
 226 .Ar publicIP
 227 .Xc
 228 These forms of
 229 .Fl redirect_port
 230 and
 231 .Fl redirect_address
 232 are used to transparently offload network load on a single server and
 233 distribute the load across a pool of servers.
 234 This function is known as
 235 .Em LSNAT
 236 (RFC 2391).
 237 For example, the argument
 238 .Pp
 239 .Dl Ar tcp www1:http,www2:http,www3:http www:http
 240 .Pp
 241 means that incoming HTTP requests for host www will be transparently
 242 redirected to one of the www1, www2 or www3, where a host is selected
 243 simply on a round-robin basis, without regard to load on the net.
 244 .It Fl dynamic
 245 If the
 246 .Fl n
 247 or
 248 .Fl interface
 249 option is used,
 250 .Nm
 251 will monitor the routing socket for alterations to the
 252 .Ar interface
 253 passed.
 254 If the interface's IP number is changed,
 255 .Nm
 256 will dynamically alter its concept of the alias address.
 257 .It Fl in_port | i Ar port
 258 Read from and write to
 259 .Xr divert 4
 260 port
 261 .Ar port ,
 262 treating all packets as
 263 .Dq incoming .
 264 .It Fl out_port | o Ar port
 265 Read from and write to
 266 .Xr divert 4
 267 port
 268 .Ar port ,
 269 treating all packets as
 270 .Dq outgoing .
 271 .It Fl port | p Ar port
 272 Read from and write to
 273 .Xr divert 4
 274 port
 275 .Ar port ,
 276 distinguishing packets as
 277 .Dq incoming
 278 or
 279 .Dq outgoing
 280 using the rules specified in
 281 .Xr divert 4 .
 282 If
 283 .Ar port
 284 is not numeric, it is searched for in the
 285 .Xr services 5
 286 database.
 287 If this option is not specified, the divert port named
 288 .Ar natd
 289 will be used as a default.
 290 .It Fl alias_address | a Ar address
 291 Use
 292 .Ar address
 293 as the aliasing address.
 294 If this option is not specified, the
 295 .Fl interface
 296 option must be used.
 297 The specified address is usually the address assigned to the
 298 .Dq public
 299 network interface.
 300 .Pp
 301 All data passing
 302 .Em out
 303 will be rewritten with a source address equal to
 304 .Ar address .
 305 All data coming
 306 .Em in
 307 will be checked to see if it matches any already-aliased outgoing
 308 connection.
 309 If it does, the packet is altered accordingly.
 310 If not, all
 311 .Fl redirect_port ,
 312 .Fl redirect_proto
 313 and
 314 .Fl redirect_address
 315 assignments are checked and actioned.
 316 If no other action can be made and if
 317 .Fl deny_incoming
 318 is not specified, the packet is delivered to the local machine
 319 using the rules specified in
 320 .Fl target_address
 321 option below.
 322 .It Fl t | target_address Ar address
 323 Set the target address.
 324 When an incoming packet not associated with any pre-existing link
 325 arrives at the host machine, it will be sent to the specified
 326 .Ar address .
 327 .Pp
 328 The target address may be set to
 329 .Ar 255.255.255.255 ,
 330 in which case all new incoming packets go to the alias address set by
 331 .Fl alias_address
 332 or
 333 .Fl interface .
 334 .Pp
 335 If this option is not used, or called with the argument
 336 .Ar 0.0.0.0 ,
 337 then all new incoming packets go to the address specified in
 338 the packet.
 339 This allows external machines to talk directly to internal machines if
 340 they can route packets to the machine in question.
 341 .It Fl interface | n Ar interface
 342 Use
 343 .Ar interface
 344 to determine the aliasing address.
 345 If there is a possibility that the IP number associated with
 346 .Ar interface
 347 may change, the
 348 .Fl dynamic
 349 option should also be used.
 350 If this option is not specified, the
 351 .Fl alias_address
 352 option must be used.
 353 .Pp
 354 The specified
 355 .Ar interface
 356 is usually the
 357 .Dq public
 358 (or
 359 .Dq external )
 360 network interface.
 361 .It Fl config | f Ar file
 362 Read configuration from
 363 .Ar file .
 364 A
 365 .Ar file
 366 should contain a list of options, one per line, in the same form
 367 as the long form of the above command line options.
 368 For example, the line
 369 .Pp
 370 .Dl alias_address 158.152.17.1
 371 .Pp
 372 would specify an alias address of 158.152.17.1.
 373 Options that do not take an argument are specified with an argument of
 374 .Ar yes
 375 or
 376 .Ar no
 377 in the configuration file.
 378 For example, the line
 379 .Pp
 380 .Dl log yes
 381 .Pp
 382 is synonymous with
 383 .Fl log .
 384 .Pp
 385 Trailing spaces and empty lines are ignored.
 386 A
 387 .Ql \&#
 388 sign will mark the rest of the line as a comment.
 389 .It Fl reverse
 390 This option makes
 391 .Nm
 392 reverse the way it handles
 393 .Dq incoming
 394 and
 395 .Dq outgoing
 396 packets, allowing it to operate on the
 397 .Dq internal
 398 network interface rather than the
 399 .Dq external
 400 one.
 401 .Pp
 402 This can be useful in some transparent proxying situations
 403 when outgoing traffic is redirected to the local machine
 404 and
 405 .Nm
 406 is running on the internal interface (it usually runs on the
 407 external interface).
 408 .It Fl proxy_only
 409 Force
 410 .Nm
 411 to perform transparent proxying only.
 412 Normal address translation is not performed.
 413 .It Fl proxy_rule Xo
 414 .Op Ar type encode_ip_hdr | encode_tcp_stream
 415 .Ar port xxxx
 416 .Ar server a.b.c.d:yyyy
 417 .Xc
 418 Enable transparent proxying.
 419 Outgoing TCP packets with the given port going through this
 420 host to any other host are redirected to the given server and port.
 421 Optionally, the original target address can be encoded into the packet.
 422 Use
 423 .Ar encode_ip_hdr
 424 to put this information into the IP option field or
 425 .Ar encode_tcp_stream
 426 to inject the data into the beginning of the TCP stream.
 427 .It Fl punch_fw Xo
 428 .Ar basenumber Ns : Ns Ar count
 429 .Xc
 430 This option directs
 431 .Nm
 432 to
 433 .Dq punch holes
 434 in an
 435 .Xr ipfirewall 4
 436 based firewall for FTP/IRC DCC connections.
 437 This is done dynamically by installing temporary firewall rules which
 438 allow a particular connection (and only that connection) to go through
 439 the firewall.
 440 The rules are removed once the corresponding connection terminates.
 441 .Pp
 442 A maximum of
 443 .Ar count
 444 rules starting from the rule number
 445 .Ar basenumber
 446 will be used for punching firewall holes.
 447 The range will be cleared for all rules on startup.
 448 .It Fl log_ipfw_denied
 449 Log when a packet cannot be re-injected because an
 450 .Xr ipfw 8
 451 rule blocks it.
 452 This is the default with
 453 .Fl verbose .
 454 .It Fl exit_delay Ar ms
 455 Specify delay in ms before daemon exit after signal.
 456 The default is
 457 .Pa 10000 .
 458 .El
 459 .Sh RUNNING NATD
 460 The following steps are necessary before attempting to run
 461 .Nm :
 462 .Bl -enum
 463 .It
 464 Build a custom kernel with the following options:
 465 .Bd -literal -offset indent
 466 options IPFIREWALL
 467 options IPDIVERT
 468 .Ed
 469 .Pp
 470 Refer to the handbook for detailed instructions on building a custom
 471 kernel.
 472 .It
 473 Ensure that your machine is acting as a gateway.
 474 This can be done by specifying the line
 475 .Pp
 476 .Dl gateway_enable=YES
 477 .Pp
 478 in the
 479 .Pa /etc/rc.conf
 480 file or using the command
 481 .Pp
 482 .Dl "sysctl net.inet.ip.forwarding=1"
 483 .It
 484 If you use the
 485 .Fl interface
 486 option, make sure that your interface is already configured.
 487 If, for example, you wish to specify
 488 .Ql tun0
 489 as your
 490 .Ar interface ,
 491 and you are using
 492 .Xr ppp 8
 493 on that interface, you must make sure that you start
 494 .Nm ppp
 495 prior to starting
 496 .Nm .
 497 .El
 498 .Pp
 499 Running
 500 .Nm
 501 is fairly straight forward.
 502 The line
 503 .Pp
 504 .Dl natd -interface ed0
 505 .Pp
 506 should suffice in most cases (substituting the correct interface name).
 507 Please check
 508 .Xr rc.conf 5
 509 on how to configure it to be started automatically during boot.
 510 Once
 511 .Nm
 512 is running, you must ensure that traffic is diverted to
 513 .Nm :
 514 .Bl -enum
 515 .It
 516 You will need to adjust the
 517 .Pa /etc/rc.firewall
 518 script to taste.
 519 If you are not interested in having a firewall, the
 520 following lines will do:
 521 .Bd -literal -offset indent
 522 /sbin/ipfw -f flush
 523 /sbin/ipfw add divert natd all from any to any via ed0
 524 /sbin/ipfw add pass all from any to any
 525 .Ed
 526 .Pp
 527 The second line depends on your interface (change
 528 .Ql ed0
 529 as appropriate).
 530 .Pp
 531 You should be aware of the fact that, with these firewall settings,
 532 everyone on your local network can fake his source-address using your
 533 host as gateway.
 534 If there are other hosts on your local network, you are strongly
 535 encouraged to create firewall rules that only allow traffic to and
 536 from trusted hosts.
 537 .Pp
 538 If you specify real firewall rules, it is best to specify line 2 at
 539 the start of the script so that
 540 .Nm
 541 sees all packets before they are dropped by the firewall.
 542 .Pp
 543 After translation by
 544 .Nm ,
 545 packets re-enter the firewall at the rule number following the rule number
 546 that caused the diversion (not the next rule if there are several at the
 547 same number).
 548 .It
 549 Enable your firewall by setting
 550 .Pp
 551 .Dl firewall_enable=YES
 552 .Pp
 553 in
 554 .Pa /etc/rc.conf .
 555 This tells the system startup scripts to run the
 556 .Pa /etc/rc.firewall
 557 script.
 558 If you do not wish to reboot now, just run this by hand from the console.
 559 NEVER run this from a remote session unless you put it into the background.
 560 If you do, you will lock yourself out after the flush takes place, and
 561 execution of
 562 .Pa /etc/rc.firewall
 563 will stop at this point - blocking all accesses permanently.
 564 Running the script in the background should be enough to prevent this
 565 disaster.
 566 .El
 567 .Sh SEE ALSO
 568 .Xr divert 4 ,
 569 .Xr protocols 5 ,
 570 .Xr rc.conf 5 ,
 571 .Xr services 5 ,
 572 .Xr syslog.conf 5 ,
 573 .Xr ipfw 8 ,
 574 .Xr ppp 8
 575 .Sh HISTORY
 576 The
 577 .Nm
 578 utility appeared in
 579 .Fx 3.0 .
 580 .Sh AUTHORS
 581 This program is the result of the efforts of many people at different
 582 times:
 583 .Pp
 584 .An Archie Cobbs Aq Mt archie@FreeBSD.org
 585 (divert sockets)
 586 .An Charles Mott Aq Mt cmott@scientech.com
 587 (packet aliasing)
 588 .An Eivind Eklund Aq Mt perhaps@yes.no
 589 (IRC support & misc additions)
 590 .An Ari Suutari Aq Mt suutari@iki.fi
 591 (natd)
 592 .An Dru Nelson Aq Mt dnelson@redwoodsoft.com
 593 (early PPTP support)
 594 .An Brian Somers Aq Mt brian@awfulhak.org
 595 (glue)
 596 .An Ruslan Ermilov Aq Mt ru@FreeBSD.org
 597 (natd, packet aliasing, glue)