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