Configuration

Services configuration

XML configuration file used by surealived is one of its arguments.
Thats why it can be taken from any place. To keep things simple let's assume, that it's /etc/surealived/services.xml.

 

Menu:

Generic services configuration:

Abstract Services configuration file has syntax like:

<surealived>
  <virtual ...>
     <tester ... />
     <real ... />
     <real ... /
     ...
 </virtual>
 
 <virtual ...>
     <tester ... />
     <real ... />
     ...
 </virtual
</surealived>
Tag <virtual> attributes:
  • name="string" [mandatory] (max 31 chars, range [a-zA-Z0-9_] is allowed),
  • addr="ip" [mandatory if attribute fwmark is not set, if fwmark is set "0.0.0.0" will be used],
  • port="int16" [0<=port<=65535, mandatory if fwmark is not set, otherwise "0"],
  • proto="tcp|udp|fwmark" [mandatory],
  • sched="string" [mandatory] (such ipvs scheduler will be used),
  • rt="dr|masq|tun" [mandatory], IPVS routing type,
  • fwmark="int" [optional, if > 0 proto="fwmark" should be set],
  • pers="int" [optional], for persistent connections - this is timeout value].

Tag <tester> attributes:

  • loopdelay="int" [optional, default 3] - defines delay in seconds between next testing loop for this virtual,
  • timeout="int" [optional, default 5] - each real server must respond in this time],
  • retries2ok="int" [optional, default 1] - how many tests must succeed to treat real as online,
  • retries2fail="int" [optional, default 1] - how many tests must fail to treat real as offline,
  • remove_on_fail="0|1" [optional, default 0 (false)] - if true and real is offline remove it from IPVS,
  • debugcomm="0|1" [optional, default 0 (false)] - enable dumping communication details for reals,
  • logmicro="0|1" [optional, default 0 (false)] - do use microseconds resolution while saving the statistics,
  • proto="string" [mandatory] - which module is used as tester module,
  • testport="int" [mandatory] - which port is tested (can be different than real port),
  • SSL="On|Off" [optional, default Off] - use SSL or not.

Tag <real> attributes:

  • name="string" [mandatory] (max 31 chars, range [a-zA-Z0-9_] is allowed),
  • addr="ip" [mandatory] - real IP address,
  • port="int16" [mandatory] - real port number in IPVS,
  • weight="int" [mandatory] - real weight in IPVS,
  • uthresh="int" [optional, default 0 (no limit)] - upper connection limit to the real in IPVS,
  • lthresh="int" [optional, default 0 (no limit)] - lower connection limit to the real in IPVS,
  • testport="int16" [optional] - overrides tester "testport" attribute for the real,
  • rt="string" [optional] - overrides tester "rt" attribute for the real.

 

HTTP Tester

