SRC_VIPA(8)SRC_VIPA(8)NAMEsrc_vipa - flexible source address selection
SYNOPSIS
src_vipa.sh program params
DESCRIPTION
src_vipa.sh starts program using params as parameters, if specified.
The program will use source address selection as described by the rules
in the configuration file. The default configuration file is
/etc/src_vipa.conf. If the environment variable SRC_VIPA_CONFIG_FILE is
defined, its content specifies the configuration file used for
src_vipa.
CONFIGURATION FILE
Please note that the layout of the configuration file has changed: the
policy was added in 2.x versions.
/etc/src_vipa.conf or, if the environment variable SRC_VIPA_CONFIG_FILE
is defined, the file specified in SRC_VIPA_CONFIG_FILE contains lines
that look like these three lines:
# comment
D1.D2.D3.D4/MASK POLICY S1.S2.S3.S4 [T1.T2.T3.T4 [...]]
.INADDR_ANY P1-P2 POLICY S1.S2.S3.S4 [T1.T2.T3.T4 [...]]
.INADDR_ANY P POLICY S1.S2.S3.S4 [T1.T2.T3.T4 [...]]
# Lines starting with # are ignored
D1.D2.D3.D4/MASK
(MASK is the number of set bits in the subnet mask) specifies a
range of destination addresses. As soon as a socket is opened
and connected to these destination addresses and the application
does not do an explicit bind to a source address, src_vipa does
a bind to all the addresses specified as S1.S2.S3.S4
[T1.T2.T3.T4 [...]], using the specified POLICY to distribute
the used source addresses. See POLICIES below for available
load distribution policies. Instead of IP addresses in dotted
notation, hostnames can be used which will be resolved using
DNS.
.INADDR_ANY P1-P2 POLICY S1.S2.S3.S4 [T1.T2.T3.T4 [...]]
and
.INADDR_ANY P POLICY S1.S2.S3.S4 [T1.T2.T3.T4 [...]]
will cause bind calls with INADDR_ANY as local address to be
intercepted, if the port the socket is bound on is between P1
and P2 (including P1 and P2). In that case, INADDR_ANY will be
replaced by one of the addresses S1.S2.S3.S4i [T1.T2.T3.T4
[...]] (which can be 0.0.0.0). POLICY is used to select, which
one source address will be used. .INADDR_ANY statements will be
read and evaluated in order of appearance. That means, two
.INADDR_ANY statements can be used to make bind be intercepted
for every port except for a certain range. This is useful e. g.
for rlogin which uses bind to bind to a local port but uses
INADDR_ANY as source address to use automatic source address
selection. See POLICIES below for available load distribution
policies. Please note that the maximum port number is currently
65535.
The default behaviour for all ports is, that the kind of bind
calls will not be modified.
Priorities of the two types of rules:
If an application does first a bind call with INADDR_ANY and an
.INADDR_ANY rule is defined with a matching port range, the
.INADDR_ANY rule is used. In this case any D1.D2.D3.D4/MASK
rules are ignored. If no matching .INADDR_ANY rule exists or the
application does not call bind at all, The D1.D2.D3.D4/MASK rule
is used, if the target address of the progam's connect call
matches.
POLICIES
Several source addresses can be specified for one destination. The
specified policy will be used to select the source address out of all
the specified ones, when src_vipa replaces the source address of a
socket. The rationale behind several source addresses lies in the
inability of some OS kernels to do load balancing of several connec‐
tions with the same source and destination address over several inter‐
faces. E.g. in Linux 2.4, a routing entry in the routing cache table is
created that always leads connections over the same interface based on
IP but not on port basis. Several VIPAs can then be used to create
several routing cache entries for the same destination, but with a dif‐
ferent VIPA as source. Luck will assign different interfaces to these
entries. This is a way to do load balancing between multi-linked
servers on a VIPA basis, when bonding is not an option or desired.
onevipa
Only and always the first address of all specified source
address will be used as source address.
random The source address used by src_vipa is selected randomly from
all specified source addresses.
lrr stands for local round robin; the source address used by
src_vipa is selected in a round robin fashion among all source
addresses specified. The round robin takes place on a per-invo‐
cation base -- each process will get its source addresses round
robin independently from other processes.
rr:ABC stands for round robin and implements a global round robin over
all src_vipa instances sharing the same configuration file. All
src_vipa'ed processes share an IPC shared memory segment to ful‐
fil a global round robin algorithm. This shared memory segment
is destroyed when the last running src_vipa goes away. However,
if this process does not terminate gracefully (e.g. is killed),
the shared memory segment (size: 4 bytes) can stay in memory
until it is removed by ipcrm. The tool ipcs can be used to dis‐
play all IPC ressources and get the key or id used for ipcrm.
ABC are unix permissions in octal writing (e.g. 700) that are
used to create the shared memory segment. This permision mask
should be as restrictive as possible; a process having access to
this mask could in the worst case create an imbalance of the
round robin distribution.
lc a policy that attempts to balance the number of connections per
source address. It always associates the socket with the VIPA
that is least in use.
If the policy cannot be parsed correctly, the policy will be set
to round robin per default
MIGRATION FROM EARLIER VERSIONS
Please note that the layout of the configuration file has changed: a
policy is now required. If you migrate from earlier versions of
src_vipa and don't need multiple VIPAs, the use of the onevipa policy,
followed by your VIPA is the recommended change. Check your syslog
(usually in /var/log/messages) for problems the first times you use a
new version.
ENVIRONMENT
SRC_VIPA_CONFIG_FILE specifies an alternate configuration file. If not
set, /etc/src_vipa.conf will be used.
RESTRICTIONS
LD_PRELOAD security prevents setuid executables to be executed under
src_vipa; that kind of programs can only be executed when the real UID
is 0. Please note, that the ping utility is usually installed with
setuid permissions.
The maximum number of VIPAs per destination is defined as 8.
Only applications are supported, which call explicitly the libc call
bind() with INADDR_ANY or connect() without a preceding bind(). E.g.
programs using the rcmd() function are not supported.
FURTHER NOTES
When using the zebra routing daemon and multiple VIPAs, make sure, that
zebra is configured using --enable-multipath=0 (or the number of multi‐
ple paths you need) and --enable-netlink.
FILES
/etc/src_vipa.conf is the default configuration file for src_vipa.
SEE ALSO
The iproute2 package (command line utility ip) is able to modify source
address selection on a route basis in the kernel FIB.
COPYRIGHT
Copyright (C) 2001-2005 IBM Corporation
Published under the terms and conditions of the CPL (common public
license).
See the file LICENSE provided with the package for a copy of the CPL.
AUTHOR
This man page was written by Utz Bacher <utz.bacher@de.ibm.com>
4th Berkeley Distribution Mo Feb 07 2005 SRC_VIPA(8)
