usr.sbin/ppp/README.nat

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