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
ADDR_DEST/MASK POLICY ADDR_SRC1 [ADDR_SRC2 [...]]
.INADDR_ANY P1-P2 POLICY ADDR_SRC1 [ADDR_SRC2 [...]]
.INADDR_ANY P POLICY ADDR_SRC1 [ADDR_SRC2 [...]]

#

Lines starting with # are ignored

ADDR_DEST, ADDR_SRC1 [ADDR_SRC2 [...]]

addresses IPv4 or IPv6.

ADDR_DEST/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 ADDR_SRC1 [ADDR_SRC2 [...]], 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 ADDR_SRC1 [ADDR_SRC2 [...]]

and

.INADDR_ANY P POLICY ADDR_SRC1 [ADDR_SRC2 [...]]

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 ADDR_SRC1 [ADDR_SRC2 [...]] (which can be 0.0.0.0 or ::). 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.

Note, src_vipa support only IPv4 or only IPv6 sessions. Joint usage of IPv4 and IPv6 addresses within a single rule in the config file is impermissible. src_vipa prefers IPv4-entry than IPv6_entry in this case. It helps to keep over old config useable.

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 ADDR_DEST/MASK rules are ignored. If no matching .INADDR_ANY rule exists or the application does not call bind at all. The ADDR_DEST/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 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.

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 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 IBM Corp. 2001, 2013

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>