xrctl.xml.5 (9945B)
1 .TH "XRCTL.XML" "5" "2008,2009" "Crossroads" "Man Page" 2 3 .SH "NAME" 4 xrctl.xml \- Crossroads control-script configuration file 5 6 .SH "SYNOPSIS" 7 The file /etc/xrctl.xml is xrctl's configuration. It defines how xrctl 8 will start the balancer xr. If you wish to use xrctl to control the 9 balancer, then you must configure all services, options and back ends 10 in xrctl.xml. 11 12 .SH "EXAMPLE" 13 The following is a configuration example. See the file xr.pdf which is 14 distributed with the sources for a full description. 15 16 .nf 17 <?xml version="1.0" encoding="UTF-8"> 18 19 <configuration> 20 21 <!-- General system configuration section --> 22 23 <system> 24 <!-- Path where the "xr" binary is searched, and zippers as "gzip" 25 and "bzip2", and the "ps" command. Default is that xrctl 26 uses $PATH. --> 27 <path>/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/local/bin:/opt/local/sbin</path> 28 <!-- "ps" command that shows the PID and command. On Solaris, use 29 /usr/bin/ps -ef "pid comm" and on Linux/MacOSX use 30 /bin/ps -ax -o pid,command. Default is that xrctl guesses 31 the right command. Example: 32 <pscmd>/bin/ps ax -o pid,command</pscmd> --> 33 <!-- Use "logger" to add output to syslog or not? Logger will be 34 used if the binary can be found, and if uselogger is true. --> 35 <uselogger>true</uselogger> 36 <!-- The default logger is the program "logger". Redefine here if 37 you like, for example to a piping logrotate program. Example: 38 <logger>clpipe /var/log/xr.clog</logger> 39 The default <logger> command is: logger -t xr.{service} --> 40 <!-- If logger is NOT used, xrctl will manage log output. In that 41 case, specify the following: 42 - Where do logs get written? 43 <logdir>/var/log</logdir> 44 - How big may the logs become? Manipulated during "xrctl rotate". 45 <maxlogsize>100000</maxlogsize> 46 - How many history logs to keep? 47 <loghistory>10</loghistory> --> 48 <!-- To force log line timestamping, add: 49 <prefixtimestamp>true</prefixtimestamp> 50 Or turn it off with value "false". --> 51 </system> 52 53 <!-- Service descriptions: This section defines all balancing 54 services that you want to start. Each service will lead to one 55 invocation of "xr". --> 56 57 <!-- Very simple TCP service that dispatches SSH connections on 58 port 20.000 to three back ends. Most options are left to 59 their defaults. --> 60 <service> 61 <!-- Service name, must be unique --> 62 <name>ssh</name> 63 <server> 64 <!-- Type (tcp/http, here: tcp), and IP-address/port to bind 65 to. Use "0" for IP-address to bind to all interfaces. The 66 web interface will listen to localhost, port 20.001. --> 67 <type>tcp</type> 68 <address>0:20000</address> 69 <webinterface>0:20001</webinterface> 70 <!-- Clients may be idle for 30 minutes, then they are logged 71 out. But they must accept data from XR within 3 seconds, 72 the latter is the write timeout: --> 73 <clienttimeout>1800:3</clienttimeout> 74 75 <!-- DNS entries are by default cached for 3600 sec (1 hour). 76 Change if you like, for example to half an hour: --> 77 <dnscachetimeout>1800</dnscachetimeout> 78 </server> 79 80 <!-- Back ends for the service. --> 81 <backend> 82 <!-- IP:port to dispatch to. --> 83 <address>server1:22</address> 84 </backend> 85 <backend> 86 <address>server2:22</address> 87 </backend> 88 <backend> 89 <address>server2:22</address> 90 </backend> 91 </service> 92 93 <!-- Here is an HTTP service for web balancing. It shows more 94 advanced features. --> 95 <service> 96 <name>webone</name> 97 98 <!-- Balancer server description --> 99 <server> 100 <!-- Server binding. XR will listen to any IP interface, on port 101 20.010. It'll be an HTTP balancer. The web interface will 102 be on port 20.011 and bound only to the local host address. --> 103 <address>0:20010</address> 104 <type>http</type> 105 <webinterface>127.0.0.1:20011</webinterface> 106 107 <!-- A non-default dispatch mode, here: by client IP.--> 108 <dispatchmode>lax-hashed-ip</dispatchmode> 109 110 <!-- Checks. Dead back ends are checked each 3 seconds. There is 111 no checking of dead and live back ends (checkupinterval 0). --> 112 <checks> 113 <wakeupinterval>3</wakeupinterval> 114 <checkupinterval>0</checkupinterval> 115 </checks> 116 117 <debugging> 118 <!-- Let's go with full messaging: verbose, debug, and logging 119 of transmitted messages. --> 120 <verbose>yes</verbose> 121 <debug>yes</debug> 122 <logtrafficdir>/tmp</logtrafficdir> 123 </debugging> 124 125 <!-- If the balancer runs out of sockets because too many 126 closing connections are in TIME_WAIT state, use: --> 127 <closesocketsfast>yes</closesocketsfast> 128 129 <!-- XR can run specific scripts when client activity starts or 130 ends. When given, the scripts are run with the arguments: 131 the client IP, and the back end (server:port), and the 132 number of connections to that back end. A very simple script 133 /where/ever/activitystart might e.g. do: 134 echo Client $1 going to back end $2, $3 connections so far \ 135 >> /tmp/activity.log 136 A very simple script /where/ever/activityend might e.g. do: 137 echo Client $1 is done with back end $2 >> /tmp/activity.log 138 - onstart: is run when a client is about to be handled at a 139 back end 140 - onend: is run after succesful termination 141 - onfail: is run after unsuccesful termination 142 --> 143 <onstart>/where/ever/activitystart</onstart> 144 <onend>/where/ever/activityend</onend> 145 <onfail>/where/ever/activityaborted</onfail> 146 147 <!-- Access restrictions: we allow from two IP ranges, and deny 148 from one IP address. The overall results:will be: 149 - Access will be allowed from 10.*.*.* 150 - And allowed from 192.168.1.*, but not from 192.168.1.100 --> 151 <acl> 152 <allowfrom>10.255.255.255</allowfrom> 153 <allowfrom>192.168.1.255</allowfrom> 154 <denyfrom>192.168.1.100</denyfrom> 155 </acl> 156 157 <!-- For a nonstandard buffer size (default is 2k), use: --> 158 <buffersize>4096</buffersize> 159 160 <dosprotection> 161 <!-- Here is some basic DOS protection. Connections from IP's 162 are counted over timeinterval seconds (here: 2 sec). When a 163 client exceeds the hard limit hardmaxconnrate (here: 200), 164 then it is denied access. When it exceeds the soft limit 165 softmaxconnrate (here: 150), then each connection is 166 delayed for defertime microsecs (here: 1.000.000, one 167 sec). 168 Finally, the entire balancer will be allowed to serve up 169 to 400 simultaneous connections. --> 170 <timeinterval>2</timeinterval> 171 <hardmaxconnrate>200</hardmaxconnrate> 172 <softmaxconnrate>150</softmaxconnrate> 173 <defertime>1000000</defertime> 174 <maxconnections>400</maxconnections> 175 176 <!-- Let's add some more protection. When a user exceeds their 177 hard maxconn rate, "/path/to/program" will be invoked 178 with the IP as argument. That program may eg. call 179 iptables to block the client. There is also a tag 180 softmaxconnexcess (not shown here). --> 181 <hardmaxconnexcess>/path/to/program</hardmaxconnexcess> 182 183 </dosprotection> 184 185 <http> 186 <!-- Since this is an HTTP balancer, let's add some goodies: 187 no header for the XR version, 188 a header X-Forwarded-For: client-ip 189 no sticky http sessions 190 two serverheaders to insert --> 191 <addxrversion>off</addxrversion> 192 <addxforwardedfor>on</addxforwardedfor> 193 <stickyhttp>off</stickyhttp> 194 <serverheaders> 195 <header>MyFirstHeader: Whatever</header> 196 <header>MySecondHeader: WhateverElse</header> 197 </serverheaders> 198 </http> 199 </server> 200 201 <!-- Back end definitions --> 202 <backend> 203 <!-- Backend lives on server1:80 and is very big (weight 2). 204 XR will forward up to 300 connections to it. The back end 205 checking is left to the default, which is: connect to the 206 IP and port of the back end. Requests for host 207 www.mysite.org will be serviced here. --> 208 <address>server1:80</address> 209 <weight>2</weight> 210 <maxconnections>300</maxconnections> 211 <hostmatch>www.mysite.org</hostmatch> 212 </backend> 213 <backend> 214 <!-- Backend lives on server2:80, has the default weight 1. 215 XR will forward up to 100 connections to it. The back end 216 checking is done by connecting to an alternative port 81. 217 This back end will be eligible for requests for the site 218 www.myothersite.org. --> 219 <address>server2:80</address> 220 <maxconnections>100</maxconnections> 221 <backendcheck>connect::81</backendcheck> 222 <hostmatch>www.myothersite.org</hostmatch> 223 </backend> 224 <backend> 225 <!-- Backend lives on server3:80, has the standard weight and no 226 limitations for the max nr. of connections. Back end 227 checking is done by retrieving /healthcheck.cgi from the 228 server. The back end is eligible for www.myothersite.org. --> 229 <address>server3:80</address> 230 <backendcheck>get:server3:80/healthcheck.cgi</backendcheck> 231 <hostmatch>www.myothersite.org</hostmatch> 232 </backend> 233 </service> 234 235 </configuration> 236 .fi 237 238 .SH "SEE ALSO" 239 xr(1), xrctl(1) 240 241 .SH "AUTHOR" 242 xrctl and the corresponding configuration file format were written by 243 Karel Kubat <karel@kubat.nl>. Web page: http://crossroads.e-tunity.com 244 245 .P 246 This man page was written by Karel Kubat <karel@kubat.nl>.