TCPVSADM(8)

NAME
tcpvsadm - Kernel TCP Virtual Server administration

SYNOPSIS
tcpvsadm -A|E -i ident [-s scheduler] [-P port]
tcpvsadm -D -i ident
tcpvsadm -F
tcpvsadm -a|e -i ident -r server-address [-w weight]
tcpvsadm -d -i ident -r server-address
tcpvsadm --add-rule -i ident -p pattern -r server-address [-m /fImatchnum/fP]
tcpvsadm --del-rule -i ident -p pattern -r server-address
tcpvsadm -L [options]
tcpvsadm -f config-file
tcpvsadm --start|stop [-i ident]
tcpvsadm -h

DESCRIPTION
Tcpvsadm is used to set up, maintain or inspect the TCP Virtual Server table inside the Linux kernel (KTCPVS). KTCPVS is a Layer-7 switching software in the Linux Virtual Server framework, and can do application-level load balancing (such as content-based scheduling) inside the Linux kernel. The reason of implementing it inside the kernel is to avoid the overhead of context switching and memory copying between user-space and kernel-space. Although the scalability of KTCPVS is lower than that of IPVS (IP Virtual Server), it is flexible, because the content of request is known before the request is redirected to real server.

  COMMANDS
tcpvsadm(8) recognises the commands described below.

-A, --add-service
    Add a TCP virtual service.

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

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

-F, --flush
    Flush the TCP virtual server table.

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

-e, --edit-server
    Edit a real server in a TCP virtual service.

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

--add-rule
    Add a content-based scheduling rule to a TCP virtual service. Currently, the rule is simple, if a request content matchs a pattern, then the request will be redirected to the specified server.

--del-rule
    Remove a content-based scheduling rule from a TCP virtual service.

-L, --list
    List the TCP virtual server table if no argument is specified. If a service ident is selected, list this service only. The exact output is affected by the other arguments given.

-f --load-configfile config-file
    Load the TCP virtual server table from the specified config-file. The original table will be flushed before loading from the config-file.

--start [-i ident]
    Start all the services in the TCP virtual server table if no argument is specified. If a service ident is selected, start this service only.

--stop [-i ident]
    Stop all the services in the TCP virtual server table if no argument is specified. If a service ident is selected, stop this service only.

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

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

-i, --ident ident
    The ident is a string of alphabetic and numeric characters, to identify the name of a TCP virtual service.

-s, --scheduler scheduling-method
    The scheduling-method is an algorithm for allocating TCP connections to real servers. The scheduling algorithms are implemented as kernel modules. Two are shipped with KTCPVS now:

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

    http - HTTP content-based scheduling: assign jobs to servers according to the specified content-based scheduling rules.

    hhttp - Hash-based HTTP scheduling: assign jobs to servers according to the specified content-based scheduling rules where regular expression matches are hashed and the virtual server is selected based on the resulting hash value.

    Note: If a scheduling module cannot be automatically loaded by modprobe(8), the module may be manually inserted into the kernel using insmod(8).

-l, --listen server-address[:port]
    Specify the ip address (and port number) that a TCP virtual service listens to. The server-address is the host address of a real server, and possibly 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.

-P, --port port
    Specify the port number that a TCP virtual service listens to.

-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. port may be ommitted, in which case the destination port on the real server will be the destination port of the request sent to the virtual service.

-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.

-p, --pattern pattern
    Pattern is a string specifying a matching pattern, and it is interpreted as an extended regular expression. The pattern ".*" or "^/.*" is used to specify the default server. When no other server pattern is matched, the default server will be used.

-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.

EXAMPLES
The following commands configure a TCP virtual service to distribute incoming requests addressed to port 80 at local address to three web servers, according the content-based scheduling rules.

tcpvsadm -A -i web -s http -P 80
tcpvsadm -a -i web -r 192.168.10.1:80
tcpvsadm -a -i web -r 192.168.10.2:80
tcpvsadm -a -i web -r 192.168.10.3:80
tcpvsadm --add-rule -i web --pattern=^/cgi-bin/ -r 192.168.10.1:80
tcpvsadm --add-rule -i web --pattern=^/images/ -r 192.168.10.2:80
tcpvsadm --add-rule -i web --pattern=.* -r 192.168.10.3:80

Alternatively, this could be achieved by "tcpvsadm -f config-file", the config file is as follows:

virtual web {
    listen = 0.0.0.0:80
    scheduler = http
    startservers = 8
    maxclients = 256
    minspareservers = 6
    maxspareservers = 18
    server = 192.168.10.3:80 1
    server = 192.168.10.2:80 1
    server = 192.168.10.1:80 1
    rule = pattern "^/cgi-bin/"  use server 192.168.10.1:80
    rule = pattern "^/images/"  use server 192.168.10.2:80
    rule = pattern ".*"  use server 192.168.10.3:80
}

NOTES

FILES
/proc/sys/net/ktcpvs/max_backlog
/proc/sys/net/ktcpvs/unload

SEE ALSO
ipvsadm(8), insmod(8), modprobe(8)

AUTHORS
Wensong Zhang <wensong@linuxvirtualserver.org>