SRC_VIPA(8)

NAME
src_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 nubmer 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. The default behaviour for all ports is, that the kind of bind calls will not be modified.

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 connections with the same source and destination address over several interfaces. 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 different 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-invocation 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 fulfil 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 display 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.

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 multiple 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 2001,2003 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>