home | help
LIBALIAS(3)		     Library Functions Manual		     LIBALIAS(3)

NAME
     libalias  --  packet  aliasing library for masquerading and network address
     translation

SYNOPSIS
     #include <sys/types.h>
     #include <netinet/in.h>
     #include <alias.h>

     Function prototypes are given in the main body of the text.

DESCRIPTION
     The libalias library is a collection of  functions  for  aliasing	and  de-
     aliasing  of  IP  packets,  intended  for	masquerading and network address
     translation (NAT).

INTRODUCTION
     This library is a moderately portable set of functions designed  to  assist
     in  the process of IP masquerading and network address translation.  Outgo-
     ing packets from a local network with  unregistered  IP  addresses  can  be
     aliased  to appear as if they came from an accessible IP address.	Incoming
     packets are then de-aliased so that they are sent to the correct machine on
     the local network.

     A certain amount of flexibility is built into the packet  aliasing  engine.
     In  the  simplest	mode  of  operation, a many-to-one address mapping takes
     place between local network and the packet aliasing host.	This is known as
     IP masquerading.  In addition, one-to-one mappings between local and public
     addresses can also be implemented, which is known as static  NAT.	 In  be-
     tween  these  extremes, different groups of private addresses can be linked
     to different public addresses, comprising several distinct many-to-one map-
     pings.  Also, a given public address and port can be statically  redirected
     to a private address/port.

     The packet aliasing engine was designed to operate in user space outside of
     the  kernel,  without  any access to private kernel data structure, but the
     source code can also be ported to a kernel environment.

