1Copyright (c) 2001 Charles Mott <cm@linktel.net> 2All rights reserved. 3 4Redistribution and use in source and binary forms, with or without 5modification, are permitted provided that the following conditions 6are met: 71. Redistributions of source code must retain the above copyright 8 notice, this list of conditions and the following disclaimer. 92. 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 13THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23SUCH DAMAGE. 24 25$FreeBSD: src/usr.sbin/ppp/README.nat,v 1.4.4.4 2002/09/01 02:12:22 brian Exp $ 26$DragonFly: src/usr.sbin/ppp/README.nat,v 1.2 2003/06/17 04:30:00 dillon Exp $ 27 28User PPP NAT (Packet Aliasing) 29 30 31 320. Contents 33 1. Background 34 2. Setup 35 3. New commands in ppp 36 4. Future Work 37 5. Authors / Acknowledgements 38 6. Revision History for Aliasing Code 39 40 41 421. Background 43 44User mode ppp has embedded NAT (Network Address Translation) code. 45Enabling this, either by the "-nat" command line option or the 46"nat enable yes" command in a ppp.conf file, makes the ppp host 47automatically NAT IP packets forwarded from a local network, making 48them appear to come from the ppp host machine. Incoming packets 49from the outside world are then appropriately de-NAT'd. 50 51The process of NAT'ing involves both the IP address and the TCP or UDP 52port numbers. ICMP echo and timestamp packets are natted by their id 53numbers. ICMP error messages can be properly directed by examining the 54fragment of the offending packet which is contained in the body of the 55message. 56 57This software was specifically meant to support users who have 58unregistered, private address IP networks (e.g. 192.168.0.x or 10.0.0.x 59addresses). The ppp host can act as a gateway for these networks, and 60computers on the local area net will have some degree of Internet access 61without the need for a registered IP address. Additionally, there will 62be no need for an Internet service provider to maintain routing tables 63for the local area network. 64 65A disadvantage of NAT is that machines on the local network, 66behind the ppp host, are not visible from the outside world. They can 67establish TCP connections and make UDP inquiries (such as domain name 68service requests) but the connections seem to come from the ppp host 69itself. There is, in effect, a partial firewall. Of course, if this is 70what you want, the disadvantage becomes an advantage. 71 72A second disadvantage is that "IP encoding" protocols, which send IP 73address or port information within the data stream, are not supported 74for the cases where exception code exists. This implementation has 75workarounds for FTP and IRC DCC, the most well known of the IP encoding 76protocols. This frees users from depending on using the ftp passive 77mode and avoiding IRC DCC sends, as is sometimes the case with other 78masquerading solutions. 79 80The implementation supports all standard, non-encoding TCP and UDP protocols. 81Examples of these protocols are http, gopher and telnet. The standard UDP 82mode of Real-Audio is not presently supported, but the TCP mode does work 83correctly. 84 85The NAT code also handles many ICMP messages. In particular, 86ping and traceroute are supported. 87 88 89 902. Packet Aliasing Setup 91 92It is recommended that users first verify correct ppp operation without 93NAT enabled. This will confirm that the ppp.conf file is 94properly set up and that there are no ppp problems. Then start ppp with 95the "-nat" option on the command line. The user should verify that 96the ppp host can correctly connect to the Internet in NAT 97mode. Finally, check that machines on the private network can access 98the Internet. 99 100The NAT software handles all packets, whether they come from 101the host or another computer on the local area network. Thus, a correctly 102operating ppp host indicates that the software should work properly for 103other computers on the private network. 104 105If the ppp host can access the Internet, but other computers on the local 106network cannot, check that IP forwarding is enabled on the ppp host. Also, 107verify that the other computers use this machine as a gateway. Of course, 108you should also verify that machines within the local area network 109communicate properly. A common error is inconsistent subnet addresses 110and masks. 111 112 113 1143. New commands in ppp 115 116In order to control NAT behaviour in a simple manner (no need for 117recompilation), a new command has been added to ppp: nat. This 118is in addition to the -nat command line option. System managers and 119more experienced users may prefer to use the ppp command syntax 120within the ppp.conf file. The nat command also allows NAT 121behaviour to be more precisely specified. 122 123The decision to add a command instead of extending 'set' or 'option' was 124to make obvious that these options only work when NAT is enabled. 125 126The syntax for 'nat' is 127 128 ppp> nat option [yes|no] 129 130where option is given by one of the following templates. 131 132 133 - nat enable [yes|no] (default no) 134 135Enable NAT functionality. If disabled, no other NAT 136options will have any effect. You should usually enable NAT 137before routing any packets over the link; good points are in the 138initial script or right before adding a route. If you do not always 139want NAT, consider using the -nat option to ppp instead of this 140command. 141 142 143 - nat deny_incoming [yes|no] (default yes) 144 145Set to "yes" to disable all incoming connections. This just drops 146connections to, for example, ftp, telnet or web servers. The NAT 147mechanism prevents these connections. Technically, this option denies 148all incoming TCP and UDP requests, making the NAT software a 149fairly efficient one-way firewall. The default is no, which will allow 150all incoming connections to telnetd, ftpd, etc. 151 152 153 - nat log [yes|no] 154 155Controls logging of NAT link creation to "/var/log/alias.log" - this 156is usually only useful if debugging a setup, to see if the bug is in 157the PPP NATing. The debugging information is fairly limited, listing 158the number of NAT links open for different protocols. 159 160 161 - nat same_ports [yes|no] (default yes) 162 163When a connection is being established going through the NAT 164routines, it will normally have its port number changed to allow the 165NAT code to track it. If same_ports is enabled, the NAT 166software attempts to keep the connection's source port unchanged. 167This will allow rsh, RPC and other specialised protocols to work 168_most of the time_, at least on the host machine. Please, do not 169report this being unstable as a bug - it is a result of the way 170NAT has to work. TCP/IP was intended to have one IP address 171per machine. 172 173 174 - nat use_sockets [yes|no] (default yes) 175 176This is a fairly obscure option. For the most part, the NAT 177software does not have to allocate system sockets when it chooses a 178NAT port number. Under very specific circumstances, FTP data 179connections (which don't know the remote port number, though it is 180usually 20) and IRC DCC send (which doesn't know either the address or 181the port from which the connection will come), there can potentially be 182some interference with an open server socket having the same port number 183on the ppp host machine. This possibility for interference only exists 184until the TCP connection has been acknowledged on both sides. The safe 185option is yes, though fewer system resources are consumed by specifying 186no. 187 188 189 - nat unregistered_only [yes|no] (default no) 190 191NAT normally remaps all packets coming from the local area 192network to the ppp host machine address. Set this option to only map 193addresses from the following standard ranges for private, unregistered 194addresses: 195 196 10.0.0.0 -> 10.255.255.255 197 172.16.0.0 -> 172.31.255.255 198 192.168.0.0 -> 192.168.255.255 */ 199 200In the instance that there is a subnet of public addresses and another 201subnet of private addresses being routed by the ppp host, then only the 202packets on the private subnet will be NAT'd. 203 204 205- nat port <proto> <local addr>:<port> <nat port> 206 207This command allows incoming traffic to <nat port> on the host 208machine to be redirected to a specific machine and port on the 209local area network. One example of this would be: 210 211 nat port tcp 192.168.0.4:telnet 8066 212 213All traffic to port 8066 of the ppp host would then be sent to 214the telnet port (23) of machine 192.168.0.4. Port numbers 215can either be designated numerically or by symbolic names 216listed in /etc/services. Similarly, addresses can be either 217in dotted quad notation or in /etc/hosts. 218 219 220- nat addr <local addr> <public addr> 221 222This command allows traffic for a public IP address to be 223redirected to a machine on the local network. This function 224is known as "static NAT". An address assignment of 0 refers 225to the default address of the ppp host. Normally static 226NAT is useful if your ISP has allocated a small block of 227IP addresses to the user, but it can even be used in the 228case of a single, dynamically allocated IP address: 229 230 nat addr 10.0.0.8 0 231 232The above command would redirect all incoming traffic to 233machine 10.0.0.8. 234 235If several address NATs specify the same public address 236as follows 237 238 nat addr 192.168.0.2 public_addr 239 nat addr 192.168.0.3 public_addr 240 nat addr 192.168.0.4 public_addr 241 242then incoming traffic will be directed to the last 243translated local address (192.168.0.4), but outgoing 244traffic to the first two addresses will still be NAT'd 245to the specified public address. 246 247 248 2494. Future Work 250 251What is called NAT here has been variously called masquerading, packet 252aliasing and transparent proxying by others. It is an extremely useful 253function to many users, but it is also necessarily imperfect. The 254occasional IP-encoding protocols always need workarounds (hacks). 255Users who are interested in supporting new IP-encoding protocols 256can follow the examples of alias_ftp.c and alias_irc.c. 257 258ICMP error messages are currently handled only in the incoming direction. 259A handler needs to be added to correctly NAT outgoing error messages. 260 261IRC and FTP exception handling make reasonable, though not strictly correct 262assumptions, about how IP encoded messages will appear in the control 263stream. Programmers may wish to consider how to make this process more 264robust. 265 266The NAT engine (alias.c, alias_db.c, alias_ftp.c, alias_irc.c 267and alias_util.c) runs in user space, and is intended to be both portable 268and reusable for interfaces other than ppp. To access the basic engine 269only requires four simple function calls (initialisation, communication of 270host address, outgoing NAT and incoming de-NATing). 271 272 273 2745. Authors / Acknowledgements 275 276Charles Mott (cm@linktel.net) <versions 1.0 - 1.8, 2.0, 2.1> 277Eivind Eklund (perhaps@yes.no) <versions 1.8b - 1.9, new ppp commands> 278 279Listed below, in chronological order, are individuals who have provided 280valuable comments and/or debugging assistance. 281 282 Gary Roberts 283 Tom Torrance 284 Reto Burkhalter 285 Martin Renters 286 Brian Somers 287 Paul Traina 288 Ari Suutari 289 J. Fortes 290 Andrzej Bialeki 291 292 293 2946. Revision History for Aliasing Code 295 296Version 1.0: August 11, 1996 (cjm) 297 298Version 1.1: August 20, 1996 (cjm) 299 PPP host accepts incoming connections for ports 0 to 1023. 300 301Version 1.2: September 7, 1996 (cjm) 302 Fragment handling error in alias_db.c corrected. 303 304Version 1.3: September 15, 1996 (cjm) 305 - Generalised mechanism for handling incoming connections 306 (no more 0 to 1023 restriction). 307 - Increased ICMP support (will handle traceroute now). 308 - Improved TCP close connection logic. 309 310Version 1.4: September 16, 1996 311 Can't remember (this version only lasted a day -- cjm). 312 313Version 1.5: September 17, 1996 (cjm) 314 Corrected error in handling incoming UDP packets 315 with zero checksum. 316 317Version 1.6: September 18, 1996 318 Simplified ICMP data storage. Will now handle 319 tracert from Win95 as well as FreeBSD traceroute. 320 321Version 1.7: January 9, 1997 (cjm) 322 - Reduced malloc() activity for ICMP echo and 323 timestamp requests. 324 - Added handling for out-of-order IP fragments. 325 - Switched to differential checksum computation 326 for IP headers (TCP, UDP and ICMP checksums 327 were already differential). 328 - Accepts FTP data connections from other than 329 port 20. This allows one ftp connections 330 from two hosts which are both running packet 331 aliasing. 332 333Version 1.8: January 14, 1997 (cjm) 334 - Fixed data type error in function StartPoint() 335 in alias_db.c (this bug did not exist before v1.7) 336 337Version 1.8b: January 16, 1997 (Eivind Eklund <perhaps@yes.no>) 338 - Upgraded base PPP version to be the source code from 339 FreeBSD 2.1.6, with additional security patches. This 340 version should still be possible to run on 2.1.5, though - 341 I've run it with a 2.1.5 kernel without problems. 342 (Update done with the permission of cjm) 343 344Version 1.9: February 1, 1997 (Eivind Eklund <perhaps@yes.no>) 345 - Added support for IRC DCC (ee) 346 - Changed the aliasing routines to use ANSI style throughout - 347 minor API changes for integration with other programs than PPP (ee) 348 - Changed the build process, making all options switchable 349 from the Makefile (ee) 350 - Fixed minor security hole in alias_ftp.c for other applications 351 of the aliasing software. Hole could _not_ manifest in 352 PPP+pktAlias, but could potentially manifest in other 353 applications of the aliasing. (ee) 354 - Connections initiated from packet aliasing host machine will 355 not have their port number aliased unless it conflicts with 356 an aliasing port already being used. (There is an option to 357 disable this for debugging) (cjm) 358 - Sockets will be allocated in cases where there might be 359 port interference with the host machine. This can be disabled 360 in cases where the ppp host will be acting purely as a 361 masquerading router and not generate any traffic of its own. 362 (cjm) 363 364Version 2.0: March, 1997 (cjm) 365 - Incoming packets which are not recognised by the packet 366 aliasing engine are now completely dropped in ip.c. 367 - Aliasing links are cleared when a host interface address 368 changes (due to re-dial and dynamic address allocation). 369 - PacketAliasPermanentLink() API added. 370 - Option for only aliasing private, unregistered IP addresses 371 added. 372 - Substantial rework to the aliasing lookup engine. 373 374Version 2.1: May, 1997 (cjm) 375 - Continuing rework to the aliasing lookup engine to support 376 multiple incoming addresses and static NAT. 377 - Now supports outgoing as well as incoming ICMP error messages/ 378 - PPP commands to support address and port redirection. 379 380