Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BALANCE(1)		    General Commands Manual		    BALANCE(1)

       balance	3.54  -	 A  simple  TCP	proxy with load	balancing and failover

       balance [ -b addr ] [ -B	addr ] [ -t sec	] [ -T sec ] [ -adfpHM6	] port
       host1[:port1[:maxc]] [!|%] [ ...	hostn[:portn[:maxc]]]

       balance [ -b addr ] -i [	-d ] [ -M ] port

       balance [ -b addr ] -c cmd [ -d ] [ -M ]	port

       Balance	is a simple, generic "userland"	TCP proxy, which allows	simple
       round-robin load	balancing and graceful failover	between	several	desti-
       nation servers.

       Balance	supports IPv6 on the listening side which makes	it a very use-
       ful tool	for IPv6 migration of IPv4 only	services and servers.

       Balance is available at

       Definitions: A possible destination consisting of a host	address	and  a
       port  is	called a "channel".  A channel is member of a "channel group".
       Channels	are numbered in	a group	starting with 0.  Groups are  numbered
       starting	with 0,	which is the initial default group.

       Balance	accepts	connections on the given port and forwards them	to the
       supplied	channels.  At least one	channel	(in the	default	group) must be
       specified.  If there are	two or more channels specified in a group bal-
       ance performs a simple round-robin load balancing between the channels.

       Balance allows the definition of	further	channel	groups.	The connection
       scheme  works as	follows: balance tries first to	establish a connection
       to a channel in the first group (0),  performing	 the  standard	round-
       robin  load balancing scheme. If	no channel in this group is available,
       balance proceeds	with the next higher channel group. Groups are	simply
       separated  with	a  "!"	at the command line at startup and can be con-
       trolled interactively with the "group" command.

       A "%" instead of	a "!" as a group separator declares the	previous group
       to  be  of type "hash".	This means that	instead	of a round-robin algo-
       rithm, a	hash distribution based	on the client ip address  is  used  to
       determine  the  destination  channel. This allows connecting one	client
       always to the same server (e.g. balancing http  sessions	 to  a	single

       Hosts  may  be specified	either by hostname or by IP address. Ports may
       be specified either by name (as listed  in  /etc/services)  or  numeri-
       cally.	If no port is specified	in a destination, the destination port
       defaults	to the source port that	balance	controls.

       Balance allows the specification	of the maximum number  of  connections
       per  channel.  This  parameter  can  be optionally added	after the port
       specification separated by a colon (":"). If a maximum number  of  con-
       nections	is specified a channel will only be used for this maximum num-
       ber of simultaneous connections.	A maxc value of	0 denotes an unlimited
       number of connections. This is the initial default value	of a channel.

       The  maximum number of groups and channels balance can handle is	speci-
       fied at compile time and	is initially 16	channels in 16 groups.

       Failover	to another destination (a "channel") occurs if the  connection
       is  refused on the current channel or if	the connect timeout is reached
       trying to establish a connection. If all	possible  destinations	(chan-
       nels) currently fail, the client	connection to balance is closed.

       Balance accepts the following options:

       6      Forces  to  bind	on  IPv6  socket by setting hints.ai_family to

       a      Enable autodisable option: A channel needs to be manually	re-en-
	      abled after a failure.

       b      Bindhost:	 Balance  binds	to the specified host (or address) for
	      listen() instead to INADDR_ANY.

       B      Bindhost:	Balance	binds to the specified host (or	 address)  for
	      outgoing connections (the	connection will	be initiated from this

       c      Command: allows to send a	command	to the balance master  process
	      (see interactive mode)

       d      Debug:  Balance  outputs	debugging and tracing information mes-
	      sages on stderr.

       H      Hashfailover: Balance does failover to next node even if hash is

       F      Foreground:  tells  balance to stay in foreground. This might be
	      useful for testing and debugging since balance can be stopped in
	      that mode	using ^C (or other interrupt character).

       M      Use memory mapping for IPC instead of shared memory

       i      Interactive  Control:  Balance  connects to the running instance
	      defined by local port and	bind address via shared	memory and al-
	      lows  to control the behaviour of	it using a command line	inter-
	      face. The	access permission using	this interface are  determined
	      by  the  access restrictions of the shared memory	segment	in ef-
	      fect.  help or ?	prints out a short  command  overview,	assign
	      allows  to change	the host_port assignment of a channel (only if
	      disabled), create	allows to establish a new destination  defini-
	      tion (channel) consisting	of host	and port in the	current	group,
	      disable disables a channel in the	current	group, enable  enables
	      a	 channel again in the current group, group changes the current
	      group in interactive mode	where all following commands are  tar-
	      geted, hash changes the current group to be of type "Hash", help
	      prints out online	help informations, kill	shuts down the	master
	      process  and  exits interactive mode, maxc _channel_ _maxc_ sets
	      the maximum number of connection ot the channel (0  means	 infi-
	      nite),  mrtg-bytes  _group_  _channel_  prints out the bytes re-
	      ceived/sent in MRTG compatible format  (intended	to  be	called
	      with  -c	automatically  by  MRTG), mrtg-conns _group_ _channel_
	      prints out the total connections in MRTG compatible format  (in-
	      tended  to  be called with -c automatically by MRTG), quit exits
	      the interactive mode, reset resets the byte counters of a	 chan-
	      nel,  rr	changes	the current group to be	of type	"Round Robin",
	      show shows an overview and the status of all channels  including
	      the  incoming  and outgoing transfer volume in bytes. The	output
	      is sorted	by groups. Additionally	the  current  connections  (c)
	      and  the maximum allowed connections (maxc) are printed, version
	      prints out the version and MAXGROUPS and	MAXCHANNELS  constants
	      at compile time.

       p      Packetdump: Balance shows	all incoming and outgoing data on std-
	      out using	a simple always	readable  external  representation  of
	      data.  This might	be useful for debugging	and protocol analysis.

       t      Connect  Timeout:	the default timeout trying to establish	a con-
	      nection to any destination can be	changed	using this option. The
	      default timeout after which a destination	is regarded to be cur-
	      rently inaccessible is 5 seconds.

       T      Select Timeout: Timeout for select(), default = 0	(never).  This
	      feature is currently untested.

       $ balance smtp
	      Connection  to  the local	SMTP port will be forwarded alterating
	      to the SMTP port on host1	and host2.  Balance runs automatically
	      in background.

       $ balance -b 2001:DB8::1	80
	      Balance	binds  on  port	 80  of	 the  local  IPv6  IP  address
	      2001:DB8::1 and distributes connections to  the  IPv4  addresses and

       $ balance -b ::ffff: 80
	      Balance  binds  on port 80 of the	local IPv4 IP address
	      (provided	in IPv6	notation) and distributes connections  to  the
	      IPv4 addresses and

       $ balance -fp imap mailserver
	      Connections  to  the local IMAP port will	always be forwarded to
	      the host "mailserver".  Balance stays in foreground and all data
	      is printed in readable format on stdout.

       $ balance -f 8888 host1
	      Connections  to the local	port 8888 are forwarded	alternating to
	      host1, port 8888 and the	host,	 port  8000.   Balance
	      stays in foreground connected to the "controlling	tty".

       $ balance imap mailserver1::16 !	mailserver2
	      Two  groups  are	specified, each	containing one channel member.
	      First  up	 to  16	 simultaneous  connections  are	 forwarded  to
	      "mailserver1".  As  soon	as they	are consumed, balance proceeds
	      with the next group (1) which will consume all remaining connec-
	      tions forwarding them to the imap	ort on "mailserver2".

       $ balance pop3 host1 host2 host3	! failover1
	      Balance  does  round robin load balancing	for the	three hosts in
	      the default group	0 for pop3 services. If	 all  three  hosts  in
	      group  0	fail,  all  connections	are then forwarded to the host

       $ balance telnet
	      Here balance is used to restrict all connections to exactly  one
	      at a time	forwarding the telnet port.

       $ balance 8888 localhost::12 ! localhost::4 ! localhost::2 localhost::2
       ! localhost:25
	      This is a	simple test, forming 5 groups where  balance  is  self
	      referencing  its	own  services  20 times. This is simply	a test
	      which definitely can be tried at home.

       In case that balance is not able	to forward the connection to any  des-
       tination	 the inital connection to balance is always first accepted and
       then closed again immediately. This is not in every case	the  behaviour
       that would have been seen directly on the destination host.

       Thomas Obermair,	Inlab Software GmbH (

       Copyright  (c) 2000-2009,2010 by	Thomas Obermair	( and
       Inlab Software GmbH  (,  Gruenwald,	Germany.   All
       rights reserved.

       Balance	is released under the GNU GENERAL PUBLIC LICENSE, see the file
       COPYING in the source code distribution.

				  03 Dec 2010			    BALANCE(1)


Want to link to this manual page? Use this URL:

home | help