diff options
Diffstat (limited to 'sys/netinet/libalias/libalias.3')
| -rw-r--r-- | sys/netinet/libalias/libalias.3 | 1011 |
1 files changed, 0 insertions, 1011 deletions
diff --git a/sys/netinet/libalias/libalias.3 b/sys/netinet/libalias/libalias.3 deleted file mode 100644 index e5ef09eb03ac..000000000000 --- a/sys/netinet/libalias/libalias.3 +++ /dev/null @@ -1,1011 +0,0 @@ -.\"- -.\" Copyright (c) 2001 Charles Mott <cm@linktel.net> -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd April 13, 2000 -.Dt LIBALIAS 3 -.Os -.Sh NAME -.Nm libalias -.Nd packet aliasing library for masquerading and network address translation -.Sh SYNOPSIS -.In sys/types.h -.In netinet/in.h -.In alias.h -.Pp -Function prototypes are given in the main body of the text. -.Sh DESCRIPTION -The -.Nm -library is a collection of functions for aliasing and de-aliasing of IP -packets, intended for masquerading and network address translation (NAT). -.Sh INTRODUCTION -This library is a moderately portable set of functions designed to assist -in the process of IP masquerading and network address translation. -Outgoing 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. -.Pp -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 between these extremes, different groups of private addresses can be -linked to different public addresses, comprising several distinct -many-to-one mappings. -Also, a given public address and port can be statically redirected to a -private address/port. -.Pp -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. -.Sh INITIALIZATION AND CONTROL -One special function, -.Fn PacketAliasInit , -must always be called before any packet handling may be performed. -Normally, the -.Fn PacketAliasSetAddress -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 -.Fn PacketAliasSetMode . -.Pp -.Ft void -.Fn PacketAliasInit void -.Bd -ragged -offset indent -This function has no arguments or return value and is used to initialize -internal data structures. -The following mode bits are always set after calling -.Fn PacketAliasInit . -See the description of -.Fn PacketAliasSetMode -below for the meaning of these mode bits. -.Pp -.Bl -item -offset indent -compact -.It -.Dv PKT_ALIAS_SAME_PORTS -.It -.Dv PKT_ALIAS_USE_SOCKETS -.It -.Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE -.El -.Pp -This function will always return the packet aliasing engine to the same -initial state. -The -.Fn PacketAliasSetAddress -function is normally called afterwards, and any desired changes from the -default mode bits listed above require a call to -.Fn PacketAliasSetMode . -.Pp -It is mandatory that this function be called at the beginning of a program -prior to any packet handling. -.Ed -.Pp -.Ft void -.Fn PacketAliasUninit void -.Bd -ragged -offset indent -This function has no arguments or return value and is used to clear any -resources attached to internal data structures. -.Pp -This functions should be called when a program stops using the aliasing -engine; it does, amongst other things, clear out any firewall holes. -To provide backwards compatibility and extra security, it is added to -the -.Xr atexit 3 -chain by -.Fn PacketAliasInit . -Calling it multiple times is harmless. -.Ed -.Pp -.Ft void -.Fn PacketAliasSetAddress "struct in_addr addr" -.Bd -ragged -offset indent -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 -.Fn PacketAliasRedirectAddr . -If this function is not called, and no static rules match, an outgoing -packet retains its source address. -.Pp -If the -.Dv 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 interfaces such as -.Xr ppp 8 , -where the IP -address may or may not change on successive dial-up attempts. -.Pp -If the -.Dv 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). -.Pp -It is mandatory that this function be called prior to any packet handling. -.Ed -.Pp -.Ft unsigned int -.Fn PacketAliasSetMode "unsigned int flags" "unsigned int mask" -.Bd -ragged -offset indent -This function sets or clears mode bits -according to the value of -.Fa flags . -Only bits marked in -.Fa mask -are affected. -The following mode bits are defined in -.In alias.h : -.Bl -tag -width indent -.It Dv PKT_ALIAS_LOG -Enables logging into -.Pa /var/log/alias.log . -Each time an aliasing 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 -.Xr tail 1 . -.It Dv 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 -.Fn ( PacketAliasIn -returns -.Dv PKT_ALIAS_IGNORED -code) -by the calling program. -Response packets to connections 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. -.It Dv PKT_ALIAS_SAME_PORTS -If this mode bit is set, the packet aliasing engine will attempt to leave -the alias port numbers unchanged from the actual 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. -.It Dv PKT_ALIAS_USE_SOCKETS -This bit should be set when the packet aliasing host originates network -traffic as well as forwards it. -When the packet aliasing host is waiting for a connection from an unknown -host address or unknown port number (e.g. an FTP data connection), this -mode bit specifies that a socket be allocated as a place holder to prevent -port conflicts. -Once a connection is established, usually within a minute or so, the socket -is closed. -.It Dv 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: -.Bd -literal -offset indent -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) -.Ed -.Pp -This option is useful in the case that packet aliasing host has both -registered and unregistered subnets on different interfaces. -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. -.It Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE -When this mode bit is set and -.Fn PacketAliasSetAddress -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 -.Xr ppp 8 -links where the interface address can sometimes change or remain the same -between dial-up attempts. -If this mode bit is not set, the link table will never be reset in the event -of an address change. -.It Dv PKT_ALIAS_PUNCH_FW -This option makes -.Nm -`punch holes' in an -.Xr 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 -.Nm -(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 initial call to -.Fn PacketAliasSetFWBase . -This call must happen prior to setting this flag. -.It Dv PKT_ALIAS_REVERSE -This option makes -.Nm -reverse the way it handles incoming and outgoing packets, allowing it -to be fed with data that passes through the internal interface rather -than the external one. -.It Dv PKT_ALIAS_PROXY_ONLY -This option tells -.Nm -to obey transparent proxy rules only. -Normal packet aliasing is not performed. -See -.Fn PacketAliasProxyRule -below for details. -.El -.Ed -.Pp -.Ft void -.Fn PacketAliasSetFWBase "unsigned int base" "unsigned int num" -.Bd -ragged -offset indent -Set firewall range allocated for punching firewall holes (with the -.Dv PKT_ALIAS_PUNCH_FW -flag). -The range will be cleared for all rules on initialization. -.Ed -.Pp -.Ft void -.Fn PacketAliasSkinnyPort "unsigned int port" -.Bd -ragged -offset indent -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. -.Ed -.Sh 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. -.Pp -Along with -.Fn PacketAliasInit -and -.Fn PacketAliasSetAddress , -the two packet handling functions, -.Fn PacketAliasIn -and -.Fn PacketAliasOut , -comprise minimal set of functions needed for a basic IP masquerading -implementation. -.Pp -.Ft int -.Fn PacketAliasIn "char *buffer" "int maxpacketsize" -.Bd -ragged -offset indent -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 -.Fa buffer , -and -.Fa maxpacketsize -indicates the size of the data structure containing the packet and should -be at least as large as the actual packet size. -.Pp -Return codes: -.Bl -tag -width indent -.It Dv PKT_ALIAS_OK -The packet aliasing process was successful. -.It Dv 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 connections are being -ignored (if -.Dv PKT_ALIAS_DENY_INCOMING -mode bit was set by -.Fn PacketAliasSetMode ) . -.It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT -This is returned when a fragment cannot be resolved because the header -fragment has not been sent yet. -In this situation, fragments must be saved with -.Fn PacketAliasSaveFragment -until a header fragment is found. -.It Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT -The packet aliasing process was successful, and a header fragment was found. -This is a signal to retrieve any unresolved fragments with -.Fn PacketAliasGetFragment -and de-alias them with -.Fn PacketAliasFragmentIn . -.It Dv PKT_ALIAS_ERROR -An internal error within the packet aliasing engine occurred. -.El -.Ed -.Pp -.Ft int -.Fn PacketAliasOut "char *buffer" "int maxpacketsize" -.Bd -ragged -offset indent -An outgoing packet coming from the local network to a remote machine is -aliased by this function. -The IP packet is pointed to by -.Fa buffer , -and -.Fa maxpacketsize -indicates the maximum packet size permissible should the packet length be -changed. -IP encoding protocols place address 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. -.Pp -Return codes: -.Bl -tag -width indent -.It Dv PKT_ALIAS_OK -The packet aliasing process was successful. -.It Dv 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. -.It Dv PKT_ALIAS_ERROR -An internal error within the packet aliasing engine occurred. -.El -.Ed -.Sh 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 external -network. -Individual ports can be re-mapped or static network address translations can -be designated. -.Pp -.Ft struct alias_link * -.Fo PacketAliasRedirectPort -.Fa "struct in_addr local_addr" -.Fa "u_short local_port" -.Fa "struct in_addr remote_addr" -.Fa "u_short remote_port" -.Fa "struct in_addr alias_addr" -.Fa "u_short alias_port" -.Fa "u_char proto" -.Fc -.Bd -ragged -offset indent -This function specifies that traffic from a given remote address/port to -an alias address/port be redirected to a specified local address/port. -The parameter -.Fa proto -can be either -.Dv IPPROTO_TCP -or -.Dv IPPROTO_UDP , -as defined in -.In netinet/in.h . -.Pp -If -.Fa local_addr -or -.Fa alias_addr -is zero, this indicates that the packet aliasing address as established -by -.Fn PacketAliasSetAddress -is to be used. -Even if -.Fn PacketAliasSetAddress -is called to change the address after -.Fn PacketAliasRedirectPort -is called, a zero reference will track this change. -.Pp -If the link is further set up to operate for a load sharing, then -.Fa local_addr -and -.Fa local_port -are ignored, and are selected dynamically from the server pool, as described in -.Fn PacketAliasAddServer -below. -.Pp -If -.Fa remote_addr -is zero, this indicates to redirect packets from any remote address. -Likewise, if -.Fa remote_port -is zero, this indicates to redirect packets originating from any remote -port number. -Almost always, the remote port specification will be zero, but non-zero -remote addresses can sometimes be useful for firewalling. -If two calls to -.Fn PacketAliasRedirectPort -overlap in their address/port specifications, then the most recent call -will have precedence. -.Pp -This function returns a pointer which can subsequently be used by -.Fn PacketAliasRedirectDelete . -If -.Dv NULL -is returned, then the function call did not complete successfully. -.Pp -All port numbers should be in network address byte order, so it is necessary -to use -.Xr htons 3 -to convert these parameters from internally readable numbers to network byte -order. -Addresses are also in network byte order, which is implicit in the use of the -.Fa struct in_addr -data type. -.Ed -.Pp -.Ft struct alias_link * -.Fo PacketAliasRedirectAddr -.Fa "struct in_addr local_addr" -.Fa "struct in_addr alias_addr" -.Fc -.Bd -ragged -offset indent -This function designates that all incoming traffic to -.Fa alias_addr -be redirected to -.Fa local_addr . -Similarly, all outgoing traffic from -.Fa local_addr -is aliased to -.Fa alias_addr . -.Pp -If -.Fa local_addr -or -.Fa alias_addr -is zero, this indicates that the packet aliasing address as established by -.Fn PacketAliasSetAddress -is to be used. -Even if -.Fn PacketAliasSetAddress -is called to change the address after -.Fn PacketAliasRedirectAddr -is called, a zero reference will track this change. -.Pp -If the link is further set up to operate for a load sharing, then -.Fa local_addr -is ignored, and is selected dynamically from the server pool, as described in -.Fn PacketAliasAddServer -below. -.Pp -If subsequent calls to -.Fn PacketAliasRedirectAddr -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. -Consider the following example: -.Bd -literal -offset indent -PacketAliasRedirectAddr(inet_aton("192.168.0.2"), - inet_aton("141.221.254.101")); -PacketAliasRedirectAddr(inet_aton("192.168.0.3"), - inet_aton("141.221.254.101")); -PacketAliasRedirectAddr(inet_aton("192.168.0.4"), - inet_aton("141.221.254.101")); -.Ed -.Pp -Any outgoing connections such as -.Xr telnet 1 -or -.Xr 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. -.Pp -Any calls to -.Fn PacketAliasRedirectPort -will have precedence over address mappings designated by -.Fn PacketAliasRedirectAddr . -.Pp -This function returns a pointer which can subsequently be used by -.Fn PacketAliasRedirectDelete . -If -.Dv NULL -is returned, then the function call did not complete successfully. -.Ed -.Pp -.Ft int -.Fo PacketAliasAddServer -.Fa "struct alias_link *link" -.Fa "struct in_addr addr" -.Fa "u_short port" -.Fc -.Bd -ragged -offset indent -This function sets the -.Fa link -up for Load Sharing using IP Network Address Translation (RFC 2391, LSNAT). -LSNAT operates as follows. -A client attempts to access a server by using the server virtual address. -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 desired for just a few specific services, the configuration -on LSNAT could be defined to restrict load share for just the services -desired. -.Pp -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. -.Pp -First, the -.Fa link -is created by either -.Fn PacketAliasRedirectPort -or -.Fn PacketAliasRedirectAddr . -Then, -.Fn PacketAliasAddServer -is called multiple times to add entries to the -.Fa link Ns 's -server pool. -.Pp -For links created with -.Fn PacketAliasRedirectAddr , -the -.Fa port -argument is ignored and could have any value, e.g. htons(~0). -.Pp -This function returns 0 on success, \-1 otherwise. -.Ed -.Pp -.Ft int -.Fn PacketAliasRedirectDynamic "struct alias_link *link" -.Bd -ragged -offset indent -This function marks the specified static redirect rule entered by -.Fn PacketAliasRedirectPort -as dynamic. -This can be used to e.g. dynamically redirect a single TCP connection, -after which the rule is removed. -Only fully specified links can be made dynamic. -(See the -.Sx STATIC AND DYNAMIC LINKS -and -.Sx PARTIALLY SPECIFIED ALIASING LINKS -sections below for a definition of static vs. dynamic, -and partially vs. fully specified links.) -.Pp -This function returns 0 on success, \-1 otherwise. -.Ed -.Pp -.Ft void -.Fn PacketAliasRedirectDelete "struct alias_link *link" -.Bd -ragged -offset indent -This function will delete a specific static redirect rule entered by -.Fn PacketAliasRedirectPort -or -.Fn PacketAliasRedirectAddr . -The parameter -.Fa link -is the pointer returned by either of the redirection functions. -If an invalid pointer is passed to -.Fn PacketAliasRedirectDelete , -then a program crash or unpredictable operation could result, so it is -necessary to be careful using this function. -.Ed -.Pp -.Ft int -.Fn PacketAliasProxyRule "const char *cmd" -.Bd -ragged -offset indent -The passed -.Fa 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: -.Bl -tag -width indent -.It Cm 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 -.Cm encode_ip_hdr -is specified, the original destination address and port are passed -as an extra IP option. -If -.Cm 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 -.Dq Li DEST Ar IP port . -.It Cm port Ar portnum -Only packets with the destination port -.Ar portnum -are proxied. -.It Cm server Ar host Ns Op : Ns Ar portnum -This specifies the -.Ar host -and -.Ar portnum -that the data is to be redirected to. -.Ar host -must be an IP address rather than a DNS host name. -If -.Ar portnum -is not specified, the destination port number is not changed. -.Pp -The -.Ar server -specification is mandatory unless the -.Cm delete -command is being used. -.It Cm rule Ar index -Normally, each call to -.Fn PacketAliasProxyRule -inserts the next rule at the start of a linear list of rules. -If an -.Ar index -is specified, the new rule will be checked after all rules with lower -indices. -Calls to -.Fn PacketAliasProxyRule -that do not specify a rule are assigned rule 0. -.It Cm delete Ar index -This token and its argument MUST NOT be used with any other tokens. -When used, all existing rules with the given -.Ar index -are deleted. -.It Cm proto tcp | udp -If specified, only packets of the given protocol type are matched. -.It Cm src Ar IP Ns Op / Ns Ar bits -If specified, only packets with a source address matching the given -.Ar IP -are matched. -If -.Ar bits -is also specified, then the first -.Ar bits -bits of -.Ar IP -are taken as a network specification, and all IP addresses from that -network will be matched. -.It Cm dst Ar IP Ns Op / Ns Ar bits -If specified, only packets with a destination address matching the given -.Ar IP -are matched. -If -.Ar bits -is also specified, then the first -.Ar bits -bits of -.Ar IP -are taken as a network specification, and all IP addresses from that -network will be matched. -.El -.Pp -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. -.Ed -.Pp -.Ft struct alias_link * -.Fo PacketAliasRedirectProto -.Fa "struct in_addr local_addr" -.Fa "struct in_addr remote_addr" -.Fa "struct in_addr alias_addr" -.Fa "u_char proto" -.Fc -.Bd -ragged -offset indent -This function specifies that any IP packet with protocol number of -.Fa proto -from a given remote address to an alias address be -redirected to a specified local address. -.Pp -If -.Fa local_addr -or -.Fa alias_addr -is zero, this indicates that the packet aliasing address as established -by -.Fn PacketAliasSetAddress -is to be used. -Even if -.Fn PacketAliasSetAddress -is called to change the address after -.Fn PacketAliasRedirectProto -is called, a zero reference will track this change. -.Pp -If -.Fa remote_addr -is zero, this indicates to redirect packets from any remote address. -Non-zero remote addresses can sometimes be useful for firewalling. -.Pp -If two calls to -.Fn PacketAliasRedirectProto -overlap in their address specifications, then the most recent call -will have precedence. -.Pp -This function returns a pointer which can subsequently be used by -.Fn PacketAliasRedirectDelete . -If -.Dv NULL -is returned, then the function call did not complete successfully. -.Ed -.Sh FRAGMENT HANDLING -The functions in this section are used to deal with incoming fragments. -.Pp -Outgoing fragments are handled within -.Fn PacketAliasOut -by changing the address according to any applicable mapping set by -.Fn PacketAliasRedirectAddr , -or the default aliasing address set by -.Fn PacketAliasSetAddress . -.Pp -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. -.Pp -.Ft int -.Fn PacketAliasSaveFragment "char *ptr" -.Bd -ragged -offset indent -When -.Fn PacketAliasIn -returns -.Dv PKT_ALIAS_UNRESOLVED_FRAGMENT , -this function can be used to save the pointer to the unresolved fragment. -.Pp -It is implicitly assumed that -.Fa ptr -points to a block of memory allocated by -.Xr 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 callback function -for freeing memory is passed as an argument.] -.Pp -This function returns -.Dv PKT_ALIAS_OK -if it was successful and -.Dv PKT_ALIAS_ERROR -if there was an error. -.Ed -.Pp -.Ft char * -.Fn PacketAliasGetFragment "char *buffer" -.Bd -ragged -offset indent -This function can be used to retrieve fragment pointers saved by -.Fn PacketAliasSaveFragment . -The IP header fragment pointed to by -.Fa buffer -is the header fragment indicated when -.Fn PacketAliasIn -returns -.Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT . -Once a fragment pointer is retrieved, it becomes the calling program's -responsibility to free the dynamically allocated memory for the fragment. -.Pp -The -.Fn PacketAliasGetFragment -function can be called sequentially until there are no more fragments -available, at which time it returns -.Dv NULL . -.Ed -.Pp -.Ft void -.Fn PacketAliasFragmentIn "char *header" "char *fragment" -.Bd -ragged -offset indent -When a fragment is retrieved with -.Fn PacketAliasGetFragment , -it can then be de-aliased with a call to -.Fn PacketAliasFragmentIn . -The -.Fa header -argument is the pointer to a header fragment used as a template, and -.Fa fragment -is the pointer to the packet to be de-aliased. -.Ed -.Sh MISCELLANEOUS FUNCTIONS -.Ft void -.Fn PacketAliasSetTarget "struct in_addr addr" -.Bd -ragged -offset indent -When an incoming packet not associated with any pre-existing aliasing link -arrives at the host machine, it will be sent to the address indicated by a -call to -.Fn PacketAliasSetTarget . -.Pp -If this function is called with an -.Dv INADDR_NONE -address argument, then all new incoming packets go to the address set by -.Fn PacketAliasSetAddress . -.Pp -If this function is not called, or is called with an -.Dv INADDR_ANY -address argument, then all new incoming packets go to the address specified -in the packet. -This allows external machines to talk directly to internal machines if they -can route packets to the machine in question. -.Ed -.Pp -.Ft int -.Fn PacketAliasCheckNewLink void -.Bd -ragged -offset indent -This function returns a non-zero value when a new aliasing link is created. -In circumstances where incoming traffic is being sequentially sent to -different local servers, this function can be used to trigger when -.Fn PacketAliasSetTarget -is called to change the default target address. -.Ed -.Pp -.Ft u_short -.Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes" -.Bd -ragged -offset indent -This is a utility function that does not seem to be available elsewhere and -is included as a convenience. -It computes the internet checksum, which is used in both IP and -protocol-specific headers (TCP, UDP, ICMP). -.Pp -The -.Fa buffer -argument points to the data block to be checksummed, and -.Fa nbytes -is the number of bytes. -The 16-bit checksum field should be zeroed before computing the checksum. -.Pp -Checksums can also be verified by operating on a block of data including -its checksum. -If the checksum is valid, -.Fn PacketAliasInternetChecksum -will return zero. -.Ed -.Pp -.Ft int -.Fn PacketUnaliasOut "char *buffer" "int maxpacketsize" -.Bd -ragged -offset indent -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 -.Fa buffer , -and -.Fa maxpacketsize -is provided for error checking purposes. -This function can be used if an already-aliased packet needs to have its -original IP header restored for further processing (eg. logging). -.Ed -.Sh 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. -.Sh AUTHORS -.An Charles Mott Aq cm@linktel.net , -versions 1.0 - 1.8, 2.0 - 2.4. -.An Eivind Eklund Aq 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. -.An Erik Salander Aq erik@whistle.com -added support for PPTP and RTSP. -.An Junichi Satoh Aq junichi@junichi.org -added support for RTSP/PNA. -.An Ruslan Ermilov Aq ru@FreeBSD.org -added support for PPTP and LSNAT as well as general hacking. -.Sh ACKNOWLEDGMENTS -Listed below, in approximate chronological order, are individuals who -have provided valuable comments and/or debugging assistance. -.Pp -.Bd -ragged -offset indent -.An -split -.An Gary Roberts -.An Tom Torrance -.An Reto Burkhalter -.An Martin Renters -.An Brian Somers -.An Paul Traina -.An Ari Suutari -.An Dave Remien -.An J. Fortes -.An Andrzej Bialecki -.An Gordon Burditt -.Ed -.Sh 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. -.Pp -The conceptual framework under which the packet aliasing engine operates -is described here. -Central to the discussion is the idea of an -.Em 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. -.Ss ALIASING LINKS -There is a notion of an -.Em aliasing link , -which is a 7-tuple describing a specific translation: -.Bd -literal -offset indent -(local addr, local port, alias addr, alias port, - remote addr, remote port, protocol) -.Ed -.Pp -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. -.Pp -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.) -.Pp -Each aliasing link must have a unique combination of the following five -quantities: alias address/port, remote address/port and protocol. -This ensures 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. -.Ss STATIC AND DYNAMIC LINKS -Aliasing links can either be static or dynamic. -Static links persist indefinitely 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 monitored 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 apply to TCP connections which do not open or close -properly. -.Ss 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 created. -If the original partially specified link is dynamic, it will be deleted -after the fully specified link is created, otherwise it will persist. -.Pp -For instance, a partially specified link might be -.Bd -literal -offset indent -(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp) -.Ed -.Pp -The zeros denote unspecified components for the remote address and port. -If this link were static it would have the effect of redirecting all -incoming traffic from port 8066 of 204.228.203.215 to port 23 (telnet) -of machine 192.168.0.4 on the local network. -Each individual telnet connection would initiate the creation of a distinct -dynamic link. -.Ss 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. -.Bd -literal -offset indent -(local addr, alias addr) -.Ed -.Pp -Address mappings are searched when creating new dynamic links. -.Pp -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 default address can be changed as often as each individual -packet arrives. -.Pp -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 unrelated to the local port number. |