NAME¶

xrctl.xml - Crossroads control-script configuration file

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>

SEE ALSO¶

xr(1), xrctl(1)

AUTHOR¶

xrctl and the corresponding configuration file format were written by Karel Kubat <karel@kubat.nl>. Web page: http://crossroads.e-tunity.com

This man page was written by Karel Kubat <karel@kubat.nl>.