If we want to use HTTP tester to check specific real we have to set proto="http" in the tester tag and attributes:

  • url="string" [mandatory, max 4095 chars] - requested object,
  • host="string" [mandatory, max 255 znak√≥w] - defines "Host" header,
  • retcode="string" [optional, default "200"] - response code we expect,
  • naive="True|False" [optional, default "False" - do we need to fetch whole object or response code is good enough to decide whether test was successful.

Example XML config file:

<surealived>
 <virtual name="onet" addr="192.168.0.1" port="80" proto="tcp" sched="wrr" rt="dr">
   <tester loopdelay="1" timeout="2" retries2fail="1" retries2ok="1"
           proto="http" testport="80" url="/" host="www.onet.pl"/>
   <real name="sg" addr="213.180.146.27" port="80" weight="10"/>
 </virtual>
</surealived>

 

TCP Tester

The simplest tester, it checks only TCP port availibility. Requires proto="tcp" in the tester tag. It doesn't use other attributes.

Example XML config file:

<surealived>
 <virtual name="onet" addr="192.168.0.1" port="22" proto="tcp" sched="wrr" rt="dr">
   <tester loopdelay="1" timeout="2" retries2fail="1" retries2ok="1"
           proto="tcp" testport="22" />
   <real name="sg" addr="213.180.146.27" port="22" weight="10"/>
 </virtual>

</surealived>

 

DNS Tester

Tester which checks SOA for specified domain. Requires proto="dns" in the tester tag. It uses only one attribute:

  • request="string" [mandatory, max 255 chars] - domain for which SOA request will be sent.

Example XML config file:

<surealived>
 <virtual name="onetdns1" addr="192.168.0.1" port="53" proto="udp" sched="wrr" rt="dr">
  <tester loopdelay="1" timeout="2" retries2fail="1" retries2ok="1"
          proto="dns" testport="53" request="onet.pl" logmicro="1"/>

  <real name="dns1" addr="213.180.128.240" port="53" weight="10"/>
  <real name="dns2" addr="217.97.201.240" port="53" weight="11"/>
 </virtual>
</surealived>

EXEC Tester

Tester which executes external program to perform test. Requires proto="exec" in the tester tag. Uses additional attributes: 

  • exec="string" [mandatory, max MAXPATHLEN-1 chars (1023 in includes)] - path to external program,
  • params="string" [optional, max 1023 chars] - additional space-separated arguments.

When external tester program is called, argument list is created as:

  • arg0 - real IP address,
  • arg1 - real port (testport),
  • arg2 - params[0],
  • arg. - params[...],
  • argn - params[n].

Of course if there is no params attribute an external program will be executed only with first two arguments.

Return code == 0 means, that test was successful. Any other response is treated as test fail.

Example XML config file:

<surealived>
 <virtual name="onetexec" proto="tcp"
          addr="192.168.0.1" port="80" sched="wrr" rt="dr">
  <tester loopdelay="1" timeout="5" retries2fail="1" retries2ok="1" testport="80"
          proto="exec" exec="/usr/lib/surealived/scripts/testexec.pl"
          params="www.onet.pl /0" />

  <real name="sg" addr="213.180.146.27" port="80" weight="10" rt="dr"/>
 </virtual>
</surealived>

LUA Tester

Tester which switch to the LUA script when event on a socket binded to this tester occured. Requires proto="lua" in the tester tag. Uses additional attributes: 

  • script="string" [mandatory, max MAXPATHLEN-1 chars (1023 in includes)] - path to the lua script,
  • params="string" [optional, max 1023 chars] - additional arguments (lua script should to parse it).

When you're using lua script you need to realize the connection establishing and reading / writing to the socket is managed by surealived. Lua script needs to tell surealived what action it want to perform. Possible actions are:

  • "rav", bytes, "" - read up to bytes from the socket. You need to return also empty string due to communication between surealived (C) and Lua require it - vector which contains <"ACTION", SIZE, "BUFFER"> is returned,
  • "r", bytes, "" - read exactly bytes from the socket,
  • "w", bytes, buffer - write bytes length buffer,
  • "eok", 0, "" - test succeeded,
  • "efail", 0, "" - test failed.

Your lua script has to be "state" machine. Before test, prepare() function is called, which gives you possibility to parse params. When test starts and event occurs on the socket, surealived will call the process_event(txt) function. When you're requesting to read data from the socket ("rav" or "r" request), txt will contain data read from the socket, in the other cases its content is uknown. Be careful - if your script will hang the whole surealived will hang because code execution point won't return to it. 

See example files: sunsite-lua.xml and sunsite.lua how can you implement simple ftp tester.

Example XML config file:

<surealived>
 <virtual name="sunsiteftp" addr="192.168.0.1" port="21" proto="tcp" sched="wrr" rt="dr">
   <tester loopdelay="1" timeout="5" retries2fail="1" retries2ok="1"
           proto="lua" testport="21"
           script="/usr/lib/surealived/scripts/sunsite.lua"
           params="username=anonymous; password=test@"
           debugcomm="1"
         />
   <real name="ftp1" addr="193.219.28.2" port="21" weight="10"/>
 </virtual
</surealived>

NO-TEST Pseudotester

Pseudotester which always treats real servers as online. Requires proto="no-test" in the tester tag.

Example XML config file:

<surealived>
 <virtual name="onet" addr="192.168.0.1" port="80" proto="tcp" sched="wrr" rt="dr">
   <tester loopdelay="1" timeout="2" retries2fail="1" retries2ok="1"
           proto="no-test" testport="80" />
   <real name="sg" addr="213.180.146.27" port="80" weight="10"/>
 </virtual
</surealived>