1BALANCE(1)                  General Commands Manual                 BALANCE(1)
2
3
4

NAME

6       balance  3.54  -  A  simple  TCP proxy with load balancing and failover
7       mechanisms.
8

SYNOPSIS

10       balance [ -b addr ] [ -B addr ] [ -t sec ] [ -T sec ] [ -adfpHM6 ] port
11       host1[:port1[:maxc]] [!|%] [ ... hostn[:portn[:maxc]]]
12
13       balance [ -b addr ] -i [ -d ] [ -M ] port
14
15       balance [ -b addr ] -c cmd [ -d ] [ -M ] port
16

DESCRIPTION

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
22       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
25       Balance is available at http://balance.sourceforge.net.
26
27       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
32       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
37       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
45       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
52       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
57       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
64       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
67       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
72       Balance accepts the following options:
73
74       6      Forces  to  bind  on  IPv6  socket by setting hints.ai_family to
75              AF_INET6.
76
77       a      Enable autodisable option: A channel needs to  be  manually  re-
78              enabled after a failure.
79
80       b      Bindhost:  Balance  binds to the specified host (or address) for
81              listen() instead to INADDR_ANY.
82
83       B      Bindhost: Balance binds to the specified host (or  address)  for
84              outgoing connections (the connection will be initiated from this
85              address).
86
87       c      Command: allows to send a command to the balance master  process
88              (see interactive mode)
89
90       d      Debug:  Balance  outputs  debugging and tracing information mes‐
91              sages on stderr.
92
93       H      Hashfailover: Balance does failover to next node even if hash is
94              used.
95
96       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
100       M      Use memory mapping for IPC instead of shared memory
101
102       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
132       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
136       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
141       T      Select Timeout: Timeout for select(), default = 0 (never).  This
142              feature is currently untested.
143

EXAMPLES

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
150       $ 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
155       $ 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
160       $ 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
165       $ 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
170       $ 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
177       $ 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
183       $ 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
187       $ 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

BUGS

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

AUTHOR

200       Thomas Obermair, Inlab Software GmbH (obermair@acm.org)
201
202       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
206       Balance  is released under the GNU GENERAL PUBLIC LICENSE, see the file
207       COPYING in the source code distribution.
208
209
210
211                                  03 Dec 2010                       BALANCE(1)
Impressum