IPVSADM(8)

NAME
ipvsadm - Linux Virtual Server administration

SYNOPSIS
ipvsadm -[A|E] -[t|u|f] service-address [-s scheduler]
[-p [timeout]] [-M netmask]
ipvsadm -D -[t|u|f] service-address
ipvsadm -C
ipvsadm -R
ipvsadm -S [-n]
ipvsadm -[a|e] -[t|u|f] service-address
-[r|R] server-address [-g|-i|-m] [-w weight]
ipvsadm -d -[t|u|f] service-address -[r|R] server-address
ipvsadm -[L|l] [-n]
ipvsadm -h

DESCRIPTION
Ipvsadm(8) is used to set up, maintain or inspect the virtual server table in the Linux kernel. Linux Virtual Server can be used to built scalable network services based on a cluster of two or more nodes. The active node of the cluster redirects service requests to a collection of server hosts that will actually perform the services. Supported features include two protocols (TCP and UDP), three packet-forwarding methods (NAT, tunneling, and direct routing), and four load balancing algorithms (round robin, weighted round robin, least-connection and weighted least-connection).

The command has two basic formats for execution:

ipvsadm COMMAND [protocol] service-address
    [scheduling-method] [persistence options]

ipvsadm command [protocol] service-address
    server-address [packet-forwarding-method]
    [weight options]

The first format manipulates a virtual service and the algorithm for assigning service requests to real servers. Optionally, a the persistent timeout and mask for the granularity of a persistent service may be specified. The second format manipulates a real servers that are associated with an existing virtual service. When specifying a real server, the packet-forwarding method and the weight of the real server, relative to other real servers for the virtual service, may be specified, otherwise defaults will be used.

  COMMANDS
ipvsadm(8) recognises the commands described below. Upper-case commands maintain virtual services. Lower-case commands maintain real servers that are associated with a virtual service.

-A, --add-service
    Add a virtual service. A service address is uniquely defined by a triplet: IP address, port number, and protocol. Alternatively, a virtual service may be defined by a firewall-mark.

-E, --edit-service
    Edit a virtual service.

-D, --delete-service
    Delete a virtual service, along with any associated real servers.

-C, --clear
    Clear the virtual server table.

-R, --restore
    Restore Linux Virtual Server rules from stdin. Each line read from stdin will be treated as the command line options to a separate invocation of ipvsadm. Lines read from stdin can optionally begin with "ipvsadm". This option is useful to avoid executing a large number or ipvsadm commands when constructing an extensive routing table.

    This option only works if ipvsadm is compiled against popt(3).

-S, --save
    Dump the Linux Virtual Server rules to stdout in a format that can be read by -R|--restore.

    This option only works if ipvsadm is compiled against popt(3).

-a, --add-server
    Add a real server to a virtual service.

-d, --delete-server
    Remove a real server from a virtual service.

-L, -l, --list
    Display the virtual server table.

-h, --help
    Display a description of the command syntax.

  PARAMETERS
The commands above accept or require zero or more of the following parameters.

-t, --tcp-service service-address
    Use TCP service. The service-address is of the form host[:port]. Host may be one of a plain IP address or a hostname. Port may be either a plain port number or the service name of port. The Port may be omitted, in which case zero will be used. A Port of zero is only valid if the service is persistent as per the -p|--persistent option, in which case it is a wild-card port, that is connections will be accepted to any port.

-u, --udp-service service-address
    Use UDP service. See the -t|--tcp-service for the description of the service-address.

-f, --fwmark-service integer
    Use a firewall-mark, an integer value greater than zero, to denote a virtual service instead of an address, port and protocol, UDP or TCP. The marking of packets with a firewall-mark is configured using the -m|--mark option to ipchains(8). It can be used to build a virtual service assoicated with the same real servers, covering multiple IP addresss, port and protocol tripplets.

-s, --scheduler scheduling-method
    scheduling-method Algorithm for allocating TCP connections and UDP datagrams to real servers. Scheduling algorithms are implemented as kernel modules. Four are shipped with the Linux Virtual Server:

    rr - Robin Robin: distribute jobs equally amongst the available real servers.

    wrr - Weighted Round Robin: assign jobs to real servers proportionally to there real servers' weight. Servers with higher weights receives new jobs first and get more jobs than servers with lower weights, servers with equal weights get an eaqual distribution of new jobs.

    lc - Least-Connection: assign more jobs to real servers with fewer acive jobs.

    wlc - Weighted Least-Connection: assign more jobs to servers with fewer jobs and relative to the real servers' weight. This is the default.

-p, --persistent [timeout]
    Specify that a virtual service is persistent. If this option is specified, multiple requests from a client are redirected to the same real server selected for the first request. Optionally, the timeout of persistent sessions may be specified given in seconds, otherwise the default of 300 seconds will be used. This option may be used in conjunction with protocols such as SSL or FTP where it is important that clients consistently connect with the same real server.

-M, --netmask netmask
    Specify the granularity with which clients are grouped for persistent virtual services. The source address of the request is masked with this netmask to direct all clients from a network to the same real server. The default is 255.255.255.255, that is, the persistence granularity is per client host. Less specific netmasks may be used to resolve problems with non-persistent cache clusters on the client side.

