.\"

.\"

.\" $FreeBSD: src/sys/netinet/libalias/libalias.3,v 1.61 2011/06/22 20:00:27 ae Exp $

.\" $FreeBSD: src/sys/netinet/libalias/libalias.3,v 1.61 2011/06/22 20:00:27 ae Exp $

.\"

.\"

.Dt LIBALIAS 3

.Dt LIBALIAS 3

.Os

.Os

.Sh NAME

.Sh NAME

.Pp

.Pp

A certain amount of flexibility is built into the packet aliasing engine.

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

In the simplest mode of operation, a many-to-one address mapping takes

This is known as IP masquerading.

This is known as IP masquerading.

In addition, one-to-one mappings between local and public addresses can

In addition, one-to-one mappings between local and public addresses can

also be implemented, which is known as static NAT.

also be implemented, which is known as static NAT.

private address/port.

private address/port.

.Pp

.Pp

The packet aliasing engine was designed to operate in user space outside

The packet aliasing engine was designed to operate in user space outside

the source code can also be ported to a kernel environment.

the source code can also be ported to a kernel environment.

.Sh INITIALIZATION AND CONTROL

.Sh INITIALIZATION AND CONTROL

One special function,

One special function,

.Fn LibAliasInit ,

.Fn LibAliasInit ,

Normally, the

Normally, the

.Fn LibAliasSetAddress

.Fn LibAliasSetAddress

function is called afterwards, to set the default aliasing address.

function is called afterwards, to set the default aliasing address.

This function has no return value and is used to clear any

This function has no return value and is used to clear any

resources attached to internal data structures.

resources attached to internal data structures.

.Pp

.Pp

To provide backwards compatibility and extra security, it is added to

To provide backwards compatibility and extra security, it is added to

the

the

.Xr atexit 3

.Xr atexit 3

All outgoing packets are re-mapped to this address unless overridden by a

All outgoing packets are re-mapped to this address unless overridden by a

static address mapping established by

static address mapping established by

.Fn LibAliasRedirectAddr .

.Fn LibAliasRedirectAddr .

packet retains its source address.

packet retains its source address.

.Pp

.Pp

If the

If the

If the

If the

.Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE

.Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE

mode bit is set to zero, this function can also be used to dynamically change

mode bit is set to zero, this function can also be used to dynamically change

.Pp

.Pp

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

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

.Ed

.Ed

.It Dv PKT_ALIAS_LOG

.It Dv PKT_ALIAS_LOG

Enables logging into

Enables logging into

.Pa /var/log/alias.log .

.Pa /var/log/alias.log .

with the current number of ICMP, TCP and UDP links.

with the current number of ICMP, TCP and UDP links.

Mainly useful for debugging when the log file is viewed continuously with

Mainly useful for debugging when the log file is viewed continuously with

.Xr tail 1 .

.Xr tail 1 .

aliasing host or local network will be unaffected.

aliasing host or local network will be unaffected.

This mode bit is useful for implementing a one-way firewall.

This mode bit is useful for implementing a one-way firewall.

.It Dv PKT_ALIAS_SAME_PORTS

.It Dv PKT_ALIAS_SAME_PORTS

the alias port numbers unchanged from the actual local port numbers.

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,

This can be done as long as the quintuple (proto, alias addr, alias port,

remote addr, remote port) is unique.

remote addr, remote port) is unique.

192.168.0.0  ->  192.168.255.255  (Class C subnets)

192.168.0.0  ->  192.168.255.255  (Class C subnets)

.Ed

.Ed

.Pp

.Pp

registered and unregistered subnets on different interfaces.

registered and unregistered subnets on different interfaces.

The registered subnet is fully accessible to the outside world, so traffic

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.

from it does not need to be passed through the packet aliasing engine.

.It Dv PKT_ALIAS_PUNCH_FW

.It Dv PKT_ALIAS_PUNCH_FW

This option makes

This option makes

.Nm

.Nm

based firewall for FTP/IRC DCC connections.

based firewall for FTP/IRC DCC connections.

The holes punched are bound by from/to IP address and port; it will not be

The holes punched are bound by from/to IP address and port; it will not be

possible to use a hole for another connection.

possible to use a hole for another connection.

(e.g.\& kill -9),

(e.g.\& kill -9),

changing the state of the flag will clear the entire firewall range

changing the state of the flag will clear the entire firewall range

allocated for holes.

allocated for holes.

.It Dv PKT_ALIAS_REVERSE

.It Dv PKT_ALIAS_REVERSE

This option makes

This option makes

.Nm

.Nm

.It Dv PKT_ALIAS_SKIP_GLOBAL

.It Dv PKT_ALIAS_SKIP_GLOBAL

This option is used by

This option is used by

.Pa ipfw_nat

.Pa ipfw_nat

.Fn LibAliasSetMode

.Fn LibAliasSetMode

.Sx NETWORK ADDRESS TRANSLATION

.Sx NETWORK ADDRESS TRANSLATION

in

in

.Xr ipfw 8

.Xr ipfw 8

.Ft void

.Ft void

.Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"

.Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num"

.Bd -ragged -offset indent

.Bd -ragged -offset indent

.Dv PKT_ALIAS_PUNCH_FW

.Dv PKT_ALIAS_PUNCH_FW

flag).

flag).

.Ed

.Ed

.Pp

.Pp

.Ft void

.Ft void

.Fn LibAliasIn

.Fn LibAliasIn

and

and

.Fn LibAliasOut ,

.Fn LibAliasOut ,

implementation.

implementation.

.Pp

.Pp

.Ft int

.Ft int

The packet aliasing process was successful.