INITIALIZATION AND CONTROL
     One special function, LibAliasInit(), must  always  be  called  before  any
     packet  handling  may be performed and the returned instance pointer passed
     to all the other functions.  Normally, the LibAliasSetAddress() function is
     called afterwards, to set the default aliasing address.  In  addition,  the
     operating	mode  of the packet aliasing engine can be customized by calling
     LibAliasSetMode().

     struct libalias * LibAliasInit(struct libalias *)

	   This function is used to initialize internal data structures.  When
	   called the first time, a NULL pointer should be passed as an argu-
	   ment.  The following mode bits are always set after calling
	   LibAliasInit().  See the description of LibAliasSetMode() below for
	   the meaning of these mode bits.

		 PKT_ALIAS_SAME_PORTS
		 PKT_ALIAS_USE_SOCKETS
		 PKT_ALIAS_RESET_ON_ADDR_CHANGE

	   This function will always return the packet aliasing engine to the
	   same initial state.	The LibAliasSetAddress() function is normally
	   called afterwards, and any desired changes from the default mode bits
	   listed above require a call to LibAliasSetMode().

	   It is mandatory that this function be called at the beginning of a
	   program prior to any packet handling.

     void LibAliasUninit(struct libalias *)

	   This function has no return value and is used to clear any resources
	   attached to internal data structures.

	   This functions should be called when a program stops using the alias-
	   ing engine; it does, amongst other things, clear out any firewall
	   holes.  To provide backwards compatibility and extra security, it is
	   added to the atexit(3) chain by LibAliasInit().

     void LibAliasSetAddress(struct libalias *, struct in_addr addr)

	   This function sets the source address to which outgoing packets from
	   the local area network are aliased.	All outgoing packets are re-
	   mapped to this address unless overridden by a static address mapping
	   established by LibAliasRedirectAddr().  If this function is not
	   called, and no static rules match, an outgoing packet retains its
	   source address.

	   If the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit is set (the default
	   mode of operation), then the internal aliasing link tables will be
	   reset any time the aliasing address changes.  This is useful for in-
	   terfaces such as ppp(8), where the IP address may or may not change
	   on successive dial-up attempts.

	   If the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit is set to zero, this
	   function can also be used to dynamically change the aliasing address
	   on a packet to packet basis (it is a low overhead call).

	   It is mandatory that this function be called prior to any packet han-
	   dling.

     unsigned int LibAliasSetMode(struct libalias *,  unsigned	int  flags,  un-
     signed int mask)

	   This function sets or clears mode bits according to the value of
	   flags.  Only bits marked in mask are affected.  The following mode
	   bits are defined in <alias.h>:

	   PKT_ALIAS_LOG
		   Enables logging into /var/log/alias.log.  Each time an alias-
		   ing link is created or deleted, the log file is appended with
		   the current number of ICMP, TCP and UDP links.  Mainly useful
		   for debugging when the log file is viewed continuously with
		   tail(1).

	   PKT_ALIAS_DENY_INCOMING
		   If this mode bit is set, all incoming packets associated with
		   new TCP connections or new UDP transactions will be marked
		   for being ignored (LibAliasIn() returns PKT_ALIAS_IGNORED
		   code) by the calling program.  Response packets to connec-
		   tions or transactions initiated from the packet aliasing host
		   or local network will be unaffected.  This mode bit is useful
		   for implementing a one-way firewall.

	   PKT_ALIAS_SAME_PORTS
		   If this mode bit is set, the packet aliasing engine will at-
		   tempt to leave the alias port numbers unchanged from the ac-
		   tual local port numbers.  This can be done as long as the
		   quintuple (proto, alias addr, alias port, remote addr, remote
		   port) is unique.  If a conflict exists, a new aliasing port
		   number is chosen even if this mode bit is set.

	   PKT_ALIAS_USE_SOCKETS
		   This bit should be set when the packet aliasing host origi-
		   nates network traffic as well as forwards it.  When the
		   packet aliasing host is waiting for a connection from an un-
		   known host address or unknown port number (e.g. an FTP data
		   connection), this mode bit specifies that a socket be allo-
		   cated as a place holder to prevent port conflicts.  Once a
		   connection is established, usually within a minute or so, the
		   socket is closed.

	   PKT_ALIAS_UNREGISTERED_ONLY
		   If this mode bit is set, traffic on the local network which
		   does not originate from unregistered address spaces will be
		   ignored.  Standard Class A, B and C unregistered addresses
		   are:

			 10.0.0.0     ->  10.255.255.255   (Class A subnet)
			 172.16.0.0   ->  172.31.255.255   (Class B subnets)
			 192.168.0.0  ->  192.168.255.255  (Class C subnets)

		   This option is useful in the case that packet aliasing host
		   has both registered and unregistered subnets on different in-
		   terfaces.  The registered subnet is fully accessible to the
		   outside world, so traffic from it does not need to be passed
		   through the packet aliasing engine.

	   PKT_ALIAS_RESET_ON_ADDR_CHANGE
		   When this mode bit is set and LibAliasSetAddress() is called
		   to change the aliasing address, the internal link table of
		   the packet aliasing engine will be cleared.	This operating
		   mode is useful for ppp(8) links where the interface address
		   can sometimes change or remain the same between dial-up at-
		   tempts.  If this mode bit is not set, the link table will
		   never be reset in the event of an address change.

	   PKT_ALIAS_PUNCH_FW
		   This option makes libalias `punch holes' in an ipfirewall(4)
		   based firewall for FTP/IRC DCC connections.	The holes
		   punched are bound by from/to IP address and port; it will not
		   be possible to use a hole for another connection.  A hole is
		   removed when the connection that uses it dies.  To cater to
		   unexpected death of a program using libalias (e.g. kill -9),
		   changing the state of the flag will clear the entire firewall
		   range allocated for holes.  This will also happen on the ini-
		   tial call to LibAliasSetFWBase().  This call must happen
		   prior to setting this flag.

	   PKT_ALIAS_REVERSE
		   This option makes libalias reverse the way it handles incom-
		   ing and outgoing packets, allowing it to be fed with data
		   that passes through the internal interface rather than the
		   external one.

	   PKT_ALIAS_PROXY_ONLY
		   This option tells libalias to obey transparent proxy rules
		   only.  Normal packet aliasing is not performed.  See
		   LibAliasProxyRule() below for details.

     void  LibAliasSetFWBase(struct  libalias *, unsigned int base, unsigned int
     num)

	   Set firewall range allocated for punching firewall holes (with the
	   PKT_ALIAS_PUNCH_FW flag).  The range will be cleared for all rules on
	   initialization.

     void LibAliasSkinnyPort(struct libalias *, unsigned int port)

	   Set the TCP port used by the Skinny Station protocol.  Skinny is used
	   by Cisco IP phones to communicate with Cisco Call Managers to set up
	   voice over IP calls.  If this is not set, Skinny aliasing will not be
	   done.  The typical port used by Skinny is 2000.

PACKET HANDLING
     The packet handling functions are used to modify incoming (remote to local)
     and outgoing (local to remote) packets.  The calling program is responsible
     for receiving and sending packets via network interfaces.

     Along with LibAliasInit() and LibAliasSetAddress(), the two packet handling
     functions, LibAliasIn() and LibAliasOut(), comprise minimal  set  of  func-
     tions needed for a basic IP masquerading implementation.

     int LibAliasIn(struct libalias *, char *buffer, int maxpacketsize)

	   An incoming packet coming from a remote machine to the local network
	   is de-aliased by this function.  The IP packet is pointed to by
	   buffer, and maxpacketsize indicates the size of the data structure
	   containing the packet and should be at least as large as the actual
	   packet size.

	   Return codes:

	   PKT_ALIAS_OK
		   The packet aliasing process was successful.

	   PKT_ALIAS_IGNORED
		   The packet was ignored and not de-aliased.  This can happen
		   if the protocol is unrecognized, possibly an ICMP message
		   type is not handled or if incoming packets for new connec-
		   tions are being ignored (if PKT_ALIAS_DENY_INCOMING mode bit
		   was set by LibAliasSetMode()).

	   PKT_ALIAS_UNRESOLVED_FRAGMENT
		   This is returned when a fragment cannot be resolved because
		   the header fragment has not been sent yet.  In this situa-
		   tion, fragments must be saved with LibAliasSaveFragment() un-
		   til a header fragment is found.

	   PKT_ALIAS_FOUND_HEADER_FRAGMENT
		   The packet aliasing process was successful, and a header
		   fragment was found.	This is a signal to retrieve any unre-
		   solved fragments with LibAliasGetFragment() and de-alias them
		   with LibAliasFragmentIn().

	   PKT_ALIAS_ERROR
		   An internal error within the packet aliasing engine occurred.

     int LibAliasOut(struct libalias *, char *buffer, int maxpacketsize)

	   An outgoing packet coming from the local network to a remote machine
	   is aliased by this function.  The IP packet is pointed to by buffer,
	   and maxpacketsize indicates the maximum packet size permissible
	   should the packet length be changed.  IP encoding protocols place ad-
	   dress and port information in the encapsulated data stream which has
	   to be modified and can account for changes in packet length.  Well
	   known examples of such protocols are FTP and IRC DCC.

	   Return codes:

	   PKT_ALIAS_OK
		   The packet aliasing process was successful.

	   PKT_ALIAS_IGNORED
		   The packet was ignored and not aliased.  This can happen if
		   the protocol is unrecognized, or possibly an ICMP message
		   type is not handled.

	   PKT_ALIAS_ERROR
		   An internal error within the packet aliasing engine occurred.

PORT AND ADDRESS REDIRECTION
     The functions described in this section allow machines on the local network
     to be accessible in some degree to new incoming connections from the exter-
     nal  network.   Individual ports can be re-mapped or static network address
     translations can be designated.

     struct	 alias_link	 *	 LibAliasRedirectPort(struct libalias *,
     struct in_addr local_addr,  u_short local_port, struct in_addr remote_addr,
     u_short remote_port,     struct in_addr alias_addr,     u_short alias_port,
     u_char proto)

	   This function specifies that traffic from a given remote address/port
	   to an alias address/port be redirected to a specified local ad-
	   dress/port.	The parameter proto can be either IPPROTO_TCP or
	   IPPROTO_UDP, as defined in <netinet/in.h>.

	   If local_addr or alias_addr is zero, this indicates that the packet
	   aliasing address as established by LibAliasSetAddress() is to be
	   used.  Even if LibAliasSetAddress() is called to change the address
	   after LibAliasRedirectPort() is called, a zero reference will track
	   this change.

	   If the link is further set up to operate for a load sharing, then
	   local_addr and local_port are ignored, and are selected dynamically
	   from the server pool, as described in LibAliasAddServer() below.

	   If remote_addr is zero, this indicates to redirect packets from any
	   remote address.  Likewise, if remote_port is zero, this indicates to
	   redirect packets originating from any remote port number.  Almost al-
	   ways, the remote port specification will be zero, but non-zero remote
	   addresses can sometimes be useful for firewalling.  If two calls to
	   LibAliasRedirectPort() overlap in their address/port specifications,
	   then the most recent call will have precedence.

	   This function returns a pointer which can subsequently be used by
	   LibAliasRedirectDelete().  If NULL is returned, then the function
	   call did not complete successfully.

	   All port numbers should be in network address byte order, so it is
	   necessary to use htons(3) to convert these parameters from internally
	   readable numbers to network byte order.  Addresses are also in net-
	   work byte order, which is implicit in the use of the struct in_addr
	   data type.

     struct	  alias_link	  *	 LibAliasRedirectAddr(struct libalias *,
     struct in_addr local_addr, struct in_addr alias_addr)

	   This function designates that all incoming traffic to alias_addr be
	   redirected to local_addr.  Similarly, all outgoing traffic from
	   local_addr is aliased to alias_addr.

	   If local_addr or alias_addr is zero, this indicates that the packet
	   aliasing address as established by LibAliasSetAddress() is to be
	   used.  Even if LibAliasSetAddress() is called to change the address
	   after LibAliasRedirectAddr() is called, a zero reference will track
	   this change.

	   If the link is further set up to operate for a load sharing, then
	   local_addr is ignored, and is selected dynamically from the server
	   pool, as described in LibAliasAddServer() below.

	   If subsequent calls to LibAliasRedirectAddr() use the same aliasing
	   address, all new incoming traffic to this aliasing address will be
	   redirected to the local address made in the last function call.  New
	   traffic generated by any of the local machines, designated in the
	   several function calls, will be aliased to the same address.  Con-
	   sider the following example:

		 LibAliasRedirectAddr(la, inet_aton("192.168.0.2"),
					 inet_aton("141.221.254.101"));
		 LibAliasRedirectAddr(la, inet_aton("192.168.0.3"),
					 inet_aton("141.221.254.101"));
		 LibAliasRedirectAddr(la, inet_aton("192.168.0.4"),
					 inet_aton("141.221.254.101"));

	   Any outgoing connections such as telnet(1) or ftp(1) from
	   192.168.0.2, 192.168.0.3 and 192.168.0.4 will appear to come from
	   141.221.254.101.  Any incoming connections to 141.221.254.101 will be
	   directed to 192.168.0.4.

	   Any calls to LibAliasRedirectPort() will have precedence over address
	   mappings designated by LibAliasRedirectAddr().

	   This function returns a pointer which can subsequently be used by
	   LibAliasRedirectDelete().  If NULL is returned, then the function
	   call did not complete successfully.

     int      LibAliasAddServer(struct libalias *,	struct alias_link *link,
     struct in_addr addr, u_short port)

	   This function sets the link up for Load Sharing using IP Network Ad-
	   dress Translation (RFC 2391, LSNAT).  LSNAT operates as follows.  A
	   client attempts to access a server by using the server virtual ad-
	   dress.  The LSNAT router transparently redirects the request to one
	   of the hosts in server pool, selected using a real-time load sharing
	   algorithm.  Multiple sessions may be initiated from the same client,
	   and each session could be directed to a different host based on load
	   balance across server pool hosts at the time.  If load share is de-
	   sired for just a few specific services, the configuration on LSNAT
	   could be defined to restrict load share for just the services de-
	   sired.

	   Currently, only the simplest selection algorithm is implemented,
	   where a host is selected on a round-robin basis only, without regard
	   to load on the host.

	   First, the link is created by either LibAliasRedirectPort() or
	   LibAliasRedirectAddr().  Then, LibAliasAddServer() is called multiple
	   times to add entries to the link's server pool.

	   For links created with LibAliasRedirectAddr(), the port argument is
	   ignored and could have any value, e.g. htons(~0).

	   This function returns 0 on success, -1 otherwise.

     int LibAliasRedirectDynamic(struct libalias *, struct alias_link *link)

	   This function marks the specified static redirect rule entered by
	   LibAliasRedirectPort() as dynamic.  This can be used to e.g. dynami-
	   cally redirect a single TCP connection, after which the rule is re-
	   moved.  Only fully specified links can be made dynamic.  (See the
	   "STATIC AND DYNAMIC LINKS" and "PARTIALLY SPECIFIED ALIASING LINKS"
	   sections below for a definition of static vs. dynamic, and partially
	   vs. fully specified links.)

	   This function returns 0 on success, -1 otherwise.

     void LibAliasRedirectDelete(struct libalias *, struct alias_link *link)

	   This function will delete a specific static redirect rule entered by
	   LibAliasRedirectPort() or LibAliasRedirectAddr().  The parameter link
	   is the pointer returned by either of the redirection functions.  If
	   an invalid pointer is passed to LibAliasRedirectDelete(), then a pro-
	   gram crash or unpredictable operation could result, so it is neces-
	   sary to be careful using this function.

     int LibAliasProxyRule(struct libalias *, const char *cmd)

	   The passed cmd string consists of one or more pairs of words.  The
	   first word in each pair is a token and the second is the value that
	   should be applied for that token.  Tokens and their argument types
	   are as follows:

	   type encode_ip_hdr | encode_tcp_stream | no_encode
		   In order to support transparent proxying, it is necessary to
		   somehow pass the original address and port information into
		   the new destination server.	If encode_ip_hdr is specified,
		   the original destination address and port are passed as an
		   extra IP option.  If encode_tcp_stream is specified, the
		   original destination address and port are passed as the first
		   piece of data in the TCP stream in the format "DEST IP port".

	   port portnum
		   Only packets with the destination port portnum are proxied.

	   server host[:portnum]
		   This specifies the host and portnum that the data is to be
		   redirected to.  host must be an IP address rather than a DNS
		   host name.  If portnum is not specified, the destination port
		   number is not changed.

		   The server specification is mandatory unless the delete com-
		   mand is being used.

	   rule index
		   Normally, each call to LibAliasProxyRule() inserts the next
		   rule at the start of a linear list of rules.  If an index is
		   specified, the new rule will be checked after all rules with
		   lower indices.  Calls to LibAliasProxyRule() that do not
		   specify a rule are assigned rule 0.

	   delete index
		   This token and its argument MUST NOT be used with any other
		   tokens.  When used, all existing rules with the given index
		   are deleted.

	   proto tcp | udp
		   If specified, only packets of the given protocol type are
		   matched.

	   src IP[/bits]
		   If specified, only packets with a source address matching the
		   given IP are matched.  If bits is also specified, then the
		   first bits bits of IP are taken as a network specification,
		   and all IP addresses from that network will be matched.

	   dst IP[/bits]
		   If specified, only packets with a destination address match-
		   ing the given IP are matched.  If bits is also specified,
		   then the first bits bits of IP are taken as a network speci-
		   fication, and all IP addresses from that network will be
		   matched.

	   This function is usually used to redirect outgoing connections for
	   internal machines that are not permitted certain types of internet
	   access, or to restrict access to certain external machines.

     struct	 alias_link	 *	LibAliasRedirectProto(struct libalias *,
     struct in_addr local_addr, 		     struct in_addr remote_addr,
     struct in_addr alias_addr, u_char proto)

	   This function specifies that any IP packet with protocol number of
	   proto from a given remote address to an alias address be redirected
	   to a specified local address.

	   If local_addr or alias_addr is zero, this indicates that the packet
	   aliasing address as established by LibAliasSetAddress() is to be
	   used.  Even if LibAliasSetAddress() is called to change the address
	   after LibAliasRedirectProto() is called, a zero reference will track
	   this change.

	   If remote_addr is zero, this indicates to redirect packets from any
	   remote address.  Non-zero remote addresses can sometimes be useful
	   for firewalling.

	   If two calls to LibAliasRedirectProto() overlap in their address
	   specifications, then the most recent call will have precedence.

	   This function returns a pointer which can subsequently be used by
	   LibAliasRedirectDelete().  If NULL is returned, then the function
	   call did not complete successfully.

FRAGMENT HANDLING
     The functions in this section are used to deal with incoming fragments.

     Outgoing fragments are handled within LibAliasOut() by changing the address
     according	to  any applicable mapping set by LibAliasRedirectAddr(), or the
     default aliasing address set by LibAliasSetAddress().

     Incoming fragments are handled in one of two ways.   If  the  header  of  a
     fragmented  IP  packet has already been seen, then all subsequent fragments
     will be re-mapped in the same manner the header  fragment	was.   Fragments
     which arrive before the header are saved and then retrieved once the header
     fragment has been resolved.

     int LibAliasSaveFragment(struct libalias *, char *ptr)

	   When LibAliasIn() returns PKT_ALIAS_UNRESOLVED_FRAGMENT, this func-
	   tion can be used to save the pointer to the unresolved fragment.

	   It is implicitly assumed that ptr points to a block of memory allo-
	   cated by malloc(3).	If the fragment is never resolved, the packet
	   aliasing engine will automatically free the memory after a timeout
	   period.  [Eventually this function should be modified so that a call-
	   back function for freeing memory is passed as an argument.]

	   This function returns PKT_ALIAS_OK if it was successful and
	   PKT_ALIAS_ERROR if there was an error.

     char * LibAliasGetFragment(struct libalias *, char *buffer)

	   This function can be used to retrieve fragment pointers saved by
	   LibAliasSaveFragment().  The IP header fragment pointed to by buffer
	   is the header fragment indicated when LibAliasIn() returns
	   PKT_ALIAS_FOUND_HEADER_FRAGMENT.  Once a fragment pointer is re-
	   trieved, it becomes the calling program's responsibility to free the
	   dynamically allocated memory for the fragment.

	   The LibAliasGetFragment() function can be called sequentially until
	   there are no more fragments available, at which time it returns NULL.

     void LibAliasFragmentIn(struct libalias *, char *header, char *fragment)

	   When a fragment is retrieved with LibAliasGetFragment(), it can then
	   be de-aliased with a call to LibAliasFragmentIn().  The header argu-
	   ment is the pointer to a header fragment used as a template, and
	   fragment is the pointer to the packet to be de-aliased.

MISCELLANEOUS FUNCTIONS
     void LibAliasSetTarget(struct libalias *, struct in_addr addr)

	   When an incoming packet not associated with any pre-existing aliasing
	   link arrives at the host machine, it will be sent to the address in-
	   dicated by a call to LibAliasSetTarget().

	   If this function is called with an INADDR_NONE address argument, then
	   all new incoming packets go to the address set by LibAliasSetAd-
	   dress().

	   If this function is not called, or is called with an INADDR_ANY ad-
	   dress argument, then all new incoming packets go to the address spec-
	   ified in the packet.  This allows external machines to talk directly
	   to internal machines if they can route packets to the machine in
	   question.

     int LibAliasCheckNewLink(void)

	   This function returns a non-zero value when a new aliasing link is
	   created.  In circumstances where incoming traffic is being sequen-
	   tially sent to different local servers, this function can be used to
	   trigger when LibAliasSetTarget() is called to change the default tar-
	   get address.

     u_short  LibAliasInternetChecksum(struct  libalias  *, u_short *buffer, int
     nbytes)

	   This is a utility function that does not seem to be available else-
	   where and is included as a convenience.  It computes the internet
	   checksum, which is used in both IP and protocol-specific headers
	   (TCP, UDP, ICMP).

	   The buffer argument points to the data block to be checksummed, and
	   nbytes is the number of bytes.  The 16-bit checksum field should be
	   zeroed before computing the checksum.

	   Checksums can also be verified by operating on a block of data in-
	   cluding its checksum.  If the checksum is valid, LibAliasInter-
	   netChecksum() will return zero.

     int LibAliasUnaliasOut(struct libalias *, char *buffer, int maxpacketsize)

	   An outgoing packet, which has already been aliased, has its private
	   address/port information restored by this function.	The IP packet is
	   pointed to by buffer, and maxpacketsize is provided for error check-
	   ing purposes.  This function can be used if an already-aliased packet
	   needs to have its original IP header restored for further processing
	   (e.g. logging).

BUGS
     PPTP aliasing does not work when more than one internal client connects  to
     the  same	external server at the same time, because PPTP requires a single
     TCP control connection to be established between any two IP addresses.

AUTHORS
     Charles Mott <cm@linktel.net>, versions 1.0 - 1.8, 2.0 - 2.4.
     Eivind Eklund <eivind@FreeBSD.org>, versions 1.8b, 1.9 and 2.5.  Added  IRC
     DCC support as well as contributing a number of architectural improvements;
     added the firewall bypass for FTP/IRC DCC.
     Erik Salander <erik@whistle.com> added support for PPTP and RTSP.
     Junichi Satoh <junichi@junichi.org> added support for RTSP/PNA.
     Ruslan Ermilov <ru@FreeBSD.org> added support for PPTP and LSNAT as well as
     general hacking.

ACKNOWLEDGMENTS
     Listed  below, in approximate chronological order, are individuals who have
     provided valuable comments and/or debugging assistance.

	   Gary Roberts
	   Tom Torrance
	   Reto Burkhalter
	   Martin Renters
	   Brian Somers
	   Paul Traina
	   Ari Suutari
	   Dave Remien
	   J. Fortes
	   Andrzej Bialecki
	   Gordon Burditt

CONCEPTUAL BACKGROUND
     This section is intended for those who are planning to  modify  the  source
     code  or  want  to  create  somewhat esoteric applications using the packet
     aliasing functions.

     The conceptual framework under which the packet aliasing engine operates is
     described here.  Central to the discussion is the idea of an aliasing  link
     which describes the relationship for a given packet transaction between the
     local  machine,  aliased  identity and remote machine.  It is discussed how
     such links come into existence and are destroyed.

   ALIASING LINKS
     There is a notion of an aliasing link, which is a 7-tuple describing a spe-
     cific translation:

	   (local addr, local port, alias addr, alias port,
	    remote addr, remote port, protocol)

     Outgoing packets have the local address and port number replaced  with  the
     alias  address  and  port	number.   Incoming  packets  undergo the reverse
     process.  The packet aliasing engine attempts to match packets  against  an
     internal  table  of  aliasing  links  to determine how to modify a given IP
     packet.  Both the IP header and protocol dependent headers are modified  as
     necessary.   Aliasing  links are created and deleted as necessary according
     to network traffic.

     Protocols can be TCP, UDP or even ICMP  in  certain  circumstances.   (Some
     types  of	ICMP  packets  can be aliased according to sequence or ID number
     which acts as an equivalent port  number  for  identifying  how  individual
     packets should be handled.)

     Each  aliasing  link  must  have a unique combination of the following five
     quantities: alias address/port, remote address/port and protocol.	This en-
     sures that several machines on a local network can share the same	aliasing
     IP  address.   In	cases  where conflicts might arise, the aliasing port is
     chosen so that uniqueness is maintained.

   STATIC AND DYNAMIC LINKS
     Aliasing links can either be static or dynamic.  Static links  persist  in-
     definitely  and  represent fixed rules for translating IP packets.  Dynamic
     links come into existence for a specific TCP connection or UDP  transaction
     or  ICMP  ECHO  sequence.	For the case of TCP, the connection can be moni-
     tored to see when the associated aliasing link should be deleted.	Aliasing
     links for UDP transactions (and ICMP ECHO and TIMESTAMP requests) work on a
     simple timeout rule.  When no activity is observed on a dynamic link for  a
     certain amount of time it is automatically deleted.  Timeout rules also ap-
     ply to TCP connections which do not open or close properly.

   PARTIALLY SPECIFIED ALIASING LINKS
     Aliasing  links can be partially specified, meaning that the remote address
     and/or remote port are unknown.  In this case, when a packet  matching  the
     incomplete  specification	is found, a fully specified dynamic link is cre-
     ated.  If the original partially specified link  is  dynamic,  it	will  be
     deleted  after  the fully specified link is created, otherwise it will per-
     sist.

     For instance, a partially specified link might be

	   (192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp)

     The zeros denote unspecified components for the remote  address  and  port.
     If this link were static it would have the effect of redirecting all incom-
     ing  traffic  from  port 8066 of 204.228.203.215 to port 23 (telnet) of ma-
     chine 192.168.0.4 on the local network.  Each individual telnet  connection
     would initiate the creation of a distinct dynamic link.

   DYNAMIC LINK CREATION
     In  addition to aliasing links, there are also address mappings that can be
     stored within the internal data table of the packet aliasing mechanism.

	   (local addr, alias addr)

     Address mappings are searched when creating new dynamic links.

     All outgoing packets from the local network automatically create a  dynamic
     link  if they do not match an already existing fully specified link.  If an
     address mapping exists for the outgoing packet, this determines  the  alias
     address  to be used.  If no mapping exists, then a default address, usually
     the address of the packet aliasing host, is used.	If necessary,  this  de-
     fault address can be changed as often as each individual packet arrives.

     The  aliasing port number is determined such that the new dynamic link does
     not conflict with any existing links.  In the default operating  mode,  the
     packet aliasing engine attempts to set the aliasing port equal to the local
     port number.  If this results in a conflict, then port numbers are randomly
     chosen  until  a  unique aliasing link can be established.  In an alternate
     operating mode, the first choice of an aliasing port is also random and un-
     related to the local port number.

FreeBSD 5.3			January 17, 2004		     LIBALIAS(3)

home | help