-r, -R, --real-server server-address
    Real server that an associated request for service may be assigned to. The server-address is the host address of a real server, and may plus port. Host can be either a plain IP address or a hostname. Port can be either a plain port number or the service name of port. In the case of the masquerading method, the host address is usually a private IP address, and the port can be different from that of the associated service. If port is not specified, the port specified in the service address will be used. With the tunneling and direct routing methods, port must be equal to that of the service address.

[packet-forwarding-method]

    -g, --gatewaying Use gatewaying (direct routing). This is the default.

    -i, --ipip Use ipip encapsulation (tunneling).

    -m, --masquerading Use masquerading (network access translation, or NAT).

    Note: Regardless of the packet-forwarding mechanism specified, real servers for addresses for which there are interfaces on the local node will be use the local forwarding method. This cannot be specified by ipvsadm, rather it set by the kernel as real servers are added or modified.

    If the server-address is specified as one of its own interfaces, packets for this server will be just passed to upper layer to handle it locally. None of the above three packet-forwarding methods is applied.

-w, --weight weight
    Weight is an integer specifying the capacity of a server relative to the others in the pool. The valid values of weight are 0 through to 65535. The default is 1. Quiescent servers are specified with a weight of zero. A quiescent server will receive no new jobs but still serve the existing jobs, for all scheduling algorithms distributed with the Linux Virtual Server. Setting a quiescent server may be useful if the server is overloaded or needs to be taken out of service for maintenance.

-n, --numeric
    Numeric output. IP addresses and port numbers will be printed in numeric format rather than as as host names and services respectively, which is the default.

EXAMPLE
The following commands configure a LVS host to distribute incoming requests addressed to port 80 on 207.175.44.110 equally to port 80 on five real servers server. The forwarding method used in this example is NAT, with each of the real servers being masqueraded by the Linux Director.

ipvsadm -A -t 207.175.44.110:80 -s rr
ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.1 -m
ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.2 -m
ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.3 -m
ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.4 -m
ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.5 -m

Alternatively, this could be achieved in a single ipvsadm command.

echo "
-A -t 207.175.44.110:80 -s rr
-a -t 207.175.44.110:80 -r 192.168.10.1 -m
-a -t 207.175.44.110:80 -r 192.168.10.2 -m
-a -t 207.175.44.110:80 -r 192.168.10.3 -m
-a -t 207.175.44.110:80 -r 192.168.10.4 -m
-a -t 207.175.44.110:80 -r 192.168.10.5 -m
" | ipvsadm -R

The default route of the real servers must be set to the LVS host and the LVS host will need to be configured to forward and masquerade packets. This can be achieved using the following command:

echo "1" > /proc/sys/net/ipv4/ip_forward
ipchains -A forward -j MASQ -s 192.168.10.0/24 -d 0.0.0.0/0

NOTES
The Linux Virtual Server implements three defense strategies against some types of denial of service attack. The LVS host creates an entry for each connection in order to keep its state, and each entry occupies 128 bytes effective memory. LVS's vulnerability to a DoS attack lies in the potential to increase the number entries as much as possible until the LVS host runs out of memory. The three defense strategies against the attack are to randomly drop some entries in the table, to drop 1/rate packets before forwarding them and to use secure tcp state transition table and short timeouts. The strategies are controlled by sysctl variables:

/proc/sys/net/ipv4/vs/drop_entry /proc/sys/net/ipv4/vs/drop_packet /proc/sys/net/ipv4/vs/secure_tcp

The valid values are from 0 to 3 with a default of 0. 0 means that this strategy is always disabled. 1 and 2 mean automatic modes - when there is no enough available memory, the strategy is enabled and the variable is automatically set to 2, otherwise the strategy is disabled and the variable is set to 1. 3 means that that the strategy is always enabled. The available memory threshold and secure tcp timeouts can be tuned using the sysctl variables:

/proc/sys/net/ipv4/vs/amemthresh /proc/sys/net/ipv4/vs/timeout_*

FILES
/proc/net/ip_masq/vs
/proc/sys/net/ipv4/vs/am_droprate
/proc/sys/net/ipv4/vs/amemthresh
/proc/sys/net/ipv4/vs/drop_entry
/proc/sys/net/ipv4/vs/drop_packet
/proc/sys/net/ipv4/vs/secure_tcp
/proc/sys/net/ipv4/vs/timeout_close
/proc/sys/net/ipv4/vs/timeout_closewait
/proc/sys/net/ipv4/vs/timeout_established
/proc/sys/net/ipv4/vs/timeout_finwait
/proc/sys/net/ipv4/vs/timeout_icmp
/proc/sys/net/ipv4/vs/timeout_lastack
/proc/sys/net/ipv4/vs/timeout_listen
/proc/sys/net/ipv4/vs/timeout_synack
/proc/sys/net/ipv4/vs/timeout_synrecv
/proc/sys/net/ipv4/vs/timeout_synsent
/proc/sys/net/ipv4/vs/timeout_timewait
/proc/sys/net/ipv4/vs/timeout_udp

AUTHOR
ipvsadm - Wensong Zhang <wensong@iinchina.net>
          Peter Kese <peter.kese@ijs.si>
man page - Mike Wangsmo <wanger@redhat.com>
           Wensong Zhang <wensong@iinchina.net>
           Horms <horms@valinux.com>