Provided by: ipvsadm_1.25.clean-1ubuntu5_amd64 bug

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 server-address
               [-g|i|m] [-w weight] [-x upper] [-y lower]
       ipvsadm -d -t|u|f service-address -r server-address
       ipvsadm -L|l [options]
       ipvsadm -Z [-t|u|f service-address]
       ipvsadm --set tcp tcpfin udp
       ipvsadm --start-daemon state [--mcast-interface interface]
               [--syncid syncid]
       ipvsadm --stop-daemon state
       ipvsadm -h

DESCRIPTION

       Ipvsadm(8)  is  used  to set up, maintain or inspect the virtual server table in the Linux
       kernel. The Linux Virtual Server can be used to build 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 eight load balancing algorithms (round robin, weighted  round  robin,
       least-connection,  weighted  least-connection,  locality-based least-connection, locality-
       based least-connection with replication, destination-hashing, and source-hashing).

       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  persistent  timeout and network mask for the
       granularity of a persistent service may be specified. The second format manipulates a real
       server that is 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.

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

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

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

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

       -L, -l, --list
              List the virtual server table if no argument is specified. If a service-address  is
              selected,  list  this  service only. If the -c option is selected, then display the
              connection table. The exact output is affected by the other arguments given.

       -Z, --zero
              Zero the packet, byte and rate counters in a service or all services.

       --set tcp tcpfin udp
              Change the timeout values used for IPVS connections. This command  always  takes  3
              parameters,   representing  the  timeout  values (in seconds) for TCP sessions, TCP
              sessions after receiving a  FIN packet, and  UDP  packets, respectively.  A timeout
              value  0  means  that  the  current  timeout value of the  corresponding  entry  is
              preserved.

       --start-daemon state
              Start the connection synchronization daemon. The state  is  to  indicate  that  the
              daemon  is  started  as  master or backup. The connection synchronization daemon is
              implemented inside the Linux kernel. The master daemon running at the primary  load
              balancer  multicasts  changes  of  connections  periodically, and the backup daemon
              running at the  backup  load  balancers  receives  multicast  message  and  creates
              corresponding  connections. Then, in case the primary load balancer fails, a backup
              load balancer will takeover, and it has state of almost all  connections,  so  that
              almost all established connections can continue to access the service.

       The sync daemon currently only supports IPv4 connections.

       --stop-daemon
              Stop the connection synchronization daemon.

       -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  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
              iptables(8). It can be used to build a virtual service  assoicated  with  the  same
              real  servers,  covering  multiple IP address, port and protocol tripplets. If IPv6
              addresses are used, the -6 option must be used.

              Using firewall-mark virtual services  provides  a  convenient  method  of  grouping
              together different IP addresses, ports and protocols into a single virtual service.
              This is useful for both simplifying configuration if  a  large  number  of  virtual
              services  are  required  and  grouping  persistence  across what would otherwise be
              multiple virtual services.

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

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

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

              lc - Least-Connection: assigns more jobs to real servers with fewer active jobs.

              wlc  -  Weighted Least-Connection: assigns more jobs to servers with fewer jobs and
              relative to the real servers' weight (Ci/Wi). This is the default.

              lblc - Locality-Based Least-Connection: assigns  jobs  destined  for  the  same  IP
              address to the same server if the server is not overloaded and available; otherwise
              assign jobs to servers with fewer jobs, and keep it for future assignment.

              lblcr - Locality-Based Least-Connection with Replication: assigns jobs destined for
              the  same  IP  address  to  the  least-connection node in the server set for the IP
              address. If all the node in the server set are over loaded, it picks up a node with
              fewer  jobs  in  the  cluster  and  adds it in the sever set for the target. If the
              server set has not been modified for the specified time, the most  loaded  node  is
              removed from the server set, in order to avoid high degree of replication.

              dh  -  Destination Hashing: assigns jobs to servers through looking up a statically
              assigned hash table by their destination IP addresses.

              sh - Source Hashing: assigns jobs  to  servers  through  looking  up  a  statically
              assigned hash table by their source IP addresses.

              sed  -  Shortest  Expected  Delay:  assigns  an incoming job to the server with the
              shortest expected delay. The expected delay that the job will experience is  (Ci  +
              1)  /  Ui  if  sent to the ith server, in which Ci is the number of jobs on the the
              ith server and Ui is the fixed service rate (weight) of the ith server.

              nq - Never Queue: assigns an incoming job to an idle server if there is, instead of
              waiting  for  a  fast  one;  if  all  the  servers are busy, it adopts the Shortest
              Expected Delay policy to assign the job.

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

              Note:  If  a  virtual service is to handle FTP connections then persistence must be
              set for the virtual service  if  Direct  Routing  or  Tunnelling  is  used  as  the
              forwarding  mechanism.  If  Masquerading is used in conjunction with an FTP service
              than persistence is not necessary, but the ip_vs_ftp kernel module  must  be  used.
              This module may be manually inserted into the kernel using insmod(8).

       -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.
              IPv6 netmasks should be specified as a  prefix  length  between  1  and  128.   The
              default prefix length is 128.

       -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  an RFC 1918 private IP address, and the port can be different from that of
              the associated service. With the tunneling and direct routing methods, port must be
              equal  to  that of the service address. For normal services, the port specified  in
              the service address will be used if port is not  specified.  For  fwmark  services,
              port may be omitted, in which case  the destination port on the real server will be
              the destination port of the request sent to the virtual service.

       [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, then packets for the servers will be passed to  upper  layer  on
              the local node. This cannot be specified by ipvsadm, rather it set by the kernel as
              real servers are added or modified.

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

       -x, --u-threshold uthreshold
              uthreshold is an integer specifying the upper connection threshold of a server. The
              valid  values  of  uthreshold are 0 through to 65535. The default is 0, which means
              the upper connection threshold is not set. If uthreshold is set with other  values,
              no  new  connections  will be sent to the server when the number of its connections
              exceeds its upper connection threshold.

       -y, --l-threshold lthreshold
              lthreshold is an integer specifying the lower connection threshold of a server. The
              valid  values  of  lthreshold are 0 through to 65535. The default is 0, which means
              the lower connection threshold is not set. If lthreshold is set with other  values,
              the  server  will  receive new connections when the number of its connections drops
              below its lower connection threshold. If lthreshold is not set  but  uthreshold  is
              set,  the  server  will  receive new connections when the number of its connections
              drops below three forth of its upper connection threshold.

       --mcast-interface interface
              Specify the  multicast  interface  that  the  sync  master  daemon  sends  outgoing
              multicasts through, or the sync backup daemon listens to for multicasts.

       --syncid syncid
              Specify  the  syncid  that  the sync master daemon fills in the SyncID header while
              sending multicast messages, or the sync backup daemon uses to filter out  multicast
              messages  not  matched  with  the  SyncID  value.  The valid values of syncid are 0
              through to 255. The default is 0, which means no filtering at all.

       -c, --connection
              Connection output. The list  command  with  this  option  will  list  current  IPVS
              connections.

       --timeout
              Timeout  output. The list command with this option will display the  timeout values
              (in seconds) for TCP sessions, TCP sessions after receiving a FIN packet,  and  UDP
              packets.

       --daemon
              Daemon  information  output.  The  list  command  with this option will display the
              daemon status and its multicast interface.

       --stats
              Output of statistics information. The list command with this  option  will  display
              the statistics information of services and their servers.

       --rate Output of rate information. The list command with this option will display the rate
              information  (such  as  connections/second,  bytes/second  and  packets/second)  of
              services and their servers.

       --thresholds
              Output  of  thresholds  information. The list command with this option will display
              the upper/lower connection threshold information of each server in service listing.

       --persistent-conn
              Output of persistent connection information. The list command with this option will
              display  the  persistent  connection  counter information of each server in service
              listing. The persistent connection is used to forward the actual  connections  from
              the same client/network to the same server.

       --sort Sort the list of virtual services and real servers. The virtual service entries are
              sorted in ascending order by <protocol, address, port>. The real server entries are
              sorted in ascending order by <address, port>. (default)

       --nosort
              Do not sort the list of virtual services and real servers.

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

       --exact
              Expand numbers.  Display the exact value of the packet and  byte counters,  instead
              of  only  the rounded number in K's (multiples of 1000) M's (multiples of 1000K) or
              G's (multiples  of 1000M).  This option is only relevant for the -L command.

       -6     Use with -f to signify fwmark rule uses IPv6 addresses.

EXAMPLE 1 - Simple Virtual Service

       The following  commands  configure  a  Linux  Director  to  distribute  incoming  requests
       addressed  to  port  80  on  207.175.44.110  equally  to port 80 on five real servers. 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:80 -m
       ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.2:80 -m
       ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.3:80 -m
       ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.4:80 -m
       ipvsadm -a -t 207.175.44.110:80 -r 192.168.10.5:80 -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:80 -m
       -a -t 207.175.44.110:80 -r 192.168.10.2:80 -m
       -a -t 207.175.44.110:80 -r 192.168.10.3:80 -m
       -a -t 207.175.44.110:80 -r 192.168.10.4:80 -m
       -a -t 207.175.44.110:80 -r 192.168.10.5:80 -m
       " | ipvsadm -R

       As  masquerading is used as the forwarding mechanism in this example, the default route of
       the real servers must be set to the linux director, which will need to  be  configured  to
       forward and masquerade packets. This can be achieved using the following commands:

       echo "1" > /proc/sys/net/ipv4/ip_forward

EXAMPLE 2 - Firewall-Mark Virtual Service

       The  following  commands  configure  a  Linux  Director  to  distribute  incoming requests
       addressed to any port on 207.175.44.110 or 207.175.44.111  equally  to  the  corresponding
       port on five real servers. As per the previous example, the forwarding method used in this
       example is NAT, with each of the real servers being masqueraded by the Linux Director.

       ipvsadm -A -f 1  -s rr
       ipvsadm -a -f 1 -r 192.168.10.1:0 -m
       ipvsadm -a -f 1 -r 192.168.10.2:0 -m
       ipvsadm -a -f 1 -r 192.168.10.3:0 -m
       ipvsadm -a -f 1 -r 192.168.10.4:0 -m
       ipvsadm -a -f 1 -r 192.168.10.5:0 -m

       As masquerading is used as the forwarding mechanism in this example, the default route  of
       the  real  servers  must be set to the linux director, which will need to be configured to
       forward and masquerade packets. The real server should also be configured to mark incoming
       packets  addressed to any port on 207.175.44.110 and  207.175.44.111 with firewall-mark 1.
       If FTP traffic is to be handled by this virtual service, then the ip_vs_ftp kernel  module
       needs  to  be  inserted  into  the  kernel.   These  operations  can be achieved using the
       following commands:

       echo "1" > /proc/sys/net/ipv4/ip_forward
       modprobe ip_tables
       iptables  -A PREROUTING -t mangle -d 207.175.44.110/31 -j MARK --set-mark 1
       modprobe ip_vs_ftp

IPv6

       IPv6 addresses should be surrounded by square brackets ([ and ]).

       ipvsadm -A -t [2001:db8::80]:80 -s rr
       ipvsadm -a -t [2001:db8::80]:80 -r [2001:db8::a0a0]:80 -m

       fwmark IPv6 services require the -6 option.

NOTES

       The Linux Virtual Server implements three defense strategies against some types of  denial
       of service (DoS) attacks. The Linux Director 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 linux director runs out of memory. The  three  defense  strategies  against  the
       attack are: Randomly drop some entries in the table. Drop 1/rate packets before forwarding
       them. And use secure tcp state transition table and short  timeouts.  The  strategies  are
       controlled by sysctl variables and corresponding entries in the /proc filesystem:

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

       Valid values for each variable are 0 through to 3. The default value is 0, which  disables
       the  respective  defense  strategy.  1 and 2 are automatic modes - when there is no enough
       available  memory,  the  respective  strategy  will  be  enabled  and  the   variable   is
       automatically set to 2, otherwise the strategy is disabled and the variable is set to 1. A
       value of 3 denotes that the respective strategy is always enabled.  The  available  memory
       threshold   and  secure  TCP  timeouts  can  be  tuned  using  the  sysctl  variables  and
       corresponding entries in the /proc filesystem:

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

FILES

       /proc/net/ip_vs
       /proc/net/ip_vs_app
       /proc/net/ip_vs_conn
       /proc/net/ip_vs_stats
       /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

SEE ALSO

       The LVS web site (http://www.linuxvirtualserver.org/) for more documentation about LVS.

       ipvsadm-save(8), ipvsadm-restore(8), iptables(8),
       insmod(8), modprobe(8)

AUTHORS

       ipvsadm - Wensong Zhang <wensong@linuxvirtualserver.org>
              Peter Kese <peter.kese@ijs.si>
       man page - Mike Wangsmo <wanger@redhat.com>
               Wensong Zhang <wensong@linuxvirtualserver.org>
               Horms <horms@verge.net.au>