1BALANCE(1) General Commands Manual BALANCE(1)
2
6 balance 3.54 - A simple TCP proxy with load balancing and failover
7 mechanisms.
8
10 balance [ -b addr ] [ -B addr ] [ -t sec ] [ -T sec ] [ -adfpHM6 ] port
11 host1[:port1[:maxc]] [!|%] [ ... hostn[:portn[:maxc]]]
12 balance [ -b addr ] -i [ -d ] [ -M ] port
14 balance [ -b addr ] -c cmd [ -d ] [ -M ] port
16
18 Balance is a simple, generic "userland" TCP proxy, which allows simple
19 round-robin load balancing and graceful failover between several desti‐
20 nation servers.
21 Balance supports IPv6 on the listening side which makes it a very use‐
23 ful tool for IPv6 migration of IPv4 only services and servers.
24 Balance is available at http://balance.sourceforge.net.
26 Definitions: A possible destination consisting of a host address and a
28 port is called a "channel". A channel is member of a "channel group".
29 Channels are numbered in a group starting with 0. Groups are numbered
30 starting with 0, which is the initial default group.
31 Balance accepts connections on the given port and forwards them to the
33 supplied channels. At least one channel (in the default group) must be
34 specified. If there are two or more channels specified in a group bal‐
35 ance performs a simple round-robin load balancing between the channels.
36 Balance allows the definition of further channel groups. The connection
38 scheme works as follows: balance tries first to establish a connection
39 to a channel in the first group (0), performing the standard round-
40 robin load balancing scheme. If no channel in this group is available,
41 balance proceeds with the next higher channel group. Groups are simply
42 separated with a "!" at the command line at startup and can be con‐
43 trolled interactively with the "group" command.
44 A "%" instead of a "!" as a group separator declares the previous group
46 to be of type "hash". This means that instead of a round-robin algo‐
47 rithm, a hash distribution based on the client ip address is used to
48 determine the destination channel. This allows connecting one client
49 always to the same server (e.g. balancing http sessions to a single
50 server).
51 Hosts may be specified either by hostname or by IP address. Ports may
53 be specified either by name (as listed in /etc/services) or numeri‐
54 cally. If no port is specified in a destination, the destination port
55 defaults to the source port that balance controls.
56 Balance allows the specification of the maximum number of connections
58 per channel. This parameter can be optionally added after the port
59 specification separated by a colon (":"). If a maximum number of con‐
60 nections is specified a channel will only be used for this maximum num‐
61 ber of simultaneous connections. A maxc value of 0 denotes an unlimited
62 number of connections. This is the initial default value of a channel.
63 The maximum number of groups and channels balance can handle is speci‐
65 fied at compile time and is initially 16 channels in 16 groups.
66 Failover to another destination (a "channel") occurs if the connection
68 is refused on the current channel or if the connect timeout is reached
69 trying to establish a connection. If all possible destinations (chan‐
70 nels) currently fail, the client connection to balance is closed.
71 Balance accepts the following options:
73 6 Forces to bind on IPv6 socket by setting hints.ai_family to
75 AF_INET6.
76 a Enable autodisable option: A channel needs to be manually re-
78 enabled after a failure.
79 b Bindhost: Balance binds to the specified host (or address) for
81 listen() instead to INADDR_ANY.
82 B Bindhost: Balance binds to the specified host (or address) for
84 outgoing connections (the connection will be initiated from this
85 address).
86 c Command: allows to send a command to the balance master process
88 (see interactive mode)
89 d Debug: Balance outputs debugging and tracing information mes‐
91 sages on stderr.
92 H Hashfailover: Balance does failover to next node even if hash is
94 used.
95 F Foreground: tells balance to stay in foreground. This might be
97 useful for testing and debugging since balance can be stopped in
98 that mode using ^C (or other interrupt character).
99 M Use memory mapping for IPC instead of shared memory
101 i Interactive Control: Balance connects to the running instance
103 defined by local port and bind address via shared memory and
104 allows to control the behaviour of it using a command line
105 interface. The access permission using this interface are deter‐
106 mined by the access restrictions of the shared memory segment in
107 effect. help or ? prints out a short command overview, assign
108 allows to change the host_port assignment of a channel (only if
109 disabled), create allows to establish a new destination defini‐
110 tion (channel) consisting of host and port in the current group,
111 disable disables a channel in the current group, enable enables
112 a channel again in the current group, group changes the current
113 group in interactive mode where all following commands are tar‐
114 geted, hash changes the current group to be of type "Hash", help
115 prints out online help informations, kill shuts down the master
116 process and exits interactive mode, maxc <channel> <maxc> sets
117 the maximum number of connection ot the channel (0 means infi‐
118 nite), mrtg-bytes <group> <channel> prints out the bytes
119 received/sent in MRTG compatible format (intended to be called
120 with -c automatically by MRTG), mrtg-conns <group> <channel>
121 prints out the total connections in MRTG compatible format
122 (intended to be called with -c automatically by MRTG), quit
123 exits the interactive mode, reset resets the byte counters of a
124 channel, rr changes the current group to be of type "Round
125 Robin", show shows an overview and the status of all channels
126 including the incoming and outgoing transfer volume in bytes.
127 The output is sorted by groups. Additionally the current connec‐
128 tions (c) and the maximum allowed connections (maxc) are
129 printed, version prints out the version and MAXGROUPS and MAX‐
130 CHANNELS constants at compile time.
131 p Packetdump: Balance shows all incoming and outgoing data on std‐
133 out using a simple always readable external representation of
134 data. This might be useful for debugging and protocol analysis.
135 t Connect Timeout: the default timeout trying to establish a con‐
137 nection to any destination can be changed using this option. The
138 default timeout after which a destination is regarded to be cur‐
139 rently inaccessible is 5 seconds.
140 T Select Timeout: Timeout for select(), default = 0 (never). This
142 feature is currently untested.
143
145 $ balance smtp host1.test.net host2.test.net
146 Connection to the local SMTP port will be forwarded alterating
147 to the SMTP port on host1 and host2. Balance runs automatically
148 in background.
149 $ balance -b 2001:DB8::1 80 10.1.1.1 10.1.1.2
151 Balance binds on port 80 of the local IPv6 IP address
152 2001:DB8::1 and distributes connections to the IPv4 addresses
153 10.1.1.1 and 10.1.1.2.
154 $ balance -b ::ffff:10.1.1.3 80 10.1.1.1 10.1.1.2
156 Balance binds on port 80 of the local IPv4 IP address 10.1.1.3
157 (provided in IPv6 notation) and distributes connections to the
158 IPv4 addresses 10.1.1.1 and 10.1.1.2.
159 $ balance -fp imap mailserver
161 Connections to the local IMAP port will always be forwarded to
162 the host "mailserver". Balance stays in foreground and all data
163 is printed in readable format on stdout.
164 $ balance -f 8888 host1 10.1.1.1:8000
166 Connections to the local port 8888 are forwarded alternating to
167 host1, port 8888 and the host 10.1.1.1, port 8000. Balance
168 stays in foreground connected to the "controlling tty".
169 $ balance imap mailserver1::16 ! mailserver2
171 Two groups are specified, each containing one channel member.
172 First up to 16 simultaneous connections are forwarded to
173 "mailserver1". As soon as they are consumed, balance proceeds
174 with the next group (1) which will consume all remaining connec‐
175 tions forwarding them to the imap ort on "mailserver2".
176 $ balance pop3 host1 host2 host3 ! failover1
178 Balance does round robin load balancing for the three hosts in
179 the default group 0 for pop3 services. If all three hosts in
180 group 0 fail, all connections are then forwarded to the host
181 "failover1".
182 $ balance telnet target.munich.net::1
184 Here balance is used to restrict all connections to exactly one
185 at a time forwarding the telnet port.
186 $ balance 8888 localhost::12 ! localhost::4 ! localhost::2 localhost::2
188 ! localhost:25
189 This is a simple test, forming 5 groups where balance is self
190 referencing its own services 20 times. This is simply a test
191 which definitely can be tried at home.
192
194 In case that balance is not able to forward the connection to any des‐
195 tination the inital connection to balance is always first accepted and
196 then closed again immediately. This is not in every case the behaviour
197 that would have been seen directly on the destination host.
198
200 Thomas Obermair, Inlab Software GmbH (obermair@acm.org)
201 Copyright (c) 2000-2009,2010 by Thomas Obermair (obermair@acm.org) and
203 Inlab Software GmbH (http://www.inlab.de), Gruenwald, Germany. All
204 rights reserved.
205 Balance is released under the GNU GENERAL PUBLIC LICENSE, see the file
207 COPYING in the source code distribution.
208 03 Dec 2010 BALANCE(1)