.TH "XRCTL.XML" "5" "2008,2009" "Crossroads" "Man Page"

.SH "NAME"
xrctl.xml \- Crossroads control-script configuration file

.SH "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.

.SH "EXAMPLE"
The following is a configuration example. See the file xr.pdf which is
distributed with the sources for a full description.

.nf
<?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>
.fi

.SH "SEE ALSO"
xr(1), xrctl(1)

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

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