Man pages sections > man5 > xrctl

xrctl.xml - Crossroads control-script configuration file

XRCTL.XML(5) Man Page XRCTL.XML(5)

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>.
2008,2009 Crossroads