diff --git a/lib/libalias/libalias.3 b/lib/libalias/libalias.3 index 6e4ebc5483b3..6186e19d919a 100644 --- a/lib/libalias/libalias.3 +++ b/lib/libalias/libalias.3 @@ -1,380 +1,336 @@ .\" $FreeBSD$ .\" -.Dd July, 1997 -.Dt LIBALIAS 3 -.Os +.Dd April 13, 2000 +.Dt LIBALIAS 3 +.Os FreeBSD .Sh NAME .Nm libalias -.Nd packet aliasing library for masquerading and address translation (NAT) +.Nd packet aliasing library for masquerading and network address translation .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include - -Function prototypes are given in the main body -of the text. +.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 CONTENTS -.Bd -literal -offset left -1. Introduction -2. Initialization and Control - 2.1 PacketAliasInit() - 2.2 PacketAliasUninit() - 2.3 PacketAliasSetAddress() - 2.4 PacketAliasSetMode() - 2.5 PacketAliasSetFWBase() -3. Packet Handling - 3.1 PacketAliasIn() - 3.2 PacketAliasOut() -4. Port and Address Redirection - 4.1 PacketAliasRedirectPort() - 4.2 PacketAliasRedirectAddr() - 4.3 PacketAliasRedirectDelete() - 4.4 PacketAliasProxyRule() - 4.5 PacketAliasPptp() -5. Fragment Handling - 5.1 PacketAliasSaveFragment() - 5.2 PacketAliasGetFragment() - 5.3 PacketAliasFragmentIn() -6. Miscellaneous Functions - 6.1 PacketAliasSetTarget() - 6.2 PacketAliasCheckNewLink() - 6.3 PacketAliasInternetChecksum() -7. Authors -8. Acknowledgments - -Appendix A: Conceptual Background - A.1 Aliasing Links - A.2 Static and Dynamic Links - A.3 Partially Specified Links - A.4 Dynamic Link Creation -.Ed -.Sh 1. 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. - -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. - -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 2. Initialization and Control -Two specific functions, PacketAliasInit() -and PacketAliasSetAddress(), must always be -called before any packet handling may be -performed. In addition, the operating mode -of the packet aliasing engine can be customized -by calling PacketAliasSetMode(). -.Ss 2.1 PacketAliasInit() - +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 +Two special functions, +.Fn PacketAliasInit +and +.Fn PacketAliasSetAddress , +must always be called before any packet handling may be performed. +In addition, the operating mode of the packet aliasing engine can be +customized by calling +.Fn PacketAliasSetMode . +.Pp .Ft void -.Fn PacketAliasInit "void" - -This function has no argument or return -value and is used to initialize internal -data structures. -The following mode bits -are always set after calling -PacketAliasInit(). See section 2.3 for -the meaning of these mode bits. -.Bd -literal -offset indent - PKT_ALIAS_USE_SAME_PORTS - PKT_ALIAS_USE_SOCKETS - PKT_ALIAS_RESET_ON_ADDR_CHANGE - -.Ed -This function will always return the packet -aliasing engine to the same initial state. -PacketAliasSetAddress() must be called afterwards, -and any desired changes from the default mode +.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. +.Fn PacketAliasSetAddress +must be called afterwards, and any desired changes from the default mode bits listed above require a call to -PacketAliasSetMode(). - -It is mandatory that this function be called -at the beginning of a program prior to any -packet handling. -.Ss 2.2 PacketAliasUninit() - +.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" - -This function has no argument or return -value and is used to clear any resources -attached to internal data structures. - -This functions should be called when a -program stop 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 atexit() chain by -PacketAliasInit(). Calling it multiple -times is harmless. -.Ss 2.3 PacketAliasSetAddress() - +.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" - -This function sets the source address to which -outgoing packets from the local area network -are aliased. All outgoing packets are remapped -to this address unless overridden by a static -address mapping established by -PacketAliasRedirectAddr(). - -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 interfaces such as ppp 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 handling. -.Ss 2.4 PacketAliasSetMode() - +.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 . +.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 mode" "unsigned int mask" - +.Fn PacketAliasSetMode "unsigned int flags" "unsigned int mask" +.Bd -ragged -offset indent This function sets or clears mode bits according to the value of -.Em mode . +.Fa flags . Only bits marked in -.Em mask -are affected. The following mode bits are -defined in alias.h: -.Bl -hang -offset left -.It PKT_ALIAS_LOG. -Enables logging /var/log/alias.log. The log file -shows total numbers of links (icmp, tcp, udp) each -time an aliasing link is created or deleted. Mainly -useful for debugging when the log file is viewed -continuously with "tail -f". -.It 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 (PacketAliasIn() return code -PKT_ALIAS_IGNORED) 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 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 -number. 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 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 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: +.Fa mask +are affected. +The following mode bits are defined in +.Aq Pa 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 +.Po +.Fn PacketAliasIn +returns +.Dv PKT_ALIAS_IGNORED +code +.Pc +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) - +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 -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 doesn't -need to be passed through the packet aliasing -engine. -.It PKT_ALIAS_RESET_ON_ADDR_CHANGE. +.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 -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 ppp links -where the interface address can sometimes -change or remain the same between dial-ups. -If this mode bit is not set, the link table -will never be reset in the event of an -address change. -.It PKT_ALIAS_PUNCH_FW. -This option makes libalias `punch holes' in an -ipfw 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 ipfw range allocated for holes. +.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 -PacketAliasSetFWBase(). This call must happen -prior to setting this flag. -.It PKT_ALIAS_REVERSE. -This option makes libalias reverse the way it -handles incoming and outgoing packets, allowing -it to be fed data that passes through the internal -interface rather than the external one. -.It PKT_ALIAS_PROXY_ONLY. -This option tells libalias to obey transparent proxy -rules only. Normal packet aliasing is not performed. +.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 - -.Ss 2.5 PacketAliasSetFWBase() - +.Ed +.Pp .Ft void .Fn PacketAliasSetFWBase "unsigned int base" "unsigned int num" - -Set IPFW range allocated for punching firewall holes (with the -PKT_ALIAS_PUNCH_FW flag). The range will be cleared for all rules on -initialization. -.Sh 3. Packet Handling -The packet handling functions are used to -modify incoming (remote->local) and outgoing -(local->remote) packets. The calling program -is responsible for receiving and sending -packets via network interfaces. - -Along with PacketAliasInit() and PacketAliasSetAddress(), -the two packet handling functions, PacketAliasIn() -and PacketAliasOut(), comprise minimal set of functions -needed for a basic IP masquerading implementation. -.Ss 3.1 PacketAliasIn() - +.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 +.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" - -An incoming packet coming from a remote machine to -the local network is de-aliased by this function. +.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 -.Em buffer , +.Fa buffer , and -.Em maxpacketsize -indicates the size of the data structure containing -the packet and should be at least as large as the -actual packet size. - +.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 -hang -offset left -.It PKT_ALIAS_ERROR. -An internal error within the packet aliasing -engine occurred. -.It PKT_ALIAS_OK. +.Bl -tag -width indent +.It Dv PKT_ALIAS_OK The packet aliasing process was successful. -.It PKT_ALIAS_IGNORED. +.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 (see PKT_ALIAS_DENY_INCOMING in section -2.2). -.It 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 PacketAliasSaveFragment() +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 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 PacketAliasGetFragment() and de-alias -them with PacketAliasFragmentIn(). +.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 -.Ss 3.2 PacketAliasOut() - +.Ed +.Pp .Ft int .Fn PacketAliasOut "char *buffer" "int maxpacketsize" - -An outgoing packet coming from the local network -to a remote machine is aliased by this function. +.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 -.Em buffer , +.Fa buffer , and -.Em 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 have to be -modified and can account for changes in packet -length. Well known examples of such protocols -are FTP and IRC DCC. - +.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 -hang -offset left -.It PKT_ALIAS_ERROR. -An internal error within the packet aliasing -engine occurred. -.It PKT_ALIAS_OK. +.Bl -tag -width indent +.It Dv PKT_ALIAS_OK The packet aliasing process was successful. -.It PKT_ALIAS_IGNORED. -The packet was ignored and not de-aliased. -This can happen if the protocol is unrecognized, -or possibly an ICMP message type is not handled. +.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 -.Sh 4. 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. -.Ss 4.1 PacketAliasRedirectPort() - +.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" @@ -385,185 +341,214 @@ address translations can be designated. .Fa "u_short alias_port" .Fa "u_char proto" .Fc - -This function specifies that traffic from a -given remote address/port to an alias address/port -be redirected to a specified local address/port. +.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 -.Em proto -can be either IPPROTO_TCP or IPPROTO_UDP, as -defined in . - -If -.Em local_addr +.Fa proto +can be either +.Dv IPPROTO_TCP or -.Em alias_addr -is zero, this indicates that the packet aliasing -address as established by PacketAliasSetAddress() -is to be used. Even if PacketAliasSetAddress() is -called to change the address after PacketAliasRedirectPort() +.Dv IPPROTO_UDP , +as defined in +.Aq Pa 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 +.Nm PacketAliasSetAddress +is called to change the address after +.Nm PacketAliasRedirectPort is called, a zero reference will track this change. - -If -.Em remote_addr -is zero, this indicates to redirect packets from -any remote address. Likewise, if -.Em 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 PacketAliasRedirectPort() 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 PacketAliasRedirectDelete(). If NULL is -returned, then the function call did not complete -successfully. - -All port numbers are in network address byte order, -so it is necessary to use htons() 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 -.Em struct in_addr +.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. -.Ss 4.2 PacketAliasRedirectAddr() - +.Ed +.Pp .Ft struct alias_link * .Fo PacketAliasRedirectAddr .Fa "struct in_addr local_addr" .Fa "struct in_addr alias_addr" .Fc - -This function desgnates that all incoming -traffic to -.Em alias_addr +.Bd -ragged -offset indent +This function designates that all incoming traffic to +.Fa alias_addr be redirected to -.Em local_addr. +.Fa local_addr . Similarly, all outgoing traffic from -.Em local_addr -is aliased to -.Em alias_addr . - +.Fa local_addr +is aliased to +.Fa alias_addr . +.Pp If -.Em local_addr +.Fa local_addr or -.Em alias_addr -is zero, this indicates that the packet aliasing -address as established by PacketAliasSetAddress() -is to be used. Even if PacketAliasSetAddress() is -called to change the address after PacketAliasRedirectAddr() +.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. - -If subsequent calls to 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 left - 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")); +.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 - -Any outgoing connections such as telnet or ftp -from 192.168.0.2, 192.168.0.3, 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 PacketAliasRedirectPort() will -have precedence over address mappings designated -by PacketAliasRedirectAddr(). - -This function returns a pointer which can subsequently -be used by PacketAliasRedirectDelete(). If NULL is -returned, then the function call did not complete -successfully. -.Ss 4.3 PacketAliasRedirectDelete() - +.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 void -.Fn PacketAliasRedirectDelete "struct alias_link *ptr" - -This function will delete a specific static redirect -rule entered by PacketAliasRedirectPort() or -PacketAliasRedirectAddr(). The parameter -.Em ptr -is the pointer returned by either of the redirection -functions. If an invalid pointer is passed to -PacketAliasRedirectDelete(), then a program crash -or unpredictable operation could result, so it is +.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. -.Ss 4.4 PacketAliasProxyRule() - +.Ed +.Pp .Ft int .Fn PacketAliasProxyRule "const char *cmd" - +.Bd -ragged -offset indent The passed -.Ar 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 -offset XXX -width XXX -.It type encode_ip_hdr|encode_tcp_stream|no_encode +.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 -.Dq encode_ip_hdr +server. +If +.Cm encode_ip_hdr is specified, the original address and port is passed as an extra IP -option. If -.Dq encode_tcp_stream +option. +If +.Cm encode_tcp_stream is specified, the original address and port is passed as the first -piece of data in the tcp stream in the format +piece of data in the TCP stream in the format .Dq DEST Ar IP port . -.It port Ar portnum +.It Cm port Ar portnum Only packets with the destination port .Ar portnum are proxied. -.It server Ar host[:portnum] +.It Cm server Ar host Ns Xo +.Op : Ns Ar portnum +.Xc 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 +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 -.Dq delete +.Cm delete command is being used. -.It rule Ar index +.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 +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 +indices. +Calls to .Fn PacketAliasProxyRule that do not specify a rule are assigned rule 0. -.It delete Ar index -This token and its argument must not be used with any other tokens. When -used, all existing rules with the given +.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 proto tcp|udp +.It Cm proto tcp | udp If specified, only packets of the given protocol type are matched. -.It src Ar IP[/bits] +.It Cm src Ar IP Ns Xo +.Op / Ns Ar bits +.Xc If specified, only packets with a source address matching the given .Ar IP -are matched. If +are matched. +If .Ar bits is also specified, then the first .Ar bits @@ -571,10 +556,13 @@ bits of .Ar IP are taken as a network specification, and all IP addresses from that network will be matched. -.It dst Ar IP[/bits] +.It Cm dst Ar IP Ns Xo +.Op / Ns Ar bits +.Xc If specified, only packets with a destination address matching the given .Ar IP -are matched. If +are matched. +If .Ar bits is also specified, then the first .Ar bits @@ -583,315 +571,289 @@ bits of 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. -.Ss 4.5 PacketAliasPptp() - -.Ft extern int +.Ed +.Pp +.Ft int .Fn PacketAliasPptp "struct in_addr addr" - -This function causes any -.Em G Ns No eneral -.Em R Ns No outing -.Em E Ns No ncapsulation +.Bd -ragged -offset indent +This function causes any General Routing Encapsulation .Pq Dv IPPROTO_GRE packets to be aliased using .Ar addr rather than the address set via .Fn PacketAliasSetAddress . -This allows the uses of the -.Em P Ns No oint -to -.Em P Ns No oint -.Em T Ns No unneling -.Em P Ns No rotocol +This allows the uses of the Point to Point Tunneling Protocol (PPTP) on a machine on the internal network. .Pp If the passed address is -.Dv INADDR_NONE -.Pq 255.255.255.255 , +.Dv INADDR_NONE , .Dv PPTP aliasing is disabled. -.Sh 5. Fragment Handling -The functions in this section are used to deal with -incoming fragments. - -Outgoing fragments are handled within PacketAliasOut() -by changing the address according to any -applicable mapping set by PacketAliasRedirectAddress(), +.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 PacketAliasRedirectAddress , or the default aliasing address set by -PacketAliasSetAddress(). - +.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. -.Ss 5.1 PacketAliasSaveFragment() - +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" - -When PacketAliasIn() returns -PKT_ALIAS_UNRESOLVED_FRAGMENT, this -function can be used to save the pointer to -the unresolved fragment. - +.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 -.Em ptr +.Fa ptr points to a block of memory allocated by -malloc(). 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.] - -This function returns PKT_ALIAS_OK if it -was successful and PKT_ALIAS_ERROR if there -was an error. - -.Ss 5.2 PacketAliasGetFragment() - +.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" - -This function can be used to retrieve fragment -pointers saved by PacketAliasSaveFragment(). +.Bd -ragged -offset indent +This function can be used to retrieve fragment pointers saved by +.Fn PacketAliasSaveFragment . The IP header fragment pointed to by -.Em buffer +.Fa buffer is the header fragment indicated when -PacketAliasIn() returns PKT_ALIAS_FOUND_HEADER_FRAGMENT. -Once a a fragment pointer is retrieved, it -becomes the calling program's responsibility -to free the dynamically allocated memory for -the fragment. - -PacketAliasGetFragment() can be called -sequentially until there are no more fragments -available, at which time it returns NULL. -.Ss 5.3 PacketAliasFragmentIn() - +.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 +.Fn PacketAliasGetFragment +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" - +.Fn PacketAliasFragmentIn "char *header" "char *fragment" +.Bd -ragged -offset indent When a fragment is retrieved with -PacketAliasGetFragment(), it can then be -de-aliased with a call to PacketAliasFragmentIn(). -.Em header -is the pointer to a header fragment used as a -template, and -.Em fragment +.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. -.Sh 6. Miscellaneous Functions - -.Ss 6.1 PacketAliasSetTarget() - +.Ed +.Sh MISCELLANEOUS FUNCTIONS .Ft void .Fn PacketAliasSetTarget "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 -indicated by a call to PacketAliasSetTarget(). - -If this function is not called, or is called -with a INADDR_NONE address argument, then all new -incoming packets go to the address set by -PacketAliasSetAddress. - -If this function is called with a 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. -.Ss 6.2 PacketAliasCheckNewLink() - +.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 not called, or 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 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" - -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 PacketAliasSetTarget() +.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. -.Ss 6.3 PacketAliasInternetChecksum() - +.Ed +.Pp .Ft u_short .Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes" - -This is a utility function that does not seem -to be available elswhere and is included as a -convenience. It computes the internet checksum, -which is used in both IP and protocol-specific -headers (TCP, UDP, ICMP). - -.Em buffer -points to the data block to be checksummed, and -.Em 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 including its checksum. If the checksum is -valid, PacketAliasInternetChecksum() will return zero. -.Sh 7. Authors -Charles Mott (cmott@scientech.com), 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. -.Sh 8. Acknowledgments - -Listed below, in approximate chronological -order, are individuals who have provided -valuable comments and/or debugging assistance. - -.Bl -inset -compact -offset left -.It Gary Roberts -.It Tom Torrance -.It Reto Burkhalter -.It Martin Renters -.It Brian Somers -.It Paul Traina -.It Ari Suutari -.It Dave Remien -.It J. Fortes -.It Andrzej Bialeki -.It Gordon Burditt +.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 +.Sh AUTHORS +.An Charles Mott Aq cmott@scientech.com , +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. +.Sh ACKNOWLEDGMENTS +Listed below, in approximate chronological order, are individuals who +have provided valuable comments and/or debugging assistance. +.Pp +.Bl -item -offset indent -compact +.It +Gary Roberts +.It +Tom Torrance +.It +Reto Burkhalter +.It +Martin Renters +.It +Brian Somers +.It +Paul Traina +.It +Ari Suutari +.It +Dave Remien +.It +J. Fortes +.It +Andrzej Bialecki +.It +Gordon Burditt .El -.Sh Appendix: Conceptual Background -This appendix 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. +.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 -"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 A.1 Aliasing Links -There is a notion of an "aliasing link", -which is 7-tuple describing a specific -translation: +.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 - -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 ensures that several -machines on a local network can share the -same aliased IP address. In cases where -conflicts might arise, the aliasing port -is chosen so that uniqueness is maintained. -.Ss A.2 Static and Dynamic Links +.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 +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 A.3 Partially Specified Aliasing Links -Aliasing links can be partially specified, -meaning that the remote address and/or remote -ports 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. - -For instance, a partially specified link might -be +.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 - -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 A.4 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. +.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 - -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 default 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 unrelated -to the local port number. - +.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. diff --git a/sys/netinet/libalias/libalias.3 b/sys/netinet/libalias/libalias.3 index 6e4ebc5483b3..6186e19d919a 100644 --- a/sys/netinet/libalias/libalias.3 +++ b/sys/netinet/libalias/libalias.3 @@ -1,380 +1,336 @@ .\" $FreeBSD$ .\" -.Dd July, 1997 -.Dt LIBALIAS 3 -.Os +.Dd April 13, 2000 +.Dt LIBALIAS 3 +.Os FreeBSD .Sh NAME .Nm libalias -.Nd packet aliasing library for masquerading and address translation (NAT) +.Nd packet aliasing library for masquerading and network address translation .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include - -Function prototypes are given in the main body -of the text. +.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 CONTENTS -.Bd -literal -offset left -1. Introduction -2. Initialization and Control - 2.1 PacketAliasInit() - 2.2 PacketAliasUninit() - 2.3 PacketAliasSetAddress() - 2.4 PacketAliasSetMode() - 2.5 PacketAliasSetFWBase() -3. Packet Handling - 3.1 PacketAliasIn() - 3.2 PacketAliasOut() -4. Port and Address Redirection - 4.1 PacketAliasRedirectPort() - 4.2 PacketAliasRedirectAddr() - 4.3 PacketAliasRedirectDelete() - 4.4 PacketAliasProxyRule() - 4.5 PacketAliasPptp() -5. Fragment Handling - 5.1 PacketAliasSaveFragment() - 5.2 PacketAliasGetFragment() - 5.3 PacketAliasFragmentIn() -6. Miscellaneous Functions - 6.1 PacketAliasSetTarget() - 6.2 PacketAliasCheckNewLink() - 6.3 PacketAliasInternetChecksum() -7. Authors -8. Acknowledgments - -Appendix A: Conceptual Background - A.1 Aliasing Links - A.2 Static and Dynamic Links - A.3 Partially Specified Links - A.4 Dynamic Link Creation -.Ed -.Sh 1. 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. - -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. - -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 2. Initialization and Control -Two specific functions, PacketAliasInit() -and PacketAliasSetAddress(), must always be -called before any packet handling may be -performed. In addition, the operating mode -of the packet aliasing engine can be customized -by calling PacketAliasSetMode(). -.Ss 2.1 PacketAliasInit() - +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 +Two special functions, +.Fn PacketAliasInit +and +.Fn PacketAliasSetAddress , +must always be called before any packet handling may be performed. +In addition, the operating mode of the packet aliasing engine can be +customized by calling +.Fn PacketAliasSetMode . +.Pp .Ft void -.Fn PacketAliasInit "void" - -This function has no argument or return -value and is used to initialize internal -data structures. -The following mode bits -are always set after calling -PacketAliasInit(). See section 2.3 for -the meaning of these mode bits. -.Bd -literal -offset indent - PKT_ALIAS_USE_SAME_PORTS - PKT_ALIAS_USE_SOCKETS - PKT_ALIAS_RESET_ON_ADDR_CHANGE - -.Ed -This function will always return the packet -aliasing engine to the same initial state. -PacketAliasSetAddress() must be called afterwards, -and any desired changes from the default mode +.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. +.Fn PacketAliasSetAddress +must be called afterwards, and any desired changes from the default mode bits listed above require a call to -PacketAliasSetMode(). - -It is mandatory that this function be called -at the beginning of a program prior to any -packet handling. -.Ss 2.2 PacketAliasUninit() - +.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" - -This function has no argument or return -value and is used to clear any resources -attached to internal data structures. - -This functions should be called when a -program stop 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 atexit() chain by -PacketAliasInit(). Calling it multiple -times is harmless. -.Ss 2.3 PacketAliasSetAddress() - +.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" - -This function sets the source address to which -outgoing packets from the local area network -are aliased. All outgoing packets are remapped -to this address unless overridden by a static -address mapping established by -PacketAliasRedirectAddr(). - -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 interfaces such as ppp 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 handling. -.Ss 2.4 PacketAliasSetMode() - +.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 . +.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 mode" "unsigned int mask" - +.Fn PacketAliasSetMode "unsigned int flags" "unsigned int mask" +.Bd -ragged -offset indent This function sets or clears mode bits according to the value of -.Em mode . +.Fa flags . Only bits marked in -.Em mask -are affected. The following mode bits are -defined in alias.h: -.Bl -hang -offset left -.It PKT_ALIAS_LOG. -Enables logging /var/log/alias.log. The log file -shows total numbers of links (icmp, tcp, udp) each -time an aliasing link is created or deleted. Mainly -useful for debugging when the log file is viewed -continuously with "tail -f". -.It 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 (PacketAliasIn() return code -PKT_ALIAS_IGNORED) 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 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 -number. 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 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 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: +.Fa mask +are affected. +The following mode bits are defined in +.Aq Pa 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 +.Po +.Fn PacketAliasIn +returns +.Dv PKT_ALIAS_IGNORED +code +.Pc +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) - +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 -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 doesn't -need to be passed through the packet aliasing -engine. -.It PKT_ALIAS_RESET_ON_ADDR_CHANGE. +.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 -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 ppp links -where the interface address can sometimes -change or remain the same between dial-ups. -If this mode bit is not set, the link table -will never be reset in the event of an -address change. -.It PKT_ALIAS_PUNCH_FW. -This option makes libalias `punch holes' in an -ipfw 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 ipfw range allocated for holes. +.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 -PacketAliasSetFWBase(). This call must happen -prior to setting this flag. -.It PKT_ALIAS_REVERSE. -This option makes libalias reverse the way it -handles incoming and outgoing packets, allowing -it to be fed data that passes through the internal -interface rather than the external one. -.It PKT_ALIAS_PROXY_ONLY. -This option tells libalias to obey transparent proxy -rules only. Normal packet aliasing is not performed. +.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 - -.Ss 2.5 PacketAliasSetFWBase() - +.Ed +.Pp .Ft void .Fn PacketAliasSetFWBase "unsigned int base" "unsigned int num" - -Set IPFW range allocated for punching firewall holes (with the -PKT_ALIAS_PUNCH_FW flag). The range will be cleared for all rules on -initialization. -.Sh 3. Packet Handling -The packet handling functions are used to -modify incoming (remote->local) and outgoing -(local->remote) packets. The calling program -is responsible for receiving and sending -packets via network interfaces. - -Along with PacketAliasInit() and PacketAliasSetAddress(), -the two packet handling functions, PacketAliasIn() -and PacketAliasOut(), comprise minimal set of functions -needed for a basic IP masquerading implementation. -.Ss 3.1 PacketAliasIn() - +.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 +.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" - -An incoming packet coming from a remote machine to -the local network is de-aliased by this function. +.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 -.Em buffer , +.Fa buffer , and -.Em maxpacketsize -indicates the size of the data structure containing -the packet and should be at least as large as the -actual packet size. - +.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 -hang -offset left -.It PKT_ALIAS_ERROR. -An internal error within the packet aliasing -engine occurred. -.It PKT_ALIAS_OK. +.Bl -tag -width indent +.It Dv PKT_ALIAS_OK The packet aliasing process was successful. -.It PKT_ALIAS_IGNORED. +.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 (see PKT_ALIAS_DENY_INCOMING in section -2.2). -.It 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 PacketAliasSaveFragment() +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 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 PacketAliasGetFragment() and de-alias -them with PacketAliasFragmentIn(). +.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 -.Ss 3.2 PacketAliasOut() - +.Ed +.Pp .Ft int .Fn PacketAliasOut "char *buffer" "int maxpacketsize" - -An outgoing packet coming from the local network -to a remote machine is aliased by this function. +.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 -.Em buffer , +.Fa buffer , and -.Em 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 have to be -modified and can account for changes in packet -length. Well known examples of such protocols -are FTP and IRC DCC. - +.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 -hang -offset left -.It PKT_ALIAS_ERROR. -An internal error within the packet aliasing -engine occurred. -.It PKT_ALIAS_OK. +.Bl -tag -width indent +.It Dv PKT_ALIAS_OK The packet aliasing process was successful. -.It PKT_ALIAS_IGNORED. -The packet was ignored and not de-aliased. -This can happen if the protocol is unrecognized, -or possibly an ICMP message type is not handled. +.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 -.Sh 4. 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. -.Ss 4.1 PacketAliasRedirectPort() - +.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" @@ -385,185 +341,214 @@ address translations can be designated. .Fa "u_short alias_port" .Fa "u_char proto" .Fc - -This function specifies that traffic from a -given remote address/port to an alias address/port -be redirected to a specified local address/port. +.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 -.Em proto -can be either IPPROTO_TCP or IPPROTO_UDP, as -defined in . - -If -.Em local_addr +.Fa proto +can be either +.Dv IPPROTO_TCP or -.Em alias_addr -is zero, this indicates that the packet aliasing -address as established by PacketAliasSetAddress() -is to be used. Even if PacketAliasSetAddress() is -called to change the address after PacketAliasRedirectPort() +.Dv IPPROTO_UDP , +as defined in +.Aq Pa 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 +.Nm PacketAliasSetAddress +is called to change the address after +.Nm PacketAliasRedirectPort is called, a zero reference will track this change. - -If -.Em remote_addr -is zero, this indicates to redirect packets from -any remote address. Likewise, if -.Em 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 PacketAliasRedirectPort() 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 PacketAliasRedirectDelete(). If NULL is -returned, then the function call did not complete -successfully. - -All port numbers are in network address byte order, -so it is necessary to use htons() 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 -.Em struct in_addr +.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. -.Ss 4.2 PacketAliasRedirectAddr() - +.Ed +.Pp .Ft struct alias_link * .Fo PacketAliasRedirectAddr .Fa "struct in_addr local_addr" .Fa "struct in_addr alias_addr" .Fc - -This function desgnates that all incoming -traffic to -.Em alias_addr +.Bd -ragged -offset indent +This function designates that all incoming traffic to +.Fa alias_addr be redirected to -.Em local_addr. +.Fa local_addr . Similarly, all outgoing traffic from -.Em local_addr -is aliased to -.Em alias_addr . - +.Fa local_addr +is aliased to +.Fa alias_addr . +.Pp If -.Em local_addr +.Fa local_addr or -.Em alias_addr -is zero, this indicates that the packet aliasing -address as established by PacketAliasSetAddress() -is to be used. Even if PacketAliasSetAddress() is -called to change the address after PacketAliasRedirectAddr() +.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. - -If subsequent calls to 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 left - 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")); +.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 - -Any outgoing connections such as telnet or ftp -from 192.168.0.2, 192.168.0.3, 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 PacketAliasRedirectPort() will -have precedence over address mappings designated -by PacketAliasRedirectAddr(). - -This function returns a pointer which can subsequently -be used by PacketAliasRedirectDelete(). If NULL is -returned, then the function call did not complete -successfully. -.Ss 4.3 PacketAliasRedirectDelete() - +.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 void -.Fn PacketAliasRedirectDelete "struct alias_link *ptr" - -This function will delete a specific static redirect -rule entered by PacketAliasRedirectPort() or -PacketAliasRedirectAddr(). The parameter -.Em ptr -is the pointer returned by either of the redirection -functions. If an invalid pointer is passed to -PacketAliasRedirectDelete(), then a program crash -or unpredictable operation could result, so it is +.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. -.Ss 4.4 PacketAliasProxyRule() - +.Ed +.Pp .Ft int .Fn PacketAliasProxyRule "const char *cmd" - +.Bd -ragged -offset indent The passed -.Ar 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 -offset XXX -width XXX -.It type encode_ip_hdr|encode_tcp_stream|no_encode +.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 -.Dq encode_ip_hdr +server. +If +.Cm encode_ip_hdr is specified, the original address and port is passed as an extra IP -option. If -.Dq encode_tcp_stream +option. +If +.Cm encode_tcp_stream is specified, the original address and port is passed as the first -piece of data in the tcp stream in the format +piece of data in the TCP stream in the format .Dq DEST Ar IP port . -.It port Ar portnum +.It Cm port Ar portnum Only packets with the destination port .Ar portnum are proxied. -.It server Ar host[:portnum] +.It Cm server Ar host Ns Xo +.Op : Ns Ar portnum +.Xc 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 +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 -.Dq delete +.Cm delete command is being used. -.It rule Ar index +.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 +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 +indices. +Calls to .Fn PacketAliasProxyRule that do not specify a rule are assigned rule 0. -.It delete Ar index -This token and its argument must not be used with any other tokens. When -used, all existing rules with the given +.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 proto tcp|udp +.It Cm proto tcp | udp If specified, only packets of the given protocol type are matched. -.It src Ar IP[/bits] +.It Cm src Ar IP Ns Xo +.Op / Ns Ar bits +.Xc If specified, only packets with a source address matching the given .Ar IP -are matched. If +are matched. +If .Ar bits is also specified, then the first .Ar bits @@ -571,10 +556,13 @@ bits of .Ar IP are taken as a network specification, and all IP addresses from that network will be matched. -.It dst Ar IP[/bits] +.It Cm dst Ar IP Ns Xo +.Op / Ns Ar bits +.Xc If specified, only packets with a destination address matching the given .Ar IP -are matched. If +are matched. +If .Ar bits is also specified, then the first .Ar bits @@ -583,315 +571,289 @@ bits of 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. -.Ss 4.5 PacketAliasPptp() - -.Ft extern int +.Ed +.Pp +.Ft int .Fn PacketAliasPptp "struct in_addr addr" - -This function causes any -.Em G Ns No eneral -.Em R Ns No outing -.Em E Ns No ncapsulation +.Bd -ragged -offset indent +This function causes any General Routing Encapsulation .Pq Dv IPPROTO_GRE packets to be aliased using .Ar addr rather than the address set via .Fn PacketAliasSetAddress . -This allows the uses of the -.Em P Ns No oint -to -.Em P Ns No oint -.Em T Ns No unneling -.Em P Ns No rotocol +This allows the uses of the Point to Point Tunneling Protocol (PPTP) on a machine on the internal network. .Pp If the passed address is -.Dv INADDR_NONE -.Pq 255.255.255.255 , +.Dv INADDR_NONE , .Dv PPTP aliasing is disabled. -.Sh 5. Fragment Handling -The functions in this section are used to deal with -incoming fragments. - -Outgoing fragments are handled within PacketAliasOut() -by changing the address according to any -applicable mapping set by PacketAliasRedirectAddress(), +.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 PacketAliasRedirectAddress , or the default aliasing address set by -PacketAliasSetAddress(). - +.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. -.Ss 5.1 PacketAliasSaveFragment() - +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" - -When PacketAliasIn() returns -PKT_ALIAS_UNRESOLVED_FRAGMENT, this -function can be used to save the pointer to -the unresolved fragment. - +.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 -.Em ptr +.Fa ptr points to a block of memory allocated by -malloc(). 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.] - -This function returns PKT_ALIAS_OK if it -was successful and PKT_ALIAS_ERROR if there -was an error. - -.Ss 5.2 PacketAliasGetFragment() - +.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" - -This function can be used to retrieve fragment -pointers saved by PacketAliasSaveFragment(). +.Bd -ragged -offset indent +This function can be used to retrieve fragment pointers saved by +.Fn PacketAliasSaveFragment . The IP header fragment pointed to by -.Em buffer +.Fa buffer is the header fragment indicated when -PacketAliasIn() returns PKT_ALIAS_FOUND_HEADER_FRAGMENT. -Once a a fragment pointer is retrieved, it -becomes the calling program's responsibility -to free the dynamically allocated memory for -the fragment. - -PacketAliasGetFragment() can be called -sequentially until there are no more fragments -available, at which time it returns NULL. -.Ss 5.3 PacketAliasFragmentIn() - +.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 +.Fn PacketAliasGetFragment +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" - +.Fn PacketAliasFragmentIn "char *header" "char *fragment" +.Bd -ragged -offset indent When a fragment is retrieved with -PacketAliasGetFragment(), it can then be -de-aliased with a call to PacketAliasFragmentIn(). -.Em header -is the pointer to a header fragment used as a -template, and -.Em fragment +.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. -.Sh 6. Miscellaneous Functions - -.Ss 6.1 PacketAliasSetTarget() - +.Ed +.Sh MISCELLANEOUS FUNCTIONS .Ft void .Fn PacketAliasSetTarget "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 -indicated by a call to PacketAliasSetTarget(). - -If this function is not called, or is called -with a INADDR_NONE address argument, then all new -incoming packets go to the address set by -PacketAliasSetAddress. - -If this function is called with a 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. -.Ss 6.2 PacketAliasCheckNewLink() - +.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 not called, or 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 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" - -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 PacketAliasSetTarget() +.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. -.Ss 6.3 PacketAliasInternetChecksum() - +.Ed +.Pp .Ft u_short .Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes" - -This is a utility function that does not seem -to be available elswhere and is included as a -convenience. It computes the internet checksum, -which is used in both IP and protocol-specific -headers (TCP, UDP, ICMP). - -.Em buffer -points to the data block to be checksummed, and -.Em 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 including its checksum. If the checksum is -valid, PacketAliasInternetChecksum() will return zero. -.Sh 7. Authors -Charles Mott (cmott@scientech.com), 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. -.Sh 8. Acknowledgments - -Listed below, in approximate chronological -order, are individuals who have provided -valuable comments and/or debugging assistance. - -.Bl -inset -compact -offset left -.It Gary Roberts -.It Tom Torrance -.It Reto Burkhalter -.It Martin Renters -.It Brian Somers -.It Paul Traina -.It Ari Suutari -.It Dave Remien -.It J. Fortes -.It Andrzej Bialeki -.It Gordon Burditt +.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 +.Sh AUTHORS +.An Charles Mott Aq cmott@scientech.com , +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. +.Sh ACKNOWLEDGMENTS +Listed below, in approximate chronological order, are individuals who +have provided valuable comments and/or debugging assistance. +.Pp +.Bl -item -offset indent -compact +.It +Gary Roberts +.It +Tom Torrance +.It +Reto Burkhalter +.It +Martin Renters +.It +Brian Somers +.It +Paul Traina +.It +Ari Suutari +.It +Dave Remien +.It +J. Fortes +.It +Andrzej Bialecki +.It +Gordon Burditt .El -.Sh Appendix: Conceptual Background -This appendix 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. +.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 -"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 A.1 Aliasing Links -There is a notion of an "aliasing link", -which is 7-tuple describing a specific -translation: +.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 - -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 ensures that several -machines on a local network can share the -same aliased IP address. In cases where -conflicts might arise, the aliasing port -is chosen so that uniqueness is maintained. -.Ss A.2 Static and Dynamic Links +.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 +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 A.3 Partially Specified Aliasing Links -Aliasing links can be partially specified, -meaning that the remote address and/or remote -ports 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. - -For instance, a partially specified link might -be +.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 - -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 A.4 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. +.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 - -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 default 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 unrelated -to the local port number. - +.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.