SYNOPSIS
The file /etc/xrctl.xml is xrctl's configuration. It defines how xrctl will start the balancer xr. If you wish to use xrctl to control the balancer, then you must configure all services, options and back ends in xrctl.xml.
EXAMPLE
The following is a configuration example. See the file xr.pdf which is distributed with the sources for a full description.
<?xml version="1.0" encoding="UTF-8">
<configuration>
<!-- General system configuration section -->
<system>
<!-- Path where the "xr" binary is searched, and zippers as "gzip"
and "bzip2", and the "ps" command. Default is that xrctl
uses $PATH. -->
<path>/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/local/bin:/opt/local/sbin</path>
<!-- "ps" command that shows the PID and command. On Solaris, use
/usr/bin/ps -ef "pid comm" and on Linux/MacOSX use
/bin/ps -ax -o pid,command. Default is that xrctl guesses
the right command. Example:
<pscmd>/bin/ps ax -o pid,command</pscmd> -->
<!-- Use "logger" to add output to syslog or not? Logger will be
used if the binary can be found, and if uselogger is true. -->
<uselogger>true</uselogger>
<!-- The default logger is the program "logger". Redefine here if
you like, for example to a piping logrotate program. Example:
<logger>clpipe /var/log/xr.clog</logger>
The default <logger> command is: logger -t xr.{service} -->
<!-- If logger is NOT used, xrctl will manage log output. In that
case, specify the following:
- Where do logs get written?
<logdir>/var/log</logdir>
- How big may the logs become? Manipulated during "xrctl rotate".
<maxlogsize>100000</maxlogsize>
- How many history logs to keep?
<loghistory>10</loghistory> -->
<!-- To force log line timestamping, add:
<prefixtimestamp>true</prefixtimestamp>
Or turn it off with value "false". -->
</system>
<!-- Service descriptions: This section defines all balancing
services that you want to start. Each service will lead to one
invocation of "xr". -->
<!-- Very simple TCP service that dispatches SSH connections on
port 20.000 to three back ends. Most options are left to
their defaults. -->
<service>
<!-- Service name, must be unique -->
<name>ssh</name>
<server>
<!-- Type (tcp/http, here: tcp), and IP-address/port to bind
to. Use "0" for IP-address to bind to all interfaces. The
web interface will listen to localhost, port 20.001. -->
<type>tcp</type>
<address>0:20000</address>
<webinterface>0:20001</webinterface>
<!-- Clients may be idle for 30 minutes, then they are logged
out. But they must accept data from XR within 3 seconds,
the latter is the write timeout: -->
<clienttimeout>1800:3</clienttimeout>
<!-- DNS entries are by default cached for 3600 sec (1 hour).
Change if you like, for example to half an hour: -->
<dnscachetimeout>1800</dnscachetimeout>
</server>
<!-- Back ends for the service. -->
<backend>
<!-- IP:port to dispatch to. -->
<address>server1:22</address>
</backend>
<backend>
<address>server2:22</address>
</backend>
<backend>
<address>server2:22</address>
</backend>
</service>
<!-- Here is an HTTP service for web balancing. It shows more
advanced features. -->
<service>
<name>webone</name>
<!-- Balancer server description -->
<server>
<!-- Server binding. XR will listen to any IP interface, on port
20.010. It'll be an HTTP balancer. The web interface will
be on port 20.011 and bound only to the local host address. -->
<address>0:20010</address>
<type>http</type>
<webinterface>127.0.0.1:20011</webinterface>
<!-- A non-default dispatch mode, here: by client IP.-->
<dispatchmode>lax-hashed-ip</dispatchmode>
<!-- Checks. Dead back ends are checked each 3 seconds. There is
no checking of dead and live back ends (checkupinterval 0). -->
<checks>
<wakeupinterval>3</wakeupinterval>
<checkupinterval>0</checkupinterval>
</checks>
<debugging>
<!-- Let's go with full messaging: verbose, debug, and logging
of transmitted messages. -->
<verbose>yes</verbose>
<debug>yes</debug>
<logtrafficdir>/tmp</logtrafficdir>
</debugging>
<!-- If the balancer runs out of sockets because too many
closing connections are in TIME_WAIT state, use: -->
<closesocketsfast>yes</closesocketsfast>
<!-- XR can run specific scripts when client activity starts or
ends. When given, the scripts are run with the arguments:
the client IP, and the back end (server:port), and the
number of connections to that back end. A very simple script
/where/ever/activitystart might e.g. do:
echo Client $1 going to back end $2, $3 connections so far >> /tmp/activity.log
A very simple script /where/ever/activityend might e.g. do:
echo Client $1 is done with back end $2 >> /tmp/activity.log
- onstart: is run when a client is about to be handled at a
back end
- onend: is run after successful termination
- onfail: is run after unsuccessful termination
-->
<onstart>/where/ever/activitystart</onstart>
<onend>/where/ever/activityend</onend>
<onfail>/where/ever/activityaborted</onfail>
<!-- Access restrictions: we allow from two IP ranges, and deny
from one IP address. The overall results:will be:
- Access will be allowed from 10.*.*.*
- And allowed from 192.168.1.*, but not from 192.168.1.100 -->
<acl>
<allowfrom>10.255.255.255</allowfrom>
<allowfrom>192.168.1.255</allowfrom>
<denyfrom>192.168.1.100</denyfrom>
</acl>
<!-- For a nonstandard buffer size (default is 2k), use: -->
<buffersize>4096</buffersize>
<dosprotection>
<!-- Here is some basic DOS protection. Connections from IP's
are counted over timeinterval seconds (here: 2 sec). When a
client exceeds the hard limit hardmaxconnrate (here: 200),
then it is denied access. When it exceeds the soft limit
softmaxconnrate (here: 150), then each connection is
delayed for defertime microsecs (here: 1.000.000, one
sec).
Finally, the entire balancer will be allowed to serve up
to 400 simultaneous connections. -->
<timeinterval>2</timeinterval>
<hardmaxconnrate>200</hardmaxconnrate>
<softmaxconnrate>150</softmaxconnrate>
<defertime>1000000</defertime>
<maxconnections>400</maxconnections>
<!-- Let's add some more protection. When a user exceeds their
hard maxconn rate, "/path/to/program" will be invoked
with the IP as argument. That program may eg. call
iptables to block the client. There is also a tag
softmaxconnexcess (not shown here). -->
<hardmaxconnexcess>/path/to/program</hardmaxconnexcess>
</dosprotection>
<http>
<!-- Since this is an HTTP balancer, let's add some goodies:
no header for the XR version,
a header X-Forwarded-For: client-ip
no sticky http sessions
two serverheaders to insert -->
<addxrversion>off</addxrversion>
<addxforwardedfor>on</addxforwardedfor>
<stickyhttp>off</stickyhttp>
<serverheaders>
<header>MyFirstHeader: Whatever</header>
<header>MySecondHeader: WhateverElse</header>
</serverheaders>
</http>
</server>
<!-- Back end definitions -->
<backend>
<!-- Backend lives on server1:80 and is very big (weight 2).
XR will forward up to 300 connections to it. The back end
checking is left to the default, which is: connect to the
IP and port of the back end. Requests for host
www.mysite.org will be serviced here. -->
<address>server1:80</address>
<weight>2</weight>
<maxconnections>300</maxconnections>
<hostmatch>www.mysite.org</hostmatch>
</backend>
<backend>
<!-- Backend lives on server2:80, has the default weight 1.
XR will forward up to 100 connections to it. The back end
checking is done by connecting to an alternative port 81.
This back end will be eligible for requests for the site
www.myothersite.org. -->
<address>server2:80</address>
<maxconnections>100</maxconnections>
<backendcheck>connect::81</backendcheck>
<hostmatch>www.myothersite.org</hostmatch>
</backend>
<backend>
<!-- Backend lives on server3:80, has the standard weight and no
limitations for the max nr. of connections. Back end
checking is done by retrieving /healthcheck.cgi from the
server. The back end is eligible for www.myothersite.org. -->
<address>server3:80</address>
<backendcheck>get:server3:80/healthcheck.cgi</backendcheck>
<hostmatch>www.myothersite.org</hostmatch>
</backend>
</service>
</configuration>
AUTHOR
xrctl and the corresponding configuration file format were written by Karel Kubat <[email protected]>. Web page: http://crossroads.e-tunity.com
This man page was written by Karel Kubat <[email protected]>.