CONTENTS

SYNOPSIS

INTRODUCTION

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.

"struct libalias *" LibAliasInit "struct libalias *"
This function is used to initialize
internal data structures.
When called the first time, a

NULL
pointer should be passed as an argument.
The following mode bits are always set after calling

LibAliasInit.
See the description of

LibAliasSetMode
below for the meaning of these mode bits.

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

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

void LibAliasUninit "struct libalias *"
This function has no return value and is used to clear any
resources attached to internal data structures.

This functions should be called when a program stops using the 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(3)
chain by

LibAliasInit.

void LibAliasSetAddress "struct libalias *" "struct in_addr addr"
This function sets the source address to which outgoing packets from the
local area network are aliased.
All outgoing packets are re-mapped to this address unless overridden by a
static address mapping established by

LibAliasRedirectAddr.
If this function is not called, and no static rules match, an outgoing
packet retains its source address.

If the

PKT_ALIAS_RESET_ON_ADDR_CHANGE
mode bit is set (the default mode of operation), then the internal aliasing
link tables will be reset any time the aliasing address changes.
This is useful for interfaces such as

ppp(8),
where the IP
address may or may not change on successive dial-up attempts.

If the

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

It is mandatory that this function be called prior to any packet handling.

unsigned int LibAliasSetMode "struct libalias *" "unsigned int flags" "unsigned int mask"
This function sets or clears mode bits
according to the value of

flags.
Only bits marked in

mask
are affected.
The following mode bits are defined in


.In alias.h :

void LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"
Set firewall range allocated for punching firewall holes (with the

PKT_ALIAS_PUNCH_FW
flag).
The range will be cleared for all rules on initialization.

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

int LibAliasIn "struct libalias *" "char *buffer" "int maxpacketsize"
An incoming packet coming from a remote machine to the local network is
de-aliased by this function.
The IP packet is pointed to by

buffer,
and

maxpacketsize
indicates the size of the data structure containing the packet and should
be at least as large as the actual packet size.

Return codes:

int LibAliasOut "struct libalias *" "char *buffer" "int maxpacketsize"
An outgoing packet coming from the local network to a remote machine is
aliased by this function.
The IP packet is pointed to by

buffer,
and

maxpacketsize
indicates the maximum packet size permissible should the packet length be
changed.
IP encoding protocols place 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.

Return codes:

PORT AND ADDRESS REDIRECTION

struct alias_link *
.Fo LibAliasRedirectPort "struct libalias *" "struct in_addr local_addr" "u_short local_port" "struct in_addr remote_addr" "u_short remote_port" "struct in_addr alias_addr" "u_short alias_port" "u_char proto"
.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.
The parameter

proto
can be either

IPPROTO_TCP
or

IPPROTO_UDP,
as defined in


.In netinet/in.h .

If

local_addr
or

alias_addr
is zero, this indicates that the packet aliasing address as established
by

LibAliasSetAddress
is to be used.
Even if

LibAliasSetAddress
is called to change the address after

LibAliasRedirectPort
is called, a zero reference will track this change.

If the link is further set up to operate for a load sharing, then

local_addr
and

local_port
are ignored, and are selected dynamically from the server pool, as described in

LibAliasAddServer
below.

If

remote_addr
is zero, this indicates to redirect packets from any remote address.
Likewise, if

remote_port
is zero, this indicates to redirect packets originating from any remote
port number.
Almost always, the remote port specification will be zero, but non-zero
remote addresses can sometimes be useful for firewalling.
If two calls to

LibAliasRedirectPort
overlap in their address/port specifications, then the most recent call
will have precedence.

This function returns a pointer which can subsequently be used by

LibAliasRedirectDelete.
If

NULL
is returned, then the function call did not complete successfully.

All port numbers should be in network address byte order, so it is necessary
to use

htons(3)
to convert these parameters from internally readable numbers to network byte
order.
Addresses are also in network byte order, which is implicit in the use of the

struct in_addr
data type.

struct alias_link *
.Fo LibAliasRedirectAddr "struct libalias *" "struct in_addr local_addr" "struct in_addr alias_addr"
.Fc
This function designates that all incoming traffic to

alias_addr
be redirected to

local_addr.
Similarly, all outgoing traffic from

local_addr
is aliased to

alias_addr.

If

local_addr
or

alias_addr
is zero, this indicates that the packet aliasing address as established by

LibAliasSetAddress
is to be used.
Even if

LibAliasSetAddress
is called to change the address after

LibAliasRedirectAddr
is called, a zero reference will track this change.

If the link is further set up to operate for a load sharing, then

local_addr
is ignored, and is selected dynamically from the server pool, as described in

LibAliasAddServer
below.

If subsequent calls to

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

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

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

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

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

int
.Fo LibAliasAddServer "struct libalias *" "struct alias_link *link" "struct in_addr addr" "u_short port"
.Fc
This function sets the

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.

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

First, the

link
is created by either

LibAliasRedirectPort
or

LibAliasRedirectAddr.
Then,

LibAliasAddServer
is called multiple times to add entries to the

link ’s
server pool.

For links created with

LibAliasRedirectAddr,
the

port
argument is ignored and could have any value, e.g. htons(~0).

This function returns 0 on success, -1 otherwise.

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

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

int LibAliasSaveFragment "struct libalias *" "char *ptr"
When

LibAliasIn
returns

PKT_ALIAS_UNRESOLVED_FRAGMENT,
this function can be used to save the pointer to the unresolved fragment.

It is implicitly assumed that

ptr
points to a block of memory allocated by

malloc(3).
If the fragment is never resolved, the packet aliasing engine will
automatically free the memory after a timeout period.
[Eventually this function should be modified so that a 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.

char * LibAliasGetFragment "struct libalias *" "char *buffer"
This function can be used to retrieve fragment pointers saved by

LibAliasSaveFragment.
The IP header fragment pointed to by

buffer
is the header fragment indicated when

LibAliasIn
returns

PKT_ALIAS_FOUND_HEADER_FRAGMENT.
Once a fragment pointer is retrieved, it becomes the calling program’s
responsibility to free the dynamically allocated memory for the fragment.

The

LibAliasGetFragment
function can be called sequentially until there are no more fragments
available, at which time it returns

NULL.

If this function is called with an

INADDR_NONE
address argument, then all new incoming packets go to the address set by

LibAliasSetAddress.

If this function is not called, or is called with an

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.

int LibAliasCheckNewLink 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

LibAliasSetTarget
is called to change the default target address.

u_short LibAliasInternetChecksum "struct libalias *" "u_short *buffer" "int nbytes"
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).

The

buffer
argument points to the data block to be checksummed, and

nbytes
is the number of bytes.
The 16-bit checksum field should be zeroed before computing the checksum.

Checksums can also be verified by operating on a block of data including
its checksum.
If the checksum is valid,

LibAliasInternetChecksum
will return zero.

ACKNOWLEDGMENTS

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.)

PARTIALLY SPECIFIED ALIASING LINKS

For instance, a partially specified link might be
(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp)

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.