1 Copyright (c) 2001 Charles Mott <cm (a] linktel.net> 2 All rights reserved. 3 4 Redistribution and use in source and binary forms, with or without 5 modification, are permitted provided that the following conditions 6 are met: 7 1. Redistributions of source code must retain the above copyright 8 notice, this list of conditions and the following disclaimer. 9 2. 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 13 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23 SUCH DAMAGE. 24 25 $FreeBSD: src/usr.sbin/ppp/README.nat,v 1.7.40.1 2010/12/21 17:10:29 kensmith Exp $ 26 27 User PPP NAT (Packet Aliasing) 28 29 30 31 0. 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 41 1. Background 42 43 User mode ppp has embedded NAT (Network Address Translation) code. 44 Enabling this, either by the "-nat" command line option or the 45 "nat enable yes" command in a ppp.conf file, makes the ppp host 46 automatically NAT IP packets forwarded from a local network, making 47 them appear to come from the ppp host machine. Incoming packets 48 from the outside world are then appropriately de-NAT'd. 49 50 The process of NAT'ing involves both the IP address and the TCP or UDP 51 port numbers. ICMP echo and timestamp packets are natted by their id 52 numbers. ICMP error messages can be properly directed by examining the 53 fragment of the offending packet which is contained in the body of the 54 message. 55 56 This software was specifically meant to support users who have 57 unregistered, private address IP networks (e.g. 192.168.0.x or 10.0.0.x 58 addresses). The ppp host can act as a gateway for these networks, and 59 computers on the local area net will have some degree of Internet access 60 without the need for a registered IP address. Additionally, there will 61 be no need for an Internet service provider to maintain routing tables 62 for the local area network. 63 64 A disadvantage of NAT is that machines on the local network, 65 behind the ppp host, are not visible from the outside world. They can 66 establish TCP connections and make UDP inquiries (such as domain name 67 service requests) but the connections seem to come from the ppp host 68 itself. There is, in effect, a partial firewall. Of course, if this is 69 what you want, the disadvantage becomes an advantage. 70 71 A second disadvantage is that "IP encoding" protocols, which send IP 72 address or port information within the data stream, are not supported 73 for the cases where exception code exists. This implementation has 74 workarounds for FTP and IRC DCC, the most well known of the IP encoding 75 protocols. This frees users from depending on using the ftp passive 76 mode and avoiding IRC DCC sends, as is sometimes the case with other 77 masquerading solutions. 78 79 The implementation supports all standard, non-encoding TCP and UDP protocols. 80 Examples of these protocols are http, gopher and telnet. The standard UDP 81 mode of Real-Audio is not presently supported, but the TCP mode does work 82 correctly. 83 84 The NAT code also handles many ICMP messages. In particular, 85 ping and traceroute are supported. 86 87 88 89 2. Packet Aliasing Setup 90 91 It is recommended that users first verify correct ppp operation without 92 NAT enabled. This will confirm that the ppp.conf file is 93 properly set up and that there are no ppp problems. Then start ppp with 94 the "-nat" option on the command line. The user should verify that 95 the ppp host can correctly connect to the Internet in NAT 96 mode. Finally, check that machines on the private network can access 97 the Internet. 98 99 The NAT software handles all packets, whether they come from 100 the host or another computer on the local area network. Thus, a correctly 101 operating ppp host indicates that the software should work properly for 102 other computers on the private network. 103 104 If the ppp host can access the Internet, but other computers on the local 105 network cannot, check that IP forwarding is enabled on the ppp host. Also, 106 verify that the other computers use this machine as a gateway. Of course, 107 you should also verify that machines within the local area network 108 communicate properly. A common error is inconsistent subnet addresses 109 and masks. 110 111 112 113 3. New commands in ppp 114 115 In order to control NAT behaviour in a simple manner (no need for 116 recompilation), a new command has been added to ppp: nat. This 117 is in addition to the -nat command line option. System managers and 118 more experienced users may prefer to use the ppp command syntax 119 within the ppp.conf file. The nat command also allows NAT 120 behaviour to be more precisely specified. 121 122 The decision to add a command instead of extending 'set' or 'option' was 123 to make obvious that these options only work when NAT is enabled. 124 125 The syntax for 'nat' is 126 127 ppp> nat option [yes|no] 128 129 where option is given by one of the following templates. 130 131 132 - nat enable [yes|no] (default no) 133 134 Enable NAT functionality. If disabled, no other NAT 135 options will have any effect. You should usually enable NAT 136 before routing any packets over the link; good points are in the 137 initial script or right before adding a route. If you do not always 138 want NAT, consider using the -nat option to ppp instead of this 139 command. 140 141 142 - nat deny_incoming [yes|no] (default yes) 143 144 Set to "yes" to disable all incoming connections. This just drops 145 connections to, for example, ftp, telnet or web servers. The NAT 146 mechanism prevents these connections. Technically, this option denies 147 all incoming TCP and UDP requests, making the NAT software a 148 fairly efficient one-way firewall. The default is no, which will allow 149 all incoming connections to telnetd, ftpd, etc. 150 151 152 - nat log [yes|no] 153 154 Controls logging of NAT link creation to "/var/log/alias.log" - this 155 is usually only useful if debugging a setup, to see if the bug is in 156 the PPP NATing. The debugging information is fairly limited, listing 157 the number of NAT links open for different protocols. 158 159 160 - nat same_ports [yes|no] (default yes) 161 162 When a connection is being established going through the NAT 163 routines, it will normally have its port number changed to allow the 164 NAT code to track it. If same_ports is enabled, the NAT 165 software attempts to keep the connection's source port unchanged. 166 This will allow rsh, RPC and other specialised protocols to work 167 _most of the time_, at least on the host machine. Please, do not 168 report this being unstable as a bug - it is a result of the way 169 NAT has to work. TCP/IP was intended to have one IP address 170 per machine. 171 172 173 - nat use_sockets [yes|no] (default yes) 174 175 This is a fairly obscure option. For the most part, the NAT 176 software does not have to allocate system sockets when it chooses a 177 NAT port number. Under very specific circumstances, FTP data 178 connections (which don't know the remote port number, though it is 179 usually 20) and IRC DCC send (which doesn't know either the address or 180 the port from which the connection will come), there can potentially be 181 some interference with an open server socket having the same port number 182 on the ppp host machine. This possibility for interference only exists 183 until the TCP connection has been acknowledged on both sides. The safe 184 option is yes, though fewer system resources are consumed by specifying 185 no. 186 187 188 - nat unregistered_only [yes|no] (default no) 189 190 NAT normally remaps all packets coming from the local area 191 network to the ppp host machine address. Set this option to only map 192 addresses from the following standard ranges for private, unregistered 193 addresses: 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 199 In the instance that there is a subnet of public addresses and another 200 subnet of private addresses being routed by the ppp host, then only the 201 packets on the private subnet will be NAT'd. 202 203 204 - nat port <proto> <local addr>:<port> <nat port> 205 206 This command allows incoming traffic to <nat port> on the host 207 machine to be redirected to a specific machine and port on the 208 local area network. One example of this would be: 209 210 nat port tcp 192.168.0.4:telnet 8066 211 212 All traffic to port 8066 of the ppp host would then be sent to 213 the telnet port (23) of machine 192.168.0.4. Port numbers 214 can either be designated numerically or by symbolic names 215 listed in /etc/services. Similarly, addresses can be either 216 in dotted quad notation or in /etc/hosts. 217 218 219 - nat addr <local addr> <public addr> 220 221 This command allows traffic for a public IP address to be 222 redirected to a machine on the local network. This function 223 is known as "static NAT". An address assignment of 0 refers 224 to the default address of the ppp host. Normally static 225 NAT is useful if your ISP has allocated a small block of 226 IP addresses to the user, but it can even be used in the 227 case of a single, dynamically allocated IP address: 228 229 nat addr 10.0.0.8 0 230 231 The above command would redirect all incoming traffic to 232 machine 10.0.0.8. 233 234 If several address NATs specify the same public address 235 as 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 241 then incoming traffic will be directed to the last 242 translated local address (192.168.0.4), but outgoing 243 traffic to the first two addresses will still be NAT'd 244 to the specified public address. 245 246 247 248 4. Future Work 249 250 What is called NAT here has been variously called masquerading, packet 251 aliasing and transparent proxying by others. It is an extremely useful 252 function to many users, but it is also necessarily imperfect. The 253 occasional IP-encoding protocols always need workarounds (hacks). 254 Users who are interested in supporting new IP-encoding protocols 255 can follow the examples of alias_ftp.c and alias_irc.c. 256 257 ICMP error messages are currently handled only in the incoming direction. 258 A handler needs to be added to correctly NAT outgoing error messages. 259 260 IRC and FTP exception handling make reasonable, though not strictly correct 261 assumptions, about how IP encoded messages will appear in the control 262 stream. Programmers may wish to consider how to make this process more 263 robust. 264 265 The NAT engine (alias.c, alias_db.c, alias_ftp.c, alias_irc.c 266 and alias_util.c) runs in user space, and is intended to be both portable 267 and reusable for interfaces other than ppp. To access the basic engine 268 only requires four simple function calls (initialisation, communication of 269 host address, outgoing NAT and incoming de-NATing). 270 271 272 273 5. Authors / Acknowledgements 274 275 Charles Mott (cm (a] linktel.net) <versions 1.0 - 1.8, 2.0, 2.1> 276 Eivind Eklund (perhaps (a] yes.no) <versions 1.8b - 1.9, new ppp commands> 277 278 Listed below, in chronological order, are individuals who have provided 279 valuable 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 293 6. Revision History for Aliasing Code 294 295 Version 1.0: August 11, 1996 (cjm) 296 297 Version 1.1: August 20, 1996 (cjm) 298 PPP host accepts incoming connections for ports 0 to 1023. 299 300 Version 1.2: September 7, 1996 (cjm) 301 Fragment handling error in alias_db.c corrected. 302 303 Version 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 309 Version 1.4: September 16, 1996 310 Can't remember (this version only lasted a day -- cjm). 311 312 Version 1.5: September 17, 1996 (cjm) 313 Corrected error in handling incoming UDP packets 314 with zero checksum. 315 316 Version 1.6: September 18, 1996 317 Simplified ICMP data storage. Will now handle 318 tracert from Win95 as well as FreeBSD traceroute. 319 320 Version 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 332 Version 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 336 Version 1.8b: January 16, 1997 (Eivind Eklund <perhaps (a] 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 343 Version 1.9: February 1, 1997 (Eivind Eklund <perhaps (a] 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 363 Version 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 373 Version 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
