usr.sbin/ppp/README.nat

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