1139804SimpCopyright (c) 2001 Charles Mott <cm@linktel.net> 2139804SimpAll rights reserved. 344574Sphk 475540SjhayRedistribution and use in source and binary forms, with or without 544574Sphkmodification, are permitted provided that the following conditions 644574Sphkare met: 744574Sphk1. Redistributions of source code must retain the above copyright 844574Sphk notice, this list of conditions and the following disclaimer. 944574Sphk2. Redistributions in binary form must reproduce the above copyright 1044574Sphk notice, this list of conditions and the following disclaimer in the 1144574Sphk documentation and/or other materials provided with the distribution. 1244574Sphk 1344574SphkTHIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 1444574SphkANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1544574SphkIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1644574SphkARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 1744574SphkFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 1844574SphkDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 192858SwollmanOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 202858SwollmanHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2144574SphkLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2244666SphkOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 232858SwollmanSUCH DAMAGE. 2444574Sphk 2544574Sphk$FreeBSD: releng/11.0/usr.sbin/ppp/README.nat 98243 2002-06-15 08:03:30Z brian $ 2644574Sphk 2721101SjhayUser PPP NAT (Packet Aliasing) 2844574Sphk 2944574Sphk 3044574Sphk 312858Swollman0. Contents 3232925Seivind 1. Background 33116182Sobrien 2. Setup 34116182Sobrien 3. New commands in ppp 35116182Sobrien 4. Future Work 3644666Sphk 5. Authors / Acknowledgements 3744666Sphk 6. Revision History for Aliasing Code 382858Swollman 392858Swollman 4012221Sbde 41207360Savg1. Background 422858Swollman 43164033SrwatsonUser mode ppp has embedded NAT (Network Address Translation) code. 442858SwollmanEnabling this, either by the "-nat" command line option or the 4582717Sdillon"nat enable yes" command in a ppp.conf file, makes the ppp host 4682717Sdillonautomatically NAT IP packets forwarded from a local network, making 4744574Sphkthem appear to come from the ppp host machine. Incoming packets 482858Swollmanfrom the outside world are then appropriately de-NAT'd. 4958377Sphk 5036941SphkThe process of NAT'ing involves both the IP address and the TCP or UDP 51144445Sjhbport numbers. ICMP echo and timestamp packets are natted by their id 522858Swollmannumbers. ICMP error messages can be properly directed by examining the 532858Swollmanfragment of the offending packet which is contained in the body of the 54219028Snetchildmessage. 55219028Snetchild 56219028SnetchildThis software was specifically meant to support users who have 57219028Snetchildunregistered, private address IP networks (e.g. 192.168.0.x or 10.0.0.x 582858Swollmanaddresses). The ppp host can act as a gateway for these networks, and 5944574Sphkcomputers on the local area net will have some degree of Internet access 6044574Sphkwithout the need for a registered IP address. Additionally, there will 61126974Sphkbe no need for an Internet service provider to maintain routing tables 6244574Sphkfor the local area network. 6344574Sphk 64126974SphkA disadvantage of NAT is that machines on the local network, 6544574Sphkbehind the ppp host, are not visible from the outside world. They can 6644574Sphkestablish TCP connections and make UDP inquiries (such as domain name 6744574Sphkservice requests) but the connections seem to come from the ppp host 6844574Sphkitself. There is, in effect, a partial firewall. Of course, if this is 6944574Sphkwhat you want, the disadvantage becomes an advantage. 7044574Sphk 7144574SphkA second disadvantage is that "IP encoding" protocols, which send IP 7244574Sphkaddress or port information within the data stream, are not supported 7344574Sphkfor the cases where exception code exists. This implementation has 7444574Sphkworkarounds for FTP and IRC DCC, the most well known of the IP encoding 7544574Sphkprotocols. This frees users from depending on using the ftp passive 76126974Sphkmode and avoiding IRC DCC sends, as is sometimes the case with other 7744574Sphkmasquerading solutions. 7844574Sphk 7944574SphkThe implementation supports all standard, non-encoding TCP and UDP protocols. 8044574SphkExamples of these protocols are http, gopher and telnet. The standard UDP 8132513Sphkmode of Real-Audio is not presently supported, but the TCP mode does work 8244574Sphkcorrectly. 8344574Sphk 8444574SphkThe NAT code also handles many ICMP messages. In particular, 8544574Sphkping and traceroute are supported. 8644574Sphk 8744574Sphk 8844574Sphk 8944574Sphk2. Packet Aliasing Setup 9044574Sphk 9132513SphkIt is recommended that users first verify correct ppp operation without 9245294SphkNAT enabled. This will confirm that the ppp.conf file is 9344574Sphkproperly set up and that there are no ppp problems. Then start ppp with 9444574Sphkthe "-nat" option on the command line. The user should verify that 9545294Sphkthe ppp host can correctly connect to the Internet in NAT 9645294Sphkmode. Finally, check that machines on the private network can access 9745294Sphkthe Internet. 9845294Sphk 9945294SphkThe NAT software handles all packets, whether they come from 10045294Sphkthe host or another computer on the local area network. Thus, a correctly 10145294Sphkoperating ppp host indicates that the software should work properly for 10245294Sphkother computers on the private network. 10332513Sphk 10444574SphkIf the ppp host can access the Internet, but other computers on the local 10544574Sphknetwork cannot, check that IP forwarding is enabled on the ppp host. Also, 10644574Sphkverify that the other computers use this machine as a gateway. Of course, 10744574Sphkyou should also verify that machines within the local area network 10832513Sphkcommunicate properly. A common error is inconsistent subnet addresses 10944574Sphkand masks. 11044574Sphk 11144574Sphk 11244574Sphk 11344574Sphk3. New commands in ppp 11444574Sphk 11544574SphkIn order to control NAT behaviour in a simple manner (no need for 11632513Sphkrecompilation), a new command has been added to ppp: nat. This 11744574Sphkis in addition to the -nat command line option. System managers and 11844574Sphkmore experienced users may prefer to use the ppp command syntax 11944574Sphkwithin the ppp.conf file. The nat command also allows NAT 12045294Sphkbehaviour to be more precisely specified. 12132513Sphk 12244574SphkThe decision to add a command instead of extending 'set' or 'option' was 12344574Sphkto make obvious that these options only work when NAT is enabled. 12444574Sphk 12544574SphkThe syntax for 'nat' is 12644574Sphk 12744574Sphk ppp> nat option [yes|no] 12844574Sphk 12932513Sphkwhere option is given by one of the following templates. 13044574Sphk 13144574Sphk 13244574Sphk - nat enable [yes|no] (default no) 13345294Sphk 13432513SphkEnable NAT functionality. If disabled, no other NAT 13544574Sphkoptions will have any effect. You should usually enable NAT 13644574Sphkbefore routing any packets over the link; good points are in the 13744574Sphkinitial script or right before adding a route. If you do not always 13844574Sphkwant NAT, consider using the -nat option to ppp instead of this 13944574Sphkcommand. 14044574Sphk 14144574Sphk 1422858Swollman - nat deny_incoming [yes|no] (default yes) 14332513Sphk 14432513SphkSet to "yes" to disable all incoming connections. This just drops 14544574Sphkconnections to, for example, ftp, telnet or web servers. The NAT 14632513Sphkmechanism prevents these connections. Technically, this option denies 14744574Sphkall incoming TCP and UDP requests, making the NAT software a 14844574Sphkfairly efficient one-way firewall. The default is no, which will allow 14932513Sphkall incoming connections to telnetd, ftpd, etc. 15044574Sphk 151228856Slstewart 15265432Sphk - nat log [yes|no] 15365432Sphk 15444574SphkControls logging of NAT link creation to "/var/log/alias.log" - this 15544574Sphkis usually only useful if debugging a setup, to see if the bug is in 15644574Sphkthe PPP NATing. The debugging information is fairly limited, listing 157228856Slstewartthe number of NAT links open for different protocols. 158285611Sdelphij 15944574Sphk 16044574Sphk - nat same_ports [yes|no] (default yes) 16165432Sphk 16244574SphkWhen a connection is being established going through the NAT 16394754Sphkroutines, it will normally have its port number changed to allow the 16494754SphkNAT code to track it. If same_ports is enabled, the NAT 1652858Swollmansoftware attempts to keep the connection's source port unchanged. 1662858SwollmanThis will allow rsh, RPC and other specialised protocols to work 16744574Sphk_most of the time_, at least on the host machine. Please, do not 16844574Sphkreport this being unstable as a bug - it is a result of the way 16944574SphkNAT has to work. TCP/IP was intended to have one IP address 17044574Sphkper machine. 1712858Swollman 17244574Sphk 17375540Sjhay - nat use_sockets [yes|no] (default yes) 17450656Sphk 17544574SphkThis is a fairly obscure option. For the most part, the NAT 17644574Sphksoftware does not have to allocate system sockets when it chooses a 17750656SphkNAT port number. Under very specific circumstances, FTP data 17850656Sphkconnections (which don't know the remote port number, though it is 17932513Sphkusually 20) and IRC DCC send (which doesn't know either the address or 18050656Sphkthe port from which the connection will come), there can potentially be 18144574Sphksome interference with an open server socket having the same port number 18245294Sphkon the ppp host machine. This possibility for interference only exists 18350656Sphkuntil the TCP connection has been acknowledged on both sides. The safe 18450656Sphkoption is yes, though fewer system resources are consumed by specifying 18544574Sphkno. 18644574Sphk 18744574Sphk 18850656Sphk - nat unregistered_only [yes|no] (default no) 18944574Sphk 19044574SphkNAT normally remaps all packets coming from the local area 19132513Sphknetwork to the ppp host machine address. Set this option to only map 19232513Sphkaddresses from the following standard ranges for private, unregistered 19332513Sphkaddresses: 19444574Sphk 19544574Sphk 10.0.0.0 -> 10.255.255.255 19644574Sphk 172.16.0.0 -> 172.31.255.255 19744574Sphk 192.168.0.0 -> 192.168.255.255 */ 1982858Swollman 19932513SphkIn the instance that there is a subnet of public addresses and another 20044574Sphksubnet of private addresses being routed by the ppp host, then only the 20132513Sphkpackets on the private subnet will be NAT'd. 20232513Sphk 20344574Sphk 20444574Sphk- nat port <proto> <local addr>:<port> <nat port> 205137873Smarks 206207359SavgThis command allows incoming traffic to <nat port> on the host 20732513Sphkmachine to be redirected to a specific machine and port on the 208207359Savglocal area network. One example of this would be: 209207359Savg 2102858Swollman nat port tcp 192.168.0.4:telnet 8066 2112858Swollman 21244574SphkAll traffic to port 8066 of the ppp host would then be sent to 21344574Sphkthe telnet port (23) of machine 192.168.0.4. Port numbers 21444574Sphkcan either be designated numerically or by symbolic names 21544574Sphklisted in /etc/services. Similarly, addresses can be either 2162858Swollmanin dotted quad notation or in /etc/hosts. 2172858Swollman 2182858Swollman 21944574Sphk- nat addr <local addr> <public addr> 2202858Swollman 2212858SwollmanThis command allows traffic for a public IP address to be 22244574Sphkredirected to a machine on the local network. This function 22344574Sphkis known as "static NAT". An address assignment of 0 refers 2242858Swollmanto the default address of the ppp host. Normally static 22544574SphkNAT is useful if your ISP has allocated a small block of 22644574SphkIP addresses to the user, but it can even be used in the 2272858Swollmancase of a single, dynamically allocated IP address: 2282858Swollman 22944574Sphk nat addr 10.0.0.8 0 2302858Swollman 23144574SphkThe above command would redirect all incoming traffic to 23244574Sphkmachine 10.0.0.8. 2332858Swollman 2342858SwollmanIf several address NATs specify the same public address 23544574Sphkas follows 23644574Sphk 2372858Swollman nat addr 192.168.0.2 public_addr 23844574Sphk nat addr 192.168.0.3 public_addr 23944574Sphk nat addr 192.168.0.4 public_addr 240207359Savg 241207359Savgthen incoming traffic will be directed to the last 242207359Savgtranslated local address (192.168.0.4), but outgoing 243207359Savgtraffic to the first two addresses will still be NAT'd 244207359Savgto the specified public address. 245207359Savg 246207359Savg 247207359Savg 248207359Savg4. Future Work 249207359Savg 250207359SavgWhat is called NAT here has been variously called masquerading, packet 251207359Savgaliasing and transparent proxying by others. It is an extremely useful 252207359Savgfunction to many users, but it is also necessarily imperfect. The 253207359Savgoccasional IP-encoding protocols always need workarounds (hacks). 254207359SavgUsers who are interested in supporting new IP-encoding protocols 255207359Savgcan follow the examples of alias_ftp.c and alias_irc.c. 256207359Savg 257207359SavgICMP error messages are currently handled only in the incoming direction. 258207359SavgA handler needs to be added to correctly NAT outgoing error messages. 259207359Savg 260207359SavgIRC and FTP exception handling make reasonable, though not strictly correct 261137873Smarksassumptions, about how IP encoded messages will appear in the control 2622858Swollmanstream. Programmers may wish to consider how to make this process more 2632858Swollmanrobust. 264137879Smarks 265137879SmarksThe NAT engine (alias.c, alias_db.c, alias_ftp.c, alias_irc.c 266137879Smarksand alias_util.c) runs in user space, and is intended to be both portable 267167232Srwatsonand reusable for interfaces other than ppp. To access the basic engine 268167232Srwatsononly requires four simple function calls (initialisation, communication of 269137879Smarkshost address, outgoing NAT and incoming de-NATing). 270137873Smarks 271137873Smarks 272137873Smarks 273137873Smarks5. Authors / Acknowledgements 274137873Smarks 275137873SmarksCharles Mott (cm@linktel.net) <versions 1.0 - 1.8, 2.0, 2.1> 276137873SmarksEivind Eklund (perhaps@yes.no) <versions 1.8b - 1.9, new ppp commands> 277225617Skmacy 278137873SmarksListed below, in chronological order, are individuals who have provided 279137873Smarksvaluable comments and/or debugging assistance. 280137873Smarks 281146722Srwatson Gary Roberts 282137873Smarks Tom Torrance 283146722Srwatson Reto Burkhalter 284137873Smarks Martin Renters 285165969Simp Brian Somers 286137873Smarks Paul Traina 287137873Smarks Ari Suutari 288137873Smarks J. Fortes 289137873Smarks Andrzej Bialeki 290137873Smarks 291137873Smarks 292137873Smarks 293137873Smarks6. Revision History for Aliasing Code 294137873Smarks 295137873SmarksVersion 1.0: August 11, 1996 (cjm) 296137873Smarks 297137873SmarksVersion 1.1: August 20, 1996 (cjm) 298137873Smarks PPP host accepts incoming connections for ports 0 to 1023. 29944574Sphk 30044574SphkVersion 1.2: September 7, 1996 (cjm) 30112623Sphk Fragment handling error in alias_db.c corrected. 30212279Sphk 30350663SphkVersion 1.3: September 15, 1996 (cjm) 304228449Seadler - Generalised mechanism for handling incoming connections 305228449Seadler (no more 0 to 1023 restriction). 306228449Seadler - Increased ICMP support (will handle traceroute now). 307228449Seadler - Improved TCP close connection logic. 308217368Smdf 309228449SeadlerVersion 1.4: September 16, 1996 31056458Sphk Can't remember (this version only lasted a day -- cjm). 311228449Seadler 312228449SeadlerVersion 1.5: September 17, 1996 (cjm) 313228449Seadler Corrected error in handling incoming UDP packets 314228449Seadler with zero checksum. 31550663Sphk 316167232SrwatsonVersion 1.6: September 18, 1996 3172858Swollman Simplified ICMP data storage. Will now handle 3182858Swollman tracert from Win95 as well as FreeBSD traceroute. 31944574Sphk 320167232SrwatsonVersion 1.7: January 9, 1997 (cjm) 321167232Srwatson - Reduced malloc() activity for ICMP echo and 322167232Srwatson timestamp requests. 3232858Swollman - Added handling for out-of-order IP fragments. 32412221Sbde - Switched to differential checksum computation 3252858Swollman for IP headers (TCP, UDP and ICMP checksums 32644574Sphk were already differential). 3272858Swollman - Accepts FTP data connections from other than 32812221Sbde port 20. This allows one ftp connections 3292858Swollman from two hosts which are both running packet 3302858Swollman aliasing. 331225617Skmacy 3322858SwollmanVersion 1.8: January 14, 1997 (cjm) 33344574Sphk - Fixed data type error in function StartPoint() 33445294Sphk in alias_db.c (this bug did not exist before v1.7) 33544574Sphk 33644574SphkVersion 1.8b: January 16, 1997 (Eivind Eklund <perhaps@yes.no>) 3372858Swollman - Upgraded base PPP version to be the source code from 3382858Swollman FreeBSD 2.1.6, with additional security patches. This 3392858Swollman version should still be possible to run on 2.1.5, though - 3402858Swollman I've run it with a 2.1.5 kernel without problems. 34144574Sphk (Update done with the permission of cjm) 3422858Swollman 3432858SwollmanVersion 1.9: February 1, 1997 (Eivind Eklund <perhaps@yes.no>) 3442858Swollman - Added support for IRC DCC (ee) 3452858Swollman - Changed the aliasing routines to use ANSI style throughout - 3462858Swollman minor API changes for integration with other programs than PPP (ee) 34765432Sphk - Changed the build process, making all options switchable 34875540Sjhay from the Makefile (ee) 34975540Sjhay - Fixed minor security hole in alias_ftp.c for other applications 35075540Sjhay of the aliasing software. Hole could _not_ manifest in 3512858Swollman PPP+pktAlias, but could potentially manifest in other 35282717Sdillon applications of the aliasing. (ee) 3532858Swollman - Connections initiated from packet aliasing host machine will 35444776Sphk not have their port number aliased unless it conflicts with 355164033Srwatson an aliasing port already being used. (There is an option to 35644574Sphk disable this for debugging) (cjm) 35782717Sdillon - Sockets will be allocated in cases where there might be 3582858Swollman port interference with the host machine. This can be disabled 3592858Swollman in cases where the ppp host will be acting purely as a 3602858Swollman masquerading router and not generate any traffic of its own. 3612858Swollman (cjm) 3622858Swollman 3632858SwollmanVersion 2.0: March, 1997 (cjm) 36475540Sjhay - Incoming packets which are not recognised by the packet 36575540Sjhay aliasing engine are now completely dropped in ip.c. 36675540Sjhay - Aliasing links are cleared when a host interface address 36775540Sjhay changes (due to re-dial and dynamic address allocation). 36875540Sjhay - PacketAliasPermanentLink() API added. 36975540Sjhay - Option for only aliasing private, unregistered IP addresses 37075540Sjhay added. 3712858Swollman - Substantial rework to the aliasing lookup engine. 3722858Swollman 3732858SwollmanVersion 2.1: May, 1997 (cjm) 37445294Sphk - Continuing rework to the aliasing lookup engine to support 37545294Sphk multiple incoming addresses and static NAT. 37645294Sphk - Now supports outgoing as well as incoming ICMP error messages/ 37745294Sphk - PPP commands to support address and port redirection. 37845294Sphk 37945294Sphk