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