Professional Documents
Culture Documents
BalanceNG V3 Manual
BalanceNG V3 Manual
V3
A Modern Software Load Balancer for Linux and Solaris
User and Reference Manual
Command Set BalanceNG V3 (3.504) and higher
Status: STABLE
Version: 3.504.0
Date: Jan 23, 2014
Author: Thomas Obermair
SW-Date: 2014/23/01
Inlab Software GmbH
Josef-Wrth-Str. 3
82031 Grnwald
Germany
Tel.: +49 89 64911420
Fax: +49 89 64911421
Email: offce@inlab.de
Home: http://www.inlab.de
Table of Contents
1 Introduction.................................................................................................. 10
1.1 What is BalanceNG ? .......................................................................... 10
1.2 BalanceNG Features and Specifcations.............................................10
1.3 Hardware and OS Requirements.........................................................11
1.3.1 Linux...................................................................................................... 11
1.3.2 Solaris.................................................................................................... 11
1.4 BalanceNG Core Concepts.................................................................. 11
1.4.1 Interfaces............................................................................................... 11
1.4.2 Networks................................................................................................ 12
1.4.3 Servers.................................................................................................. 12
1.4.4 Targets................................................................................................... 12
1.4.5 Modules................................................................................................. 12
1.4.6 Threads.................................................................................................. 12
1.4.7 Confguration and Confguration Files.................................................... 12
1.4.8 Instances............................................................................................... 13
1.4.9 IPDB, Locations and Location-Groups................................................... 13
1.5 BalanceNG Design .............................................................................. 13
2 Initial Implementation................................................................................... 15
2.1 Hardware selection............................................................................... 15
2.2 Network Setup...................................................................................... 15
2.3 Installation.............................................................................................17
2.3.1 Installation on Solaris.............................................................................. 17
2.3.2 Installation on Linux (Debian/Ubuntu Package)......................................18
2.3.3 Installation on Linux (tarball)................................................................... 18
2.4 Making BalanceNG Turnkey.................................................................19
2.4.1 Making BalanceNG Turnkey on Solaris..................................................19
2.4.2 Making BalanceNG Turnkey on Linux.................................................... 19
2.4.3 Multi-Instance init.d Script...................................................................... 20
2.5 Determining the Nodeid and Licensing................................................21
2.6 Licensing of all Instances in /etc/bng.global......................................... 22
2.7 "Basic license" restrictions....................................................................22
3 Command Reference...................................................................................24
3.1 Command Line Interface ..................................................................... 24
3.1.1 bng......................................................................................................... 24
3.1.2 bng start [instance]................................................................................. 24
3.1.3 bng stop [instance]................................................................................. 25
3.1.4 bng reload [instance].............................................................................. 25
3.1.5 bng restart [instance]............................................................................. 25
3.1.6 bng status [instance].............................................................................. 25
3.1.7 bng [-e] cmdctl [instance]....................................................................... 26
3.1.8 bng [-e] imsctl [instance]........................................................................ 26
3.1.9 bng [-e] control [instance]....................................................................... 26
3.1.10 bng [-e] auxctl [instance]...................................................................... 27
3.1.11 bng purge [instance]............................................................................. 27
3.1.12 bng -I................................................................................................... 28
3.1.13 bng -L.................................................................................................. 28
3.1.14 bng -N.................................................................................................. 28
3.1.15 bng -W................................................................................................. 28
3.2 Administrative and Informational Commands.......................................29
3.2.1 benchmark............................................................................................. 29
3.2.2 check..................................................................................................... 29
3.2.3 clear....................................................................................................... 30
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 2 / 146 Grnwald Germany / All Rights Reserved
3.2.4 coredump............................................................................................... 30
3.2.5 help ....................................................................................................... 30
3.2.6 help <subtopic>..................................................................................... 31
3.2.7 inject...................................................................................................... 32
3.2.8 locate..................................................................................................... 33
3.2.9 purge..................................................................................................... 33
3.2.10 rms....................................................................................................... 34
3.2.11 rmsession............................................................................................. 34
3.2.12 rmt....................................................................................................... 34
3.2.13 resync.................................................................................................. 34
3.2.14 save..................................................................................................... 34
3.2.15 save conf............................................................................................. 35
3.2.16 save private......................................................................................... 35
3.2.17 save all ................................................................................................ 35
3.2.18 sessiondump........................................................................................ 35
3.2.19 sessionload.......................................................................................... 36
3.2.20 show.................................................................................................... 36
3.2.20.1 show ?.......................................................................................... 36
3.2.20.2 show arphash............................................................................... 37
3.2.20.3 show benchmark.......................................................................... 37
3.2.20.4 show break................................................................................... 38
3.2.20.5 show conf .................................................................................... 38
3.2.20.6 show conf <section>..................................................................... 38
3.2.20.7 show conf hostname.................................................................... 39
3.2.20.8 show conf network........................................................................ 39
3.2.20.9 show conf remark......................................................................... 39
3.2.20.10 show conf server........................................................................ 40
3.2.20.11 show conf target......................................................................... 40
3.2.20.12 show debugscopes..................................................................... 40
3.2.20.13 show gateway............................................................................. 40
3.2.20.14 show ifstat.................................................................................. 40
3.2.20.15 show instance............................................................................. 41
3.2.20.16 show interfaces ......................................................................... 42
3.2.20.17 show ipdb................................................................................... 42
3.2.20.18 show license............................................................................... 42
3.2.20.19 show lgrp.................................................................................... 43
3.2.20.20 show lgrp <g>............................................................................. 43
3.2.20.21 show locations............................................................................ 44
3.2.20.22 show log .................................................................................... 45
3.2.20.23 show machash........................................................................... 45
3.2.20.24 show maxbucket......................................................................... 46
3.2.20.25 show modules............................................................................ 46
3.2.20.26 show nat..................................................................................... 47
3.2.20.27 show network <n>...................................................................... 47
3.2.20.28 show networks............................................................................ 47
3.2.20.29 show nodeid............................................................................... 47
3.2.20.30 show nous.................................................................................. 48
3.2.20.31 show parameters........................................................................ 48
3.2.20.32 show private............................................................................... 49
3.2.20.33 show server <n>......................................................................... 49
3.2.20.34 show servers.............................................................................. 50
3.2.20.35 show sessiongroups................................................................... 50
3.2.20.36 show sessions............................................................................ 50
3.2.20.37 show snat................................................................................... 51
3.2.20.38 show startuplog.......................................................................... 51
3.2.20.39 show stinfo................................................................................. 51
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 3 / 146
3.2.20.40 show targets .............................................................................. 51
3.2.20.41 show target <n>.......................................................................... 52
3.2.20.42 show targetregistry..................................................................... 52
3.2.20.43 show threads.............................................................................. 53
3.2.20.44 show uptime............................................................................... 53
3.2.20.45 show vips................................................................................... 53
3.2.20.46 show version.............................................................................. 54
3.2.20.47 show vnodeid............................................................................. 54
3.2.20.48 show vrrp.................................................................................... 54
3.2.21 shutdown............................................................................................. 55
3.2.22 snapshot.............................................................................................. 55
3.2.23 snapshot-full........................................................................................ 55
3.2.24 snapshot-light...................................................................................... 55
3.2.25 stfll...................................................................................................... 55
3.2.26 stop...................................................................................................... 56
3.3 Confguration Commands.....................................................................56
3.3.1 ! <command>......................................................................................... 56
3.3.2 arp......................................................................................................... 57
3.3.3 commit................................................................................................... 57
3.3.4 disable................................................................................................... 58
3.3.5 dump...................................................................................................... 59
3.3.6 edit......................................................................................................... 60
3.3.7 enable.................................................................................................... 61
3.3.8 gateway................................................................................................. 62
3.3.8.1 gateway <ip4addr>......................................................................... 62
3.3.8.2 gateway alert <script>.................................................................... 63
3.3.8.3 gateway arp <interval>,<timeout>..................................................63
3.3.8.4 gateway ipaddr <ip4addr>.............................................................. 63
3.3.8.5 gateway ipaddr6 <ip6addr>............................................................ 64
3.3.8.6 gateway nd6 <interval>,<timeout>..................................................64
3.3.8.7 gateway ping <interval>,<timeout>................................................. 64
3.3.8.8 gateway ping6 <interval>,<timeout>............................................... 65
3.3.8.9 gateway trackval <value>............................................................... 65
3.3.8.10 gateway upalert <script>.............................................................. 65
3.3.9 hostname............................................................................................... 65
3.3.10 interface <name>................................................................................. 66
3.3.11 interface <n>........................................................................................ 66
3.3.11.1 interface <n> access.....................................................................66
3.3.11.2 interface <n> alert......................................................................... 67
3.3.11.3 interface <n> init........................................................................... 67
3.3.11.4 interface <n> name....................................................................... 67
3.3.11.5 interface <n> threads.................................................................... 68
3.3.11.6 interface <n> trackval................................................................... 68
3.3.11.7 interface <n> upalert..................................................................... 68
3.3.12 ipallow.................................................................................................. 68
3.3.13 ipdb...................................................................................................... 68
3.3.14 ipdeny.................................................................................................. 69
3.3.15 ipdb6.................................................................................................... 69
3.3.16 lgrp....................................................................................................... 70
3.3.17 license.................................................................................................. 70
3.3.18 log........................................................................................................ 71
3.3.19 macallow.............................................................................................. 71
3.3.20 macdeny ............................................................................................. 71
3.3.21 macrouter............................................................................................. 71
3.3.22 modules............................................................................................... 72
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 4 / 146 Grnwald Germany / All Rights Reserved
3.3.22.1 arp................................................................................................ 72
3.3.22.2 benchmark .................................................................................. 72
3.3.22.3 classic ......................................................................................... 72
3.3.22.4 crossover...................................................................................... 72
3.3.22.5 hc ................................................................................................ 73
3.3.22.6 ipallow.......................................................................................... 73
3.3.22.7 ipdeny........................................................................................... 73
3.3.22.8 llb ................................................................................................ 73
3.3.22.9 macallow ..................................................................................... 73
3.3.22.10 macdeny .................................................................................... 73
3.3.22.11 master ....................................................................................... 73
3.3.22.12 nat.............................................................................................. 74
3.3.22.13 ping .......................................................................................... 74
3.3.22.14 rt................................................................................................. 74
3.3.22.15 slb .............................................................................................. 74
3.3.22.16 switch......................................................................................... 74
3.3.22.17 tnat............................................................................................. 74
3.3.22.18 vrrp ............................................................................................ 74
3.3.23 network <n>......................................................................................... 74
3.3.23.1 network <n> addr......................................................................... 75
3.3.23.2 network <n> interface[s]............................................................... 75
3.3.23.3 network <n> mask........................................................................ 76
3.3.23.4 network <n> mask6...................................................................... 76
3.3.23.5 network <n> name........................................................................ 76
3.3.23.6 network <n> nat............................................................................ 76
3.3.23.7 network <n> real........................................................................... 77
3.3.23.8 network <n> real6......................................................................... 77
3.3.23.9 network <n> synciface.................................................................. 78
3.3.23.10 network <n> virt.......................................................................... 78
3.3.23.11 network <n> virt6........................................................................ 78
3.3.24 no ........................................................................................................ 79
3.3.25 register................................................................................................. 79
3.3.26 reload................................................................................................... 82
3.3.27 remark.................................................................................................. 82
3.3.28 server <n>............................................................................................ 83
3.3.28.1 server <n> backup[s].................................................................... 83
3.3.28.2 server <n> failover ....................................................................... 84
3.3.28.3 server <n> ftimeout <value>ldefault.............................................84
3.3.28.4 server <n> gslb dispatch.............................................................. 85
3.3.28.5 server <n> gslb enable................................................................. 85
3.3.28.6 server <n> gslbttl.......................................................................... 86
3.3.28.7 server <n> ipaddr......................................................................... 86
3.3.28.8 server <n> ipaddr6....................................................................... 88
3.3.28.9 server <n> ipdb............................................................................ 88
3.3.28.10 server <n> method..................................................................... 89
3.3.28.10.1 rr..................................................................................................89
3.3.28.10.2 hash............................................................................................ 89
3.3.28.10.3 random........................................................................................ 89
3.3.28.10.4 agent........................................................................................... 90
3.3.28.10.5 bw............................................................................................... 90
3.3.28.10.6 bwin.............................................................................................91
3.3.28.10.7 bwout.......................................................................................... 91
3.3.28.10.8 rndagent......................................................................................91
3.3.28.10.9 session........................................................................................ 91
3.3.28.11 server <n> name........................................................................ 92
3.3.28.12 server <n> plugin........................................................................ 93
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 5 / 146
3.3.28.13 server <n> port........................................................................... 94
3.3.28.14 server <n> ports <p1>,<p2>....................................................... 96
3.3.28.15 server <n> portrel....................................................................... 96
3.3.28.16 server <n> protocol.................................................................... 97
3.3.28.17 server <n> proxy enable............................................................. 97
3.3.28.18 server <n> sessionid <handler>.................................................99
3.3.28.18.1 sip.............................................................................................. 99
3.3.28.18.2 src.............................................................................................. 99
3.3.28.18.3 src+dstport................................................................................. 99
3.3.28.18.4 src+port...................................................................................... 99
3.3.28.18.5 src+ports.................................................................................... 99
3.3.28.18.6 dst.............................................................................................. 99
3.3.28.18.7 dst+port...................................................................................... 99
3.3.28.18.8 dst+ports.................................................................................... 99
3.3.28.18.9 dst+srcport................................................................................. 99
3.3.28.19 server <n> snat enableldisable...................................................99
3.3.28.20 server <n> stimeout <value>lnullldefault.................................... 99
3.3.28.21 server <n> target[s].................................................................. 100
3.3.29 set...................................................................................................... 100
3.3.29.1 set arplookup.............................................................................. 101
3.3.29.2 set arprefresh............................................................................. 102
3.3.29.3 set arptimeout............................................................................. 102
3.3.29.4 set backupalerts......................................................................... 103
3.3.29.5 set bmduration............................................................................ 103
3.3.29.6 set bmpsize................................................................................ 103
3.3.29.7 set bmwsize................................................................................103
3.3.29.8 set bngflter................................................................................. 103
3.3.29.9 set debugscope.......................................................................... 103
3.3.29.10 set dumprotation....................................................................... 104
3.3.29.11 set gnatdlimit............................................................................ 104
3.3.29.12 set gratarpremind..................................................................... 104
3.3.29.13 set hashbytes4......................................................................... 105
3.3.29.14 set hashbytes6......................................................................... 105
3.3.29.15 set hcportoffset......................................................................... 105
3.3.29.16 set ipforwarding........................................................................ 105
3.3.29.17 set localdsr............................................................................... 106
3.3.29.18 set localvirt............................................................................... 106
3.3.29.19 set multithreading..................................................................... 107
3.3.29.20 set natdlimit.............................................................................. 107
3.3.29.21 set natscan............................................................................... 107
3.3.29.22 set natsync............................................................................... 107
3.3.29.23 set natsynciv............................................................................. 107
3.3.29.24 set nattimeout........................................................................... 107
3.3.29.25 set outmtu.................................................................................107
3.3.29.26 set pthreadstacksize................................................................. 108
3.3.29.27 set psvrelearn........................................................................... 108
3.3.29.28 set maxsyncps.......................................................................... 108
3.3.29.29 set sendprobes......................................................................... 108
3.3.29.30 set sessionautoresync.............................................................. 109
3.3.29.31 set sessionarrtimeout............................................................... 109
3.3.29.32 set sessiongclimit..................................................................... 109
3.3.29.33 set sessiondlimit....................................................................... 109
3.3.29.34 set sessionscan........................................................................ 109
3.3.29.35 set sessionscanbup.................................................................. 110
3.3.29.36 set sessionsync........................................................................ 110
3.3.29.37 set sessionsyncack................................................................... 111
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 6 / 146 Grnwald Germany / All Rights Reserved
3.3.29.38 set sessionsyncetype................................................................ 111
3.3.29.39 set sessionsynciv...................................................................... 111
3.3.29.40 set sessiontimeout ................................................................... 111
3.3.29.41 set stickytarget.......................................................................... 112
3.3.29.42 set strictrouting......................................................................... 112
3.3.29.43 set syncackbdelay.................................................................... 112
3.3.29.44 set syncackmaxps.................................................................... 113
3.3.29.45 set syncackresend.................................................................... 113
3.3.29.46 set syncackwsize...................................................................... 113
3.3.29.47 set vrrpmasterdown.................................................................. 113
3.3.29.48 set vrrppreempt.........................................................................113
3.3.29.49 set vrrppreemptts...................................................................... 114
3.3.29.50 set vrrpstateplugin.................................................................... 114
3.3.30 snatrange <from> <to>....................................................................... 114
3.3.31 softdisable target <n>......................................................................... 115
3.3.32 target <n>........................................................................................... 116
3.3.32.1 target <n> agent......................................................................... 116
3.3.32.2 target <n> agent6....................................................................... 116
3.3.32.3 target <n> ascript........................................................................ 117
3.3.32.4 target <n> alert........................................................................... 118
3.3.32.5 target <n> aoffset........................................................................ 118
3.3.32.6 target <n> ascale........................................................................ 118
3.3.32.7 target <n> autodisable................................................................ 119
3.3.32.8 target <n> autodisablecount....................................................... 119
3.3.32.9 target <n> dsr............................................................................. 119
3.3.32.10 target <n> ipaddr...................................................................... 120
3.3.32.11 target <n> ipaddr6.................................................................... 120
3.3.32.12 target <n> lgrp.......................................................................... 120
3.3.32.13 target <n> maxagent................................................................ 121
3.3.32.14 target <n> maxgrpsessions...................................................... 121
3.3.32.15 target <n> maxsessions...........................................................121
3.3.32.16 target <n> name....................................................................... 122
3.3.32.17 target <n> offset....................................................................... 122
3.3.32.18 target <n> ping ........................................................................ 123
3.3.32.19 target <n> ping6....................................................................... 124
3.3.32.20 target <n> port ......................................................................... 124
3.3.32.21 target <n> protocol................................................................... 125
3.3.32.22 target <n> pseudo.................................................................... 125
3.3.32.23 target <n> router....................................................................... 125
3.3.32.24 target <n> scale........................................................................ 125
3.3.32.25 target <n> screate.................................................................... 126
3.3.32.26 target <n> script....................................................................... 127
3.3.32.27 target <n> script6..................................................................... 127
3.3.32.28 target <n> sessiongroup........................................................... 127
3.3.32.29 target <n> sessionid <handler>................................................ 128
3.3.32.29.1 sip............................................................................................ 128
3.3.32.29.2 src............................................................................................ 128
3.3.32.29.3 src+dstport............................................................................... 128
3.3.32.29.4 src+port.................................................................................... 128
3.3.32.29.5 src+ports.................................................................................. 128
3.3.32.29.6 dst............................................................................................ 128
3.3.32.29.7 dst+port.................................................................................... 128
3.3.32.29.8 dst+ports.................................................................................. 128
3.3.32.29.9 dst+srcport............................................................................... 128
3.3.32.30 target <n> tcpopen................................................................... 128
3.3.32.31 target <n> tcpopen6................................................................. 129
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 7 / 146
3.3.32.32 target <n> upalert .................................................................... 129
3.3.32.33 target <n> trackval.................................................................... 130
3.3.32.34 target <n> via........................................................................... 130
3.3.32.35 target <n> weight...................................................................... 130
3.3.33 tnat..................................................................................................... 131
3.3.34 unregister........................................................................................... 131
3.3.35 vrrp.................................................................................................... 132
3.3.35.1 vrrp bscript .................................................................................132
3.3.35.2 vrrp mscript.................................................................................132
3.3.35.3 vrrp network ............................................................................... 133
3.3.35.4 vrrp priority................................................................................. 133
3.3.35.5 vrrp tracking................................................................................134
3.3.35.6 vrrp vrid...................................................................................... 134
4 SNMP Support........................................................................................... 135
4.1 Interfacing to Net-SNMP.....................................................................135
4.2 Accessing the SNMP interface directly...............................................136
4.3 Testing with snmpget and snmpwalk..................................................137
4.4 MRTG relevant metrics.......................................................................137
5 Logging ..................................................................................................... 139
6 Bngagent....................................................................................................140
6.1 Compiling Bngagent .......................................................................... 140
6.2 Starting and Stopping of Bngagent....................................................140
6.3 The Bngagent UDP Protocol.............................................................. 141
6.3.1 The Bngagent Protocol Request.......................................................... 141
6.3.2 The Bngagent Protocol Reply.............................................................. 142
6.4 Writing Bngagent Scripts.................................................................... 142
6.5 Bngagent Source Code...................................................................... 142
7 Technical Background Information..............................................................142
7.1 BalanceNG IPv4 MAC Addresses...................................................... 142
7.2 BalanceNG IPv6 MAC Addresses...................................................... 143
7.3 VRRP extensions............................................................................... 143
7.3.1 Type 2: BalanceNG V2 Session Table Sync Advertisement.................143
7.3.2 Type 3: BalanceNG V2 NAT State Sync Advertisement ......................144
7.3.3 Type 4: BalanceNG V3 Session Table Sync Advertisement.................144
7.3.4 Type 5: BalanceNG V3 GNAT State Sync Advertisement.................... 144
7.3.5 Type 6: BalanceNG V3 Session Table Sync ACK.................................144
8 Third Party Software Copyright Notices....................................................145
8.1 LDNS (DNS Library)........................................................................... 145
9 References.................................................................................................146
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 8 / 146 Grnwald Germany / All Rights Reserved
Legal Notices
Copyright 2005-2013, 2014 by Inlab Software GmbH, Josef-Wuerth-Str. 3, Gruenwald,
Germany. All Rights Reserved / Alle Rechte vorbehalten.
This product or document is protected by copyright and distributed under licenses restricting
its use, copying, distribution, and decompilation. No part of this product or document may be
reproduced in any form by any means without prior written authorization of Inlab Software
GmbH.
BalanceNG and Rbridge are registered trademarks of Inlab Software GmbH. Gentoo is a
trademark by Gentoo Technologies, Inc. Debian is a registered trademark of Software In The
Public Interest, Inc. FreeBSD is a registered trademark of Walnut Creek CDROM, Inc. Linux
is a registered trademark of Linus Torvalds. All other trademarks and registered trademarks
mentioned in this document are properties by their respective holders.
DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR FOR A PARTICULAR PURPOSE OR NON-
INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH
DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 9 / 146
1 Introduction
1.1 What is BalanceNG ?
BalanceNG ("Balance Next Generation") is a Software Load Balancing Solution utilizing its
own network stacks and functionality. In fact, BalanceNG uses the underlying operating
system only for accessing the physical interfaces, all TCP/IP and other functionality (like ARP
and ICMP) is being processed internally.
BalanceNG runs as a user mode program using the PF_PACKET API on Linux and the DLPI
API on Solaris to access the network interfaces as directly as possible.
With BalanceNG the Network or Data center Administrator is capable to build high availability
capable load balancing devices at a very low and very competitive price (compared to
dedicated hardware boxes / Load Balancing Appliances).
At the heart of BalanceNG's is Inlab's Ethernet Switch solution ("switch") which basically
converts a multi-homed system into an Ethernet Switch. This base implementation has been
used for several years in many products and test setups.
1. BalanceNG !eatures and S"eci#cations
Layer 2 (Ethernet) based load balancer.
Available for Linux-x86 (2.6 and 3.0 kernels) and Solaris 10 (SPARC and x86).
Linux distribution independent.
Capable to run in multiple instances on the same host.
Session persistence based on client address and optional source port.
Backup targets (hosts) specifable in case of failure of all primary targets.
Health checking via: PING, TCP Socket Open and freely customizable UDP Health Check
Agent (supplied in Source-Code).
External target specifc health check scripts.
Alert/Upalert notifcation scripts (e.g. for sending email or sending a SNMP trap to a
network management system).
Distribution methods: Round Robin, Simple Weighted Round Robin, Random, Weighted
Random, Client Address Hashing, Least Session, Least Bandwidth and Least Resource
based on agent supplied information.
Unchanged client addresses on IP-level.
Supports DSR (Direct Server Return) confgurations.
Small, very fast and reliable.
Simple to implement and administer.
Simple "init script style" arguments like "start", "stop" and "status" (and "control" for
interactive confguration and control).
Interactive communications mode with command line editing.
Pcap packet dumping with automated dumpfle rotation (e.g. to implement a "transparent
forensic logging bridge").
Multi-node High Availability capability using standard VRRP (Virtual Router Redundancy
Protocol).
Session table synchronization and connection state replication using a BalanceNG-
specifc VRRP extension.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 10 / 146 Grnwald Germany / All Rights Reserved
"All service load balancing" based on client IP address enables most protocols to be
supported (e.g. active FTP, RTSP/RTP/RTCP streaming protocols etc).
SNMP Support integrating into Net-SNMP.
Layer 3 link load balancing to a set of outbound routers or ISP links.
Supports up to 512 virtual servers and up to 1024 targets (real servers).
Location-Based Load-Balancing Support.
I-memory IP-to-Location database.
DNS-based GSLB-support (Global Server Load-Balancing).
1.$ %ard&are and 'S (e)uire*ents
1.$.1 Linu+
BalanceNG runs under most x86 Linux implementations using Kernel revisions 2.6 or 3.0.
BalanceNG is distribution independent and should run on any distribution supporting 2.6 / 3.0
kernels.
Known distributions which support BalanceNG are:
Ubuntu Linux
Gentoo Linux
Redhat
Fedora Linux
CentOS
Debian
Slackware Linux
SUSE Linux (Novell)
All network adapter cards which are either compiled into the kernel or available as a module
are supported.
There is no package manager dependency as BalanceNG comprises a single, statically
linked binary that can be installed manually anywhere on the host system
Memory recommendation: 128 Megabytes minimum, 512 Megabytes recommended.
Processor minimum requirement: 1Ghz for 2 x 1000BaseT interfaces and a 100BaseT
management network
1.$. Solaris
BalanceNG is supported on the following Solaris platforms:
Solaris 10 (SPARC)
Solaris 10 (x86)
1., BalanceNG Core Conce"ts
In order to understand the simplicity of BalanceNG it's important to know about the
BalanceNG core concepts, here the basics:
1.,.1 Interfaces
Interfaces are the physical hardware interfaces to one or more networks. They are named like
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 11 / 146
the underlaying Linux kernel names them (like eth0, eth1 and so on).
BalanceNG uses the interfaces that it is allowed to use, this is done by specifying a
corresponding interface section.
Interfaces don't have to be "up" or confgured, BalanceNG performs all necessary
administrative tasks automatically. Also it is neither required or necessary to confgure
interface addresses in the Linux operating system.
1.,. Net&or-s
Networks are IPv4 network defnitions the have a network address and a network mask.
Additionally one or more interfaces are being referenced by the BalanceNG network
defnition.
On a UNIX system an interface has one or more associated network defnitions and
addresses, in the BalanceNG world this relation is reversed: One network defnition (and the
addresses) are associated to one or many interfaces.
Each network defnition additionally has to have two required IPv4 addresses: The "real"
address being used for ARP-requests and healthchecks and the "virt" address being
addressable as a routing endpoint for external devices. The "real" network address has to be
node specifc, the "virt" address has to be shared between multiple BalanceNG nodes in a
VRRP HA confguration.
1.,.$ Ser.ers
Servers are the addressable "virtual Servers" in the BalanceNG world. Servers are "virtual" or
"artifcial" IP addresses represented by BalanceNG. Network requests to those servers are
distributed among the targets according to the load balancing defnitions.
Servers may be defned in any BalanceNG network referencing targets in any BalanceNG
network.
Note: BalanceNG servers would be called "virtual servers" by other load balancing software
vendors.
1.,., Targets
BalanceNG represents one or more virtual servers and distributes the requests among a set
of targets associated with each virtual server.
Note: BalanceNG targets would be called "real servers" by other load balancing software
vendors.
1.,./ 0odules
BalanceNG implements several packet handling modules. The functionality of BalanceNG is
defned by the module chain, which defnes a sequential order of modules. Each packet
enters that module chain at the left side and is forwarded until a module gains responsibility
for that packet. After some processing, the module in charge may decide to stop processing
or may decide to forward a possibly changed packet to the next module in the module chain.
1.,.1 Threads
BalanceNG operated multi-threaded when the multi-threading packet scheduler is active. One
BalanceNG interface may be operated by 1 to 8 simultaneous threads.
1.,.2 Con#guration and Con#guration !iles
The behaviour and actions of BalanceNG are controlled by its internal confguration. This
confguration may be altered in interactive mode by entering confguration commands. An
external representation of this confguration may be saved to /etc/bng.conf, BalanceNG loads
an existing confguration in /etc/bng.conf automatically at startup (default instance 0).
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 12 / 146 Grnwald Germany / All Rights Reserved
A BalanceNG confguration consists of the following sections in exactly that order:
1. hostname, remark, license
2. module chain defnition
3. parameter settings ("set"-section)
4. interfaces section
5. interfaces register/enable section
6. vrrp-section
7. network defnitions
8. network register/enable section
9. IPDB section
10. lgrp (Location Group) section
11. gateway section
12. server defnitions
13. server register/enable section
14. target section
15. target register/enable section
BalanceNG makes use of the following confguration fles:
3etc3bng.global Global confguration fle for all instances
3etc3bng.conf Standard confguration fle for BalanceNG default instance 0
3etc3bngN.conf Confguration fle for BalanceNG instance N (N: 1 ... 127)
3etc3bng."ri.ate Node specifc private data for BalanceNG default instance 0
3etc3bngN."ri.ate Node specifc private data for BalanceNG instance N (N: 1 ... 127)
Note4 It's safe to copy the main confguration fle (/etc/bng.conf) from a master node to the
backup if the node private data has been saved on the other side before ("save private"). This
allows easy implementation of confguration synchronization scripts between nodes of the
same VRRP virtual router.
1.,.5 Instances
BalanceNG may be started independently multiple times on the same host machine (node).
Each invocation is called an instance of BalanceNG and has an unique instance number in
the range of 0 ... 127. BalanceNG instance 0 is called the default instance.
1.,.6 I78B9 Locations and Location:Grou"s
BalanceNG supports a very effcient, in-memory IP-to-Location database (IPDB). This
database associates ranges in the Ipv4 address space to a set of locations, which are usually
2-Letter codes as "US", "DE" and "AT", for example. These location may be logically grouped
using the BalanceNG "location groups" (LGRP's). Eventually, a target may be a member of
exactly one location. The whole feature set allows easy setup of very powerful "location based
server load balancing".
1./ BalanceNG 8esign
BalanceNG is implemented in C based on a multithreading switching engine. BalanceNG
additionally uses multithreading (POSIX threads / pthreads) to operate different helper
threads which communicate with the core multithreading switching engine.
These threads are used for the target specifc health check scripts and the alert/upalert
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 13 / 146
scripts (see the "target <n> script", target <n> alert" and "target <n> upalert" commands).
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 14 / 146 Grnwald Germany / All Rights Reserved
Initial I*"le*entation
.1 %ard&are selection
BalanceNG runs under nearly all Linux x86 systems with a 2.6 or 3.0 kernel, hence the
choice of hardware is extensive. Please bear in mind that in any case the BalanceNG
licensing (Full License) is hardware dependent, therefore it is recommended that the fnal
deployment hardware be purchased prior to license purchase.
For pre-implementation and evaluation testing, you may use the test license implicitly
supplied with the software (Basic License, for restrictions see section 2.5).
If you have a free choice of hardware, then the following is recommended:
Choose 2 identical nodes (If High Availability is required).
Use of a separate interface for administrative purposes and then as many 100/1000BaseT
interfaces for traffc as required. We have found that Intel Gigabit Adapter Cards (or chip
sets) work very well.
If gigabit performance is required select a machine with two (or more) on board gigabit
interfaces avoiding PCI bandwidth problems. Use the fastest processor you can get.
Install the Linux distribution of choice. You may utilize one of the special embedded Linux
distributions which do not require a hard disk.
If you wish to use a separate or multiple networks, an additional Ethernet switch (or VLAN)
will probably be required.
There's a benchmark functionality, see the "benchmark" command and take a look at the
benchmark results page at http://www.inlab.de/balanceng/bmresults.html .
. Net&or- Setu"
A common setup of BalanceNG comprises the following topology (pictured below): A local
IPv4 network connected via a router to an external network (e.g. the Internet) and via one or
more BalanceNG nodes to the target network.
We refer to the the network connected to the Router the "Access Network", and the network
to which the Targets are connected the "Target Network".
Running BalanceNG "single legged" allows integration of BalanceNG into an already existing
network installation.
Note: The real physical servers are called "Targets" in the BalanceNG world.
Note: Talking about "Servers" within BalanceNG refers to "Virtual Servers" being presented
by BalanceNG.
BalanceNG Servers perform load balancing over one or more BalanceNG Targets.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 15 / 146
!igure 14 Co**on BalanceNG Net&or- Setu"
!igure 4 ;Single Legged; Net&or- setu"
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 16 / 146 Grnwald Germany / All Rights Reserved
.$ Installation
.$.1 Installation on Solaris
BalanceNG for Solaris is distributed as a standard, platform independent package which has
to be installed with the "pkgadd" command of Solaris.
Note: BalanceNG has to be installed on the global zone if installed on Solaris 10.
A typical installation dialog looks as follows (text entered shown in bold):
# ls
BalanceNG-3.504-Solaris-pkg.gz
# gunzip BalanceNG-3.504-Solaris-pkg.gz
# pkgadd -d BalanceNG-3.504-Solaris-pkg
The following packages are available
! BalanceNG BalanceNG - Sof"ware #$ %oa& Balancer
'i3()*S$+,-. 3.504
Selec" package's. /o0 wish "o process 'or 1all1 "o process
all packages.. '&efa0l" all. 23433456<enter>
$rocessing package ins"ance 7BalanceNG8 fro9 7:"9p:BalanceNG-3.504-Solaris-pkg8
BalanceNG - Sof"ware #$ %oa& Balancer'i3()*S$+,-. 3.504
-op/righ" 'c. ;0!0 b/ #nlab Sof"ware G9b<4 Gr0enwal&4 Ger9an/.
+ll righ"s reserve& : +lle ,ech"e vorbehal"en.
=isi" h""p::www.BalanceNG.ne" for f0r"her infor9a"ion.
## >?ec0"ing checkins"all scrip".
@sing 7:op"8 as "he package base &irec"or/.
## $rocessing package infor9a"ion.
## $rocessing s/s"e9 infor9a"ion.
## =erif/ing &isk space re50ire9en"s.
## -hecking for conflic"s wi"h packages alrea&/ ins"alle&.
## -hecking for se"0i&:se"gi& progra9s.
This package con"ains scrip"s which will be e?ec0"e& wi"h s0per-0ser
per9ission &0ring "he process of ins"alling "his package.
Ao /o0 wan" "o con"in0e wi"h "he ins"alla"ion of 7BalanceNG8 2/4n436 y
#ns"alling BalanceNG - Sof"ware #$ %oa& Balancer as 7BalanceNG8
## #ns"alling par" ! of !.
:op":BalanceNG:B+%+N->NG-B#B."?"
:op":BalanceNG:%#->NS>
:op":BalanceNG:,>+AB>
:op":BalanceNG:bng-Solaris-i3()
:op":BalanceNG:bng-Solaris-sparc
:op":BalanceNG:bng-ini"scrip"
:op":BalanceNG:bngagen"-%in0?-i3()
:op":BalanceNG:bngagen"-Solaris-i3()
:op":BalanceNG:bngagen"-Solaris-sparc
:op":BalanceNG:bngagen".c
:op":BalanceNG:bngfil"3;-i3()
:op":BalanceNG:bngfil")4-i3()
:op":BalanceNG:bngfil")4-sparc
:op":BalanceNG:con"rib:Bng+gen"Service.zip
:op":BalanceNG:con"rib:,>+AB>
2 verif/ing class 7none8 6
## >?ec0"ing pos"ins"all scrip".
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 17 / 146
#ns"alla"ion of 7BalanceNG8 was s0ccessf0l.
#
The results of this installation are:
1. The BalanceNG binary is available as /usr/bin/bng
2. The bngflt STREAMS module is installed
3. The /etc/init.d scripts are setup to start BalanceNG on reboot (if /etc/bng.conf exists)
4. The remaining distribution fles are available in the directory /opt/BalanceNG.
The removal of BalanceNG is done by a simple "pkgrm BalanceNG".
.$. Installation on Linu+ <8ebian3=buntu 7ac-age>
The installation on Debian and Ubuntu i386 systems using the ".deb" package distribution is
very easy. A typical command line installation looks like this:
# ls BalanceNGC
BalanceNGD3.504Di3().&eb
# &pkg -i BalanceNGD3.504Di3().&eb
Selec"ing previo0sl/ &eselec"e& package balanceng.
',ea&ing &a"abase ... ;00E3 files an& &irec"ories c0rren"l/ ins"alle&..
@npacking balanceng 'fro9 BalanceNGD3.504Di3().&eb. ...
Se""ing 0p balanceng '3.504. ...
The BalanceNG binary installs in /sbin/bng in that case. Init scripts are also setup starting all
active instances automatically on startup (if a confg fle exists of that instance). The .deb
package does not include any confguration fles (like /etc/bng.conf or /etc/bng.global).
Removing BalanceNG works like this:
# &pkg -r BalanceNG
',ea&ing &a"abase ... ;00E5 files an& &irec"ories c0rren"l/ ins"alle&..
,e9oving balanceng ...
BalanceNG no" r0nning
#
.$.$ Installation on Linu+ <tarball>
The Linux Distribution of BalanceNG comes as a tar archive as well, containing the
BalanceNG binary.
The download fle is a "gzipped" tar archive (BalanceNG-7version8-7FS8-
7archi"ec"0re8."ar.gz) located wherever you downloaded it.
Please extract this tar archive using the ""ar" command as follows (example, assuming
BalanceNG 3.504 for Linux downloaded into /tmp):
# c& :"9p
# ls BalanceNGC
BalanceNG-3.504-%in0?-?()."ar.gz
# "ar ?vfz BalanceNG-3.504-%in0?-?()."ar.gz
.:BalanceNG-3.504-%in0?-?():
.:BalanceNG-3.504-%in0?-?():,>+AB>
.:BalanceNG-3.504-%in0?-?():%#->NS>
.:BalanceNG-3.504-%in0?-?():bng
.:BalanceNG-3.504-%in0?-?():bngagen"
.:BalanceNG-3.504-%in0?-?():bngagen".c
.:BalanceNG-3.504-%in0?-?():bngagen"-binaries:
.:BalanceNG-3.504-%in0?-?():bngagen"-binaries:bngagen"-!.4;-SolarisE-S$+,-
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 18 / 146 Grnwald Germany / All Rights Reserved
.:BalanceNG-3.504-%in0?-?():bngagen"-binaries:bngagen"-!.4;-%in0?-?()
.:BalanceNG-3.504-%in0?-?():bngagen"-binaries:bngagen"-!.4;-Solaris!0-?()
.:BalanceNG-3.504-%in0?-?():bngfil"-binaries:
.:BalanceNG-3.504-%in0?-?():bngfil"-binaries:bngfil"3;-S$+,-
.:BalanceNG-3.504-%in0?-?():bngfil"-binaries:bngfil"3;-G()
.:BalanceNG-3.504-%in0?-?():bngfil"-binaries:bngfil")4-S$+,-
.:BalanceNG-3.504-%in0?-?():bngfil"-binaries:bngfil")4-G()
.:BalanceNG-3.504-%in0?-?():bngfil"-binaries:,>+AB>
.:BalanceNG-3.504-%in0?-?():con"rib:
.:BalanceNG-3.504-%in0?-?():con"rib:Bng+gen"Service.zip
.:BalanceNG-3.504-%in0?-?():con"rib:,>+AB>
#
The fles extracted are:
(EA80E Describes where to obtain BalanceNG
LICENSE Is a copy of the End User License Agreement
bng Is the BalanceNG application executable binary
bngagent?.c@ Are the executable and source for the BalanceNG agent
Additional directories of the distribution are:
bngagent:binaries Precompiled bngagent binaries for different platforms
bng#lt:binaries Solaris bngflt STREAMS module binaries
contrib Customer contributions without warranty and support
Note: The distribution may contain additional directories and fles which are not mentioned
here.
The executable "bng" should be copied to a suitable location. Since BalanceNG is init-script
compatible we recommend to copy it to :e"c:ini".&, the default location for init scripts, as
follows:
# cp .:BalanceNG-3.504:bng :e"c:ini".&
Finally you could verify the modes and ownership which should be as follows:
# ls -l :e"c:ini".&:bng
-rw?r-?r-? ! roo" roo" ;!4;)( +pr ; ;;0H :e"c:ini".&:bng
#
N'TE: Some Linux distributions (notably Gentoo Linux) do not permit executable binaries
in /etc/init.d, in this case bng should be installed in /usr/sbin.
., 0a-ing BalanceNG Turn-eA
.,.1 0a-ing BalanceNG Turn-eA on Solaris
There are no further actions required on Solaris, the /etc/init.d/-Scripts are all setup.
BalanceNG is started during reboot if a confguration fle is present in /etc/bng.conf .
.,. 0a-ing BalanceNG Turn-eA on Linu+
If you wish to have BalanceNG started automatically at system boot (Turnkey), you must
confgure your system to execute "bng start" on boot.
Note4 This step is only needed with the tarball distribution of BalanceNG, the Debian/Ubuntu
package already contains the necessary init.d scripts.
The standard method is to provide a link from the binary "bng" wherever it is located to the
required run-level directory. This is normally achieved as follows:
Linking /etc/init.d/bng to a run-level directory and name, for example on a Fedora 3
release "ln -s /etc/init.d/bng /etc/rc5.d/S11bngI.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 19 / 146
Some Linux distributions do not support this method, please see table below, or refer to your
distribution's documentation.
In the Linux realm we recommend the following:
Linux
Distribution
Notes
Gentoo Linux installing binary in /usr/sbin
adding the line "/usr/sbin/bng start" to /etc/init.d/local.start
adding the line "/usr/sbin/bng stop" to /etc/init.d/local.stop
Fedora Linux standard method
Redhat Linux Package (.rpm)
CentOS Linux Package (.rpm)
Debian Linux Package (.deb)
Ubuntu Linux Package (.deb)
SUSE SLES Package (.rpm)
Table 14 Turn-eA Installation Notes
.,.$ 0ulti:Instance init.d Scri"t
Using the "bng -I" command line option it's possible to implement a init.d script which starts
and stops all instances on a host machine with just one init script. Such a script could look
like the following (just edit the DAEMON variable accordingly):
#J:bin:sh
$+T<K:sbin:0sr:sbin:bin:0sr:bin
N+B>Kbng
A+>BFNK:0sr:bin:LN+B>
case IL!I in
s"ar".
for i in MLA+>BFN -# N :0sr:bin:awk 1Oprin" L!P1M
&o LA+>BFN s"ar" Li
&one
e?i" 0
QQ
s"op.
for i in MLA+>BFN -# N :0sr:bin:awk 1Oprin" L!P1M
&o LA+>BFN s"op Li
&one
e?i" 0
QQ
s"a"0s.
for i in MLA+>BFN -# N :0sr:bin:awk 1Oprin" L!P1M
&o LA+>BFN s"a"0s Li
&one
e?i" 0
QQ
res"ar"Nforce-reloa&.
for i in MLA+>BFN -# N :0sr:bin:awk 1Oprin" L!P1M
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 20 / 146 Grnwald Germany / All Rights Reserved
&o LA+>BFN res"ar" Li
&one
e?i" 0
QQ
C.
echo I@sage bng Os"ar"Ns"opNres"ar"Nforce-reloa&PI 8R;
e?i" 3
QQ
esac
./ 8eter*ining the Nodeid and Licensing
To obtain a full license for BalanceNG you require the nodeid of your hardware. The nodeid is
a 6 byte hexadecimal number similar to an Ethernet address (the actual nodeid is derived
from several system parameters: The MAC address of Ethernet interface 0 (eth0), CPU and
PCI-bus parameters).
Alternatively, you may use the "virtual nodeid" (vnodeid) for licensing. The vnodeid is based
on the Ipv4 address of the primary interface only and is therefore hardware independent.
The yearly subscription license is technically the same as the "full node license".
To determine the nodeid of your installation:
Start BalanceNG:
# bng s"ar"
BalanceNG s"ar"ing 0p ...
#
Open the interactive mode of BalanceNG using:
# bng con"rol
BalanceNG connec"e& "o $#A ()E;
bng#
Enter the command to display the nodeid of the current machine:
bng# show no&ei&
baeEH5;)3)ab
bng#
Alternatively you may enter the command to display the vnodeid of the current machine:
bng# show vno&ei&
;!0)5e;4Haf3 'in"erface e"h0.
bng#
Note that the nodeid and the vnodeid of all instances are the same. Retrieving the nodeid of
instance 2 looks like this:
# bng s"ar" ;
BalanceNG s"ar"ing 0p ins"ance ; ...
#
Open the interactive mode of BalanceNG using:
# bng con"rol ;
BalanceNG connec"e& "o ins"ance ; $#A ;H(!)
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 21 / 146
bng#
Enter the command to display the nodeid of the current BalanceNG instance 2:
bng# show no&ei&
baeEH5;)3)ab
bng#
This allows you to use the same licensing key for all instances, currently there's a theoretical
limit of 128 concurrent BalanceNG instances on the same host machine.
When you receive the license key(s) for your node(s), use the "license" command on each
node to apply the relevant license. Use the "save" command to save the license information
to /etc/bng.conf. An example license session is shown below:
# bng con"rol
BalanceNG connec"e& "o $#A ()E;
bng#
bng# show license
s"a"0s vali& f0ll license
serial be"aB04(
no&ei& ;ae;Ef3(&a;0
"/pe Ishow versionI for version an& -op/righ" infor9a"ion
bng# save
ok
bng# ... b/e
Now your BalanceNG installation is fully licensed and ready for operation.
.1 Licensing of all Instances in 3etc3bng.global
BalanceNG may be started multiple times at the same time (with many instances). The
nodeid of all instances is exactly the same. In order to license all instances on the machine
just put the "license" instruction as explained above into the /etc/bng.global fle.
This fle is evaluated by each instance of BalanceNG right at the beginning, so it may also be
used for other global settings.
Example:
# ca" 8 :e"c:bng.global 77>FS
license be"aB04( 45f;E)fcEb3(HfH5H)b4E&0ceab3fE;e
>FS
# bng s"ar" !;
BalanceNG s"ar"ing 0p ins"ance !; ...
# bng c"l !;
BalanceNG connec"e& "o ins"ance !; $#A !3)53
bng# show license
s"a"0s vali& f0ll license
serial be"aB04(
no&ei& ;ae;Ef3(&a;0
"/pe Ishow versionI for version an& -op/righ" infor9a"ion
bng#
.2 BBasic licenseC restrictions
You may use BalanceNG for an evaluation for an unlimited and unspecifed period of time
(please check the LICENSE fle or the license on the BalanceNG web site).
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 22 / 146 Grnwald Germany / All Rights Reserved
For this "Basic License" the following restrictions are enforced:
You may only specify and activate ONE virtual server (server 1) for testing load balancing
features (The fully licensed BalanceNG supports up to 512 virtual servers).
You may only specify and activate TWO targets for testing load balancing features (The
fully licensed BalanceNG supports up to 1024 targets / real servers).
VRRP (Virtual Router Redundancy Protocol) HA (High Availability) functions are disabled.
There are free advanced dual node test licenses available which enable VRRP and allow
unrestricted number of servers and targets. Please consult the BalanceNG web site
(http://www.BalanceNG.net) for details.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 23 / 146
$ Co**and (eference
$.1 Co**and Line Interface
The Command Line Interface is designed in such a way, that BalanceNG may be directly
linked as an init-Script e.g. from :e"c:ini".&:bng -8 :e"c:rc5.&:SE0bng. There is
no need to implement additional init scripts.
The BalanceNG binary is called "bng" and should be installed in :e"c:ini".& 'another
possibility is installing it to :0sr:sbin linked to :e"c:ini".&..
Invoking BalanceNG requires root permissions (e0i& KK 0) since BalanceNG has to be
able to directly control the network interfaces.
$.1.1 bng
Invoking BalanceNG with no option displays the usage information together with some
Copyright information.
Example:
# :e"c:ini".&:bng
DDDDDD DD DDDDDDD DDDDDDD
N DD T.---.-.N N.---.-.-----.----.-----.N N N DDN
N DD 7N D NN NN D N N DDN -DDNN N N N
NDDDDDD:NDDD.DNNDDNNDDD.DNDDNDDNDDDDNDDDDDNNDDNDDDDNDDDDDDDN
This is BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
-op/righ" '-. ;005-;0!34;0!4 b/ #nlab Sof"ware G9b<4 Ger9an/.
+ll righ"s reserve& : +lle ,ech"e vorbehal"en.
=isi" h""p::www.BalanceNG.ne" for f0r"her infor9a"ion.
0sage bng 2-&f6 s"ar"Ns"opNres"ar"Ns"a"0sNcon"rol 2ins"ance6
#
The option -f requests that BalanceNG should stay in foreground, -& is being used for
generating debugging information and implicitly sets -f.
BalanceNG may be started in multiple instances representing as many independent software
load balancers on the same machine as desired. Instance 0 is the default instance (if no
instance is specifed).
$.1. bng start ?instance@
This starts BalanceNG in the background as a daemon. BalanceNG reads as a frst step the
confguration from /etc/bng.conf (if it exists) and commences operation.
BalanceNG may be started in multiple instances supplying an optional integer parameter
ranging from 0 up to and including 128. If the instance parameter is omitted the default
instance 0 is assumed.
Example:
# :e"c:ini".&:bng s"ar"
BalanceNG s"ar"ing 0p ...
#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 24 / 146 Grnwald Germany / All Rights Reserved
# :e"c:ini".&:bng s"ar" 4!
BalanceNG s"ar"ing 0p ins"ance 4! ...
#
If there's already a BalanceNG running on this machine the output may look like as follows:
Example:
# :e"c:ini".&:bng s"ar"
BalanceNG alrea&/ r0nning wi"h $#A HE!4
#
$.1.$ bng sto" ?instance@
This stops the current running BalanceNG process (or the specifed instance), the output may
look like this:
Example:
# :e"c:ini".&:bng s"op
BalanceNG sh0"&own of $#A HE!4 co9ple"e
#
# .:bng s"op 4!
BalanceNG sh0"&own of ins"ance 4! $#A ;H;3! co9ple"e
#
$.1., bng reload ?instance@
This command issues a CLI "reload" command (see "reload"), the requested instance needs
to be running. A third command channel is used to avoid any race conditions (see "bng
cmdctl").
$.1./ bng restart ?instance@
This restarts BalanceNG (or the specifed instance) and is equivalent to execute "bng s"op"
and "bng s"ar"" .
Example:
# :e"c:ini".&:bng res"ar"
BalanceNG sh0"&own of $#A HE!E co9ple"e
BalanceNG s"ar"ing 0p ...
#
# :e"c:ini".&:bng res"ar" 4!
BalanceNG sh0"&own of ins"ance 4! $#A ;H4!E co9ple"e
BalanceNG s"ar"ing 0p ins"ance 4! ...
#
$.1.1 bng status ?instance@
This provides information about the current status of BalanceNG (or the specifed instance).
Example:
# :e"c:ini".&:bng s"a"0s
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
Copyright 2005-2013,2014 by Inlab Software GmbH
Grnwald, Germany / All Rights Reserved Page 25 / 146
BalanceNG r0nning wi"h $#A HE;!
# :e"c:ini".&:bng s"op
BalanceNG sh0"&own of $#A HE;! co9ple"e
# :e"c:ini".&:bng s"a"0s
BalanceNG no" r0nning
#
# :e"c:ini".&:bng s"a"0s 4!
BalanceNG ins"ance 4! r0nning wi"h $#A ;H4;3
# :e"c:ini".&:bng s"op 4!
BalanceNG sh0"&own of ins"ance 4! $#A ;H4;3 co9ple"e
# :e"c:ini".&:bng s"a"0s 4!
BalanceNG ins"ance 4! no" r0nning
#
$.1.2 bng ?:e@ c*dctl ?instance@
This connects to a third, additional control interface of the instance (if specifed). This
particular interface is reserved for internal purposes and used by the "bng reload" command.
If the option "-e" is specifed, this command exits with EX_TEMPFAIL if the same command
frontend is already running.
$.1.5 bng ?:e@ i*sctl ?instance@
This connects to a fourth control interface of the instance (if specifed). This control interface
may be used for other automatic purposes that must not interfere with "bng cmdctl" or "bng
reload".
If the option "-e" is specifed, this command exits with EX_TEMPFAIL if the imsctl command
frontend is already running.
$.1.6 bng ?:e@ control ?instance@
This invokes the interactive confguration mode of BalanceNG (or the instance if specifed).
The shell invocation "bng control" may be abbreviated as "bng ctl".
If the option "-e" is specifed, this command exits with EX_TEMPFAIL if the same command
frontend is already running.
This is indicated by a prompt, the default is: "bng#".
Example:
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A HE;(
bng#
# :e"c:ini".&:bng res"ar" 4!
BalanceNG no" /e" r0nning
BalanceNG s"ar"ing 0p ins"ance 4! ...
# :e"c:ini".&:bng con"rol 4!
BalanceNG connec"e& "o ins"ance 4! $#A ;H4HE
bng#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
Copyright 2005-2013,2014 by Inlab Software GmbH
Page 26 / 146 Grnwald Germany / All Rights Reserved
Typing EOF (Ctrl-D) exits the interactive confguration mode.
The interactive confguration mode allows simple command line editing using the arrow-keys.
This is only active is an interactive terminal is detected on stdin, otherwise the command line
editing option is switches off to allow automated programs to operate on the command line.
The following command line editing capabilities are currently supported:
arro& u" move up to previous command line
arro& do&n move down to next command line in history
arro& left move cursor left
arro& right move cursor right
bac-s"ace9 D% or 8EL delete character before cursor
D8 exit to operating system shell
D= erase all characters left of cursor
DW erase word left of cursor
If the lexical scanning process fnds the token "//" this token and the rest of the line is ignored
(this is being used for adding timestamps and version stamps to the confguration fle).
It's also possible to pipe a command into BalanceNG invoked with "bng control" like this:
ec!o "s!o# targets" $ bng control
bng s!o# targets
ipaddr port prt net sr% sessions status na&e
--------------------------------------------------------------------------
' '().'(.).*0 any any ' ' 0 operational
bng