Provided by: ipvsadm_1.28-3_i386 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>