1019 lines
34 KiB
Groff
1019 lines
34 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2001 Charles Mott <cm@linktel.net>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd January 17, 2004
|
|
.Dt LIBALIAS 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libalias
|
|
.Nd packet aliasing library for masquerading and network address translation
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In netinet/in.h
|
|
.In alias.h
|
|
.Pp
|
|
Function prototypes are given in the main body of the text.
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library is a collection of functions for aliasing and de-aliasing of IP
|
|
packets, intended for masquerading and network address translation (NAT).
|
|
.Sh INTRODUCTION
|
|
This library is a moderately portable set of functions designed to assist
|
|
in the process of IP masquerading and network address translation.
|
|
Outgoing packets from a local network with unregistered IP addresses can
|
|
be aliased to appear as if they came from an accessible IP address.
|
|
Incoming packets are then de-aliased so that they are sent to the correct
|
|
machine on the local network.
|
|
.Pp
|
|
A certain amount of flexibility is built into the packet aliasing engine.
|
|
In the simplest mode of operation, a many-to-one address mapping takes
|
|
place between local network and the packet aliasing host.
|
|
This is known as IP masquerading.
|
|
In addition, one-to-one mappings between local and public addresses can
|
|
also be implemented, which is known as static NAT.
|
|
In between these extremes, different groups of private addresses can be
|
|
linked to different public addresses, comprising several distinct
|
|
many-to-one mappings.
|
|
Also, a given public address and port can be statically redirected to a
|
|
private address/port.
|
|
.Pp
|
|
The packet aliasing engine was designed to operate in user space outside
|
|
of the kernel, without any access to private kernel data structure, but
|
|
the source code can also be ported to a kernel environment.
|
|
.Sh INITIALIZATION AND CONTROL
|
|
One special function,
|
|
.Fn LibAliasInit ,
|
|
must always be called before any packet handling may be performed and
|
|
the returned instance pointer passed to all the other functions.
|
|
Normally, the
|
|
.Fn LibAliasSetAddress
|
|
function is called afterwards, to set the default aliasing address.
|
|
In addition, the operating mode of the packet aliasing engine can be
|
|
customized by calling
|
|
.Fn LibAliasSetMode .
|
|
.Pp
|
|
.Ft "struct libalias *"
|
|
.Fn LibAliasInit "struct libalias *"
|
|
.Bd -ragged -offset indent
|
|
This function is used to initialize
|
|
internal data structures.
|
|
When called the first time, a
|
|
.Dv NULL
|
|
pointer should be passed as an argument.
|
|
The following mode bits are always set after calling
|
|
.Fn LibAliasInit .
|
|
See the description of
|
|
.Fn LibAliasSetMode
|
|
below for the meaning of these mode bits.
|
|
.Pp
|
|
.Bl -item -offset indent -compact
|
|
.It
|
|
.Dv PKT_ALIAS_SAME_PORTS
|
|
.It
|
|
.Dv PKT_ALIAS_USE_SOCKETS
|
|
.It
|
|
.Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
|
|
.El
|
|
.Pp
|
|
This function will always return the packet aliasing engine to the same
|
|
initial state.
|
|
The
|
|
.Fn LibAliasSetAddress
|
|
function is normally called afterwards, and any desired changes from the
|
|
default mode bits listed above require a call to
|
|
.Fn LibAliasSetMode .
|
|
.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 LibAliasUninit "struct libalias *"
|
|
.Bd -ragged -offset indent
|
|
This function has no 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 LibAliasInit .
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn LibAliasSetAddress "struct libalias *" "struct in_addr addr"
|
|
.Bd -ragged -offset indent
|
|
This function sets the source address to which outgoing packets from the
|
|
local area network are aliased.
|
|
All outgoing packets are re-mapped to this address unless overridden by a
|
|
static address mapping established by
|
|
.Fn LibAliasRedirectAddr .
|
|
If this function is not called, and no static rules match, an outgoing
|
|
packet retains its source address.
|
|
.Pp
|
|
If the
|
|
.Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
|
|
mode bit is set (the default mode of operation), then the internal aliasing
|
|
link tables will be reset any time the aliasing address changes.
|
|
This is useful for interfaces such as
|
|
.Xr ppp 8 ,
|
|
where the IP
|
|
address may or may not change on successive dial-up attempts.
|
|
.Pp
|
|
If the
|
|
.Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
|
|
mode bit is set to zero, this function can also be used to dynamically change
|
|
the aliasing address on a packet to packet basis (it is a low overhead call).
|
|
.Pp
|
|
It is mandatory that this function be called prior to any packet handling.
|
|
.Ed
|
|
.Pp
|
|
.Ft unsigned int
|
|
.Fn LibAliasSetMode "struct libalias *" "unsigned int flags" "unsigned int mask"
|
|
.Bd -ragged -offset indent
|
|
This function sets or clears mode bits
|
|
according to the value of
|
|
.Fa flags .
|
|
Only bits marked in
|
|
.Fa mask
|
|
are affected.
|
|
The following mode bits are defined in
|
|
.In alias.h :
|
|
.Bl -tag -width indent
|
|
.It Dv PKT_ALIAS_LOG
|
|
Enables logging into
|
|
.Pa /var/log/alias.log .
|
|
Each time an aliasing link is created or deleted, the log file is appended
|
|
with the current number of ICMP, TCP and UDP links.
|
|
Mainly useful for debugging when the log file is viewed continuously with
|
|
.Xr tail 1 .
|
|
.It Dv PKT_ALIAS_DENY_INCOMING
|
|
If this mode bit is set, all incoming packets associated with new TCP
|
|
connections or new UDP transactions will be marked for being ignored
|
|
.Fn ( LibAliasIn
|
|
returns
|
|
.Dv PKT_ALIAS_IGNORED
|
|
code)
|
|
by the calling program.
|
|
Response packets to connections or transactions initiated from the packet
|
|
aliasing host or local network will be unaffected.
|
|
This mode bit is useful for implementing a one-way firewall.
|
|
.It Dv PKT_ALIAS_SAME_PORTS
|
|
If this mode bit is set, the packet aliasing engine will attempt to leave
|
|
the alias port numbers unchanged from the actual local port numbers.
|
|
This can be done as long as the quintuple (proto, alias addr, alias port,
|
|
remote addr, remote port) is unique.
|
|
If a conflict exists, a new aliasing port number is chosen even if this
|
|
mode bit is set.
|
|
.It Dv PKT_ALIAS_USE_SOCKETS
|
|
This bit should be set when the packet aliasing host originates network
|
|
traffic as well as forwards it.
|
|
When the packet aliasing host is waiting for a connection from an unknown
|
|
host address or unknown port number (e.g.\& an FTP data connection), this
|
|
mode bit specifies that a socket be allocated as a place holder to prevent
|
|
port conflicts.
|
|
Once a connection is established, usually within a minute or so, the socket
|
|
is closed.
|
|
.It Dv PKT_ALIAS_UNREGISTERED_ONLY
|
|
If this mode bit is set, traffic on the local network which does not
|
|
originate from unregistered address spaces will be ignored.
|
|
Standard Class A, B and C unregistered addresses are:
|
|
.Bd -literal -offset indent
|
|
10.0.0.0 -> 10.255.255.255 (Class A subnet)
|
|
172.16.0.0 -> 172.31.255.255 (Class B subnets)
|
|
192.168.0.0 -> 192.168.255.255 (Class C subnets)
|
|
.Ed
|
|
.Pp
|
|
This option is useful in the case that packet aliasing host has both
|
|
registered and unregistered subnets on different interfaces.
|
|
The registered subnet is fully accessible to the outside world, so traffic
|
|
from it does not need to be passed through the packet aliasing engine.
|
|
.It Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE
|
|
When this mode bit is set and
|
|
.Fn LibAliasSetAddress
|
|
is called to change the aliasing address, the internal link table of the
|
|
packet aliasing engine will be cleared.
|
|
This operating mode is useful for
|
|
.Xr ppp 8
|
|
links where the interface address can sometimes change or remain the same
|
|
between dial-up attempts.
|
|
If this mode bit is not set, the link table will never be reset in the event
|
|
of an address change.
|
|
.It Dv PKT_ALIAS_PUNCH_FW
|
|
This option makes
|
|
.Nm
|
|
`punch holes' in an
|
|
.Xr ipfirewall 4
|
|
based firewall for FTP/IRC DCC connections.
|
|
The holes punched are bound by from/to IP address and port; it will not be
|
|
possible to use a hole for another connection.
|
|
A hole is removed when the connection that uses it dies.
|
|
To cater to unexpected death of a program using
|
|
.Nm
|
|
(e.g.\& kill -9),
|
|
changing the state of the flag will clear the entire firewall range
|
|
allocated for holes.
|
|
This will also happen on the initial call to
|
|
.Fn LibAliasSetFWBase .
|
|
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 LibAliasProxyRule
|
|
below for details.
|
|
.El
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
|
|
.Bd -ragged -offset indent
|
|
Set firewall range allocated for punching firewall holes (with the
|
|
.Dv PKT_ALIAS_PUNCH_FW
|
|
flag).
|
|
The range will be cleared for all rules on initialization.
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn LibAliasSkinnyPort "struct libalias *" "unsigned int port"
|
|
.Bd -ragged -offset indent
|
|
Set the TCP port used by the Skinny Station protocol.
|
|
Skinny is used by Cisco IP phones to communicate with
|
|
Cisco Call Managers to set up voice over IP calls.
|
|
If this is not set, Skinny aliasing will not be done.
|
|
The typical port used by Skinny is 2000.
|
|
.Ed
|
|
.Sh PACKET HANDLING
|
|
The packet handling functions are used to modify incoming (remote to local)
|
|
and outgoing (local to remote) packets.
|
|
The calling program is responsible for receiving and sending packets via
|
|
network interfaces.
|
|
.Pp
|
|
Along with
|
|
.Fn LibAliasInit
|
|
and
|
|
.Fn LibAliasSetAddress ,
|
|
the two packet handling functions,
|
|
.Fn LibAliasIn
|
|
and
|
|
.Fn LibAliasOut ,
|
|
comprise minimal set of functions needed for a basic IP masquerading
|
|
implementation.
|
|
.Pp
|
|
.Ft int
|
|
.Fn LibAliasIn "struct libalias *" "char *buffer" "int maxpacketsize"
|
|
.Bd -ragged -offset indent
|
|
An incoming packet coming from a remote machine to the local network is
|
|
de-aliased by this function.
|
|
The IP packet is pointed to by
|
|
.Fa buffer ,
|
|
and
|
|
.Fa maxpacketsize
|
|
indicates the size of the data structure containing the packet and should
|
|
be at least as large as the actual packet size.
|
|
.Pp
|
|
Return codes:
|
|
.Bl -tag -width indent
|
|
.It Dv PKT_ALIAS_OK
|
|
The packet aliasing process was successful.
|
|
.It Dv PKT_ALIAS_IGNORED
|
|
The packet was ignored and not de-aliased.
|
|
This can happen if the protocol is unrecognized, possibly an ICMP message
|
|
type is not handled or if incoming packets for new connections are being
|
|
ignored (if
|
|
.Dv PKT_ALIAS_DENY_INCOMING
|
|
mode bit was set by
|
|
.Fn LibAliasSetMode ) .
|
|
.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 LibAliasSaveFragment
|
|
until a header fragment is found.
|
|
.It Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT
|
|
The packet aliasing process was successful, and a header fragment was found.
|
|
This is a signal to retrieve any unresolved fragments with
|
|
.Fn LibAliasGetFragment
|
|
and de-alias them with
|
|
.Fn LibAliasFragmentIn .
|
|
.It Dv PKT_ALIAS_ERROR
|
|
An internal error within the packet aliasing engine occurred.
|
|
.El
|
|
.Ed
|
|
.Pp
|
|
.Ft int
|
|
.Fn LibAliasOut "struct libalias *" "char *buffer" "int maxpacketsize"
|
|
.Bd -ragged -offset indent
|
|
An outgoing packet coming from the local network to a remote machine is
|
|
aliased by this function.
|
|
The IP packet is pointed to by
|
|
.Fa buffer ,
|
|
and
|
|
.Fa maxpacketsize
|
|
indicates the maximum packet size permissible should the packet length be
|
|
changed.
|
|
IP encoding protocols place address and port information in the encapsulated
|
|
data stream which has to be modified and can account for changes in packet
|
|
length.
|
|
Well known examples of such protocols are FTP and IRC DCC.
|
|
.Pp
|
|
Return codes:
|
|
.Bl -tag -width indent
|
|
.It Dv PKT_ALIAS_OK
|
|
The packet aliasing process was successful.
|
|
.It Dv PKT_ALIAS_IGNORED
|
|
The packet was ignored and not aliased.
|
|
This can happen if the protocol is unrecognized, or possibly an ICMP message
|
|
type is not handled.
|
|
.It Dv PKT_ALIAS_ERROR
|
|
An internal error within the packet aliasing engine occurred.
|
|
.El
|
|
.Ed
|
|
.Sh PORT AND ADDRESS REDIRECTION
|
|
The functions described in this section allow machines on the local network
|
|
to be accessible in some degree to new incoming connections from the external
|
|
network.
|
|
Individual ports can be re-mapped or static network address translations can
|
|
be designated.
|
|
.Pp
|
|
.Ft struct alias_link *
|
|
.Fo LibAliasRedirectPort
|
|
.Fa "struct libalias *"
|
|
.Fa "struct in_addr local_addr"
|
|
.Fa "u_short local_port"
|
|
.Fa "struct in_addr remote_addr"
|
|
.Fa "u_short remote_port"
|
|
.Fa "struct in_addr alias_addr"
|
|
.Fa "u_short alias_port"
|
|
.Fa "u_char proto"
|
|
.Fc
|
|
.Bd -ragged -offset indent
|
|
This function specifies that traffic from a given remote address/port to
|
|
an alias address/port be redirected to a specified local address/port.
|
|
The parameter
|
|
.Fa proto
|
|
can be either
|
|
.Dv IPPROTO_TCP
|
|
or
|
|
.Dv IPPROTO_UDP ,
|
|
as defined in
|
|
.In netinet/in.h .
|
|
.Pp
|
|
If
|
|
.Fa local_addr
|
|
or
|
|
.Fa alias_addr
|
|
is zero, this indicates that the packet aliasing address as established
|
|
by
|
|
.Fn LibAliasSetAddress
|
|
is to be used.
|
|
Even if
|
|
.Fn LibAliasSetAddress
|
|
is called to change the address after
|
|
.Fn LibAliasRedirectPort
|
|
is called, a zero reference will track this change.
|
|
.Pp
|
|
If the link is further set up to operate for a load sharing, then
|
|
.Fa local_addr
|
|
and
|
|
.Fa local_port
|
|
are ignored, and are selected dynamically from the server pool, as described in
|
|
.Fn LibAliasAddServer
|
|
below.
|
|
.Pp
|
|
If
|
|
.Fa remote_addr
|
|
is zero, this indicates to redirect packets from any remote address.
|
|
Likewise, if
|
|
.Fa remote_port
|
|
is zero, this indicates to redirect packets originating from any remote
|
|
port number.
|
|
Almost always, the remote port specification will be zero, but non-zero
|
|
remote addresses can sometimes be useful for firewalling.
|
|
If two calls to
|
|
.Fn LibAliasRedirectPort
|
|
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 LibAliasRedirectDelete .
|
|
If
|
|
.Dv NULL
|
|
is returned, then the function call did not complete successfully.
|
|
.Pp
|
|
All port numbers should be in network address byte order, so it is necessary
|
|
to use
|
|
.Xr htons 3
|
|
to convert these parameters from internally readable numbers to network byte
|
|
order.
|
|
Addresses are also in network byte order, which is implicit in the use of the
|
|
.Fa struct in_addr
|
|
data type.
|
|
.Ed
|
|
.Pp
|
|
.Ft struct alias_link *
|
|
.Fo LibAliasRedirectAddr
|
|
.Fa "struct libalias *"
|
|
.Fa "struct in_addr local_addr"
|
|
.Fa "struct in_addr alias_addr"
|
|
.Fc
|
|
.Bd -ragged -offset indent
|
|
This function designates that all incoming traffic to
|
|
.Fa alias_addr
|
|
be redirected to
|
|
.Fa local_addr .
|
|
Similarly, all outgoing traffic from
|
|
.Fa local_addr
|
|
is aliased to
|
|
.Fa alias_addr .
|
|
.Pp
|
|
If
|
|
.Fa local_addr
|
|
or
|
|
.Fa alias_addr
|
|
is zero, this indicates that the packet aliasing address as established by
|
|
.Fn LibAliasSetAddress
|
|
is to be used.
|
|
Even if
|
|
.Fn LibAliasSetAddress
|
|
is called to change the address after
|
|
.Fn LibAliasRedirectAddr
|
|
is called, a zero reference will track this change.
|
|
.Pp
|
|
If the link is further set up to operate for a load sharing, then
|
|
.Fa local_addr
|
|
is ignored, and is selected dynamically from the server pool, as described in
|
|
.Fn LibAliasAddServer
|
|
below.
|
|
.Pp
|
|
If subsequent calls to
|
|
.Fn LibAliasRedirectAddr
|
|
use the same aliasing address, all new incoming traffic to this aliasing
|
|
address will be redirected to the local address made in the last function
|
|
call.
|
|
New traffic generated by any of the local machines, designated in the
|
|
several function calls, will be aliased to the same address.
|
|
Consider the following example:
|
|
.Bd -literal -offset indent
|
|
LibAliasRedirectAddr(la, inet_aton("192.168.0.2"),
|
|
inet_aton("141.221.254.101"));
|
|
LibAliasRedirectAddr(la, inet_aton("192.168.0.3"),
|
|
inet_aton("141.221.254.101"));
|
|
LibAliasRedirectAddr(la, inet_aton("192.168.0.4"),
|
|
inet_aton("141.221.254.101"));
|
|
.Ed
|
|
.Pp
|
|
Any outgoing connections such as
|
|
.Xr telnet 1
|
|
or
|
|
.Xr ftp 1
|
|
from 192.168.0.2, 192.168.0.3 and 192.168.0.4 will appear to come from
|
|
141.221.254.101.
|
|
Any incoming connections to 141.221.254.101 will be directed to 192.168.0.4.
|
|
.Pp
|
|
Any calls to
|
|
.Fn LibAliasRedirectPort
|
|
will have precedence over address mappings designated by
|
|
.Fn LibAliasRedirectAddr .
|
|
.Pp
|
|
This function returns a pointer which can subsequently be used by
|
|
.Fn LibAliasRedirectDelete .
|
|
If
|
|
.Dv NULL
|
|
is returned, then the function call did not complete successfully.
|
|
.Ed
|
|
.Pp
|
|
.Ft int
|
|
.Fo LibAliasAddServer
|
|
.Fa "struct libalias *"
|
|
.Fa "struct alias_link *link"
|
|
.Fa "struct in_addr addr"
|
|
.Fa "u_short port"
|
|
.Fc
|
|
.Bd -ragged -offset indent
|
|
This function sets the
|
|
.Fa link
|
|
up for Load Sharing using IP Network Address Translation (RFC 2391, LSNAT).
|
|
LSNAT operates as follows.
|
|
A client attempts to access a server by using the server virtual address.
|
|
The LSNAT router transparently redirects the request to one of the hosts
|
|
in server pool, selected using a real-time load sharing algorithm.
|
|
Multiple sessions may be initiated from the same client, and each session
|
|
could be directed to a different host based on load balance across server
|
|
pool hosts at the time.
|
|
If load share is desired for just a few specific services, the configuration
|
|
on LSNAT could be defined to restrict load share for just the services
|
|
desired.
|
|
.Pp
|
|
Currently, only the simplest selection algorithm is implemented, where a
|
|
host is selected on a round-robin basis only, without regard to load on
|
|
the host.
|
|
.Pp
|
|
First, the
|
|
.Fa link
|
|
is created by either
|
|
.Fn LibAliasRedirectPort
|
|
or
|
|
.Fn LibAliasRedirectAddr .
|
|
Then,
|
|
.Fn LibAliasAddServer
|
|
is called multiple times to add entries to the
|
|
.Fa link Ns 's
|
|
server pool.
|
|
.Pp
|
|
For links created with
|
|
.Fn LibAliasRedirectAddr ,
|
|
the
|
|
.Fa port
|
|
argument is ignored and could have any value, e.g.\& htons(~0).
|
|
.Pp
|
|
This function returns 0 on success, \-1 otherwise.
|
|
.Ed
|
|
.Pp
|
|
.Ft int
|
|
.Fn LibAliasRedirectDynamic "struct libalias *" "struct alias_link *link"
|
|
.Bd -ragged -offset indent
|
|
This function marks the specified static redirect rule entered by
|
|
.Fn LibAliasRedirectPort
|
|
as dynamic.
|
|
This can be used to e.g.\& dynamically redirect a single TCP connection,
|
|
after which the rule is removed.
|
|
Only fully specified links can be made dynamic.
|
|
(See the
|
|
.Sx STATIC AND DYNAMIC LINKS
|
|
and
|
|
.Sx PARTIALLY SPECIFIED ALIASING LINKS
|
|
sections below for a definition of static vs.\& dynamic,
|
|
and partially vs.\& fully specified links.)
|
|
.Pp
|
|
This function returns 0 on success, \-1 otherwise.
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn LibAliasRedirectDelete "struct libalias *" "struct alias_link *link"
|
|
.Bd -ragged -offset indent
|
|
This function will delete a specific static redirect rule entered by
|
|
.Fn LibAliasRedirectPort
|
|
or
|
|
.Fn LibAliasRedirectAddr .
|
|
The parameter
|
|
.Fa link
|
|
is the pointer returned by either of the redirection functions.
|
|
If an invalid pointer is passed to
|
|
.Fn LibAliasRedirectDelete ,
|
|
then a program crash or unpredictable operation could result, so it is
|
|
necessary to be careful using this function.
|
|
.Ed
|
|
.Pp
|
|
.Ft int
|
|
.Fn LibAliasProxyRule "struct libalias *" "const char *cmd"
|
|
.Bd -ragged -offset indent
|
|
The passed
|
|
.Fa cmd
|
|
string consists of one or more pairs of words.
|
|
The first word in each pair is a token and the second is the value that
|
|
should be applied for that token.
|
|
Tokens and their argument types are as follows:
|
|
.Bl -tag -width indent
|
|
.It Cm type encode_ip_hdr | encode_tcp_stream | no_encode
|
|
In order to support transparent proxying, it is necessary to somehow
|
|
pass the original address and port information into the new destination
|
|
server.
|
|
If
|
|
.Cm encode_ip_hdr
|
|
is specified, the original destination address and port are passed
|
|
as an extra IP option.
|
|
If
|
|
.Cm encode_tcp_stream
|
|
is specified, the original destination address and port are passed
|
|
as the first piece of data in the TCP stream in the format
|
|
.Dq Li DEST Ar IP port .
|
|
.It Cm port Ar portnum
|
|
Only packets with the destination port
|
|
.Ar portnum
|
|
are proxied.
|
|
.It Cm server Ar host Ns Op : Ns Ar portnum
|
|
This specifies the
|
|
.Ar host
|
|
and
|
|
.Ar portnum
|
|
that the data is to be redirected to.
|
|
.Ar host
|
|
must be an IP address rather than a DNS host name.
|
|
If
|
|
.Ar portnum
|
|
is not specified, the destination port number is not changed.
|
|
.Pp
|
|
The
|
|
.Ar server
|
|
specification is mandatory unless the
|
|
.Cm delete
|
|
command is being used.
|
|
.It Cm rule Ar index
|
|
Normally, each call to
|
|
.Fn LibAliasProxyRule
|
|
inserts the next rule at the start of a linear list of rules.
|
|
If an
|
|
.Ar index
|
|
is specified, the new rule will be checked after all rules with lower
|
|
indices.
|
|
Calls to
|
|
.Fn LibAliasProxyRule
|
|
that do not specify a rule are assigned rule 0.
|
|
.It Cm delete Ar index
|
|
This token and its argument MUST NOT be used with any other tokens.
|
|
When used, all existing rules with the given
|
|
.Ar index
|
|
are deleted.
|
|
.It Cm proto tcp | udp
|
|
If specified, only packets of the given protocol type are matched.
|
|
.It Cm src Ar IP Ns Op / Ns Ar bits
|
|
If specified, only packets with a source address matching the given
|
|
.Ar IP
|
|
are matched.
|
|
If
|
|
.Ar bits
|
|
is also specified, then the first
|
|
.Ar bits
|
|
bits of
|
|
.Ar IP
|
|
are taken as a network specification, and all IP addresses from that
|
|
network will be matched.
|
|
.It Cm dst Ar IP Ns Op / Ns Ar bits
|
|
If specified, only packets with a destination address matching the given
|
|
.Ar IP
|
|
are matched.
|
|
If
|
|
.Ar bits
|
|
is also specified, then the first
|
|
.Ar bits
|
|
bits of
|
|
.Ar IP
|
|
are taken as a network specification, and all IP addresses from that
|
|
network will be matched.
|
|
.El
|
|
.Pp
|
|
This function is usually used to redirect outgoing connections for
|
|
internal machines that are not permitted certain types of internet
|
|
access, or to restrict access to certain external machines.
|
|
.Ed
|
|
.Pp
|
|
.Ft struct alias_link *
|
|
.Fo LibAliasRedirectProto
|
|
.Fa "struct libalias *"
|
|
.Fa "struct in_addr local_addr"
|
|
.Fa "struct in_addr remote_addr"
|
|
.Fa "struct in_addr alias_addr"
|
|
.Fa "u_char proto"
|
|
.Fc
|
|
.Bd -ragged -offset indent
|
|
This function specifies that any IP packet with protocol number of
|
|
.Fa proto
|
|
from a given remote address to an alias address be
|
|
redirected to a specified local address.
|
|
.Pp
|
|
If
|
|
.Fa local_addr
|
|
or
|
|
.Fa alias_addr
|
|
is zero, this indicates that the packet aliasing address as established
|
|
by
|
|
.Fn LibAliasSetAddress
|
|
is to be used.
|
|
Even if
|
|
.Fn LibAliasSetAddress
|
|
is called to change the address after
|
|
.Fn LibAliasRedirectProto
|
|
is called, a zero reference will track this change.
|
|
.Pp
|
|
If
|
|
.Fa remote_addr
|
|
is zero, this indicates to redirect packets from any remote address.
|
|
Non-zero remote addresses can sometimes be useful for firewalling.
|
|
.Pp
|
|
If two calls to
|
|
.Fn LibAliasRedirectProto
|
|
overlap in their address specifications, then the most recent call
|
|
will have precedence.
|
|
.Pp
|
|
This function returns a pointer which can subsequently be used by
|
|
.Fn LibAliasRedirectDelete .
|
|
If
|
|
.Dv NULL
|
|
is returned, then the function call did not complete successfully.
|
|
.Ed
|
|
.Sh FRAGMENT HANDLING
|
|
The functions in this section are used to deal with incoming fragments.
|
|
.Pp
|
|
Outgoing fragments are handled within
|
|
.Fn LibAliasOut
|
|
by changing the address according to any applicable mapping set by
|
|
.Fn LibAliasRedirectAddr ,
|
|
or the default aliasing address set by
|
|
.Fn LibAliasSetAddress .
|
|
.Pp
|
|
Incoming fragments are handled in one of two ways.
|
|
If the header of a fragmented IP packet has already been seen, then all
|
|
subsequent fragments will be re-mapped in the same manner the header
|
|
fragment was.
|
|
Fragments which arrive before the header are saved and then retrieved
|
|
once the header fragment has been resolved.
|
|
.Pp
|
|
.Ft int
|
|
.Fn LibAliasSaveFragment "struct libalias *" "char *ptr"
|
|
.Bd -ragged -offset indent
|
|
When
|
|
.Fn LibAliasIn
|
|
returns
|
|
.Dv PKT_ALIAS_UNRESOLVED_FRAGMENT ,
|
|
this function can be used to save the pointer to the unresolved fragment.
|
|
.Pp
|
|
It is implicitly assumed that
|
|
.Fa ptr
|
|
points to a block of memory allocated by
|
|
.Xr malloc 3 .
|
|
If the fragment is never resolved, the packet aliasing engine will
|
|
automatically free the memory after a timeout period.
|
|
[Eventually this function should be modified so that a callback function
|
|
for freeing memory is passed as an argument.]
|
|
.Pp
|
|
This function returns
|
|
.Dv PKT_ALIAS_OK
|
|
if it was successful and
|
|
.Dv PKT_ALIAS_ERROR
|
|
if there was an error.
|
|
.Ed
|
|
.Pp
|
|
.Ft char *
|
|
.Fn LibAliasGetFragment "struct libalias *" "char *buffer"
|
|
.Bd -ragged -offset indent
|
|
This function can be used to retrieve fragment pointers saved by
|
|
.Fn LibAliasSaveFragment .
|
|
The IP header fragment pointed to by
|
|
.Fa buffer
|
|
is the header fragment indicated when
|
|
.Fn LibAliasIn
|
|
returns
|
|
.Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT .
|
|
Once a fragment pointer is retrieved, it becomes the calling program's
|
|
responsibility to free the dynamically allocated memory for the fragment.
|
|
.Pp
|
|
The
|
|
.Fn LibAliasGetFragment
|
|
function can be called sequentially until there are no more fragments
|
|
available, at which time it returns
|
|
.Dv NULL .
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn LibAliasFragmentIn "struct libalias *" "char *header" "char *fragment"
|
|
.Bd -ragged -offset indent
|
|
When a fragment is retrieved with
|
|
.Fn LibAliasGetFragment ,
|
|
it can then be de-aliased with a call to
|
|
.Fn LibAliasFragmentIn .
|
|
The
|
|
.Fa header
|
|
argument is the pointer to a header fragment used as a template, and
|
|
.Fa fragment
|
|
is the pointer to the packet to be de-aliased.
|
|
.Ed
|
|
.Sh MISCELLANEOUS FUNCTIONS
|
|
.Ft void
|
|
.Fn LibAliasSetTarget "struct libalias *" "struct in_addr addr"
|
|
.Bd -ragged -offset indent
|
|
When an incoming packet not associated with any pre-existing aliasing link
|
|
arrives at the host machine, it will be sent to the address indicated by a
|
|
call to
|
|
.Fn LibAliasSetTarget .
|
|
.Pp
|
|
If this function is called with an
|
|
.Dv INADDR_NONE
|
|
address argument, then all new incoming packets go to the address set by
|
|
.Fn LibAliasSetAddress .
|
|
.Pp
|
|
If this function is not called, or is called with an
|
|
.Dv INADDR_ANY
|
|
address argument, then all new incoming packets go to the address specified
|
|
in the packet.
|
|
This allows external machines to talk directly to internal machines if they
|
|
can route packets to the machine in question.
|
|
.Ed
|
|
.Pp
|
|
.Ft int
|
|
.Fn LibAliasCheckNewLink 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 LibAliasSetTarget
|
|
is called to change the default target address.
|
|
.Ed
|
|
.Pp
|
|
.Ft u_short
|
|
.Fn LibAliasInternetChecksum "struct libalias *" "u_short *buffer" "int nbytes"
|
|
.Bd -ragged -offset indent
|
|
This is a utility function that does not seem to be available elsewhere and
|
|
is included as a convenience.
|
|
It computes the internet checksum, which is used in both IP and
|
|
protocol-specific headers (TCP, UDP, ICMP).
|
|
.Pp
|
|
The
|
|
.Fa buffer
|
|
argument points to the data block to be checksummed, and
|
|
.Fa nbytes
|
|
is the number of bytes.
|
|
The 16-bit checksum field should be zeroed before computing the checksum.
|
|
.Pp
|
|
Checksums can also be verified by operating on a block of data including
|
|
its checksum.
|
|
If the checksum is valid,
|
|
.Fn LibAliasInternetChecksum
|
|
will return zero.
|
|
.Ed
|
|
.Pp
|
|
.Ft int
|
|
.Fn LibAliasUnaliasOut "struct libalias *" "char *buffer" "int maxpacketsize"
|
|
.Bd -ragged -offset indent
|
|
An outgoing packet, which has already been aliased,
|
|
has its private address/port information restored by this function.
|
|
The IP packet is pointed to by
|
|
.Fa buffer ,
|
|
and
|
|
.Fa maxpacketsize
|
|
is provided for error checking purposes.
|
|
This function can be used if an already-aliased packet needs to have its
|
|
original IP header restored for further processing (e.g.\& logging).
|
|
.Ed
|
|
.Sh BUGS
|
|
PPTP aliasing does not work when more than one internal client
|
|
connects to the same external server at the same time, because
|
|
PPTP requires a single TCP control connection to be established
|
|
between any two IP addresses.
|
|
.Sh AUTHORS
|
|
.An Charles Mott Aq cm@linktel.net ,
|
|
versions 1.0 - 1.8, 2.0 - 2.4.
|
|
.An Eivind Eklund Aq eivind@FreeBSD.org ,
|
|
versions 1.8b, 1.9 and 2.5.
|
|
Added IRC DCC support as well as contributing a number of architectural
|
|
improvements; added the firewall bypass for FTP/IRC DCC.
|
|
.An Erik Salander Aq erik@whistle.com
|
|
added support for PPTP and RTSP.
|
|
.An Junichi Satoh Aq junichi@junichi.org
|
|
added support for RTSP/PNA.
|
|
.An Ruslan Ermilov Aq ru@FreeBSD.org
|
|
added support for PPTP and LSNAT as well as general hacking.
|
|
.Sh ACKNOWLEDGMENTS
|
|
Listed below, in approximate chronological order, are individuals who
|
|
have provided valuable comments and/or debugging assistance.
|
|
.Pp
|
|
.Bd -ragged -offset indent
|
|
.An -split
|
|
.An Gary Roberts
|
|
.An Tom Torrance
|
|
.An Reto Burkhalter
|
|
.An Martin Renters
|
|
.An Brian Somers
|
|
.An Paul Traina
|
|
.An Ari Suutari
|
|
.An Dave Remien
|
|
.An J. Fortes
|
|
.An Andrzej Bialecki
|
|
.An Gordon Burditt
|
|
.Ed
|
|
.Sh CONCEPTUAL BACKGROUND
|
|
This section is intended for those who are planning to modify the source
|
|
code or want to create somewhat esoteric applications using the packet
|
|
aliasing functions.
|
|
.Pp
|
|
The conceptual framework under which the packet aliasing engine operates
|
|
is described here.
|
|
Central to the discussion is the idea of an
|
|
.Em aliasing link
|
|
which describes the relationship for a given packet transaction between
|
|
the local machine, aliased identity and remote machine.
|
|
It is discussed how such links come into existence and are destroyed.
|
|
.Ss ALIASING LINKS
|
|
There is a notion of an
|
|
.Em aliasing link ,
|
|
which is a 7-tuple describing a specific translation:
|
|
.Bd -literal -offset indent
|
|
(local addr, local port, alias addr, alias port,
|
|
remote addr, remote port, protocol)
|
|
.Ed
|
|
.Pp
|
|
Outgoing packets have the local address and port number replaced with the
|
|
alias address and port number.
|
|
Incoming packets undergo the reverse process.
|
|
The packet aliasing engine attempts to match packets against an internal
|
|
table of aliasing links to determine how to modify a given IP packet.
|
|
Both the IP header and protocol dependent headers are modified as necessary.
|
|
Aliasing links are created and deleted as necessary according to network
|
|
traffic.
|
|
.Pp
|
|
Protocols can be TCP, UDP or even ICMP in certain circumstances.
|
|
(Some types of ICMP packets can be aliased according to sequence or ID
|
|
number which acts as an equivalent port number for identifying how
|
|
individual packets should be handled.)
|
|
.Pp
|
|
Each aliasing link must have a unique combination of the following five
|
|
quantities: alias address/port, remote address/port and protocol.
|
|
This ensures that several machines on a local network can share the
|
|
same aliasing IP address.
|
|
In cases where conflicts might arise, the aliasing port is chosen so that
|
|
uniqueness is maintained.
|
|
.Ss STATIC AND DYNAMIC LINKS
|
|
Aliasing links can either be static or dynamic.
|
|
Static links persist indefinitely and represent fixed rules for translating
|
|
IP packets.
|
|
Dynamic links come into existence for a specific TCP connection or UDP
|
|
transaction or ICMP ECHO sequence.
|
|
For the case of TCP, the connection can be monitored to see when the
|
|
associated aliasing link should be deleted.
|
|
Aliasing links for UDP transactions (and ICMP ECHO and TIMESTAMP requests)
|
|
work on a simple timeout rule.
|
|
When no activity is observed on a dynamic link for a certain amount of time
|
|
it is automatically deleted.
|
|
Timeout rules also apply to TCP connections which do not open or close
|
|
properly.
|
|
.Ss PARTIALLY SPECIFIED ALIASING LINKS
|
|
Aliasing links can be partially specified, meaning that the remote address
|
|
and/or remote port are unknown.
|
|
In this case, when a packet matching the incomplete specification is found,
|
|
a fully specified dynamic link is created.
|
|
If the original partially specified link is dynamic, it will be deleted
|
|
after the fully specified link is created, otherwise it will persist.
|
|
.Pp
|
|
For instance, a partially specified link might be
|
|
.Bd -literal -offset indent
|
|
(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp)
|
|
.Ed
|
|
.Pp
|
|
The zeros denote unspecified components for the remote address and port.
|
|
If this link were static it would have the effect of redirecting all
|
|
incoming traffic from port 8066 of 204.228.203.215 to port 23 (telnet)
|
|
of machine 192.168.0.4 on the local network.
|
|
Each individual telnet connection would initiate the creation of a distinct
|
|
dynamic link.
|
|
.Ss DYNAMIC LINK CREATION
|
|
In addition to aliasing links, there are also address mappings that can be
|
|
stored within the internal data table of the packet aliasing mechanism.
|
|
.Bd -literal -offset indent
|
|
(local addr, alias addr)
|
|
.Ed
|
|
.Pp
|
|
Address mappings are searched when creating new dynamic links.
|
|
.Pp
|
|
All outgoing packets from the local network automatically create a dynamic
|
|
link if they do not match an already existing fully specified link.
|
|
If an address mapping exists for the outgoing packet, this determines
|
|
the alias address to be used.
|
|
If no mapping exists, then a default address, usually the address of the
|
|
packet aliasing host, is used.
|
|
If necessary, this default address can be changed as often as each individual
|
|
packet arrives.
|
|
.Pp
|
|
The aliasing port number is determined such that the new dynamic link does
|
|
not conflict with any existing links.
|
|
In the default operating mode, the packet aliasing engine attempts to set
|
|
the aliasing port equal to the local port number.
|
|
If this results in a conflict, then port numbers are randomly chosen until
|
|
a unique aliasing link can be established.
|
|
In an alternate operating mode, the first choice of an aliasing port is also
|
|
random and unrelated to the local port number.
|