NAME

lvs-kiss.conf - Global configuration for lvs-kiss.

DESCRIPTION

lvs-kiss has a syntax which very much resembles the Apache configuration files. The Virtual server and the working nodes (RealServers) are arranged in hierarchy which should be quite intuitive.

There are virtualservers and realservers. A virtualserver is a virtual service which is load-balanced on servereal realservers. You should create virtualservers and populate these with realservers.

OPTIONS

OPTIONS FOR THE VIRTUALSERVERS

ServiceType: Can be ``tcp'' og ``udp''. FWmark is as of now not supported.
Persistance: Parameter is 0 (disable, which is default) or a number of seconds. The number tells lvs-kiss how long a connection should be remembered. Se the ipvsadm manpage for description of how persistance work.
Scheduler: lvs supports different schedulers. The recommended (my recommendation) ones for load-balancing are wrr, wlc or lblc. Se the ipvsadm manpage for description of the different schedulers.
DynamicScheduler: Boolean value. If this is set, lvs-kiss will try to do dynamic load-balancing. If dynamic load-balancing is used, lvs-kiss collects information about the workload of the different worker-nodes (RealServers) and uses this as a key for distributing incoming connections.; See the LoadMeasure and LoadCommand entries for more information.
QueueSize: Integer value, values between 1 and 8 make sense. When lvs-kiss is collecting values for dynamic load-balancing these are stored in a queue. The use of a queue prevents oscillation by adding a certain inertia to the load-balancing. The longer the queue, the more inert the lvs-kiss will be. Most users can say ``2'' here.
Fuzz: Picture the situation where you have to very fast web-servers. You use the Time LoadMeasure to acquire the load of the servers. One server responds in 0.01s and the other responds in 0.08s. Still, almost none of these have much load. The result would be approximately an 1:8 ration on incoming connections. Since none of these servers actually have any load we still want load to be distributed evenly between the RealServers. The solution is adding a bit of fuzz to all measurements. A value of 0.15 would add be appropriate in this example. A longer queue can also be applied.
RebalanceInterval: Integer value. Sets the Re-balancing interval locally for this VIP. This implies that load will only be measured every N * <interval> seconds. So, if you check that your web servers are alive every 10 seconds, but you don't feel it is necessary the check the load and recalculate the weights every 10 seconds you can set the RebalanceInterval to, say, 6, and this recalculation will only be performed once every 60 seconds.

OPTIONS FOR THE REALSERVERS

PacketForwardingMethod: How to forward the packets to the RealServer. Valid values are gatewaying, ipip or masquerading. See the ipvsadm manpage for details.
Test: The test which tells lvs-kiss whether the RealServer is working or not. If the return value is 0 the RealServer is considered up - any other value - its considered down.; If you use dynamic load-balancing without setting the LoadCommand, the test is timed and the time is used as a key when distributing incoming connections.
LoadCommand: lvs-kiss will run this command in order to acquire the load of the RealServer if lvs-kiss is set up to use dynamic load-balancing. If the loadcommand is not set the time of the RealServer-Test will be used to rebalance the RealServers.; Prefix the command with the type of execution which is to be done. ``perl:'' for perl-test and ``sh:'' for shell commands.; For mail-exchanges, I have used the LRRD client to aqiure the size of the mail-queue remote. LRRD spits out the size if you do a; ``(echo 'fetch exim_mailqueue';echo .)| nc mail-exchange 4949''; When set up this way lvs-kiss will direct most of the incoming connections to the mail-exchanges with the least queue.
RXFilter: When LoadCommand is run its output is filtered through a regular expression. This regular expression extracts the first number from the output and this is returned to lvs-kiss. If you for some reason need to use the third number from the output from wc to help balance a cluster - set RXFilter to ``\d+\s\d+\s+(\d+)'' (without the quotes). lvs-kiss applies the regular expression and the uses $1 as a key. Please see ``man perlre'' for information how to write Perl regular expressions.
LoadFactor: If set, LoadFactor will multiply the output of LoadCommand or the time spent executing the test. The only time when you need this is when some of the RealServers should not work as hard as the other. You don't need to set this option if you have servers of different speeds - the dynamic loadbalancing will detect this.
RunOnFailure: This shell-command is run whenever lvs-kiss thinks the RealServer has gone away.
RunOnRecovery: Same same - but different. :)
Inactive: If set to true the Realserver is considered inactive and is generally ignored. It can be enables runtime with ``lvs-kiss-control enable''.

EXAMPLES

MINIMAL CONFIGURATION

This configuration sets up a virtal service, web.foo.com:80, which is loadbalanced between two realservers, web1 and web2.

<VirtualServer web.foo.com:80> ServiceType tcp Scheduler wrr DynamicScheduler 1

 <RealServer web1.foo.com:80>
   Test wget --timeout=10 http://web1.foo.com/ping.pl
 </RealServer>
 <RealServer web2.foo.com:80>
   Test wget --timeout=10 http://web2.foo.com/ping.pl
 </RealServer>

</VirtualServer>

A BIT MORE COMPLEX CONFIGURATION

<VirtualServer mx.foo.com:25> ServiceType tcp

  Scheduler           wlc

  DynamicScheduler    1

  # The measurements are put in a queue in order in order to reduce
  # the effect of a single inaccurate measurements. The average is used
  # to calculate weight.

  # The longer the queue the less dynamic will the re-balancing be.
  # However; if the queue is short - the re-balancing will be very 
  # labile and there will be a risk of oscillation.

  QueueSize 4

  # if you use time as a key for re-balancing then consider the
  # situation where one server responds in 0.01 seconds and the other
  # responds in 0.02. If you still want to distribute evenly between
  # there add some fuzz, e.g. 0.1. The response-times will then be 0.01 +
  # 0.1 and 0.02 + 0.1. 
  # This will give you a even distribution unless one of the server
  # actually slows down a bit

  Fuzz           0.05

  # Here are the RIPs, the realservers, the working class.

  <RealServer smtp-worker1.foo.com:25>
    PacketForwardingMethod  gatewaying

    # here we use Netsaint plugins.

    Test           /usr/lib/netsaint/plugins/check_smtp -t 10 -H smtp-worker1.foo.com
    LoadCommand    sh:ruptime|grep -e ^smtp-worker1
    LoadRX         load\s+(\d+\.\d+)

    RunOnFailure   "echo smtp-worker1 has failed | mail admin@localhost"
    RunOnRecovery  "echo smtp-worker1 is back online | mail admin@localhost"

  </RealServer>

  <RealServer smtp-worker2.foo.com:25>
    PacketForwardingMethod gatewaying

    Test /usr/lib/netsaint/plugins/check_smtp -t 10 -H smtp-worker1.foo.com
    LoadCommand    sh:ruptime|grep -e ^smtp-worker1
    LoadRX         load\s+(\d+\.\d+)

    Test           /usr/lib/netsaint/plugins/check_smtp -t 10 -H  smtp-worker2.foo.com

    LoadCommand    sh:ruptime|grep -e ^smtp-worker2
    LoadRX         load\s+(\d+\.\d+)

    RunOnFailure   "echo smtp-worker2 has failed | mail admin@localhost"
    RunOnRecovery  "echo smtp-worker2 is back online | mail admin@localhost"

  </RealServer>

</VirtualServer>

AUTHOR

Per Andreas Buer <perbu (at) linpro.no>

REPORTING BUGS

Report bugs to the author.

COPYRIGHT

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.