Home | History | Annotate | Download | only in src
      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