usage.txt (10338B)
1 2 This is XR, a load balancer and failover utility for TCP/HTTP services. 3 Usage: xr [flags], where the flags may be the following (long versions 4 may not exist on your platform): 5 6 --add-server-header HDR, -H HDR 7 Inserts HDR into back end bound HTTP messages. The header value is 8 appended when a pre-existing header is present. 9 --add-x-forwarded-for, -x 10 Adds X-Forwarded-For with external IP address to back end streams in 11 HTTP messages. 12 --add-xr-version, -X 13 Adds an XR version header to client and back end streams in HTTP 14 messages. 15 --allow-from MASK, -a MASH 16 Allow only clients that match MASK. MASK is e.g. 192.168.255.255, which 17 would allow the class B network 192.168.*.* 18 --backend ADDRESS:PORT[:MAX[:WEIGHT]], -b ADDRESS:PORT[:MAX[:WEIGHT]] 19 Specifies a back end, use multiple -b... to specify several back ends. 20 At least one backend must be given. Specifier MAX is optional: 21 when given, defines the maximum connections for the back end. 22 WEIGHT is optional: when given, specifies the weight (bigger 23 means better server, default 1) 24 --backend-check METHOD, -g METHOD 25 Defines how back ends are checked. This flag must be specified 26 PRIOR to defining back ends with -b... The checker will then 27 apply to all next back ends. Alternatives are: 28 connect:IP:PORT - successful TCP connects at IP:PORT indicate 29 that the back end is alive. When IP is not stated, the back 30 end's IP is assumed. 31 get:IP:PORT/URI - A HTTP GET is sent to IP:PORT/URI. When an 32 HTTP status 200 is seen, the back end is assumed alive. When 33 /URI is not given, then "/" is assumed. 34 external:PROGRAM - The PROGRAM is called with the arguments 35 "IP:PORT", availability as "available" or "unavailable", and 36 the number of connections. The program must echo 0 to indicate 37 that the back end is alive. 38 The default behavior is a TCP connect, to the back end's IP, at 39 the back end's port. Use "--backend-check connect::" to reset 40 previous flags to the default. 41 --backend-timeout SEC, -t SEC 42 Defines network read timeouts for back ends, default 30 sec. Use 0 to 43 prevent timing out. Use "--backend-timeout RSEC:WSEC" to 44 specify separate timeouts for reads and writes, default 30:3. 45 --buffer-size SIZE, -B size 46 Sets the network buffer size, default is 2048 (in bytes) 47 --checkup-interval SEC, -c SEC 48 Defines the back end checking period. Each SEC seconds, every back end 49 is checked whether it is alive. Default is 0 (off). 50 --client-timeout SEC, -T SEC 51 Defines network read timeouts for clients, default 30 sec. Use 0 to 52 prevent timing out. Use "--client-timeout RSEC:WSEC" to specify 53 separate timeouts for reads and writes, default 30:5 54 --close-sockets-fast, -C 55 Sockets are closed faster to avoid TIME_WAIT states. 56 --debug, -D 57 Sets debugging on, more verbosity on top of --verbose 58 --defer-time USEC, -u USEC 59 If a connection is going to be deferred due to hitting the "soft" rate 60 (see --soft-maxconnrate), then this option sets how long the deferral 61 will last, in microseconds. Default is 500000 (0.5 seconds). 62 --deny-from MASK, -A mask 63 Deny clients that match MASK. 64 --dispatch-mode METHOD, -d METHOD 65 Defines how to dispatch over back ends, the method may be: 66 f, first-available - first live back end gets all traffic 67 e:EXT, external:EXT - external program EXT is queried 68 h, strict-hashed-ip - client IP is hashed to determine a back end, 69 the client is denied when back end is down. 70 H, lax-hashed-ip - client IP is hashed, fallback to least-connections 71 when target back end is down 72 l, least-connections - back end with least connections is taken 73 r, round-robin - back ends take turns 74 L, weighted-load - randomly picks from back end with favor given 75 to backends with lower load average. (NOTE: load average must 76 be updated by the backend, e.g. using the web interface). 77 s:SEC, strict-stored-ip:SEC - if client connected before within SEC 78 seconds, then the same backend is used. Client is denied if 79 that backend is down. Else a new is found by least-connections. 80 S:SEC, lax-stored-ip:SEC - same as strict-stored-ip, but falls back 81 to least-connections when a previously used back end is down. 82 Default method is l (least-connections). When external mode is selected, 83 program EXT is started with arguments <nbackends> <b0> <b0-availability> 84 <b0-connections> (b0 repeated for all back ends). Here <b0> is the back 85 end definition, eg. "10.1.1.1:80"; <b0-availablility> is "available" or 86 "unavailable", <b0-connections> is the nr. of connections. The program 87 must reply with a back end number (0..max) on stdout. 88 --dns-cache-timeout SEC, -F SEC 89 DNS results for back end hostnames are cached for SEC seconds. 90 The default is 3600 (1 hour). Use 0 to suppress. 91 --foreground, -f 92 Suppresses forking/threading, only for debugging. Also suppresses 93 wakeups (--wakeup-interval), checkups (--checkup-interval) and 94 the webinterface (--web-interface). 95 --hard-maxconn-excess PROGRAM, -E PROGRAM 96 When a client exceeds the hard maxconnection rate, PROGRAM is 97 invoked with the client's IP as argument. The program may e.g. 98 invoke iptables to block the offending IP. 99 --hard-maxconnrate MAXCONS, -R MAXCONS 100 Sets the "HARD" maximum average number of connections per IP allowed 101 within a given time period (see -U, --time-interval). If a 102 particular IP exceeds this number, then their connection is 103 immediately closed. Default is 0 (disabled). If both the 104 "soft" and "hard" rates are set, and the "hard" rate is lower 105 than the "soft" rate, then only the "hard" rate is obeyed. 106 --help, -?, -h 107 This text. 108 --host-match HOST, -M HOST 109 Subsequently stated backends only apply when clients request a 110 matching host. Only available when the server is in http mode. 111 --log-traffic-dir DIR, -l DIR 112 Log passing traffic with dumps in DIR. Only for debugging, slows 113 down the balancer. 114 --max-connections MAX, -m MAX 115 Sets the maximum number of connections to the balancer. Default is 0, 116 no maximum. 117 --onend CMD, -Z CMD 118 Runs CMD after successful termination of a client. For the 119 arguments of CMD see -y. 120 --onfail CMD, -y CMD 121 Runs CMD when XR fails to connect to a back end. The arguments 122 to the command are: the client's IP address, and the back end address. 123 --onstart CMD, -z CMD 124 Runs CMD just before letting a back end handle a client's connection. 125 For the arguments of CMD see --onfail, -y. 126 --pidfile FILE, -p FILE 127 FILE is written with the process id of XR upon startup, and 128 removed upon exit. 129 --prefix-timestamp, -P 130 Messages (verbose, debug, error etc.) are prefixed with a time stamp. 131 --quit-after REQUESTS, -Q REQUESTS 132 Stops the balancer after REQUESTS hits. For debugging / loadtesting. 133 --remove-reservations, -G 134 In stored-ip algorithms, outstanding reservations for expected 135 clients are removed when no more back ends are available. 136 --replace-host-header, -I 137 Inserts "Host: <backend>" into back end bound HTTP messages. 138 Pre-existing Host headers are overwritten. The value of <backend> is 139 the server name as in the setting of --backend (-b). 140 --server TYPE:IPADDRESS:PORT, -S TYPE:IPADDRESS:PORT 141 Specifies the server. TYPE is tcp or http or udp. IPADDRESS is the IP 142 address to listen to. PORT defines the TCP port to listen; when port 143 is 0, XR will listen to stdin (inetd-mode, not available for udp). 144 Default: tcp:0:10000 (TCP balancing, on all interfaces, via port 10000). 145 --soft-maxconn-excess PROGRAM, -e PROGRAM 146 When a client exceeds the soft maxconnection rate, PROGRAM is 147 invoked with the client's IP as argument. 148 --soft-maxconnrate MAXCONS, -r MAXCONS 149 Sets the "SOFT" maximum average number of connections per IP allowed 150 within a given time period (see -U, --time-interval). If a 151 particular IP exceeds this number, then their connection is 152 deferred (see -u, --defer-time). Default is 0 (disabled). 153 --sticky-http, -S 154 Enables sticky HTTP sessions by injecting XRTarget cookies into HTTP 155 streams. Only effective with "--server http:...." 156 --time-interval SEC, -U SEC 157 If either --soft-maxconnrate or --hard-maxconnrate is specified, this 158 option allows you to specify the time period to which those numbers of 159 connections apply. For example, 160 "--soft-maxconnrate 200 --time-interval 60" would trigger the 161 "soft" limit on any IP attempting more than 200 connections in 162 any 60 second period. Default is 1 (second). 163 --tryout, -n 164 Validates all flags and stops; does not start the balancer. 165 --url-match URL, -j URL 166 Subsequently stated backends only apply when clients request a 167 matching URL. Only available when the server is in http mode. 168 --verbose, -v 169 Increases verbosity, default is silent operation. 170 --version, -V 171 Shows the version info, and author/maintainer contacts (for reporting 172 bugs). 173 --wakeup-interval SEC, -w SEC 174 Defines wakeup period (rechecking) in seconds, of unavailable back 175 ends. Default is 5. Use -w0 to suppress. 176 --web-interface IP:PORT[:NAME], -W IP:PORT[:NAME] 177 Starts a web interface on specified IP address and port. The 178 optional NAME is displayed. 179 --web-interface-auth USER:PASS, -Y USER:PASS 180 Access to the web interface will be protected by basic authentication. 181 182 XR's errors and warnings are sent to stderr, debugging and verbose 183 messages go to stdout. Invoke XR daemons using something like 184 "xr --backend ... [other flags] 2>&1 | logger &", or use xrctl. 185 186 Send signal SIGHUP (-1) to write back end states to the log. 187 Send signal SUGUSR1 (-30) to toggle verbose logging. 188 Send signal SIGUSR2 (-31) to toggle debug logging. 189 Other typical signals request termination. 190