Provided by: ipvsadm_1.28-3_amd64 bug

NAME

       ipvsadm - Linux Virtual Server administration

SYNOPSIS

       ipvsadm -A|E virtual-service [-s scheduler]
               [-p [timeout]] [-M netmask] [-b sched-flags]
       ipvsadm -D virtual-service
       ipvsadm -C
       ipvsadm -R
       ipvsadm -S [-n]
       ipvsadm -a|e virtual-service -r server-address
               [-g|i|m] [-w weight] [-x upper] [-y lower]
       ipvsadm -d virtual-service -r server-address
       ipvsadm -L|l [virtual-service] [options]
       ipvsadm -Z [virtual-service]
       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  three  protocols  (TCP,  UDP  and  SCTP),  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 virtual-service
               [scheduling-method] [persistence options]

       ipvsadm command virtual-service
               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.

   virtual-service
       Specifies the virtual service based on protocol/addr/port or firewall mark.

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

       --sctp-service service-address
              Use SCTP 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  associated  with  the  same
              real  servers,  covering  multiple  IP address, port and protocol triplets. 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.

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

       -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 - Round 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.  This scheduler has two flags:
              sh-fallback, which enables fallback to a different server if  the  selected  server
              was  unavailable,  and  sh-port,  which  adds  the  source  port number to the hash
              computation.

              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.

       -b, --sched-flags sched-flags
              Set scheduler flags for this virtual server.  sched-flags is a comma-separated list
              of flags.  See the scheduler descriptions for valid scheduler flags.

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

              The  list  command  with  the  -c, --connection option and this option will include
              persistence engine data, if any is present, when listing connections.

       --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, --ipv6
              Use with -f to signify fwmark rule uses IPv6 addresses.

       -o, --ops
              One-packet  scheduling.  Used in conjunction with a UDP virtual service or a fwmark
              virtual service that handles only UDP packets.  All connections  are  created  such
              that they only schedule one packet.

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>