The packet aliasing process was successful.

.It Dv PKT_ALIAS_IGNORED

.It Dv PKT_ALIAS_IGNORED

The packet was ignored and not de-aliased.

The packet was ignored and not de-aliased.

.Dv PKT_ALIAS_DENY_INCOMING

.Dv PKT_ALIAS_DENY_INCOMING

.Fn LibAliasSetMode ) .

.Fn LibAliasSetMode ) .

.It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT

.It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT

This is returned when a fragment cannot be resolved because the header

This is returned when a fragment cannot be resolved because the header

.Fn LibAliasRedirectPort

.Fn LibAliasRedirectPort

is called, a zero reference will track this change.

is called, a zero reference will track this change.

.Pp

.Pp

.Fa local_addr

.Fa local_addr

and

and

.Fa local_port

.Fa local_port

.Fa remote_port

.Fa remote_port

is zero, this indicates to redirect packets originating from any remote

is zero, this indicates to redirect packets originating from any remote

port number.

port number.

remote addresses can sometimes be useful for firewalling.

remote addresses can sometimes be useful for firewalling.

If two calls to

If two calls to

.Fn LibAliasRedirectPort

.Fn LibAliasRedirectPort

.Fn LibAliasRedirectAddr

.Fn LibAliasRedirectAddr

is called, a zero reference will track this change.

is called, a zero reference will track this change.

.Pp

.Pp

.Fa local_addr

.Fa local_addr

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

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

.Fn LibAliasAddServer

.Fn LibAliasAddServer

below.

below.

LSNAT operates as follows.

LSNAT operates as follows.

A client attempts to access a server by using the server virtual address.

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

The LSNAT router transparently redirects the request to one of the hosts

Multiple sessions may be initiated from the same client, and each session

Multiple sessions may be initiated from the same client, and each session

desired.

desired.

.Pp

.Pp

Currently, only the simplest selection algorithm is implemented, where a

Currently, only the simplest selection algorithm is implemented, where a

is the pointer returned by either of the redirection functions.

is the pointer returned by either of the redirection functions.

If an invalid pointer is passed to

If an invalid pointer is passed to

.Fn LibAliasRedirectDelete ,

.Fn LibAliasRedirectDelete ,

.Ed

.Ed

.Pp

.Pp

.Ft int

.Ft int

.Bd -ragged -offset indent

.Bd -ragged -offset indent

This function specifies that any IP packet with protocol number of

This function specifies that any IP packet with protocol number of

.Fa proto

.Fa proto

redirected to a specified local address.

redirected to a specified local address.

.Pp

.Pp

If

If

"struct in_addr alias_addr" "u_short src_port" "u_short dst_port" \

"struct in_addr alias_addr" "u_short src_port" "u_short dst_port" \

"int alias_param" "int link_type"

"int alias_param" "int link_type"

.Bd -ragged -offset indent

.Bd -ragged -offset indent

.Ed

.Ed

.Pp

.Pp

.Ft void

.Ft void

.Ed

.Ed

.Pp

.Pp

.Va handler_chain

.Va handler_chain

.Va ddl_chain

.Va ddl_chain

.Pp

.Pp

.Va handler_chain

.Va handler_chain

is composed of

is composed of

where:

where:

.Bl -inset

.Bl -inset

.It Va pri

.It Va pri

is better.

is better.

.It Va dir

.It Va dir

is the direction of packets: ingoing or outgoing.

is the direction of packets: ingoing or outgoing.

.It Va proto

.It Va proto

.It Va fingerprint

.It Va fingerprint

points to the fingerprint function while protohandler points

points to the fingerprint function while protohandler points

to the protocol handler function.

to the protocol handler function.

.Pp

.Pp

The

The

.Va fingerprint

.Va fingerprint

module can handle.

module can handle.

.Pp

.Pp

The

The

if it meets a module hook,

if it meets a module hook,

.Va handler_chain

.Va handler_chain

is searched to see if there is an handler that matches

is searched to see if there is an handler that matches

more than one handler is found, it starts with the module with

more than one handler is found, it starts with the module with

the lowest priority number: it calls the

the lowest priority number: it calls the

.Va fingerprint

.Va fingerprint

is called.

is called.

The

The

.Fn find_handler

.Fn find_handler

.Bl -tag -width indent

.Bl -tag -width indent

.It Fa IN

.It Fa IN

direction

direction

.Pp

.Pp

As was mentioned earlier,

As was mentioned earlier,

.Nm

.Nm

.Va dll_chain

.Va dll_chain

was introduced.

was introduced.

.Pp

.Pp

.Nm

.Nm

first unloads all the loaded modules, then reloads all the modules listed in

first unloads all the loaded modules, then reloads all the modules listed in

.Pa /etc/libalias.conf :

.Pa /etc/libalias.conf :

.Pp

.Pp

.Va dll_chain

.Va dll_chain

is composed of

is composed of

.Pa alias_dummy.[ch] )

.Pa alias_dummy.[ch] )

in

in

.Nm

.Nm

module.

module.

From

From

.Pa alias_dummy.c :

.Pa alias_dummy.c :

is the

is the

.Dq "most important thing"

.Dq "most important thing"

in a module

in a module

it in an opaque way.

it in an opaque way.

.Pp

.Pp

It must ALWAYS be present in every module, and it MUST retain

It must ALWAYS be present in every module, and it MUST retain

.Ed

.Ed

When running as KLD,

When running as KLD,

.Fn mod_handler

.Fn mod_handler

.Fn attach_handlers

.Fn attach_handlers

and

and

.Fn detach_handlers ,

.Fn detach_handlers ,