BalanceNG V3 Manual

Published on February 2017 | Categories: Documents | Downloads: 50 | Comments: 0 | Views: 298
of 146
Download PDF   Embed   Report

Comments

Content


BalanceNG
®
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-Würth-Str. 3
82031 Grünwald
Germany
Tel.: +49 89 64911420
Fax: +49 89 64911421
Email: [email protected]
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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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
Grünwald, 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 Grünwald 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

In general commands may be abbreviated interactively as long as there are no ambiguities.
$.1.1E bng ?:e@ au+ctl ?instance@
This connects to a second, auxiliary control interface of the instance if specifed. This
interface is intended to be reserved for external programs and user interfaces offering exactly
the same functionality as "bng control".
If the option "-e" is specifed, this command exits with EX_TEMPFAIL if the same command
frontend is already running.
$.1.11 bng "urge ?instance@
This command removes the associated confguration fle of the supplied instance without any
further warnings. The instance needs to be down (off) for that purpose. If no instance is
specifed, the confguration fle /etc/bng.conf of the default instance is deleted.
A private confguration data fle (e.g. /etc/bng.private) is not deleted by this command.
Example:
# bng -#
0 off
3 off
# bng p0rge 3
BalanceNG :e"c:bng3.conf s0ccessf0ll/ &ele"e&
#
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 27 / 146
$.1.1 bng :I
This command displays information about the state of all instances of BalanceNG on the
system. "running" indicates a running instance whereas "off" indicates an available
confguration fle.
Example:
# bng -#
0 off
# bng s"ar" 3
BalanceNG s"ar"ing 0p ins"ance 3 ...
# bng -#
0 off
3 r0nning
# bng c"l 3
BalanceNG connec"e& "o ins"ance 3 $#A !4;HH
bng# save
ok
bng# ... b/e
# bng s"op 3
BalanceNG sh0"&own of ins"ance 3 $#A !4;HH co9ple"e
# bng -#
0 off
3 off
#
$.1.1$ bng :L
This commands allows to check the validity of a serial number and a license key for the
current node. It requires two arguments, the serial number and the license key. If the license
information is valid the invocation of bng returns the Linux/Solaris return code 0 (77
otherwise).
Example:
# bng -% T>ST 3befEfa)b3!acec)f)4abc!);b3&cb&a
# echo L3
0
$.1.1, bng :N
This command displays the BalanceNG nodeid of the BalanceNG host machine without the
need for starting a BalanceNG instance. The nodeid is needed for licensing purposes.
Example:
# bng -N
;ae;;f3(4a;0
#
$.1.1/ bng :W
This command option expects two arguments, a serial number and a license key. If the
license is valid a "license" line with those parameters is written to the fle /etc/bng.global
without further warning.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 28 / 146 Grünwald Germany / All Rights Reserved
$. Ad*inistrati.e and Infor*ational Co**ands
$..1 bench*ar-
Synopsis: bench9ark 7sen&-if8 7rcv-if8
This command executes a hardware, OS and network benchmark in the background
controlled by the parameters "bmduration", "bmpsize" and "bmwsize" (see "set" command
below). The results and/or status can be shown with "show benchmark".
This command requires the "benchmark" module being loaded ("module benchmark").
Example:
bng# 9o&0le bench9ark
bng# in"erface e"h0
bng# in"erface e"h!
bng# bench9ark e"h0 e"h!
bng# show bench9ark
bench9ark ac"ive an& r0nning
&0ra"ion 'secon&s. 300
packe"size !5!4
win&ow size !)
packe"s sen" ;!;E;!
packe"s receive& ;!;E05
secon&s re9aining ;E4
bng# show bench9ark
bench9ark finishe& wi"h "he following res0l"s
&0ra"ion 'secon&s. 300
packe"size !5!4
win&ow size !)
packe"s sen" !0HEH!5(
packe"s receive& !0HEH!4;
los" packe"s 0
packe"s per secon& 35EE0
b/"es per secon& 544(E5HH
bng#
$.. chec-
Synopsis: check
A check of the current active confguration is performed. This is especially targeted towards
the confguration of Servers and Targets. A warning is being issued at the following conditions:
• A Target is references by multiple Servers
• A Target is enabled, but not referenced at all
This function is implicitly called when Servers or Targets are entering the enabled state.
Example (no Warning):
bng!# check
bng!#
Example (with Warnings):
bng!# check
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 29 / 146
U+,N#NG "arge" ! alrea&/ reference& fro9 server !
U+,N#NG "arge" ! reference fro9 server ( ignore&
U+,N#NG "arge" ; alrea&/ reference& fro9 server !
U+,N#NG "arge" ; reference fro9 server ( ignore&
bng!#
$..$ clear
Synopsis: clear 7i"e98
This command clears counters which are maintained for informational purposes.
"clear ?" shows a list of supported items like in this Example:
bng# clear 3
available i"e9s
loca"ionco0n"ers #$AB loca"ion co0n"ers
bng#
"clear locationcounters" clears the counters which are shown by the "show locations"
command. A typical dialog may look like this:
bng# clear loca"ionco0n"ers
bng# show loca"ions
ke/ co0n"er &escrip"ion
--- -------- ------------------------------------
+A +NAF,,+
+> @N#T>A +,+B >B#,+T>S
+S +SG<+N#ST+N
...
VT B+VFTT>
W+ SF@T< +S,#-+
WB W+BB#+
WU W#BB+BU>
- CCC NFT SF@NA $S>@AF >NT,V CCC
--- -------- ------------------------------------
;35 0 "o"al
bng#
$.., coredu*"
Synopsis: core&09p
This command deferences a NULL pointer in the BalanceNG main thread and initiates a core
dump to be written (if the OS settings allow this). This command if for debugging purposes
only.
$../ hel"
Synopsis: help
Displays the main help information about available commands.
Example:
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 30 / 146 Grünwald Germany / All Rights Reserved
bng# help
available co99an&s4 "/pe >FS 'XA. "o e?i"
arp 7ip48 &eclare #$ a&&ress "o be +,$-resolve&
bench9ark 7ifsen&8 7ifrcv8 perfor9 BalanceNG loopback bench9ark
check perfor9 config0ra"ion check
clear 7i"e98 clear co0n"er '"/pe Iclear 3I for help.
co99i" 7i"e98 7n09ber's.8 regis"er an& enable ne"works:servers:"arge"s
core&09p &09p core i99e&ia"el/
&isable 7i"e98 7n09ber's.8 &isable ne"works:servers:"arge"s
&09p 7if8 7&ir8 pcap &09p "raffic on 7if8 "o 7&ir8
e&i" 7i"e98 7n09bers8 &isable*0nregis"er ne"works:servers:"arge"s
enable 7i"e98 7n09ber's.8 enable ne"works:servers:"arge"s
ga"ewa/ ... ga"ewa/ co99an&s 'see Ihelp ga"ewa/I.
help &ispla/ "his infor9a"ion
help 7"opic8 &ispla/ "opic specific infor9a"ion4 3 for lis"
hos"na9e 7na9e8 specif/ na9e of "his BalanceNG ins"ance
inYec" 7if8 7pcap8 7s8 27e86 inYec" packe"s fro9 pcap file
in"erface ... in"erface co99an&s 'see Ihelp in"erfacesI.
ipallow 7#$-a&&ress8 inser" #$ a&&ress in"o lis" '9o&0le ipallow.
ip&en/ 7#$-+&&ress8 inser" #$ a&&ress in"o lis" '9o&0le ip&en/.
ip&b 27file.csv86 loa& #$AB fro9 .csv file
license 7serno8 7ke/8 specif/ serno an& license ke/
loca"e 7a&&r8 look0p #$ a&&ress in c0rren" #$AB
log 79essage8 log a 9essage "o "he BalanceNG log
9acallow 79ac-a&&ress8 inser" B+- a&&ress in"o lis" '9o&0le 9acallow.
9ac&en/ 79ac-a&&ress8 inser" B+- a&&ress in"o lis" '9o&0le 9ac&en/.
9acro0"er 79ac-a&&ress8 &eclare B+- a&&ress as ro0"ing &evice
9o&0les 79a8479b84... &efine packe" processing 9o&0le chain
ne"work 7i&?8 7c9&8 7val0e8 9o&if/ ne"work 7i&?84 see Ihelp ne"workI
no 7co99an&8 rever" co99an&
p0rge 7i"e98 7n09ber's.8 re-ini"ialize servers:"arge"s
regis"er 7i"e98 7n09ber's.8 regis"er ne"works:servers:"arge"s
reloa& reloa& server an& "arge" config0ra"ion
re9ark 7re9ark8 specif/ config0ra"ion re9arks
res/nc sche&0le a co9ple"e session "able res/nc
r9s 7i&8 re9ove session "able en"r/ 'e?ac" look0p.
r9session 7i&8 re9ove session "able en"r/
r9" 7"arge"8 re9ove all session "able en"ries of specific "arge"
save shor"han& for Isave confI
save conf save c0rren" config0ra"ion
save priva"e save priva"e config0ra"ion &a"a
save all save config0ra"ion an& priva"e &a"a
server 7i&?8 7c9&8 7val0e8 9o&if/ server 7i&?84 see Ihelp serverI
session&09p 7file8 &09p all sessions "o file
sessionloa& 7file8 loa& all session infor9a"ion fro9 file
se" 7para9e"er8 7val0e8 se" para9e"er "o specific val0e
show 7i"e98 show i"e94 show 3 for i"e9 lis"
sh0"&own alias for s"op
snapsho" 7file8 collec" all relevan" service &a"a in file
snapsho"-ligh" 7file8 collec" snapsho" wi"h li9i"e& session"able &09p
sna"range 7fro98 7"o8 specif/ SN+T #$v4 a&&ress range
sof"&isable "arge" 7n09ber's.8 &on1" crea"e new sessions for "arge"'s.
s"op s"op backgro0n& process an& e?i"
"arge" 7i&?8 7c9&8 7val0e8 9o&if/ "arge" 7i&?84 see Ihelp "arge"I
"na" 7ipa8 7ipb8 7pr8 7pr"8 "arge" N+T for o0"bo0n& co990nica"ions
0nregis"er 7i"e98 7n09ber's.8 0nregis"er ne"works:servers:"arge"s
vip 7ip48 represen" =#$ 0sing +,$
vrrp 7sc8 7val0e8 vrrp se""ings4 see Ihelp vrrpI
bng#

$..1 hel" Fsubto"icG
Synopsis: help 7s0b"opic8
Displays subtopic based help information.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 31 / 146
Example:
bng# help 3
available help "opics
3 show "his lis" of available help "opics
cle&i" co99an& line e&i"ing f0nc"ionali"/
ga"ewa/ &efa0l" ga"ewa/ co99an&s
in"erface in"erface co99an&s
ne"work ne"work co99an&s
server vir"0al server co99an&s
show infor9a"ion abo0" i"e9s "o show
"arge" "arge" 'real server. co99an&s
vrrp vrrp co99an&s
bng# help vrrp
vrrp bscrip" 7scrip"8 specif/ B+-Z@$ s"a"e no"if/ scrip"
vrrp 9scrip" 7scrip"8 specif/ B+ST>, s"a"e no"if/ scrip"
vrrp ne"work 7n09ber8 specif/ ne"work for a&ver"ise9en"s
...
bng# help ne"work
ne"work 7n8 a&&r 7a&&r8 specif/ ne"work a&&ress
ne"work 7n8 in"erface 7if8246 specif/ one or 9ore in"erfaces
ne"work 7n8 in"erface none re9ove all in"erface &eclara"ions
...
bng# help ga"ewa/
ga"ewa/ aler" 7scrip"8 specif/ ga"ewa/ aler" no"ifica"ion scrip"
ga"ewa/ arp 7iv847"o8 perfor9 arp heal"hcheck 'ival4"o0".
ga"ewa/ arp off &isable arp heal"hcheck
...
bng# help in"erface
in"erface 7na9e8 co9pa"ibili"/ s/n"a?
in"erface 7n8 na9e 7na9e8 specif/ FS in"erface na9e
in"erface 7n8 "rackval 7val8 specif/ in"erface "racking val0e '&efa0l"K0.
...
bng# help server
server 7n8 back0p 7"8 specif/ one single back0p "arge"
server 7n8 back0ps 7"!84... specif/ 90l"iple back0p "arge"s
server 7n8 back0p none re9ove all back0p "arge" &eclara"ions
...
bng# help show
show arphash show arp hash"able
show bench9ark show bench9ark s"a"0s an& res0l"s
show conf show c0rren" config0ra"ion
...
bng# help "arge"
"arge" 7n8 agen" 7p847iv847"o8 perfor9 agen" opera"ion 'por"4ival4"o0".
"arge" 7n8 agen" off re9ove:&isable agen" opera"ion
"arge" 7n8 aler" 7scrip"8 specif/ e?"ernal aler" scrip"
...
bng# help cle&i"
arrow 0p 9ove 0p "o previo0s co99an& line
arrow &own 9ove &own "o ne?" co99an& line in his"or/
arrow lef" 9ove c0rsor lef"
arrow righ" 9ove c0rsor righ"
backspace4 X< or A>% &ele"e charac"er before c0rsor
XA e?i" "o opera"ing s/s"e9 shell
X@ erase all charac"ers lef" of c0rsor
XU erase wor& lef" of c0rsor

$..2 inHect
Synopsis: inject 7in"erface8 7pcap-file8 7fro98 27"o86
This command injects one or more packets provided in a fle in pcap format into the
BalanceNG interface with the specifed index or interval. If <to> is omitted only one packet is
injected (index <from>).
This command is intended for debugging and QA purposes only and must not be used in a
productive environment.
Example:
bng# help 3
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 32 / 146 Grünwald Germany / All Rights Reserved
# bng c"l
BalanceNG connec"e& "o $#A ;H055
"es"# inYec" ! :"9p:ic9p.pcap ;
no ; len H0
00 00 5> 00 44 04 04 !- HS 43 4( S0 0( 00 45 00
00 3( -E !! 34 04 SH 0! ;B H; 0+ >> S0 (( 0+ >>
-( A- 03 04 34 S( 00 00 05 4( 43 )( 05 50 30 3;
40 00 H) 0) >4 )5 0+ >> -( A- 0+ 43 0; )> 43 BB
S; 43 ;- >4 +4 -!
vrrp ... con"in0e
arp ... con"in0e
ping ... con"in0e
hc ... con"in0e
9as"er ... con"in0e
slb ... &one.
"es"#
$..5 locate
Synopsis: loca"e 7#$-a&&ress8
This command initiates a lookup in the in-memory IPDB or IPDB6 databases (IP to location
databases) with the given IP address (IPv4 or IPv6) as the key. The location counters (as
show by "show locations") are not being incremented by this lookup.
Example:
# bng s"ar" ;
BalanceNG s"ar"ing 0p ins"ance ; ...
# bng con"rol ;
BalanceNG connec"e& "o ins"ance ; $#A !;4;3
bng# ip&b
bng# ip&b)
bng# sh ip&b
#$AB loa&e& fro9 :op":BalanceNG:ip-"o-co0n"r/.csv
!!0!00 vali& 5-col09n lines
!!0!00 "o"al #$AB en"ries available
no consec0"ive area overlaps
;4! &ifferen" #$AB loca"ions reference&
#$AB) loa&e& fro9 :op":BalanceNG:#pTo-o0n"r/.),.csv
5)3) vali& 5-col09n lines
5)3) "o"al #$AB) en"ries available
no consec0"ive area overlaps
bng# loca"e (;.!35.!!0.;
a&&ress (;.!35.!!0.; is in A> 'G>,B+NV.
bng# loca"e ;a0!!E(;00H)c;
a&&ress ;a0!!E(;00H)c; is in A>
bng#
$..6 "urge
Synopsis: p0rge in"erface 7in"erface no.8
p0rge ne"work 7ne"work no.8
p0rge server 7server no.8
p0rge "arge" 7"arge" no.8
This command resets the given interface, network, server or target data structures to an initial
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 33 / 146
uninitialized state. The object must be in unregistered state, multiple interface, network,
server or target numbers may be specifed.
Example:
bng# 0nregis"er "arge" !
bng# p0rge "arge" !
$..1E r*s
Synopsis: r9s 7session-i&8
This command removes a single session table entry by performing one single session table
lookup. If there's no session table entry found, this command has no side-effect.
$..11 r*session
Synopsis: r9session 7session-i& s0bs"ring8
This command removes all session table entries with a matching session-id substring (the
same set as shown by "show session <session-id substring>"). Please note that a complete
linear traversal of the session table is performed every time this command is executed.
$..1 r*t
Synopsis: r9" 7"arge"8
This command removes all session table entries which are associated to a specifc target.
Please note that a complete linear traversal of the session table is performed every time this
command is executed.
$..1$ resAnc
Synopsis: res/nc
This command starts a session table resync on the current VRRP master. The parameter
sessionsyncack needs to be set to 1 (enabled).
Example:
bng# res/nc
ok4 !000000 en"ries sche&0le& for res/nc
bng# sh log
;0!;:!;:;0 !)33;H ) ,>SVN- FS !000000 >NT,#>S S-<>A@%>A
;0!;:!;:;0 !)4!3! ) ,>SVN- -FB$%>T>
bng#
$..1, sa.e
Synopsis: save
This saves the current confguration (as shown by "show conf") to the confguration fle of
BalanceNG in :e"c:bng.conf (or /etc/bngN.conf for other instances).
Example:
bng# save
save& :e"c:bng.conf
bng#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 34 / 146 Grünwald Germany / All Rights Reserved
$..1/ sa.e conf
Synopsis: save conf
This command saves the current confguration (as shown by "show conf") to the
confguration fle just like "save".
$..11 sa.e "ri.ate
Synopsis: save priva"e
This command saves the node specifc private data in the associated private data
confguration fle (/etc/bng.private or /etc/bngN.private).
The following data is considered to be "node specifc private":
– The "hostname" setting
– The VRRP priority
– All "network <n> real" addresses
The private data may be displayed with "show private" without any saving.
Example:
bng# save priva"e
save& :e"c:bng.priva"e
bng#
$..12 sa.e all
Synopsis: save all
This command save both the confguration and the private confguration data of the current
instance.
Example:
bng# save all
save& :e"c:bng.conf
save& :e"c:bng.priva"e
bng#
$..15 sessiondu*"
Synopsis: session&09p 7filena9e8
The command dumps the complete session table information into the specifed fle in ascii
readable text format (as displayed by the "show sessions" command).
Note: During the dumping process the internal packet forwarding mechanism is paused,
which may cause a noticeable delay of packet processing at very large session tables.
Example:
bng["es"no&e# session&09p :"9p:"es"."?"
&09ping !H sessions "o :"9p:"es"."?" ...... &one.
bng["es"no&e# ... b/e
"es"no&e# ca" :"9p:"es"."?"
hash ip-a&&ress por" srv "g" age s"o0"
-------- --------------- ----- --- --- ---- -------
H4HEHH4 !H;.!H.;.4 3;(;3 4 ! 33 !;0000
H4HEHH3 !H;.!H.;.4 3;(;; 4 ! 34 !;0000
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 35 / 146
H4HEHH; !H;.!H.;.4 3;(;! 4 ! 34 !;0000
H4HEHH! !H;.!H.;.4 3;(;0 4 ! 34 !;0000
H4HEHH0 !H;.!H.;.4 3;(!E 4 ! 34 !;0000
H4HEH)E !H;.!H.;.4 3;(!( 4 ! 35 !;0000
H4HEH)( !H;.!H.;.4 3;(!H 4 ! 35 !;0000
H4HEH)H !H;.!H.;.4 3;(!) 4 ! 35 !;0000
H4HEH)) !H;.!H.;.4 3;(!5 4 ! 3) !;0000
H4HEH)5 !H;.!H.;.4 3;(!4 4 ! 3) !;0000
H4HEH)4 !H;.!H.;.4 3;(!3 4 ! 3) !;0000
H4HEH)3 !H;.!H.;.4 3;(!; 4 ! 3H !;0000
H4HEH); !H;.!H.;.4 3;(!! 4 ! 3H !;0000
H4HEH)! !H;.!H.;.4 3;(!0 4 ! 3( !;0000
H4HEH)0 !H;.!H.;.4 3;(0E 4 ! 3( !;0000
H4HEH5E !H;.!H.;.4 3;(0( 4 ! 3E !;0000
H4H5H5! !H;.!H.;.4 3;E0! 4 ! )0 !;0000
"es"no&e#
$..16 sessionload
Synopsis: sessionloa& 7filena9e8
This command allows to load the internal session-table from a fle, that has been previously
exported by a "sessiondump" command invocation.
$..E sho&
Synopsis: show 7i"e98
The command show displays various informations about the current running BalanceNG
process.
$..E.1 sho& ?
Synopsis: show 3
This informational command displays which items may be specifed using the show command
(replacing the 3).
Example:
bng# show 3
show arphash show arp hash"able
show bench9ark show bench9ark s"a"0s an& res0l"s
show break show c0rren" process break
show conf show c0rren" config0ra"ion
show &eb0gscopes show available &eb0gscopes
show ga"ewa/ show ga"ewa/ info an& s"a"0s
show ifs"a" show in"erface s"a"is"ics
show ins"ance show c0rren" ins"ance n09ber
show in"erfaces sa9e as ifs"a"
show ip&b ship #$AB '#$ loca"ion &a"abase. info
show lgrp show loca"ion gro0p infor9a"ion
show lgrp 7+-W8 show specific loca"ion gro0p s"a"0s
show license show license infor9a"ion
show loca"ions show available #$AB loca"ions
show log show recen" log 9essages
show 9achash show learne& 9ac a&&resses
show 9o&0les show available an& ac"ive 9o&0les
show na" show ne"work a&&ress "ransla"ions
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 36 / 146 Grünwald Germany / All Rights Reserved
show ne"works show specifie& ne"works
show ne"work 7n8 show ne"work 7n8 infor9a"ion
show no&ei& show licensing no&ei&
show no0s show n09ber of 0ns/nc1e& sessions
show para9e"ers show se""able para9e"er &a"a
show priva"e show priva"e config0ra"ion &a"a
show server 7n8 show s"a"0s of server 7n8
show servers show server overview
show sessions show session "able infor9a"ion
show sna" show SN+T infor9a"ion
show s"ar"0plog show s"ar"0p log 9essages
show s"info show session hash"able infor9a"ion
show "arge"s show "arge" overview
show "arge" 7n8 show s"a"0s of "arge" 7n8
show "hrea&s show "hrea&s overview
show 0p"i9e show 0p"i9e in secon&s
show vips show vips an& "heir 9ac-a&&resses
show vno&ei& show licensing vno&ei&
show version &ispla/ version infor9a"ion
show vrrp &ispla/ =,,$ s"a"0s
bng#
$..E. sho& ar"hash
Synopsis: show arphash
Displays the current ARP hash of BalanceNG. The output consists of several columns: The
IP-address, the MAC address (00:00:00:00:00:00 if not yet resolved) and several fags.
Static entries are usually self generated and maintained entries (like BalanceNG virtual
servers), dynamic entries are usually BalanceNG targets.
Example:
bng!# show arphash
ipa&&r e"ha&&r "g" ne" cn"r age flags
--------------- ----------------- ---- --- ----- ----- -----------
!H;.!H.;.)! 0)00ac!!0;3& - ! - - vip fi?
!H;.!H.;.)4 00005e000!0e - ! - - vip
!H;.!H.;.E! 00e0(!5&;a)5 ! - ;03 !E;
bng!#
$..E.$ sho& bench*ar-
Synopsis: show bench9ark
Displays the current benchmark status and the results (if fnished).
Example:
bng# show bench9ark
bench9ark ac"ive an& r0nning
&0ra"ion 'secon&s. 300
packe"size !5!4
win&ow size !)
packe"s sen" ;!;E;!
packe"s receive& ;!;E05
secon&s re9aining ;E4
bng# show bench9ark
bench9ark finishe& wi"h "he following res0l"s
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 37 / 146
&0ra"ion 'secon&s. 300
packe"size !5!4
win&ow size !)
packe"s sen" !0HEH!5(
packe"s receive& !0HEH!4;
los" packe"s 0
packe"s per secon& 35EE0
b/"es per secon& 544(E5HH
$..E., sho& brea-
Synopsis: show break
Displays the current process break (of the BalanceNG main thread) as returned by sbrk() in
hexadecimal format.
Example:
bng# show break
c0rren" break is 0?b!Hb000
bng#
$..E./ sho& conf
Synopsis: show conf
Displays the current active confguration of BalanceNG as it would be saved to
I:e"c:bng.confI using the save command.
Example:
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.30
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
:: en& of config0ra"ion
bng#
$..E.1 sho& conf FsectionG
Synopsis: show conf 7sec"ion8
This command displays specifc sections of the confguration fle intended for automatic
access by programs layered on top of BalanceNG (like Web-UI's). Currently supported
sections by this command are "gateway", "vrrp", "ipdb", "lgrp" and "parameters".
Example:
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 38 / 146 Grünwald Germany / All Rights Reserved
# bng con"rol
BalanceNG connec"e& "o $#A !5(H3
No&e+# show ga"ewa/
ipa&&r !H;.!H.;.;54
"o"al s"a"0s opera"ional
No&e+# show conf ga"ewa/
ga"ewa/ O
ipa&&r !H;.!H.;.;54
P
No&e+# show conf vrrp
vrrp O
vri& !4
priori"/ ;00
ne"work !
"racking enable
9scrip" I:0sr:bin:logger -p &ae9on.no"ice =,,$ B+ST>,I
bscrip" I:0sr:bin:logger -p &ae9on.no"ice =,,$ B+-Z@$I
P
No&e+# show conf para9e"ers
se" O
vrrppree9p" !
local&sr !
P
No&e+# show conf ip&b
ip&b I:op":BalanceNG:ip-"o-co0n"r/.csvI
No&e+# show conf lgrp
lgrp O
+ IA>4+T4-<I
B IC4J+4JWI
A I>I
> ISI
S IGBI
V IA4SI
W IJVI
P
No&e+#
$..E.2 sho& conf hostna*e
Synopsis: show conf hos"na9e
This command displays just the "hostname" line as it would appear in the output of "show
conf".
$..E.5 sho& conf net&or-
Synopsis: show conf ne"work 7i&?8
show conf ne"work s"a"es
This command displays specifc network sections the same way as in the confguration fle.
$..E.6 sho& conf re*ar-
Synopsis: show conf re9ark
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 39 / 146
This command displays just the "remark" line as it would appear in the output of "show conf".
$..E.1E sho& conf ser.er
Synopsis: show conf server 7i&?8
show conf server s"a"es
This command displays specifc server sections the same way as in the confguration fle.
$..E.11 sho& conf target
Synopsis: show conf "arge" 7i&?8
show conf "arge" s"a"es
This command displays specifc target sections the same way as in the confguration fle.
$..E.1 sho& debugsco"es
Synopsis: show &eb0gscopes
This command displays a list of the available settings for the "debugscope" parameter.
Example:
"es"+# show &eb0gscopes
0 off
! "arge" scrip" &eb0gging
; "arge" ascrip" &eb0gging
3 server pl0gin &eb0gging
4 ANS librar/ &eb0gging
5 loca"ion gro0p '%G,$. &eb0gging
"es"B#
The "debugscope" parameter must not be enabled during productive use of BalanceNG.
$..E.1$ sho& gate&aA
Synopsis: show ga"ewa/
Displays informations about the gateway and its current state (see "gateway" setup
commands).
Example:
bng# show ga"ewa/
ipa&&r !H;.!H.;.;54
"o"al s"a"0s opera"ional
ping s"a"0s 0p
"rackval 4
bng#
$..E.1, sho& ifstat
Synopsis: show ifs"a"
Displays informations about the Ethernet interfaces which are currently under control of
BalanceNG.
The following data is shown:
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 40 / 146 Grünwald Germany / All Rights Reserved
• received packets
• received bytes
• sent packets
• sent bytes
• dumped bytes.
The row 'dumped bytes' refers to the number of bytes being already dumped in pcap format
to the current active dump fle (see the &09p command). This is being used to trigger
automatic dumpfle rotation as soon as this number of bytes exceeds the parameter
&09pro"a"ion (see also the se" command for more informations about parameters).
Example:
bng# show ifs"a"
in&e? 0 'e"h0.
in&e? ! 'e"h!.
in"erface ! 'e"h0.
link &e"ec"ion T,@>
a&&ress
000!(0)(;(;f
receive&
packe"s 34;
b/"es ;;E4E
sen"
packe"s 0
b/"es 0
&09pe&
b/"es 0
in"erface ; 'e"h!.
link &e"ec"ion T,@>
a&&ress
000e0c)cba4a
receive&
packe"s ;5H
b/"es 4054!
sen"
packe"s !))
b/"es (;H)
&09pe&
b/"es 0
bng!#
$..E.1/ sho& instance
Synopsis: show ins"ance
This shows the number of the current BalanceNG instance.
# bng s"ar" 4!
BalanceNG s"ar"ing 0p ins"ance 4! ...
# bng con"rol 4!
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 41 / 146
BalanceNG connec"e& "o ins"ance 4! $#A ;H;3!
bng# show ins"ance
"his is BalanceNG ins"ance 4!
bng#
$..E.11 sho& interfaces
Synopsis: show in"erfaces
This is a synonym and equivalent to "show ifs"a"".
$..E.12 sho& i"db
Synopsis: show ip&b
This shows information about the current status of the internal IPDB in-memory database.
Example:
bng# show ip&b
#$AB loa&e& fro9 :op":BalanceNG:ip-"o-co0n"r/.csv
(34;E vali& 5-col09n lines
(34;E "o"al #$AB en"ries available
no consec0"ive area overlaps
;35 &ifferen" #$AB loca"ions reference&
bng#
$..E.15 sho& license
Synopsis: show license
This shows the current licensing status of BalanceNG on the current host machine (node). If
the current confguration contains a valid license for the nodeid of the machine then the
output could look like follows:
bng# show license
s"a"0s vali& f0ll license
serial T>ST0)!!0;!
no&ei& ;ae;Ef3(&a;0
"/pe Ishow versionI for version an& -op/righ" infor9a"ion
bng#
An unspecifed license information or an invalid license key shows up as follows:
bng# show license
s"a"0s no or invali& license4 "rial res"ric"ions appl/
no&ei& ;ae;Ef3(&a;0
"/pe Ishow versionI for version an& -op/righ" infor9a"ion
bng#
A automatic OEM licensing on specifc OEM hardware looks like this:
bng# show license
s"a"0s vali& f0ll F>B license
no&ei& ;ae;Ef3(&a;0
"/pe Ishow versionI for version an& -op/righ" infor9a"ion
bng#
There's the possibility to obtain promotional full licenses. This license allows testing of VRRP
and allows unrestricted number of virtual servers. This license could show up as follows:
"es"# show license
s"a"0s vali& "es"ing license 'will "er9ina"e in E3 9in0"es.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 42 / 146 Grünwald Germany / All Rights Reserved
serial T>ST!;3:!.HH0
no&ei& ;ae;Ef3(&a;0
"/pe Ishow versionI for version an& -op/righ" infor9a"ion
"es"#
The license confguration is at the top in the confguration output or fle (after "hostname" and
"remark" entries if present). See the license and nodeid confguration command for further
reference.
$..E.16 sho& lgr"
Synopsis: show lgrp
This command displays all currently confgured location groups and their logical state. An "ok"
in column 2 means that all group interdependencies have been solved for that group whereas
a question mark indicates that the group specifcation references yet unknown information.
Example:
bng# show lgrp
+ ok IA>4+T4-<I
B ok IC4J+4JWI
A ok I>I
> ok ISI
S ok IGBI
V ok IA4SI
W ok IJVI
bng#
$..E.E sho& lgr" FgG
Synopsis: show lgrp 7gro0p8
This command displays more detailed information about the specifed location group
(referenced as a single capital letter A-Z) including all locations that are member of this group.
Example:
bng# show lgrp
+ ok IA>4+T4-<I
B ok IC4J+4JWI
A ok I>I
> ok ISI
S ok IGBI
V ok IA4SI
W ok IJVI
bng# show lgrp +
grp + 'solve&.
"?" A>4+T4-<
ke/ &escrip"ion
--- ------------------------------------
+T +@ST,#+
-< SU#TW>,%+NA
A> G>,B+NV
--- ------------------------------------
3 "o"al en"ries
bng# show lgrp B
grp B 'solve&.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 43 / 146
"?" C4J+4JW
ke/ &escrip"ion
--- ------------------------------------
+A +NAF,,+
+> @N#T>A +,+B >B#,+T>S
+S +SG<+N#ST+N
+G +NT#G@+ +NA B+,B@A+
+# +NG@#%%+
+% +%B+N#+
...
WB W+BB#+
WU W#BB+BU>
- CCC NFT SF@NA $S>@AF >NT,V CCC
--- ------------------------------------
;33 "o"al en"ries
bng#
$..E.1 sho& locations
Synopsis: show loca"ions
This command displays the current referenced locations in the internal IPDB (if loaded).
Example:
bng# show loca"ions
ke/ co0n"er &escrip"ion
--- -------- ------------------------------------
+A ! +NAF,,+
+> !) @N#T>A +,+B >B#,+T>S
+S +SG<+N#ST+N
+G +NT#G@+ +NA B+,B@A+
+# +NG@#%%+
+% +%B+N#+
+B ! +,B>N#+
+N N>T<>,%+NAS +NT#%%>S
+F +NGF%+
+\ +NT+,-T#-+
+, HE +,G>NT#N+
+S +B>,#-+N S+BF+
+T !4E +@ST,#+
+@ ;HE +@ST,+%#+
+U +,@B+
+G
+W 4 +W>,B+#]+N
B+ 4 BFSN#+ +NA <>,W>GF=#N+
BB B+,B+AFS
BA 3 B+NG%+A>S<
B> 4E B>%G#@B
...
=- S+#NT =#N->NT +NA T<> G,>N+A#N>S
=> !( =>N>W@>%+
=G =#,G#N #S%+NAS4 B,#T#S<
=# =#,G#N #S%+NAS4 @.S.
=N !) =#>T N+B
=@ =+N@+T@
US U+%%#S +NA S@T@N+
US S+BF+
V> V>B>N
VT B+VFTT>
W+ SF@T< +S,#-+
WB W+BB#+
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 44 / 146 Grünwald Germany / All Rights Reserved
WU W#BB+BU>
- E( CCC NFT SF@NA $S>@AF >NT,V CCC
--- -------- ------------------------------------
;35 !4(05 "o"al
bng#
Note: The location counters may be reset with the "clear locationcounters" command.
$..E. sho& log
Synopsis: show log
Displays the most recent log messages as they have been sent to the syslog. Up to 40 log
messages are stored in a cyclic buffer.
Errors found in the initial startup fle (/etc/bng.conf) are also reported to the syslog and may
be displayed here for further analysis.
Example:
bng!# show log
;00(:!0:!! ;!;5!( ) 9ain in"erface is bge0
;00(:!0:!! ;!;5!( ) BalanceNG !.)H; s"ar"ing backgro0n& opera"ion
;00(:!0:!! ;!;5!( ) loa&ing :e"c:bng.conf
;00(:!0:!! ;!;5!( ) config0ra"ion "aken S0n Fc" ! !55(3E ;00(
;00(:!0:!! ;!;5!( ) config0ra"ion save& b/ BalanceNG !.)43 'crea"e& ;00(:!0:0!.
;00(:!0:!! ;!;5!( 5 "his vir"0al ro0"er is now B+-Z@$
;00(:!0:!! ;!;5!( ) :e"c:bng.conf s0ccessf0ll/ loa&e&
;00(:!0:!! ;!;5;; 5 "his vir"0al ro0"er is now B+ST>,
;00(:!0:!! ;!;5;4 5 "arge" ! opera"ional
bng!#
$..E.$ sho& *achash
Synopsis: show 9achash
Displays the learned MAC addresses and their associated interfaces. For security reasons
BalanceNG restricts the amount of different MAC addresses to 10000 (and will stop any
further learning in that case).
If the MAC address belongs to a target the target number is show in the "tg" column of the
output.
Example:
bng# show 9achash
e"ha&&r "g ifc
----------------- -- ----
0004!3;50)EH bge0
000a(af(cb0! bge0
00!44f4((;50 bge0
0004!3;;!b03 bge0
00!4bf))H03) bge0
00005e000!0E bge0
000cf!EcE0e( bge0
00!43(E5Ha04 bge0
0)00ac!!0;54 bge0
000b(;00a(fe bge0
00;0e0)Ea&4c bge0
00!!50c354ce bge0
00e0(!5&;a)5 bge0
000;;&!5ac53 bge0
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 45 / 146
0004!3;50)E) bge0
0040)3cEf5b5 bge0
000e0c)cba5E ! bge0
bng#
$..E., sho& *a+buc-et
Synopsis: show 9a?b0cke"
This command displays the length of the largest bucket list of the internal session table
management data structure. This length should be minimal and is an indicator for the quality
of the session-id hash function. This command blocks all packet processing threads for some
short time and should therefore not be executed during production or stress testing.
Example:
bng# sh 9a?b0cke"
leng"h of longes" session "able b0cke" lis" ;
bng#
$..E./ sho& *odules
Synopsis: show 9o&0les
Displays the current active module chain and a list of available modules.
Examples:
bng# show 9o&0les
c0rren" 9o&0le chain
bench9ark
s0ppor"e& 9o&0le chains
bench9ark
swi"ch
vrrp4classic
vrrp4arp4ping4hc49as"er4slb4"na"4na"4r"
vrrp4arp4ping4hc49as"er4llb
available 9o&0les
arp - +,$ re50es":repl/ processing
bench9ark - <U loopback bench9ark
classic - classic BNG=; loa& balancing
crossover - vir"0al crossover cable
hc - heal"h-check processing
ipallow - si9ple #$ a&&ress allow fil"er
ip&en/ - si9ple #$ a&&ress &enial fil"er
llb - link loa&-balancing
9acallow - si9ple B+- a&&ress allow fil"er
9ac&en/ - si9ple B+- a&&ress &enial fil"er
9as"er - procee& onl/ if c0rren" 9as"er
na" - N+T processing
o0" - packe" o0"p0" processing '>G$>,#B>NT+%.
ping - #-B$ echo re50es" processing
r" - #$v4 an& #$v) ro0"ing 9o&0le
slb - server loa& balancing
swi"ch - si9ple >"herne" swi"ching
s"ric" - s"ric" #$ packe" accep"ance fil"er '>G$>,#B>NT+%.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 46 / 146 Grünwald Germany / All Rights Reserved
"na" - "arge" N+T 9o&0le
vrrp - ini"ial =,,$ han&ling
ip4&eb0g - #$v4 &eb0gging 9o&0le '>G$>,#B>NT+%.
sc"p&eb0g - S-T$ &eb0gging 9o&0le '>G$>,#B>NT+%.
$..E.1 sho& nat
Synopsis: show na"
Displays the current active NAT table contents (Network Address Translation). The NAT table
contains separate entries for TCP and UDP network address translations.
Examples:
bng# show na"
T-$ 0 en"ries
@A$ 0 en"ries
bng#
bng# show na"
T-$ ! en"r/
ip-a&&ress ipor" opor" age
--------------- ----- ----- ----
!H;.!H.;.4 3;(53 ;00!; 3
@A$ ; en"ries
ip-a&&ress ipor" opor" age
--------------- ----- ----- ----
!H;.!H.;.4 3;H)( ;05H3 3
!H;.!H.;.4 !;3 ;05H; !5E
bng#
$..E.2 sho& net&or- FnG
Synopsis: show ne"work 7n8
Displays an overview of the current parameters of network <n>.
$..E.5 sho& net&or-s
Synopsis: show ne"works
Displays current parameters of all networks.
$..E.6 sho& nodeid
Synopsis: show no&ei&
Display the nodeid of the current BalanceNG instance, which is a 6 byte identifcation being
represented in Ethernet address format. This nodeid is being used to identify the BalanceNG
instance for licensing purposes.
The nodeid is derived from the Ethernet address of the eth0 interface, the instance number
and other system parameters.
Example:
bng# show no&ei&
!3e3ac!;E&4H
bng#
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 47 / 146
The nodeid can change due to hardware replacement or extensions (e.g. due Ethernet
interface "reordering"). Please goto http://www.inlab.de for further licensing information and
relicensing procedures.
Note: All BalanceNG instances have the same nodeid.
See also "license" and "show license".
$..E.$E sho& nous
Synopsis: show no0s
Displays the number of unsynchronized sessions. If this command displays "0" on the current
VRRP master and the parameter sessionsyncack is set to 1 (enabled), the session table of
the VRRP backup is in sync with the session table of the VRRP master.
$..E.$1 sho& "ara*eters
Synopsis: show para9e"ers
This shows the settable parameter of BalanceNG. Please see the set command for detailed
parameter explanations.
Example:
bng# show para9e"ers
na9e 9in 9a? &efa0l" c0rren"
----------------- ---- ------- ------- -------
arplook0p 5 )0 !0 !0
arprefresh )0 3)00 300 300
arp"i9eo0" 0 ()400 0 0
back0paler"s 0 ! ! !
b9&0ra"ion !0 ()400 300 300
b9psize ;0 !5!4 !5!4 !5!4
b9wsize ! !0000 !;( !;(
bngfil"er 0 ! ! !
&eb0gscope 0 E 0 0
&09pro"a"ion ! !04(5H) !0;4 !0;4
gna"&li9i" !0 !00000 !0 !0
gra"arpre9in& 0 !;0 0 0
hashb/"es4 ! 4 4 4
hashb/"es) ! !) !) !)
hcpor"offse" !0;4 )5535 30000 30000
ipforwar&ing 0 ! 0 0
local&sr 0 ! 0 0
localvir" 0 ! 0 0
9a?s/ncps 0 !0000 0 0
90l"i"hrea&ing 0 ! 0 !
na"&li9i" !0 500 !0 !0
na"scan ! ;0 !0 !0
na"s/nc 0 ! ! !
na"s/nciv !0 !;0 !0 !0
na""i9eo0" !0 !H;(00 )00 )00
o0"9"0 0 !5!4 0 0
psvrelearn 0 ! 0 0
sen&probes 0 ! 0 0
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 48 / 146 Grünwald Germany / All Rights Reserved
sessiona0"ores/nc 0 ! 0 0
sessionarr"i9eo0" 0 3)00 )0 )0
sessiongcli9i" !000 500000 !00000 !00000
session&li9i" !0 !000 !0 !0
sessionscan ! ;0 !0 !0
sessionscanb0p ! !000 !00 !00
sessions/nc 0 ! ! !
sessions/ncack 0 ! 0 0
sessions/nce"/pe 0 ! 0 0
sessions/nciv !0 !;0 !0 !0
session"i9eo0" !0 !H;(00 )00 )00
sna""i9eo0" !0 !H;(00 !(00 !(00
s/ncackb&ela/ ! )0 !0 !0
s/ncack9a?ps ! !0000 ;000 ;000
s/ncackresen& ! )0 5 5
s/ncackwsize ! !0000 !00 !00
s"ick/"arge" 0 ! ! !
s"ric"ro0"ing 0 ! ! !
vrrp9as"er&own 3 !0 3 3
vrrppree9p" 0 ! 0 0
vrrppree9p""s 0 !00 0 0
vrrps"a"epl0gin 0 ! 0 0
Each parameter has a predefned minimum, maximum and default value. The NAT-specifc
parameters are currently not used and for future releases of BalanceNG.
$..E.$ sho& "ri.ate
Synopsis: show priva"e
This command shows the "private" node specifc data of the current instance as it would be
saved by "save private" to the primate confguration data fle.
Example:
No&e+# show priva"e
:: priva"e config0ra"ion &a"a S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
hos"na9e No&e+
vrrp priori"/ ;0E
ne"work ! real !H;.!H.;.)!
:: en& of priva"e config0ra"ion &a"a
No&e+#
$..E.$$ sho& ser.er FnG
Synopsis: show server 7n8
Shows information about one particular server and its current state.
Example:
bng# show server !
server !
ipa&&r !0.55.55.;;;
ne"work !
por" an/
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 49 / 146
pro"ocol an/
s"a"0s enable&
9e"ho& rr
por"rel on
"arge"s !4'5.
bng#
$..E.$, sho& ser.ers
Synopsis: show servers
This shows an overview of confgured servers and their current state including the states of
the associated targets.
A target or backup target as a number is operational according to it's health checks, a target
or backup target in round parentheses is not available due to health check failures, a target or
backup target in square brackets is disabled by purpose.
Only enabled and previously registered server defnitions are shown.
Example:
bng# show servers
# ipa&&r por" pr" ne" S "arge"s Oback0psP
------------------------------------------------------------
! !0.55.55.;;; an/ an/ ! e !4;43444'5.42)6 OP
; !0.55.55.;;) an/ an/ ! e (4E4'!0.4'!!. O;0P
bng#
In this example targets 1,2,3 and 4 of server 1 are operational. The health checks of target 5
are failing and target 6 is disabled.
Target 8 and 9 of server 2 are operational, 10 and 11 have currently failing health checks.
There's an operational backup target 20 available which would be addressed as soon as
there's no ordinary target available.
$..E.$/ sho& sessiongrou"s
Synopsis: show sessiongro0ps
Information about the current target sessiongroups is displayed (see "target <n>
sessiongroup" and "server <n> maxgrpsessions").
Example:
bng# show sessiongro0ps
grp sessions "arge"s
--- --------- ----------------------------------------
0 0 ;
H 0 ! 3 4 5
$..E.$1 sho& sessions
Synopsis: show sessions 27session-i& s0bs"ring86
Information about current active sessions is displayed.
The number of active sessions is displayed together with the frst ten active sessions (which
are usually the latest ones).
It is normal for the session tables to become very huge. The session table entry timeout is
stored with each session table entry (column "stout").
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 50 / 146 Grünwald Germany / All Rights Reserved
An optional second argument restricts the output to the specifed session-id substring. The
number of displayed session table entries is restricted by the "sessiondlimit" parameter.
bng# show sessions
4 sessions
srv "g" age "i9eo0" f"i9eo0" SVN- session-i&
--- --- ---- ------- -------- ---- ------------------
! ; )5 H3;0 0 SVN- !0.;55.!0H.!H50
! 5 ! H3;0 0 SVN- !0.;55.33.!;E0
! 5 !!4( H3;0 0 SVN- !0.;55.!;E.!3(0
! 4 HH) H3;0 0 SVN- !0.;55.!30.!3)0
bng#
bng["es"no&e# show sessions !0.;55.!0H.!H5
4 sessions
srv "g" age "i9eo0" f"i9eo0" SVN- session-i&
--- --- ---- ------- -------- ---- ------------------
! ; )5 H3;0 0 SVN- !0.;55.!0H.!H50
bng["es"no&e#
$..E.$2 sho& snat
Synopsis: show sna"
Displays information current SNAT status.
$..E.$5 sho& startu"log
Synopsis: show s"ar"0plog
Displays the frst 40 log messages that appeared after the initial startup of the instance. The
output of "show startuplog" is also included in the snapshot fle (see "snapshot" command).
$..E.$6 sho& stinfo
Synopsis: show s"info
Displays information about the internal session hashtable. Session entries are pre-allocated
in chunks, the number of current allocated chunks is displayed.
Example:
bng# show s"info
b/"es:session !44
alloca"e& !) ch0nks of )553) en"ries
c0rren" n09ber of TFT+% sessions ......... !000000
c0rren" n09ber of N>U '0ns/nche&. sessions E(EEE5
c0rren" n09ber of sessions wai"ing for +-Z 0
c0rren" n09ber of +-Z1e& sessions ........ !0005

$..E.,E sho& targets
Synopsis: show "arge"s
Displays information about current registered and enabled targets and their current health
check status.
Example:
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 51 / 146
bng# show "arge"s
no ipa&&r ipa&&r) si por" pr" ne" ne") srv sessions s"a"0s info na9e
-- -------------- ------------------------ -- ---- --- --- ---- --- -------- ----------- -------------------------- ----
! !0.!00.;0).(5 ;00!&b(5)H(aaaa(5 3 an/ an/ 3 3 ! 0 opera"ional arp0p4n&)0p4agen"!
; !0.!00.;0).!!) ;00!&b(5)H(aaaa!!) 3 an/ an/ 3 3 ! ! opera"ional arp0p4n&)0p4agen"!
3 !0.!00.;0).!!H ;00!&b(5)H(aaaa!!H 3 an/ an/ 3 3 ! 0 &own arp&own4n&)0p4agen"&own
4 !0.!00.;0).!!( ;00!&b(5)H(aaaa!!( 3 an/ an/ 3 3 ! ! opera"ional arp0p4n&)0p4agen"!
5 !0.!00.;0).!!E ;00!&b(5)H(aaaa!!E 3 an/ an/ 3 3 ! ; opera"ional arp0p4n&)0p4agen"!
!4 !0.!00.;0).!;3 ;00!&b(5)H(aaaa!;3 3 an/ an/ 3 3 ! 0 &own arp&own4n&)0p4agen"&own
!) !0.!00.;0).!;4 ;00!&b(5)H(aaaa!;4 3 an/ an/ 3 3 ! 0 &own arp0p4n&)0p4agen"&own
bng#
$..E.,1 sho& target FnG
Synopsis: show "arge" 7n8
Displays more detailed information about one specifc target.
Example:
bng# show "arge" !
"arge" !
s"a"0s opera"ional 'arp0p4scrip"0p.
ipa&&r !H;.!H.;.E!
por" an/
ne"work !
pro"ocol an/
sessions 0
9a?sessions 0
sessiongro0p H
grpsessions 0
9a?grpsessions 5000
"rackval ;0
psen" 0
bsen" 0
prcv& !H
brcv& 4();
bwin 0
bwo0" 0
bw 0
bng#
$..E., sho& targetregistrA
Synopsis: show "arge"regis"r/
Displays more detailed information about current registered targets and their current health
check status. This is a view from the internal target registry indented for debugging purposes.
This command is usually not needed and therefor not included in the output of the "help"
command.
Example:
bng# show "arge"regis"r/
"arge" ;
ipa&&r !H;.!H.;.5
por" an/
ne"work !
pro"ocol an/
s"a"0s &own
arp 0p
agen" &own
"arge" !
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 52 / 146 Grünwald Germany / All Rights Reserved
ipa&&r !H;.!H.;.4
por" an/
ne"work !
pro"ocol an/
s"a"0s &own
arp 0p
agen" &own
bng#
$..E.,$ sho& threads
Synopsis: show "hrea&s
Displays informations about all active packet processing threads if multithreading is active
(parameter multithreading is set to 1).
Example:
bng# show "hrea&s
"hrea& no !
in"erface ! 'e"h0.
packe"s processe& !33;
"hrea& no ;
in"erface ! 'e"h0.
packe"s processe& !34;
"hrea& no 3
in"erface ! 'e"h0.
packe"s processe& !303
$..E.,, sho& u"ti*e
Synopsis: show 0p"i9e
Display the uptime of the currently running BalanceNG process in seconds.
Example:
bng# show 0p"i9e
c0rren" 0p"i9e is !0(!; secon&s
bng#
$..E.,/ sho& .i"s
Synopsis: show vips
Displays current confgured virtual IP addresses, their associated Ethernet addresses and the
associated network.
Example:
bng!# show vips
ipa&&r e"ha&&r n
-----------------------------------
!0.!.!.!00 0)000a0!0!)4 ;
!0.55.55.;;; 00005e000!0! !
!0.55.55.;;! 00005e000!0! !
!0.55.55.;;0 0)005;(!05&c !
!0.55.55.;30 00005e000!0! !
!0.55.55.;34 00005e000!0! !
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 53 / 146
!0.!.!.;54 00005e000!0! ;
bng!#
$..E.,1 sho& .ersion
Synopsis: show version
Display the current version / release of this BalanceNG process.
Example:
bng# show version
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.
bng#
$..E.,2 sho& .nodeid
Synopsis: show vno&ei&
Display the vnodeid of the current BalanceNG instance, which is a 6 byte identifcation being
represented in Ethernet address format.
The vnodeid is derived from the IPv4 address of the primary interface only.
Example:
bng# show vno&ei&
;!0)5e;4Haf3 'in"erface e"h0.
bng#
Since the vnodeid is based on IPv4 address information only it is suitable for virtual
machines which may be moved from one physical hardware to another.
See also "license" and "show license".
$..E.,5 sho& .rr"
Synopsis: show vrrp
Displays the current VRRP confguration and the current state of the VRRP node (as defned
in rfc3768 with an additional "OFF"-State when deactivated).
Example 1 (node is master for 2 virtual addresses):
bng# show vrrp
s"a"e B+ST>,
vri& !
priori"/ ;00
ip00 !0.;.;.3
ip0! !0.;.;.4
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 54 / 146 Grünwald Germany / All Rights Reserved
Example 2 (vrrp is not active):
bng# show vrrp
s"a"e FSS
Example 3 (node is backup for 2 virtual addresses):
bng# show vrrp
s"a"e B+-Z@$
vri& !
priori"/ ;00
ip00 !0.;.;.3
ip0! !0.;.;.4
$..1 shutdo&n
Synopsis: sh0"&own
This is an alias for "stop.
$.. sna"shot
Synopsis: snapsho" 7file8
This command collects various important system data in text format into the supplied fle. This
fle is intended to be sent to support staff for in detail analysis in case of problems.
Only a partial session table dump is generated according to the sessiondlimit parameter (see
also "snapshot-full" below).
Example:
bng# snapsho" :"9p:snapsho"."?"
collec"ing FS &a"a ...... &one.
&09ping config0ra"ion ...... &one.
collec"ing BNG &a"a ...... &one.
&09ping session"able ...... &one.
bng#
$..$ sna"shot:full
Synopsis: snapsho"-f0ll 7file8
This command collects a snapshot with a full sessiontable dump.
$.., sna"shot:light
Synopsis: snapsho"-ligh" 7file8
This command is a synonym for "snapshot".
$../ st#ll
Synopsis: s"fill 7n09ber-of-sessions8
This command flls the session table with the specifed number of dummy session table
entries. This is intended for testing and debugging purposes only.
Example:
bng#
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 55 / 146
bng# s"fill !000000
bng# sh sessions
!000000 sessions
srv "g" age "i9eo0" f"i9eo0" SVN- session-i&
--- --- ---- ------- -------- ---- ------------------
! ! 3 )000 0 T>ST-A+T+-0000EEEEEE
! ! 3 )000 0 T>ST-A+T+-0000EEEEE(
! ! 3 )000 0 T>ST-A+T+-0000EEEEEH
! ! 3 )000 0 T>ST-A+T+-0000EEEEE)
! ! 3 )000 0 T>ST-A+T+-0000EEEEE5
! ! 3 )000 0 T>ST-A+T+-0000EEEEE4
! ! 3 )000 0 T>ST-A+T+-0000EEEEE3
! ! 3 )000 0 T>ST-A+T+-0000EEEEE;
! ! 3 )000 0 T>ST-A+T+-0000EEEEE!
! ! 3 )000 0 T>ST-A+T+-0000EEEEE0
! ! 3 )000 0 T>ST-A+T+-0000EEEE(E
... re9aining sessions no" shown
bng#
$..1 sto"
Synopsis: s"op
Immediately stops the BalanceNG program. This has the same effect as "bng s"op" on the
command line. There's no additional confrmation required.
Example:
bng# s"op
ok
BalanceNG no peer available
#
$.$ Con#guration Co**ands
The command described in this chapter are actually changing the current confguration of
BalanceNG immediately.
Some commands are revertable using the "no" special command.
$.$.1 I Fco**andG
Synopsis: J 7co99an&8
This special command executes the supplied command as expected, but suppresses the
output of the interactive prompt afterwards. This is useful for interfacing programs to
BalanceNG (like Web User Interfaces).
Example:
roo"# bng a0?c"l 77 >FS
8 J show "arge"s
8 >FS
# ipa&&r por" pr" ne" srv sessions s"a"0s na9e
--- ---------------- ---- --- --- --- -------- ----------- ---------------
! !H;.!H.;.E0 an/ an/ ! 0 0 opera"ional
roo"#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 56 / 146 Grünwald Germany / All Rights Reserved
$.$. ar"
Synopsis: 2no6 arp 7ip4-a&&ress8
This command adds an IPv4 address to the list of addresses that are being "arp resolved".
The mac (Ethernet) address of this IP address will be retrieved using the ARP protocol.
The operation can be reverted on the command line with the "no" prefx.
If the mac address is unknown, the retrieval will be tried all "arplook0p" seconds (default 10
seconds). See also parameter summary at the se" command.
If the mac address is already known, then it will be refreshed after "arprefresh" seconds
(default 120).
As soon as a target is being activated (registered and enabled) an implicit (and invisible) arp
command line is inserted for the target ip address into the running confguration.
A target always has an implicit "base" ARP health check, which times out after "arp"i9eo0""
seconds (default 0, which disables this permanent healthcheck).
ARP requests are being issued on all associated interfaces with an anonymous IP-Source
address per default.
Note: You usually don't have to enter arp command lines into the confguration, the required
administrative ARP resolving for targets and Servers is done automatically by BalanceNG.
Example:
No&e+# show arphash
ipa&&r e"ha&&r "g" ne" cn"r age flags
--------------- ----------------- ---- --- ----- ----- -----------
!H;.!H.;.)! 0)00ac!!0;3& - ! - - vip fi?
!H;.!H.;.)4 00005e000!0e - ! - - vip
!H;.!H.;.E! 00e0(!5&;a)5 ! - !!E !0(
No&e+# arp !H;.!H.;.H4
No&e+# show arphash
ipa&&r e"ha&&r "g" ne" cn"r age flags
--------------- ----------------- ---- --- ----- ----- -----------
!H;.!H.;.)! 0)00ac!!0;3& - ! - - vip fi?
!H;.!H.;.)4 00005e000!0e - ! - - vip
!H;.!H.;.H4 000000000000 - - ; - vis
!H;.!H.;.E! 00e0(!5&;a)5 ! - !5( !4H
No&e+#
$.$.$ co**it
Synopsis: co99i" 2ne"work's.Nserver's.N"arge"'s.6 7n09ber's.8
This command registers and enables one or more networks, servers or targets at once.
"commit <item> <list>" is equivalent to "regis"er 7i"e98 7lis"8" and then
executing "enable 7i"e98 7lis"8".
The network, server or target numbers in the list are separated by commas. This command is
meant to be an abbreviation for interactive use.
See also the Server and Target state description at the "regis"er" command.
Example:
"es"# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A HE5H
bng# in"erface e"h0
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 57 / 146
in"erface e"h0 s0ccessf0ll/ a""ache&
bng# ne"work ! a&&r !0.;.;.0
bng# ne"work ! 9ask ;55.;55.;55.0
bng# ne"work ! real !0.;.;.;0
bng# ne"work ! vir" !0.;.;.;!
bng# ne"work ! in"erface e"h0
bng# co99i" ne"work !
bng# "arge" ! ipa&&r !0.;.;.!0
bng# "arge" ; ipa&&r !0.;.;.;0
bng# co99i" "arge"s !4;
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
U+,N#NG "arge" ; in enable& s"a"e b0" no" reference&
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
"arge" ! O
ipa&&r !0.;.;.!0
P
"arge" ; O
ipa&&r !0.;.;.;0
P
regis"er "arge"s !4;
enable "arge"s !4;
:: en& of config0ra"ion
bng#
$.$., disable
Synopsis: &isable 2ne"work's.Nserver's.N"arge"'s.6 7lis"8
This command immediately disables the specifed networks, servers or targets. The server's
virtual IP addresses are immediately unreachable, targets are immediately taken out of any
load balancing distribution, networks are completely taken out of BalanceNG processing. The
corresponding "enable"-entries are removed from the running confguration.
Note: The networks, servers or targets remain "registered", for changing and editing
parameters they frst have to be taken to the "unregistered" state using the "0nregis"er"
command (not necessary for networks, they may be edited and changed in the registered
state).
See also the Server and Target state description at the "regis"er" command.
Example:
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 58 / 146 Grünwald Germany / All Rights Reserved
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
"arge" ! O
ipa&&r !0.;.;.!0
P
"arge" ; O
ipa&&r !0.;.;.;0
P
regis"er "arge"s !4;
enable "arge"s !4;
:: en& of config0ra"ion
bng# &isable "arge"s !4;
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
"arge" ! O
ipa&&r !0.;.;.!0
P
"arge" ; O
ipa&&r !0.;.;.;0
P
regis"er "arge"s !4;
:: en& of config0ra"ion
bng# show "arge"s
# ipa&&r por" pr" ne" srv s"a"0s
------------------------------------------------------------
! !0.;.;.!0 an/ an/ ! 0 &isable&
; !0.;.;.;0 an/ an/ ! 0 &isable&
bng#
$.$./ du*"
S/nopsis &09p 7in"erface8 7&irec"or/8
This immediately starts dumping of all traffc going through 7in"erface8 to dumpfles in the
given directory. Both inbound and outbound packets are being recorded.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 59 / 146
BalanceNG stores the packets in "pcap" format, the data can be immediately investigated
using usual tools e.g. like snoop, "cp&09p, ne"grep and e"hereal.
The flename is build up as follows (containing the time of creation):
Ie"hI7in"erface n09ber8.7/ear879on"h87&a/87ho0r879in0"e87secon&8
E.g. it could look like:
e"h0.;00(03!(!40H03
There's an automatic logfle rotation build in which closes the fle and opens a new one with a
new timestamp. When this happens is controlled by the parameter "&09pro"a"ion" which
specifes a byte threshold (see "se"" and "show para9e"ers").
Using &09p BalanceNG may be used as a "transparent logging switch / bridge" to record all
traffc for security purposes and later analysis (BalanceNG should be set into Layer 2
switching mode using the command "l;swi"ch").
Example:
bng# &09p e"h0 :bigscra"ch
$.$.1 edit
Synopsis: e&i" 2ne"work's.Nserver's.N"arge"'s.6 7lis"8
This command disables and unregisters one or more networks, servers or targets at once.
"edit <item> <list>" is equivalent to "&isable 7i"e98 7lis"8" and then executing
"0nregis"er 7i"e98 7lis"8".
The item numbers in the list are separated by commas.
See also the Server and Target state description at the "regis"er" command.
Example:
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
"arge" ! O
ipa&&r !0.;.;.!0
P
"arge" ; O
ipa&&r !0.;.;.;0
P
regis"er "arge"s !4;
enable "arge"s !4;
:: en& of config0ra"ion
bng# e&i" "arge"s !4;
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 60 / 146 Grünwald Germany / All Rights Reserved
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
:: en& of config0ra"ion
bng# show "arge"s
# ipa&&r por" pr" ne" srv s"a"0s
------------------------------------------------------------
bng#
$.$.2 enable
Synopsis:
enable 2in"erface's.Nne"work's.Nserver's.N"arge"'s.6 7lis"8
This command enables the specifed interfaces, networks, servers or targets. Targets in
"enabled" mode (or state) immediately participate in load balancing distributions. Servers in
"enabled" mode start answering ARP requests and ICP-ECHO requests ("pings"). Both
servers and targets have to be members of enabled networks.
If a virtual network address is locally occupied and used by the operating system an error
message is generated and the enabling is refused. This applies to "server ipaddr", "network
real" and "network virt" addresses (which must not be used in parallel by the underlying
operating system).
This command is revertable by the appropriate "&isable" command.
See the Server and Target state description at the "regis"er" command.
Example:
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
"arge" ! O
ipa&&r !0.;.;.!0
P
"arge" ; O
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 61 / 146
ipa&&r !0.;.;.;0
P
regis"er "arge"s !4;
:: en& of config0ra"ion
bng# show "arge"s
# ipa&&r por" pr" ne" srv s"a"0s
------------------------------------------------------------
! !0.;.;.!0 an/ an/ ! 0 &isable&
; !0.;.;.;0 an/ an/ ! 0 &isable&
bng# enable "arge"s !4;
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
U+,N#NG "arge" ; in enable& s"a"e b0" no" reference&
bng# show "arge"s
# ipa&&r por" pr" ne" srv s"a"0s
------------------------------------------------------------
! !0.;.;.!0 an/ an/ ! 0 &own
; !0.;.;.;0 an/ an/ ! 0 &own
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
regis"er ne"work !
enable ne"work !
"arge" ! O
ipa&&r !0.;.;.!0
P
"arge" ; O
ipa&&r !0.;.;.;0
P
regis"er "arge"s !4;
enable "arge"s !4;
:: en& of config0ra"ion
bng#
$.$.5 gate&aA
BalanceNG may use a default gateway, which may be specifed using the gateway
confguration command family. A DSR confguration does usually not need a gateway so it
doesn't need to be specifed in that case.
$.$.5.1 gate&aA Fi",addrG
Synopsis: ga"ewa/ 7ip4a&&r8
This command is a synonym for "ga"ewa/ ipa&&r 7ip4-a&&ress8" and is implemented
to maintain backwards compatibility to older releases of BalanceNG.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 62 / 146 Grünwald Germany / All Rights Reserved
$.$.5. gate&aA alert Fscri"tG
Synopsis: ga"ewa/ aler" 7scrip"8
This command specifes an external notifcation script which is called as soon as the specifed
gateway becomes down (not operational). For removing the script the empty string ("") needs
to be specifed.
Example:
bng# ga"ewa/ aler" I:0sr:bin:logger -p &ae9on.no"ice G+T>U+V #S AFUNI
bng#
$.$.5.$ gate&aA ar" Finter.alG9Fti*eoutG
Synopsis: ga"ewa/ arp 7in"erval847"i9eo0"8
ga"ewa/ arp off
ga"ewa/ arp &isable
This command establishes an "arp" healthcheck of the gateway. An arp request is sent out
every <interval> seconds, the gateway state changes to "down" if an arp reply has not been
received for <timeout> seconds. The special form "gateway arp off" (or "gateway arp disable")
removes the arp healthcheck from the confguration.
The arp gateway health check may exist in parallel to the arp ping healthcheck.
Example:
bng# ga"ewa/ arp ;45
bng# show ga"ewa/
ipa&&r !H;.!H.;.;54
"o"al s"a"0s opera"ional
ping s"a"0s 0p
arp s"a"0s 0p
$.$.5., gate&aA i"addr Fi",addrG
Synopsis: ga"ewa/ ipa&&r 7ip4a&&r8
Specifes the default gateway towards the external world (e.g. "Internet"). If an IP4-address is
not locally connected (not part of a local network defnition) the packet is being sent to this
gateway address for routing.
ARP-resolution of the gateway address is being processed automatically by BalanceNG.
The command "no ga"ewa/" removes the gateway declaration from the current
confguration.
Example:
bng# ga"ewa/ ipa&&r !0.;.;.;54
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.;0
vir" !0.;.;.;!
in"erface e"h0
P
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 63 / 146
regis"er ne"work !
enable ne"work !
ga"ewa/ O
ipa&&r !0.;.;.;54
P
"arge" ! O
ipa&&r !0.;.;.!0
P
"arge" ; O
ipa&&r !0.;.;.;0
P
regis"er "arge"s !4;
enable "arge"s !4;
:: en& of config0ra"ion
bng#
$.$.5./ gate&aA i"addr1 Fi"1addrG
Synopsis: ga"ewa/ ipa&&r) 7ip)a&&r8
Specifes the default IPv6 gateway towards the external world. If an IP6-address is not locally
connected (not part of a local network defnition) an IPv6 packet is being sent to this gateway
address for routing.
ND-resolution (Neighbor Discovery) of the gateway IPv6 address is being processed
automatically by BalanceNG.
The command "no ga"ewa/" removes all gateway declarations from the current
confguration (ipaddr and ipaddr6).
Example:
bng# ga"ewa/ ipa&&r) fe(0;304(fffeE3430;
$.$.5.1 gate&aA nd1 Finter.alG9Fti*eoutG
Synopsis: ga"ewa/ n&) 7in"erval847"i9eo0"8
ga"ewa/ n&) off
ga"ewa/ n&) &isable
This command establishes an IPv6 Neighbor Discovery healthcheck towards the gateway
IPv6 address (ipaddr6).
$.$.5.2 gate&aA "ing Finter.alG9Fti*eoutG
Synopsis: ga"ewa/ ping 7in"erval847"i9eo0"8
ga"ewa/ ping off
ga"ewa/ ping &isable
This command establishes a "ping" healthcheck of the gateway. An ICMP echo request is
sent out every <interval> seconds, the gateway state changes to "down" if an ICMP echo
reply has not been received for <timeout> seconds. The special form "gateway ping off" (or
"gateway ping disable") removes the ping healthcheck from the confguration.
The ping gateway health check may exist in parallel to the arp healthcheck.
Example:
bng# ga"ewa/ ping !43
bng# show ga"ewa/
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 64 / 146 Grünwald Germany / All Rights Reserved
ipa&&r !H;.!H.;.;54
"o"al s"a"0s opera"ional
ping s"a"0s 0p
arp status: up
$.$.5.5 gate&aA "ing1 Finter.alG9Fti*eoutG
Synopsis: ga"ewa/ ping) 7in"erval847"i9eo0"8
ga"ewa/ ping) off
ga"ewa/ ping) &isable
This command establishes a ping IPv6 healthcheck, the ipaddr6 IPv6 address must be
present.
$.$.5.6 gate&aA trac-.al F.alueG
Synopsis: ga"ewa/ "rackval 7val0e8
ga"ewa/ "rackval &efa0l"
This command associates a tracking value to the gateway. If the gateway state changes to
"down" (according to the current active health checks) and VRRP is active and the current
priority is not equal to 255 then the current priority is degraded by the tracking value of the
gateway. The default value is 0, the special form "gateway trackval default" resets the
gateway tracking value to 0.
Example:
bng# show ga"ewa/
ipa&&r !H;.!H.;.;54
"o"al s"a"0s opera"ional
ping s"a"0s 0p
bng# ga"ewa/ "rackval 4
bng# show ga"ewa/
ipa&&r !H;.!H.;.;54
"o"al s"a"0s opera"ional
ping s"a"0s 0p
"rackval 4
bng#
$.$.5.1E gate&aA u"alert Fscri"tG
Synopsis: ga"ewa/ 0paler" 7scrip"8
This command specifes an external notifcation script which is called as soon as the specifed
gateway becomes operational. For removing the script the empty string ("") needs to be
specifed.
Example:
bng# ga"ewa/ 0paler" I:0sr:bin:logger -p &ae9on.no"ice G+T>U+V #S @$I
bng#
$.$.6 hostna*e
Synopsis: 2no6 hos"na9e 7na9e8
This sets the current hostname of the BalanceNG instance to the specifed name and
changes the interactive command line prompt to that name followed by a "#". This is just for
informational purposes and does not change functionality.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 65 / 146
This command may be reverted by the "no" keyword, changing the name to "undefned" and
changing the interactive command line prompt back to the default (which is "bng#").
The hostname may contain spaces, in that case the hostname must be embedded in double
quotes. Specifying an empty string in double quotes also sets the hostname to the initial
"undefned" state.
Example:
# bng con"rol
BalanceNG connec"e& "o $#A ())0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
:: en& of config0ra"ion
bng# hos"na9e "es"!
"es"!# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
hos"na9e "es"!
:: en& of config0ra"ion
"es"!# no hos"na9e "es"!
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
:: en& of config0ra"ion
bng# hos"na9e I%oa&Balancer Si&e +I
%oa&Balancer Si&e +# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
hos"na9e I%oa&Balancer Si&e +I
:: en& of config0ra"ion
%oa&Balancer Si&e +# hos"na9e II
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
:: en& of config0ra"ion
bng#
$.$.1E interface Fna*eG
Synopsis: in"erface 7in"erface specifier8
This command is implemented for compatibility reasons with older BalanceNG versions,
where "interface <name>" is an abbreviation for the following three commands (using the next
free numerical index):
in"erface 7n8 na9e 7na9e8
regis"er in"erface 7n8
enable in"erface 7n8
$.$.11 interface FnG
$.$.11.1 interface FnG access
Synopsis: in"erface 7n8 access raw
in"erface 7n8 access "ap
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 66 / 146 Grünwald Germany / All Rights Reserved
in"erface 7n8 access vpn
This directive defnes the access method for the specifed interface. Access method "raw" is
the default and enables direct "raw" access to the Ethernet Layer-2 network. Access method
"tap" creates a virtual Layer-2 NIC and connects BalanceNG to the outer side. Access method
"vpn" connects BalanceNG to a remote interface using the RBridge UDP protocol.
Note: Access method "tap" is not available on Solaris platforms.
$.$.11. interface FnG alert
Synopsis: in"erface 7n8 aler" ^7scrip"8_
in"erface 7n8 aler" none
This directive allows to specify a script, which is called in the event of link loss on this
particular interface. The link detection runs once per second in the background. Specifying
"none" removes and disables the external alert script (if in place). The special variable
"$name$" is replaced by the interface name.
bng# in"erface ! aler" I:0sr:bin:logger -p &ae9on.no"ice %#NZ %FST FN #NT>,S+-> Lna9eLI
bng#
$.$.11.$ interface FnG init
Synopsis: in"erface 7n8 ini" 7co99an&s8
This confgurational command allows to specify initialization commands which are executed
by the operating system shell at "enable interface".
Example:
This confguration fle excerpt declares an bng0 "TAP"-Device on Linux and initializes the
interface bng0 with a specifc IP address.
in"erface ! O
na9e e"h0
P
in"erface ; O
na9e bng0
ini" Iip a&&r a&& !H;.!H.;.)0:;4 &ev bng0Q ip link se" bng0 0pI
P
regis"er in"erfaces !4;
enable in"erfaces !4;
$.$.11., interface FnG na*e
Synopsis: in"erface 7n8 na9e 7na9e8
This confgurational command specifes the OS interface to be used by the BalanceNG
interface with the specifed number.
On Linux the special names "bng0" up to "bng9" defne a "TAP" device which allows
BalanceNG to communicate directly with the Linux TCP/IP Stack.
The HW interface is brought into promiscuous mode as soon as the numerical BalanceNG
interface is both registered and enabled.
Example:
# ifconfig e"h0
e"h0 %ink encap>"herne" <Ua&&r 000>0-)-B+5E
ine" a&&r!0.55.55.!; Bcas"!0.55.55.;55 Bask;55.;55.;55.0
@$ B,F+A-+ST ,@NN#NG B@%T#-+ST BT@!500 Be"ric!
,G packe"s5045 errors0 &roppe&0 overr0ns0 fra9e0
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 67 / 146
TG packe"s3!!! errors0 &roppe&0 overr0ns0 carrier0
collisions0 "?50e0elen!000
,G b/"esH400)3 'H;;.H Zb. TG b/"es!;!5)0; '!.! Bb.
Base a&&ress0?c000 Be9or/&f0;0000-&f040000
# :e"c:ini".&:bng s"ar"
BalanceNG s"ar"ing 0p ...
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A (0!;
bng# in"erface ! na9e e"h0
bng# co99i" in"erface !
bng#
$.$.11./ interface FnG threads
Synopsis: in"erface 7n8 "hrea&s 7val0e8
This command specifes the number of packet processing threads per interface. The default value is 1
(one packet processing thread per interface). This command directive is effective only when
multithreading is activated ("set multithreading 1"). The current confgurable maximum of threads per
interface is 8.
$.$.11.1 interface FnG trac-.al
Synopsis: in"erface 7n8 "rackval 7val0e8
This command associates a VRRP tracking value to an interface, which is deducted if an enabled
interface loses its link (determined by the automatic link detection).
$.$.11.2 interface FnG u"alert
Synopsis: in"erface 7n8 0paler" ^7scrip"8_
in"erface 7n8 0paler" none
This directive allows to specify a script, which is called in the event of link availability on this particular
interface. The link detection runs once per second in the background. Specifying "none" removes and
disables the external upalert script (if in place). The special variable "$name$" is replaced by the
interface name.
bng# in"erface ! aler" I:0sr:bin:logger -p &ae9on.no"ice %#NZ A>T>-T>A FN #NT>,S+-> Lna9eLI
bng#
$.$.1 i"allo&
Synopsis: ipallow 7ipa&&r8
no ipallow
This directive allows to add IP addresses to the ipallow list. IPv4 addresses have to be specified in IPv6
notation (e.g. ::ffff:10.1.2.3 ). This list is used by the ipallow module.
$.$.1$ i"db
Synopsis: 2no6 ip&b 2filena9e.csv6
This command loads a IP-to-location database (IPDB) from a fle in .csv format into memory.
The default location "/opt/BalanceNG/ip-to-country.csv" is used when there's no flename
specifed. This fle is in place automatically if BalanceNG has been installed using the Solaris
or Ubuntu/Debian packages.
The command "no ipdb" unloads the IPDB in memory database. Both, "ipdb <fle>" and "no
ipdb" may be entered interactively even during operation as an active VRRP master. During
the time the database is being loaded packet processing is suspended for a short time.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 68 / 146 Grünwald Germany / All Rights Reserved
The command "ipdb" understands the following two .csv formats:
A) The 5-column format as found in the fle "ip-to-country.csv" as available for free from
webhosting.info (URL: http://ip-to-country.webhosting.info/ ). A probably outdated version of
this fle is being distributed with the Solaris and Ubuntu/Debian package distribution of
BalanceNG.
B) The 7-column format as found in the fle "IpToCountry.csv" as available for free from
"software77.net" (URL: http://software77.net/cgi-bin/ip-country/geo-ip.pl ).
Please note that Inlab is not responsible for the quality of the available database fles. We
recommend performing some prior analysis and testing before deploying a live location based
load balancing installation. Also, it's up to the administrator to schedule updates of the chosen
database fle.
There's currently a hard coded maximum of 120000 IPDB entries and a current maximum of
512 locations being referenced by the IPDB (these values will be increased as soon as
necessary).
The IPDB reference is automatically inserted into the running confguration and will be loaded
on startup or restart if made permanent (with "save").
Example:
bng# ip&b
bng# show ip&b
#$AB loa&e& fro9 :op":BalanceNG:ip-"o-co0n"r/.csv
(34;E vali& 5-col09n lines
(34;E "o"al #$AB en"ries available
no consec0"ive area overlaps
;35 &ifferen" #$AB loca"ions reference&
bng# no ip&b
bng# show ip&b
no #$AB en"ries available
bng# ip&b :"9p:#pTo-o0n"r/.csv
bng# show ip&b
#$AB loa&e& fro9 :"9p:#pTo-o0n"r/.csv
()5)E vali& H-col09n lines
()5)E "o"al #$AB en"ries available
; consec0"ive area overlaps
;;; &ifferen" #$AB loca"ions reference&
bng# show conf ip&b
ip&b I:"9p:#pTo-o0n"r/.csvI
bng#
$.$.1, i"denA
Synopsis: ip&en/ 7ipa&&r8
no ip&en/
This directive allows to add IP addresses to the ipdeny list. IPv4 addresses have to be specifed in IPv6
notation (e.g. ::ffff:10.1.2.3 ). This list is used by the ipdeny module.
$.$.1/ i"db1
Synopsis: 2no6 ip&b) 2filena9e.csv6
This command loads a IPv6-to-location database (IPDB6) from a fle in .csv format into
memory. The default location "/opt/BalanceNG/IpToCountry.6R.csv" is used when there's no
flename specifed. This fle is in place automatically if BalanceNG has been installed using
the Solaris or Ubuntu/Debian packages.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 69 / 146
The command "no ipdb6" unloads the IPDB6 in memory database. Both, "ipdb6 <fle>" and
"no ipdb6" may be entered interactively even during operation as an active VRRP master.
During the time the database is being loaded packet processing is suspended for a short
time.
The command "ipdb6" accepts the 5-column format as found in the fle "IpToCountry.6R.csv"
as available for free from software77.net (URL: http://software77.net/geo-ip/ ).
$.$.11 lgr"
Synopsis: lgrp 7+-W8 7specifica"ion8
no lgrp 7+-W8
no lgrp
This command specifes a location group based on the set of locations as found in the IP-to-
location database (IPDB). A location group is being referenced by a single, capital letter such
allowing 26 location groups per BalanceNG instance. A target may be associated with exactly
one location group (see "target <n> lgrp").
The specifcation of a location group may contain one of the following tokens, separated by
commas:
1) A dual character location reference which declares to include that location in the
location group (allowed characters are [A-Z] and [0-9]).
2) A single group letter ([A-Z]) referencing a different location group to be included to the
specifed group.
3) The special character "*" declaring "all possible locations" including locations not
found in the database.
4) The special character "-" referencing the "not found" pseudo location.
All four token types may be preceded by a "!", which specifes that the location set is not part
of the location group. Recursion and self-referencing of location groups is not allowed.
Examples:
lgrp + ^A>4+T4-<_ Location group A should include locations DE,AT and CH.
lgrp B ^C4J+_ Location group B should include "everything" but not lgrp A.
lgrp - ^-_ Location group C should include only "not found" entries.
lgrp A ^+4B4J-_ Location group B should include group A, group B, but
not location group C.
$.$.12 license
Synopsis: license 7serial-n09ber8 7license-ke/8
This command fully activates BalanceNG using the purchased license for exactly this node.
The serial number and license key is being provided by Inlab Software GmbH. The license-
key is only valid for exactly one specifc node identifed by its nodeid (see also "show
no&ei&").
BalanceNG with no or without valid licensing information is operational with Basic Licensing
restrictions, Please take a look at the summary chapter at above.
The effect of the "license" command can be examined with "show license".
Example:
bng# show license
no license specifie&
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 70 / 146 Grünwald Germany / All Rights Reserved
bng# show no&ei&
faeE55;)))a(
bng# license be"a!;3 e0bf3035c3c)H3eeH;5eae!bbb30c3!b
bng# show license
s"a"0s vali& f0ll license
serial T>ST0)!!0;!
no&ei& ;ae;Ef3(&a;0
"/pe Ishow versionI for version an& -op/righ" infor9a"ion
bng#
$.$.15 log
Synopsis: log 79essage8
This command logs a specifc message to the BalanceNG log.
Example:
bng# log ^now s"ar"ing wi"h 0pgra&e_
bng#
$.$.16 *acallo&
Synopsis: 9acallow 7B+- a&&ress8
no 9acallow
This command enters the MAC address into the set of "macallow" addresses. If the module
"macallow" is in the module chain, all packets with a source MAC address out of this set will
be forwarded and all other packets will be discarded. "no macallow" empties the complete
list.
$.$.E *acdenA
Synopsis: 9ac&en/ 7B+- a&&ress8
no 9ac&en/
This command enters the MAC address into the set of "macdeny" addresses. If the module
"macdeny" is in the module chain, all packets with a source MAC address out of this set will
be discarded. "no macdeny" empties the complete list.
$.$.1 *acrouter
Synopsis: 9acro0"er 7B+- a&&ress8
no 9acro0"er
This command allows the declaration of routing devices by specifying their MAC address. If a
routing device is specifed this way, updates of the internal ARP table are disabled in the
special case that the source IPv4 address is already known to be reachable directly.
Example:
bng# 9acro0"er !!;;334455))
bng# 9acro0"er !!;;334455)H
bng# show conf
...
9acro0"er O
!!;;334455))
!!;;334455)H
P
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 71 / 146
...
bng#
$.$. *odules
Synopsis: 9o&0le 79o&0le8
9o&0les 79o&0le!8479o&0le;84...
This command defnes the module chain which controls the core functionality of BalanceNG.
The command "show modules" displays a list of supported module chains and a short
description of the available modules.
BalanceNG encapsulates packet processing functionalities in modules. The module chain
defnes a sequential order of modules and thus controls the core functionality of the
BalanceNG packet handling engine.
If there's no module chain specifed in the confguration, the module chain initializes with "vrrp
classic" in order to maintain BalanceNG V2 compatibility.
There are the following 5 supported standard module chains:
bench*ar-
This single module module chain needs to be in place for running the BalanceNG
benchmark.
s&itch
This single module module chain implements a simple Layer 2 switch.
.rr"9classic
This module chain implements BalanceNG V2 compatibility.
.rr"9ar"9"ing9hc9*aster9slb9tnat9nat9rt
This is the standard module chain for SLB (server load balancing) processing of IPv4
and IPv6 traffc.
.rr"9ar"9"ing9hc9*aster9llb
This is the standard module chain for LLB (link load balancing) of IPv4 and IPv6
traffc.
The following modules are available:
$.$..1 ar"
The arp module answers IPv4 ARP requests and IPv6 ND (Neighbor Discovery) requests for
IP addresses represented by BalanceNG. Additionally, it processes IPv4 ARP and IPv6 ND
replies.
$.$.. bench*ar-
The benchmark module has to be in place for the built-in hardware benchmark (see
"benchmark" command).
$.$..$ classic
This module encapsulates all BalanceNG 2.x functionality.
$.$.., crosso.er
This module implements a virtual crossover cable which may connect two virtual TAP
interfaces. The following example dialog shows a simple confguration of a BNG instance 1,
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 72 / 146 Grünwald Germany / All Rights Reserved
which implements two virtual TAP interfaces on the Linux host (veth0 and veth1) and
connects them with a virtual crossover cable implemented by the "crossover" module:
cD!Dcrossover# sh conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
hos"na9e cD!Dcrossover
license #N%+B H&&eHc5H55b)4cc0bbc0H)He&ee!&)fb
9o&0le crossover
in"erface ! O
na9e ve"h0
access "ap
"hrea&s 4
ini" Iip a&&r a&& !0.0.0.!:;4 &ev ve"h0Q ip link se" ve"h0 0pI
P
in"erface ; O
na9e ve"h!
access "ap
"hrea&s 4
ini" Iip a&&r a&& !0.0.0.;:;4 &ev ve"h!Q ip link se" ve"h! 0pI
P
regis"er in"erfaces !4;
enable in"erfaces !4;
:: en& of config0ra"ion
cD!Dcrossover#sh ins"
"his is BalanceNG ins"ance !
cD!Dcrossover#
$.$../ hc
This module encapsulates all health-check processing (IPv4 and IPv6).
$.$..1 i"allo&
The ipallow module allows only packets to pass which source IP address is in the ipallow list
of IP addresses (see ipallow command). All other packets are dropped.
$.$..2 i"denA
The ipdeny module drops packets, whose source address is contained in the ipdeny list of IP
addresses (see ipdeny command). All other packets are passed unchanged.
$.$..5 llb
The "llb" module implements IPv4 and IPv6 Link Load Balancing (LLB) with automatic IPv4
and IPv6 NAT (Network Address Translation).
The parameter "ipforwarding" needs to be set to 1 ("set ipforwarding 1") and the "llb" modules
needs to be part of the module chain. Additionally, VRRP needs to be active.
All traffc received on a special "ipaddr any" virtual server (which may be the default route) is
distributed among the targets, representing outgoing routers (e.g. DSL lines) in that case.
$.$..6 *acallo&
This is a positive MAC address flter.
$.$..1E *acdenA
This is a negative MAC address flter.
$.$..11 *aster
This module passes packets to the remaining part of the chain if the instance is VRRP
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 73 / 146
master.
$.$..1 nat
The "nat" module implements both IPv4 and IPv6 network address translation. The parameter
"ipforwarding" needs to be set to 1 ("set ipforwarding 1"). Network translation state is kept in
the "Generic NAT" table (GNAT) and is synchronized with a special, non-standard VRRP
packet (type 5) to the backup if parameter "natsync" is set to "1" (which is the default).
VRRP needs to be active for this module and the "network virt" addresses need to be used as
routing endpoints. All traffc received at "network virt" routing addresses on a network with
"nat inside" are translated to the "network virt" address of the network with the "nat outside"
property.
Packets of the following types are processed: IPv4 (UDP, TCP, ICMP ECHO) and IPv6 (UDP,
TCP, ICMP ECHO). You may "ping" to the outside from a host which is located in a "nat
inside" network either over IPv4 or IPv6.
$.$..1$ "ing
This answers IPv4 and IPv6 echo requests sent to virtual IP addresses represented by
BalanceNG.
$.$..1, rt
This module implements IPv4 and IPv6 routing and should be placed at the very end of the
module chain. The parameter "ipforwarding" needs to be set to 1 in order to enable routing.
$.$..1/ slb
This is the IPv4/IPv6 server load balancing module.
$.$..11 s&itch
This module implements a simple layer 2 switch.
$.$..12 tnat
This modules implements IPv4 and IPv6 "target" NAT allowing a 1:1 network address
translation optionally selectable by protocol and port (see "tnat" command).
$.$..15 .rr"
This module processes VRRP replies and control the VRRP status (master/backup) of the
BalanceNG instance.
$.$.$ net&or- FnG
Synopsis: ne"work 7n8 7s0bco99an&8 7val0e8
This command family is used to specify network defnitions in the BalanceNG confguration.
The special subcommand "{" opens a network defnition block interactively, so that the frst
two arguments can be omitted until the block is closed with a corresponding "}". A currently
open block is indicated by a "+"-sign at the end of the command line prompt (instead of a "#").
The network index may range from 1 to 10, such allowing a total of 10 network section per
BalanceNG instance.
A network ca only be enable, if "addr", "mask", "real" and "virt" parameters are all specifed
correctly.
Example:
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 74 / 146 Grünwald Germany / All Rights Reserved
bng# ne"work ! O
bng* a&&r !0.3.3.0
bng* 9ask ;55.;55.;55.0
bng* real !0.3.3.!0
bng* vir" !0.3.3.;0
bng* P
bng#
$.$.$.1 net&or- FnG addr
Synopsis: ne"work 7n8 a&&r 7a&&ress8
This command specifes the network address of the specifed network. The host part of the
network must be all "0" bits (determined by the "mask" specifcation).
This address is not a virtual IP address (not "pingable") and has to be specifed equally on all
participating VRRP nodes.
Example:
bng# ne"work ; a&&r !0.;0.0.0
bng# co99i" ne"work ;
9ask of ne"work ; no" specifie&
bng#
$.$.$. net&or- FnG interface?s@
Synopsis: ne"work 7n8 in"erface2s6 7lis"8
This command associates one or more interfaces to the network with the given number. All
interfaces in the list have to be activated using the "interface" command before. Multiple
networks may share the same interfaces (or interface).
In general network activities will be restricted on the specifed interfaces, e.g.:
• ARP-requests will be sent out only to the specifed interfaces for IP addresses in the
network
• ARP-requests are only accepted (and answered) if received on a suitable interface.
• ICMP-echo requests ("ping's") will be not answered on not associated interfaces.
• VRRP multicast packets will only be sent out on interfaces associated to the VRRP
network.
Example:
bng# in"erface e"h0
in"erface e"h0 s0ccessf0ll/ a""ache&
bng# in"erface e"h!
in"erface e"h! s0ccessf0ll/ a""ache&
bng# ne"work ; in"erface e"h0
bng# show ne"works
# na9e S ne"a&&r ne"9ask real a&&r vir" a&&r in"erfaces
------------------------------------------------------------------------------------
; A !0.;0.0.0 0.0.0.0 0.0.0.0 0.0.0.0 e"h0
bng# ne"work ; in"erface e"h04e"h!
bng# show ne"works
# na9e S ne"a&&r ne"9ask real a&&r vir" a&&r in"erfaces
------------------------------------------------------------------------------------
; A !0.;0.0.0 0.0.0.0 0.0.0.0 0.0.0.0 e"h04e"h!
bng#
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 75 / 146
$.$.$.$ net&or- FnG *as-
Synopsis: ne"work 7n8 9ask 7ne"9ask8
This specifes the IP4 netmask for the given network.
Example:
bng# in"erface e"h!
in"erface e"h! s0ccessf0ll/ a""ache&
bng# ne"work 3 a&&r !0.;0.0.0
bng# ne"work 3 9ask ;55.;55.0.0
bng# co99i" ne"work 3
vir" of ne"work 3 no" specifie&
bng#
$.$.$., net&or- FnG *as-1
Synopsis: ne"work 7n8 9ask) 7#$v) ne"9ask8
This specifes the IPv6 netmask prefx for the given network.
Example:
bng# in"erface e"h!
in"erface e"h! s0ccessf0ll/ a""ache&
bng# ne"work 3 real) ;00!AB(4
bng# ne"work 3 9ask) 3;
bng# co99i" ne"work 3
$.$.$./ net&or- FnG na*e
Synopsis: ne"work 7n8 na9e 7na9e8
This command specifes an optional name for the given network. Specifying "none" removes
the current name defnition. The network name may be embedded in double quotes to specify
a name containing spaces. Specifying an empty string in double quotes also removes the
current name defnition.
Example:
bng# ne"work 3 na9e "es"!;3
bng# show ne"works
# na9e S ne"a&&r ne"9ask real a&&r vir" a&&r in"erfaces
------------------------------------------------------------------------------------
3 "es"!;3 A !0.;0.0.0 ;55.;55.0.0 0.0.0.0 0.0.0.0 -
bng# ne"work 3 na9e none
bng# show ne"works
# na9e S ne"a&&r ne"9ask real a&&r vir" a&&r in"erfaces
------------------------------------------------------------------------------------
3 A !0.;0.0.0 ;55.;55.0.0 0.0.0.0 0.0.0.0 -
bng#
$.$.$.1 net&or- FnG nat
Synopsis: ne"work 7n8 na" insi&eNo0"si&eNoff
This network parameter controls the participation of the network in NAT (network address
translation). If "network nat" is set to "inside", all IP addresses in that network are being
translated to the "network virt" address of the network with "network nat" set to "outside".
Only one network may have "nat outside" set, NAT is active as soon as at least one network
with "nat inside" and one network with "nat outside" exist and are enabled.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 76 / 146 Grünwald Germany / All Rights Reserved
NAT table entries are synced per default between master and backup nodes (if VRRP is
active). See the NAT parameters for more information.
Example:
na"-"es"# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
hos"na9e na"-"es"
license "es"!;3 ))0a;4a35!)Hcc(e)Eacfe;;3cc;&3)0
in"erface bge0
in"erface nge0
ne"work ! O
a&&r !0.!35.!!0.0
9ask ;55.;55.;55.0
real !0.!35.!!0.)!
vir" !0.!35.!!0.);
na" o0"si&e
in"erface bge0
P
ne"work ; O
a&&r !0.!H.;.0
9ask ;55.;55.;55.0
real !0.!H.;.)!
vir" !0.!H.;.);
na" insi&e
in"erface nge0
P
regis"er ne"works !4;
enable ne"works !4;
ga"ewa/ O
ipa&&r !0.!35.!!0.;54
ping 54!;
P
:: en& of config0ra"ion
ne"-"es"#
$.$.$.2 net&or- FnG real
Synopsis: ne"work 7n8 real 7real ip a&&ress8
This specifes a "real" IP address for the given network. The IP address has to be "inside" the
network (according to the address and netmask settings). This address is a "pingable" virtual
IP address (active on the networks interfaces). It has to be unique for each BalanceNG node
in a VRRP setup (it will not hop at a VRRP failover).
The specifcation of a "real" (node specifc) address is recommended, since it is needed to
make ARP-lookups and health checks work (they both need an originating address).
It is being used for the following purposes:
• ARP-requests are using it as the source address resolving IP addresses in the network
• Health-checks will use it as the source address checking targets in this particular network.
Example:
bng# ne"work 3 real !0.;0.3.3
bng# show ne"works
# na9e S ne"a&&r ne"9ask real a&&r vir" a&&r in"erfaces
------------------------------------------------------------------------------------
3 A !0.;0.0.0 ;55.;55.0.0 !0.;0.3.3 0.0.0.0 -
bng#
$.$.$.5 net&or- FnG real1
Synopsis: ne"work 7n8 real) 7real #$v) a&&ress8
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 77 / 146
This specifes a "real" IPv6 address for the given network.
$.$.$.6 net&or- FnG sAnciface
Synopsis: ne"work 7n8 s/nciface 7in"erface8
This specifes a dedicated interface, where session synchronization traffc and NAT
synchronization traffc should be directed.
Using this, a dedicated crossover cable may be put between two BalanceNG VRRP nodes in
order to separate this traffc from everything else. This command is only effective in a network
section which is referenced by the VRRP section.
Example:
in"erface e"h!
in"erface e"h;
vrrp O
...
ne"work !
...
P
ne"work ! O
...
in"erface e"h!
s/nciface e"h;
...
P
$.$.$.1E net&or- FnG .irt
Synopsis: ne"work 7n8 vir" 7a&&ress8
This specifes the virtual address in the given network. This is a "pingable" address that is
being shared bet&een all J((7 nodes.
The specifcation of a network "virt" address is not mandatory (using 0.0.0.0 as "unspecifed").
This should be used as a routing endpoint (gateway) for all hosts in tat network, e.g.:
• Default gateway for targets in that network
• Gateway for targets in that network using a specifc routing rule.
Example:
bng# ne"work 3 vir" !0.;0.4.4
bng# enable ne"work 3
bng# show ne"works
# na9e S ne"a&&r ne"9ask real a&&r vir" a&&r in"erfaces
------------------------------------------------------------------------------------
3 > !0.;0.0.0 ;55.;55.0.0 !0.;0.3.3 !0.;0.4.4 -
bng#
$.$.$.11 net&or- FnG .irt1
Synopsis: ne"work 7n8 vir") 7#$v) a&&ress8
This specifes the virtual IPv6 address for the given network. This address is represented by
all VRRP nodes and may be used as a routing endpoint.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 78 / 146 Grünwald Germany / All Rights Reserved
$.$., no
Synopsis: no 7co99an&8
This special command reverts another command and eventually removes the confguration
command out of the current confguration. This applies to a subset of commands, the
following commands are revertable by "no" (in alphabetical order):
arp, &09p, ga"ewa/, hos"na9e, license4 "na" and vip.
The arguments of the original command are only checked if necessary when reverting it with
"no".
Example:
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
:: en& of config0ra"ion
bng#
bng# vip !E;.!)(.!.!00
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
vip !E;.!)(.!.!00
:: en& of config0ra"ion
bng# no vip !E;.!)(.!.!00
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
:: en& of config0ra"ion
bng#
$.$./ register
Synopsis: regis"er 7ne"works2s6N"arge"2sPNserver2s68 7lis"8
The specifed list of networks, targets or servers (or just one of them) is taken from the
"unregistered" state to the "registered state".
Target and Ser.er4 8e#nitions and States
A "Network" in BalanceNG associates the network parameters to a set of physical interfaces.
A "Server" in BalanceNG is a "virtual Server" and an addressable virtual "Host" that is capable
to forward and load balance requests to the so called "real servers", the Targets.
A "Target" in BalanceNG is associated with a real existing address in the Target Network.
One Server is associated to one or more Targets and performs load balancing between them
according to the specifed load balancing methods.
Both Servers and Targets are associated automatically to a network according to the
addressing.
Each Network, Server or Target is inside in BalanceNG in one of three states. See the state
diagram below:
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 79 / 146
!igure ,4 Ser.er and Target States
The states are defned as follows:
;unregistered;:State
Each Target or Server is initially in that state. The Target or Server is unknown for
BalanceNG and there's no associated functionality. The Entity (Target or Server) does
not appear in the confguration. This state allows parameters and settings of the
Target or Server to be edited and changed.
The command "regis"er" registers the Target or Server and it's internal state
changes to registered.
Using the abbreviation command "co99i"" the Target or Server may also be
immediately taken to the "enabled"-State.
;registered;:State
In this state the entities (Target or Servers) are registered at the internal
administrative data structures of BalanceNG. They appear in the confguration (e.g. at
"show conf") but are not functional. The can not be edited or changed in that state.
The further properties in this state are as follows:
Net&or-s4
• Network is visible in "show networks"
Targets4
• Health checks are not being executed
• Targets are not being addressed by their associated Servers (they appear in
square brackets at "show servers").
• ARP resolving is not being performed
Ser.ers4
• ARP request are not answered
• ICMP echo requests are not answered ("pings")
• Requests to Services are ignored
• No VRRP sharing of Server address
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 80 / 146 Grünwald Germany / All Rights Reserved
unregistered
(Start)
enabled
registered
regis"er
0nregis"er
e
n
a
b
l
e
&
i
s
a
b
l
e
c
o
9
9
i
" e
&
i
"
The command "enable" puts the entity into "enabled" state, the command
"0nregis"er" puts it back into "unregistered" state.
;enabled;:state
In that state the entities are functional, that means the following:
Net&or-s4
• "real" and "virt" addresses are pingable and usable by all other processing.
• VRRP is usable on the VRRP network
Targets4
• ARP resolving of the targets IP-address is performed
• Health checks are being executed according to the defnitions
• Targets participate in load balancing is their health checks succeed
Ser.ers4
• ARP requests are being answered
• ICP-ECHO requests ("Pings") are being answered
• Requests to Services are "load balanced" to the associated targets
• The session tables are active
• The Servers address is being shared using VRRP (if activated)
Examples:
BalanceNG connec"e& "o $#A (!5(
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
:: en& of config0ra"ion
bng#
bng# ne"work ! a&&r !0.3.3.0
bng# ne"work ! 9ask ;55.;55.;55.0
bng# ne"work ! real !0.3.3.!
bng# ne"work ! vir" !0.3.3.;
bng# regis"er ne"work !
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
ne"work ! O
a&&r !0.3.3.0
9ask ;55.;55.;55.0
real !0.3.3.!
vir" !0.3.3.;
in"erface none
P
regis"er ne"work !
:: en& of config0ra"ion
bng#
bng# "arge" ! ipa&&r !0.3.3.!0
bng# regis"er "arge" !
bng# show conf
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 81 / 146
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
ne"work ! O
a&&r !0.3.3.0
9ask ;55.;55.;55.0
real !0.3.3.!
vir" !0.3.3.;
in"erface none
P
regis"er ne"work !
"arge" ! O
ipa&&r !0.3.3.!0
P
regis"er "arge" !
:: en& of config0ra"ion
bng#
$.$.1 reload
Synopsis: reloa&
This command allows to reload the confguration fle and potentially updated server / target
relationships where not affected session-table entries are maintained.
The command reload fails, if there are any changes to the network and vrrp sections or to the
"set" parameter section (and a "bng restart" is required immediately afterwards). In that case
the error message "ERROR: was unable to reload, restart required." is displayed and
reported to the log.
Example:
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A ()H3
bng# reloa&
$.$.2 re*ar-
Synopsis: re9ark I7arbi"rar/ re9arks8I
This command is available to allow adding custom remarks to the confguration fle. This
might be helpful e.g. for version tracking, confguration management and more.
The following example shows how the remark confguration command could be used to
transport the Id of RCS (Revision Control System).
Example:
# :e"c:ini".&:bng res"ar"
BalanceNG no" /e" r0nning
BalanceNG s"ar"ing 0p ...
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A ()H3
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
:: en& of config0ra"ion
bng# re9ark IL#&LI
bng# save
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 82 / 146 Grünwald Germany / All Rights Reserved
ok
bng# ... b/e
# ci -l :e"c:bng.conf
:e"c:bng.conf4v 7-- :e"c:bng.conf
en"er &escrip"ion4 "er9ina"e& wi"h single 1.1 or en& of file
NFT> This is NFT "he log 9essageJ
88 BalanceNG config0ra"ion Si&e +
88
ini"ial revision !.!
&one
# :e"c:ini".&:bng res"ar"
BalanceNG sh0"&own of $#A ()H3 co9ple"e
BalanceNG s"ar"ing 0p ...
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A ()(3
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
re9ark IL#& bng.conf4v !.! 03:!E:;00) !!!H roo" >?p roo" LI
:: en& of config0ra"ion
bng#
$.$.5 ser.er FnG
Synopsis: server 7n8 7s0bco99an&8 7val0es8
This command is used to confgure the parameters of a BalanceNG server. In general this is
only possible if the Server is in the "unregistered" state (see the explanations at the
"regis"er" command).
The server index may range from 1 to 512, such allowing a total of 512 server sections per
BalanceNG instance.
BalanceNG is capable of handling 512 independent Servers. Each server has one or multiple
associated Targets where the load is being distributed to.
$.$.5.1 ser.er FnG bac-u"?s@
Synopsis: server 7n09ber8 back0p2s6 7lis"8NInoneI
This command assigns one or more backup targets to the Server with the specifed number.
Backup targets are being addressed if either there's no available addressable operational
target available or if the "frst choice" target fails and the Server's failover mode is "back0p"
(see "server 7n8 failover").
The list of backup targets contains of the backup target numbers separated by commas.
The command "server 7n8 back0p none" deletes the list of backup targets completely. If
there are multiple backup targets available BalanceNG always uses a Round Robin
distribution among them.
The specifcation of a backup target together with "failover back0p" allows the
confguration of "N+1" high availability, where the overall load capacity of the target cluster
remains the same even if one target fails.
Example:
BalanceNG connec"e& "o $#A (!)E
bng# server ! "arge"s !4;
bng# server ! ipa&&r !0.!!.40.!;
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 83 / 146
bng# server ! back0p 3
bng# co99i" server !
U+,N#NG server ! has no 9a"ching ne"work
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
server ! O
ipa&&r !0.!!.40.!;
"arge"s !4;
back0p 3
P
regis"er server !
enable server !
:: en& of config0ra"ion
bng#
$.$.5. ser.er FnG failo.er
Synopsis: server 7n8 failover Iback0pINInor9alI
This command allows to switch a virtual server from normal failover mode to "backup" failover
mode (and backwards). This has only an effect for the round-robin (default) method.
If this frst target is not operational (either because disabled or a health check is failing) then
BalanceNG selects the "next" alternate target among the group of defned targets (failover
mode "normal").
If the failover mode for that server is "backup" then BalanceNG immediately selects a target
from the set of backup targets.
Example:
bng# e&i" server !
bng# server ! failover back0p
bng# co99i" server !
U+,N#NG server ! has no 9a"ching ne"work
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
server ! O
ipa&&r !0.!!.40.!;
failover back0p
"arge"s !4;
back0p 3
P
regis"er server !
enable server !
:: en& of config0ra"ion
bng#
$.$.5.$ ser.er FnG fti*eout F.alueGKdefault
Synopsis: server 7n8 f"i9eo0" 7val0e8N&efa0l"
This command sets a server specifc TCP FIN/RST session timeout in seconds. A value of 0
or the string "default" disables this server specifc TCP FIN/RST timeout.
As soon as a TCP FIN or RST packet is seen for such a session (in each direction), the
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 84 / 146 Grünwald Germany / All Rights Reserved
session specifc timeout will be degraded to that value. This session table entry event will be
synchronized to the VRRP backup.
This command directive is implemented in the "slb" module for TCP IPv4 and TCP IPv6.
The garbage collection mechanism will then remove (or reclaim) that entry when this new
timeout expires (if there's no more associated traffc).
The minimum value is 5 seconds, the maximum value is 172880 seconds (48 hours).
$.$.5., ser.er FnG gslb dis"atch
Synopsis: server 7n8 gslb &ispa"ch
This server setting instructs BalanceNG to intercept DNS traffc which is handled by this
server and instructs BalanceNG to directly return special A-record replies for a specifc set of
requested names.
The virtual server containing this instruction typically needs to do load balancing of DNS
traffc on port 53 for both UDP and TCP for this kind of operation.
Only UDP traffc is handled by this setting. If an A record is requested for a name which is set
as "name" of a different virtual server with "gslb enable" set, then the IPv4 address of the next
available target is returned applying the usual load balancing and health check rules.
Example:
In this example "server 1" is used to load-balance DNS traffc to targets 1 and 2. If an A record
is requested for "example.balanceng.net" (the "name" of server 2), then the IP address of
either target 10 or 11 is returned instead with a TTL of only 10 seconds. The target is selected
with the "session" method using the usual session management and health check rules.
server ! O
gslb dispatc!
ipa&&r !H;.!H.;.H0
por" 53
ip&b enable
9e"ho& session
"arge"s !4;
P
server ; O
na9e e?a9ple.balanceng.ne"
gslb enable
gslb""l !0
9e"ho& session
"arge"s !04!!
P
regis"er server !4;
enable servers !4;
$.$.5./ ser.er FnG gslb enable
Synopsis: server 7n8 gslb enable
This command enables GSLB (global server load balancing) operation for the server. If an
DNS A-record request received on a virtual server with "gslb dispatch" set and if the name of
this server matches the "name" of the server with "gslb enable" set, then BalanceNG returns
the Ipv4 address of the target according to the usual load balancing and session handling
rules.
Example:
server ! O
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 85 / 146
gslb &ispa"ch
ipa&&r !H;.!H.;.H0
por" 53
ip&b enable
9e"ho& session
"arge"s !4;
P
server ; O
na9e e?a9ple.balanceng.ne"
gslb enable
gslb""l !0
9e"ho& session
"arge"s !04!!
P
regis"er servers !4;
enable servers !4;
...
"arge" !0 O
ipa&&r !0.!!.!;.!
...
P
"arge" !! O
ipa&&r !0.!!.!;.;
...
P
$.$.5.1 ser.er FnG gslbttl
Synopsis: server 7n8 gslb""l 7secon&s8
This command specifes the DNS TTL which should be returned in the A-records generated
with GSLB processing.
Example:
...
server ; O
na9e e?a9ple.balanceng.ne"
gslb enable
gslbttl '0
9e"ho& session
"arge"s !04!!
P
regis"er servers !4;
enable servers !4;
$.$.5.2 ser.er FnG i"addr
Synopsis: server 7n8 ipa&&r 7ip4-a&&ress8
server 7n8 ipa&&r none
This command specifes the IPv4 address of the Server. As soon as the Server is in "enabled"
State, BalanceNG responds to IPv4 ARP and ICMP ECHO (ping) requests and represents
that address that way.
If VRRP is enabled then this IP address is being shared between all BalanceNG nodes of the
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 86 / 146 Grünwald Germany / All Rights Reserved
VRRP vrid (virtual router id).
Example:
BalanceNG connec"e& "o $#A (!H;
bng# server ! ipa&&r !0.!!.40.!;
bng# server ! "arge" !
bng# regis"er server !
bng# enable server !
U+,N#NG server ! has no 9a"ching ne"work
bng# show server !
server !
ipa&&r !0.!!.40.!;
ne"work 0
por" an/
pro"ocol an/
s"a"0s enable&
9e"ho& rr
por"rel off
"arge" 2!6
bng#
If a special keyword "any" is supplied as the address, BalanceNG enters Link Load Balancing
mode and performs routing using the targets as Layer 3 routing endpoints.
The following example shows a confguration which offers a virtual router with the private
address 10.10.10.71 to a network and distributes the traffc evenly to two different outbound
routers.
Example:
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
license #N%+B0! &E4e!aH3bH54H(f4e!H5!b;E;53bf;&e
se" ipforwar&ing !
in"erface e"h0
in"erface e"h!
vrrp O
vri& !0
priori"/ ;55
ne"work ;
"racking enable
P
ne"work ! O
na9e I,o0"er Ne"workI
a&&r !H;.!H.;.0
9ask ;55.;55.;55.0
real !H;.!H.;.H0
vir" !H;.!H.;.H!
in"erface e"h0
P
ne"work ; O
na9e I#n"ernal Ne"workI
a&&r !0.!0.!0.0
9ask ;55.;55.;55.0
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 87 / 146
real !0.!0.!0.H0
vir" !0.!0.!0.H!
in"erface e"h!
P
regis"er ne"works !4;
enable ne"works !4;
server ! O
na9e IBalanceNG vir"0al ro0"erI
ipa&&r an/
9e"ho& session
"arge"s !4;
P
regis"er server !
enable server !
"arge" ! O
na9e IF0"bo0n& ,o0"er !I
ipa&&r !H;.!H.;.;54
ping ;45
P
"arge" ; O
na9e IF0"bo0n& ,o0"er ;I
ipa&&r !H;.!H.;.;53
ping ;45
P
regis"er "arge"s !4;
enable "arge"s !4;
:: en& of config0ra"ion
$.$.5.5 ser.er FnG i"addr1
Synopsis: server 7n8 ipa&&r) 7ip)-a&&ress8
server 7n8 ipa&&r) none
This command specifes the IPv6 address of the Server.
Example:
bng# server ! ipa&&r) fe(0;0ecfffe)c!
bng# co99i" server !
$.$.5.6 ser.er FnG i"db
Synopsis: server 7n8 ip&b enable
server 7n8 ip&b &isable
This command enables IPDB processing for the specifed server. All source Ipv4 addresses
are being looked up in the database updating the location counters. Targets that are
associated with a location group (see "target <n> lgrp") will receive traffc if the location of the
client source IP address is part of the target's location group.
The whole IPDB location based server load balancing is working with the load balancing
methods "agent", "bw", "bwin", "bwout", "random", "rndagent" and "session" (but not with
"hash", "rr" and server plugins).
It's valid to specify "server <n> ipdb enable" only, which allows to keep track of just the client
locations (as shown by the command "show locations").
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 88 / 146 Grünwald Germany / All Rights Reserved
Example:
bng# show conf
...
server ! O
ipa&&r !H;.!H.;.H0
por" 53
ip&b enable
9e"ho& session
"arge"s !4;
P
...
"arge" ! O
ipa&&r !H;.!H.;.E!
por" 53
lgrp +
ping 54!;
"cpopen 53454!;
&sr enable
P
...
bng#
$.$.5.1E ser.er FnG *ethod
Synopsis: server 7n8 9e"ho& IrrINIhashINIran&o9INIagen"IN...
This command specifes which load balancing method should be active for the specifed
Server. The load balancing method determines which target to choose for new sessions and
for sessions, where the associated target has become nonoperational (down).
The following methods are available:
$.$.5.1E.1 rr
This is the default "Round Robin" distribution method. Targets are chosen cyclically. A simple
weighting can be implemented by adding the same target twice or multiple times to the
servers target list. If the method "rr" is active there's no output in the confguration fle since
this is the default method.
$.$.5.1E. hash
Using a hash function with the client source IP address as the key each possible client source
address is being associated with the same target in a target set. This method may be used to
achieve a session persistence which "survives" even VRRP failover. Simple weighting is
possible here too by specifying the same target multiple times.
The hash function consists of XOR'ing the four octets of the source IP address modulo the
total number of associated (enabled) targets of the server.
The behaviour of this method may be modifed using the hashbytes4 and hashbytes6
parameters.
$.$.5.1E.$ rando*
One target out of the set is chosen randomly. A weighting is possible using the "target <n>
weight" keyword (see there). The default target weight is 1.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 89 / 146
$.$.5.1E., agent
All targets of a Servers target set have to be specifed with "agent" as one of the health
checks. This method chooses the target with the lowest agent return value (starting with 1).
This allows "least resource" load balancing using the bngagent program on the target.
Please take also a look at method "rndagent" which avoids overloading a target in some
situations.
Example:
BalanceNG connec"e& "o $#A (!H5
bng# server ! ipa&&r !0.;.;.!
bng# server ! 9e"ho& agen"
bng# server ! "arge"s !4!4;
bng# co99i" server !
U+,N#NG server ! has no 9a"ching ne"work
bng# show servers
# ipa&&r por" pr" ne" S "arge"s Oback0psP
------------------------------------------------------------
! !0.;.;.! an/ an/ 0 e 2!642!642;6 OP
bng# show server !
server !
ipa&&r !0.;.;.!
ne"work 0
por" an/
pro"ocol an/
s"a"0s enable&
9e"ho& agen"
por"rel off
"arge"s 2!642!642;6
bng#
$.$.5.1E./ b&
This method chooses the target which consumes the least current total bandwidth among all
targets of the server. The current total bandwidth value may be modifed virtually by the
"offset" and "scale" parameters of the target allowing arbitrary weighting and preference
settings.
Example:
bng# e&i" server !
bng# server ! 9e"ho& bw
bng# co99i" server !
bng# show server !
server !
ipa&&r !H;.!H.;.!(E
ne"work !
por" ;;
pro"ocol "cp
s"a"0s enable&
9e"ho& bw
por"rel off
"arge" !
bng#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 90 / 146 Grünwald Germany / All Rights Reserved
$.$.5.1E.1 b&in
This method operates like method "bw", but only the incoming bandwidth is taken into
account.
$.$.5.1E.2 b&out
This method operates like method "bw", but only the outgoing bandwidth is taken into
account.
$.$.5.1E.5 rndagent
This method takes the scores collected by the BalanceNG agent (bngagent) into account very
similar to the "agent" method. The difference is, that internally a weight is calculated per target
and that the next session is chosen by a weighted random algorithm.
The weight for rndagent is calculated by the following formula:
target_weightN = 100 * (1 - agent_scoreN / (agent_score1 + agent_score2 + ...));
The agent_scores above are calculated by the following formula:
agent_scoreN = original_agent_scoreN * target_scaleN + target_offsetN;
Example:
bng# e&i" server !
bng# server ! 9e"ho& rn&agen"
bng# co99i" server !
bng# show server !
server !
ipa&&r !H;.!H.;.!(E
ne"work !
por" ;;
pro"ocol "cp
s"a"0s enable&
9e"ho& rn&agen"
por"rel off
"arge" !
bng#
$.$.5.1E.6 session
This method chooses the target with the least number of current sessions as target for the
current new session.
Example:
bng# e&i" server !
bng# server ! 9e"ho& session
bng# co99i" server !
bng# show server !
server !
ipa&&r !H;.!H.;.!(E
ne"work !
por" ;;
pro"ocol "cp
s"a"0s enable&
9e"ho& session
por"rel off
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 91 / 146
"arge" !
bng#
The session distribution method may be modifed by the target "offset" and "scale" parameters
allowing weighting by applying a linear function to the current number of sessions.
$.$.5.11 ser.er FnG na*e
Synopsis: server 7n8 na9e 7na9e8NInoneI
Assigns a server a name for informational purposes. The string "none" as the name
arguments deletes the name from the specifed server.
The server name may be embedded in double quotes to specify a name containing spaces.
Specifying an empty string in double quotes also removes the current name defnition.
For GSLB (Global Server Load Balancing) this parameter contains the name for which an A
record should be returned by BalanceNG (GSLB needs to be enable with "gslb enable" for
that server).
Example:
bng# e&i" server !
bng# server ! na9e "es"44
bng# co99i" server !
U+,N#NG server ! has no 9a"ching ne"work
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
server ! O
na9e "es"44
ipa&&r !0.;.;.!
9e"ho& hash
"arge"s !4!4;
P
regis"er server !
enable server !
:: en& of config0ra"ion
bng# e&i" server !
bng# server ! na9e none
bng# co99i" server !
U+,N#NG server ! has no 9a"ching ne"work
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
server ! O
ipa&&r !0.;.;.!
9e"ho& hash
"arge"s !4!4;
P
regis"er server !
enable server !
:: en& of config0ra"ion
bng#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 92 / 146 Grünwald Germany / All Rights Reserved
$.$.5.1 ser.er FnG "lugin
Synopsis: server 7n8 pl0gin 7scrip"8NInoneINII
This command connects the session creation mechanism of the virtual server <n> to a plugin
program or script. The plugin script path has to be specifed as a full path name.
Specifying "none" or two double quotes ("") sets the plugin parameter of the virtual server to
"nothing", which is equivalent of disabling that feature.
A plugin script or program is connected through stdin and stdout and receives session
information as a line in readable ASCII format containing the following fve parameters
separated by a single blank:
1. Protocol "UDP" or "TCP"
2. Source IP Address Ipv4 address in numerical dot notation
3. Source Port decimal number
4. Destination IP Address Ipv4 address (usually that of the virtual server)
5. Destination Port decimal number
The result of the plugin is delivered back to BalanceNG by stdout by printing one line
consisting of a number in readable ASCII. The semantics are as follows:
Return Value Meaning
-1 This session request is denied, drop the packet
0 This session request is OK, proceed as usual
>= 1 The session should be directed to the target with this
specifc number (target has to be among the target set of
the virtual server).
WARNING: Server plugins should be as fast as possible since the BalanceNG core switching
engine actually waits until the plugin returned it's result value.
BalanceNG assumes an ultra fast, 100% working component at this very critical interface.
Plugins are started once at "server enable" and killed at "server disable".
Example:
Here's a simple example of a server plugin written in perl. This example implements a flter
which allows session only from source IP addresses originating from 10.10.10.0/24.
IMPORTANT: Setting the autofush (IO::Handle) functionality is required for perl scripts to
allow a line-by-line communication with BalanceNG (BalanceNG could stall otherwise).
#J:0sr:bin:perl
0se #F<an&leQ
a0"ofl0sh STAF@T !Q
while 'Lre50es" K 7STA#N8. O
cho9p Lre50es"Q
'Lpro"o4 Lsa&&r4 Lspor"4 L&a&&r4 L&por". K spli" :Ts*:4 Lre50es"Q
if'Lsa&&rK` 9:!0T.!0T.!0T.T&*:. O
prin"f'I0TnI.Q
P else O
prin"f'I-!TnI.Q
P
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 93 / 146
P
This script is connected using the "plugin" keyword inside a server block:
server ! O
ipa&&r !H;.!H.;.)4
por" (0
pro"ocol "cp
pl0gin :ho9e:bng:fil"er.pl
9e"ho& session
"arge"s !4;
P
$.$.5.1$ ser.er FnG "ort
Synopsis: server 7n8 por" 7por"spec8NIan/I
This command restricts the services being offered by the BalanceNG Server to a specifc port.
Per default any port (and any protocol) is being load balanced to the associated targets. If a
specifc port is specifed, then a new session is only created if the destination port towards the
Server matches this port.
The specifcation of a port may be removed / reverted to the default by applying the keyword
"an/".
If the port is specifed using this command, but the protocol is "any" then new sessions will be
created for both UDP and TCP packets.
A server with a specifed port and an associated target with a different port means that a port
translation takes place.
Example (round robin load balancing port 8080 to two targets port 80):
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A (!H(
bng# in"erface e"h0
in"erface e"h0 s0ccessf0ll/ a""ache&
bng# in"erface e"h!
in"erface e"h! s0ccessf0ll/ a""ache&
bng# ne"work ! O
bng* a&&r !0.;.;.0
bng* 9ask ;55.;55.;55.0
bng* real !0.;.;.!00
bng* vir" !0.;.;.!0!
bng* in"erface e"h0
bng* P
bng# ne"work ; O
bng* a&&r !E;.!)(.!.0
bng* 9ask ;55.;55.;55.0
bng* real !E;.!)(.!.!00
bng* vir" !E;.!)(.!.!0!
bng* in"erface e"h!
bng* P
bng# co99i" ne"works !4;
bng# "arge" ! ipa&&r !0.;.;.!
bng# "arge" ! por" (0
bng# "arge" ! pro"ocol "cp
bng# "arge" ! "cpopen (04!0430
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 94 / 146 Grünwald Germany / All Rights Reserved
bng# co99i" "arge" !
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
bng# "arge" ; ipa&&r !0.;.;.;
bng# "arge" ; por" (0
bng# "arge" ; pro"ocol "cp
bng# "arge" ; "cpopen (04!0430
bng# co99i" "arge" ;
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
U+,N#NG "arge" ; in enable& s"a"e b0" no" reference&
bng# server ! ipa&&r !E;.!)(.!.!
bng# server ! por" (0(0
bng# server ! pro"ocol "cp
bng# server ! "arge"s !4;
bng# co99i" server !
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
in"erface e"h!
ne"work ! O
a&&r !0.;.;.0
9ask ;55.;55.;55.0
real !0.;.;.!00
vir" !0.;.;.!0!
in"erface e"h0
P
ne"work ; O
a&&r !E;.!)(.!.0
9ask ;55.;55.;55.0
real !E;.!)(.!.!00
vir" !E;.!)(.!.!0!
in"erface e"h!
P
regis"er ne"works !4;
enable ne"works !4;
server ! O
ipa&&r !E;.!)(.!.!
por" (0(0
pro"ocol "cp
"arge"s !4;
P
regis"er server !
enable server !
"arge" ! O
ipa&&r !0.;.;.!
por" (0
pro"ocol "cp
"cpopen (04!0430
P
"arge" ; O
ipa&&r !0.;.;.;
por" (0
pro"ocol "cp
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 95 / 146
"cpopen (04!0430
P
regis"er "arge"s !4;
enable "arge"s !4;
:: en& of config0ra"ion
bng#
$.$.5.1, ser.er FnG "orts F"1G9F"G
Synopsis: server 7n8 por"s 7p!847p;8
This command specifes two related ports for a server. BalanceNG directs connections to
each of the ports always to the same target and manages sessions accordingly. This is useful
to combine e.g. port 80 and 443 in order to maintain the same target during a switchover from
HTTP to SSL-HTTP.
Port relevance of the server has to be switched off and the associated targets must have "port
any" specifed.
Example:
bng# e&i" server !
bng# server ! por"s (04443
bng# co99i" server !
bng# show server !
server !
ipa&&r !H;.!H.;.!(E
ne"work !
por"s (04443
pro"ocol an/
s"a"0s enable&
9e"ho& rr
por"rel off
"arge" !
bng#
$.$.5.1/ ser.er FnG "ortrel
Synopsis: server 7n8 por"rel onNoff
This command switches server specifc "port relevance" on or off. "Off"is the default which is
not displayed in the confguration fle.
Attention4 This co**and is onlA .alid for the BclassicC ser.er load balancing *odule.
7lease use the Bser.er FnG sessionidC co**and for the BslbC *odule.
When off, load balancing sessions are being created based only on the source IP address of
the client host addressing the server.
When on, also the source port is taken into account, a new connection from a different source
port from a already known client will cause a new session to be created (with an alternate
target, depending on the LB method). Connection persistence is then handled on connection
level, not on client IP address level.
This is useful when many different connections from a limited set of IP addresses have to be
load-balanced to the targets (e.g. one big HTTP-proxy).
Example:
bng# show server !
server !
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 96 / 146 Grünwald Germany / All Rights Reserved
ipa&&r !E;.!)(.!.!
ne"work ;
por" (0(0
pro"ocol "cp
s"a"0s enable&
9e"ho& rr
por"rel off
"arge"s '!.4';.
bng# e&i" server !
bng# server ! por"rel on
bng# co99i" server !
bng# show server !
server !
ipa&&r !E;.!)(.!.!
ne"work ;
por" (0(0
pro"ocol "cp
s"a"0s enable&
9e"ho& rr
por"rel on
"arge"s '!.4';.
bng#
$.$.5.11 ser.er FnG "rotocol
Synopsis: server 7n8 pro"ocol an/N"cpN0&pNsc"p
This command either restricts the server load balanced connections to tcp, udp, sctp or to any
of these protocols.
SCTP support is experimental and available in DSR mode only.
This command may be used with "server 7n8 por"" in any combination.
Example:
bng# e&i" server !
bng# server ! ipa&&r !0.;.;.4
bng# server ! pro"ocol an/
bng# co99i" server !
bng# show server !
server !
ipa&&r !0.;.;.4
ne"work !
por" (0(0
pro"ocol an/
s"a"0s enable&
9e"ho& rr
por"rel on
"arge"s '!.4';.
bng#
$.$.5.12 ser.er FnG "ro+A enable
Synopsis: server 7n8 pro?/ enable
This command enables proxy mode for the specifed server and is implemented in the "slb"
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 97 / 146
module. If enabled, connections to the virtual server are forwarded to the selected target by
replacing the original client IP address and port by the IP address of the virtual server and a
new source port. Per default, "server <n> proxy" is disabled. This mechanism works for IPv4
and IPv6 addresses, state information is replicated from the VRRP server node to the VRRP
backup node.
Example:
:: config0ra"ion "aken T0e Nov !) !5;355 ;0!0
:: BalanceNG 3.44E 'crea"e& ;0!0:!!:!).
license #N%+B-T>ST-0! 5(4e)beefec!)c55cb&5ce(fa(&!aH4a
9o&0les vrrp4arp4ping4hc49as"er4slb
in"erface ! O
na9e e"h0
P
regis"er in"erface !
enable in"erface !
vrrp O
vri& 33
priori"/ ;00
ne"work !
P
ne"work ! O
a&&r !H;.!H.;.0
9ask ;55.;55.;55.0
real !H;.!H.;.55
vir" !H;.!H.;.5)
in"erface !
P
regis"er ne"work !
enable ne"work !
server ! O
ipa&&r !H;.!H.;.5(
por" (0
pro"ocol "cp
pro+y enable
"arge"s !4;
P
regis"er server !
enable server !
"arge" ! O
ipa&&r !H;.!H.;.30
por" (0
pro"ocol "cp
"cpopen (0434!0
P
"arge" ; O
ipa&&r !H;.!H.;.3!
por" (0
pro"ocol "cp
"cpopen (0434!0
P
regis"er "arge"s !4;
enable "arge"s !4;
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 98 / 146 Grünwald Germany / All Rights Reserved
:: en& of config0ra"ion
$.$.5.15 ser.er FnG sessionid FhandlerG
This command associates a specifc session handler to a particular virtual server. The "slb"
(Server Load Balancing) Module needs to be part of the current module chain.
$.$.5.15.1 si"
The sessionid is based on SIP/UDP Call-ID only.
$.$.5.15. src
The sessionid is based only on the source IP address.
$.$.5.15.$ srcLdst"ort
The sessionid is based on the source IP address and the destination port.
$.$.5.15., srcL"ort
The sessionid is based on the source IP address and the source port.
$.$.5.15./ srcL"orts
The sessionid is based on the source IP address and both the source and destination ports.
$.$.5.15.1 dst
The sessionid is based only on the destination IP address.
$.$.5.15.2 dstL"ort
The sessionid is based on the destination IP address and the destination port.
$.$.5.15.5 dstL"orts
The sessionid is based on the destination IP address and both the source and destination
ports.
$.$.5.15.6 dstLsrc"ort
The sessionid is based on the source IP address and the source port.
$.$.5.16 ser.er FnG snat enableKdisable
Synopsis: server 7n8 sna" enableN&isable
This command enables or disables SNAT processing in the SLB module for a specifc virtual
server, respectively. See also "snatrange" and "show snat" as related commands.
$.$.5.E ser.er FnG sti*eout F.alueGKnullKdefault
Synopsis: server 7n8 s"i9eo0" 7val0e8N&efa0l"
This command sets a server specifc session timeout in seconds. A value of 0 or the string
"default" disables the server specifc sessions timeout, in that case the global session timeout
is valid for all sessions (see the parameter "sessiontimeout").
The special value "null" disables session generation completely, which is useful to implement
true round robin load-balancing for UDP protocols (like SIP).
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 99 / 146
The minimum value is 10 seconds, the maximum value is 172880 seconds (48 hours).
Example:
bng# show server 4
server 4
ipa&&r !H;.!H.;.(;
ne"work !
por" ;;
pro"ocol "cp
s"a"0s enable&
9e"ho& rr
por"rel off
"arge" !
bng# e&i" server 4
bng# server 4 s"i9eo0" !;0
bng# co99i" server 4
bng#
$.$.5.1 ser.er FnG target?s@
Synopsis: server 7n8 "arge"2s6 7lis"8Nnone
This command associates one or more targets to the specifed server. The "virtual" server
then distributes the requests to the operational targets in that set according to the specifed
load balancing method.
One or more target can be specifed. The same target may appear multiple times to allow a
simple weighting of the distribution.
Either the singular or plural of ""arge"I may be used.
Specifying "none" as list parameter completely empties the list of associated targets.
Example:
bng# e&i" server !
bng# server ! "arge"s !4;4344454)4H4(
bng# co99i" server !
bng# show server !
server !
ipa&&r !0.;.;.4
ne"work !
por" (0(0
pro"ocol an/
s"a"0s enable&
9e"ho& rr
por"rel on
"arge"s '!.4';.42364246425642)642H642(6
bng# show servers
# ipa&&r por" pr" ne" S "arge"s Oback0psP
------------------------------------------------------------
! !0.;.;.4 (0(0 an/ ! e '!.4';.42364246425642)642H642(6 OP
bng#
$.$.6 set
Synopsis: se" 7para9e"er8 7val0e8NI&efa0l"I
BalanceNG uses a set of internal parameters. Using set these parameters may be changed.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 100 / 146 Grünwald Germany / All Rights Reserved
All parameters are numeric with a minimum, a maximum and a default. If the parameter is
currently set to the default value then no "se"" line appears in the confguration fle (see
"show para9e"ers").
A special set block may be opened by specifying "{" as the frst argument to se".
The command "se" 7para9e"er8 &efa0l"" sets the specifed parameter back to its
default value.
$.$.6.1 set ar"loo-u"
Synopsis: se" arplook0p 7val0e8N&efa0l"
This parameter controls how often (interval in seconds) an still unknown mac address is being
requested using the ARP protocol. The minimum of this parameter is 5, the maximum 60 and
the default value is 10 seconds.
Example:
BalanceNG connec"e& "o $#A (!(;
bng# se" arplook0p 40
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" arplook0p 40
:: en& of config0ra"ion
bng# show para9e"ers
na9e 9in 9a? &efa0l" c0rren"
-------------- ---------- ---------- ---------- ----------
arplook0p 5 )0 !0 !0
arprefresh )0 3)00 300 300
arp"i9eo0" 0 ()400 0 0
back0paler"s 0 ! ! !
b9&0ra"ion !0 ()400 300 300
b9psize ;0 !5!4 !5!4 !5!4
b9wsize ! !0000 !;( !;(
bngfil"er 0 ! ! !
&eb0gscope 0 H 0 0
&09pro"a"ion ! !04(5H) !0;4 !0;4
gna"&li9i" !0 500 !0 !0
gra"arpre9in& 0 !;0 0 0
hashb/"es4 ! 4 4 4
hashb/"es) ! !) !) !)
hcpor"offse" !0;4 )5535 30000 30000
ipforwar&ing 0 ! 0 !
local&sr 0 ! 0 0
localvir" 0 ! 0 0
9a?s/ncps 0 !0000 0 0
na"&li9i" !0 500 !0 !0
na"scan ! ;0 !0 !0
na"s/nc 0 ! ! !
na"s/nciv !0 !;0 !0 !0
na""i9eo0" !0 !H;(00 )00 )00
o0"9"0 0 !5!4 0 0
psvrelearn 0 ! 0 0
sen&probes 0 ! 0 0
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 101 / 146
session&li9i" !0 !000 !0 !0
sessionscan ! ;0 !0 !0
sessionscanb0p ! !000 !00 !00
sessions/nc 0 ! ! !
sessions/ncack 0 ! 0 0
sessions/nciv !0 !;0 !0 !0
session"i9eo0" !0 !H;(00 )00 )00
sna""i9eo0" !0 !H;(00 !(00 !(00
s"ric"ro0"ing 0 ! ! !
vrrp9as"er&own 3 !0 3 3
vrrppree9p" 0 ! 0 0
vrrppree9p""s 0 !00 0 0
bng# se" arprefresh !(0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
arplook0p 40
arprefresh !(0
P
:: en& of config0ra"ion
bng#
$.$.6. set ar"refresh
Synopsis: se" arprefresh 7val0e8N&efa0l"
This parameter controls how often an already known mac address is being reexamined using
the ARP-Protocol (interval in seconds). The minimum of this parameter is 60, the maximum
300 and the default value is 120 seconds.
This parameter determines how e.g. fast a changed mac address of a target is being
recognized by BalanceNG.
Example:
bng# se" arprefresh ;40
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
arplook0p 40
arprefresh ;40
P
:: en& of config0ra"ion
bng#
$.$.6.$ set ar"ti*eout
Synopsis: se" arp"i9eo0" 7val0e8N&efa0l"
All targets in "enabled" state have an associated IP address, for which the mac / Ethernet
address has to be determined using the ARP protocol. This action can be regarded as a basic
health check, that has to succeed as a prerequisite for all other health checks.
The parameter "arptimeout" controls after how many seconds of a missing ARP reply a target
has to become not operational.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 102 / 146 Grünwald Germany / All Rights Reserved
The special value of 0 disables this particular implicit healthcheck.
The minimum of this parameter is 0, the maximum 86400 and the default value is 0 seconds
(disabled).
bng# se" arp"i9eo0" )0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
arplook0p 40
arprefresh ;40
arp"i9eo0" )0
P
:: en& of config0ra"ion
bng#
$.$.6., set bac-u"alerts
Synopsis: se" back0paler"s 7val0e8N&efa0l"
If this parameter is set to 1 (default) alert and upalert scripts are also execute on a backup
VRRP node. If this parameter is set to 0 the execution of these alert/upalert scripts is
suppressed on the VRRP backup node.
$.$.6./ set b*duration
Synopsis: se" b9&0ra"ion 7val0e8N&efa0l"
This sets the benchmark duration in seconds (see benchmark command).
$.$.6.1 set b*"siMe
Synopsis: se" b9psize 7val0e8N&efa0l"
This sets the packet size in bytes being used for benchmarking (see benchmark command).
$.$.6.2 set b*&siMe
Synopsis: se" b9wsize 7val0e8N&efa0l"
This parameter controls the number of packets being sent out at the beginning of the
benchmark ("window size").
$.$.6.5 set bng#lter
Synopsis: se" bngfil"er 7val0e8N&efa0l"
This parameter controls an additional flter and operational only for the Solaris versions of
BalanceNG. The default is 1 (flter active), it may be switched off by setting it to 0. Please
contact BalanceNG support frst before changing this parameter.
$.$.6.6 set debugsco"e
Synopsis: se" &eb0gscope 7val0e8N&efa0l"
This parameter sets the scope for additional built in debug messages. The default is 0 (no
debug messages). The command "show debugscopes" displays the currently available
debugging scopes.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 103 / 146
$.$.6.1E set du*"rotation
Synopsis: se" &09pro"a"ion 7val0e8N&efa0l"
This parameter controls the dumpfle rotation of the fles generated by the "dump" command.
The parameter dumprotation specifes the maximum size threshold of one dumpfle in
megabytes.
Specifying "&efa0l"" as parameter restores the current value to the default value.
The minimum of this parameter is 1 (one Megabyte), the maximum 1048576 (one Terabyte)
and the default value is 1024 (one Gigabyte).
Example:
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A (!E!
bng# in"erface e"h0
in"erface e"h0 s0ccessf0ll/ a""ache&
bng# in"erface e"h!
in"erface e"h! s0ccessf0ll/ a""ache&
bng# se" &09pro"a"ion !00
bng# l;swi"ch
bng# &09p e"h! :&a"a
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" &09pro"a"ion !00
in"erface e"h0
in"erface e"h!
&09p e"h! :"9p
l;swi"ch
:: en& of config0ra"ion
bng#
The example above sets up a transparent bridge between eth0 and eth1 and dumps all data
on eth1 to the directory /data (e.g. a large volume) with the &09pro"a"ion parameter set to
100 Megabytes.
$.$.6.11 set gnatdli*it
Synopsis: se" gna"&li9i" 7val0e8N&efa0l"
This parameter controls the maximum number of GNAT (Generic NAT) entries at the "show
nat" command. The Generic NAT Table is used by the "nat" module and the server proxy
mode. The default of this parameter is 10, the maximum may be set up to 100000 for testing
purposes.
$.$.6.1 set gratar"re*ind
Synopsis: se" gra"arpre9in& 7val0e8N&efa0l"
This parameters specifes an interval in minutes at which additional "reminding" gratuitous
ARP requests are being sent out by BalanceNG. A value of "0" disables this feature (default).
If VRRP is active only the current VRRP master will send out additional gratuitous arp
requests.
Example:
# :e"c:ini".&:bng con"rol
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 104 / 146 Grünwald Germany / All Rights Reserved
BalanceNG connec"e& "o $#A (!E4
bng# se" gra"arpre9in& 30
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
!. :: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" gra"arpre9in& 30
:: en& of config0ra"ion
bng#N+TA%#B#T
$.$.6.1$ set hashbAtes,
Synopsis: se" hashb/"es4 7val0e8N&efa0l"
This parameter controls the number of bytes which are considered by the "hash" method
(server <n> method hash) of the IPv4 source address. The default value is 4 (all 4 octets).
$.$.6.1, set hashbAtes1
Synopsis: se" hashb/"es) 7val0e8N&efa0l"
This parameter controls the number of bytes which are considered by the "hash" method
(server <n> method hash) of the IPv6 source address. The default value is 16 (all 16 octets).
$.$.6.1/ set hc"ortoffset
Synopsis: se" hcpor"offse" 7val0e8N&efa0l"
This parameter controls the offset of the source port being used for tcpopen and agen"
health checks. To calculate the source port the target index is simply added to this offset.
The minimum of this parameter is 1024 (the frst usually non privileged port), the maximum
65535 (maximum of unsigned short) and the default value is 30000.
Example:
# :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A (!E4
bng# se" hcpor"offse" !0;4
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" hcpor"offse" !0;4
:: en& of config0ra"ion
bng#
$.$.6.11 set i"for&arding
Synopsis: se" ipforwar&ing 7val0e8N&efa0l"
This parameter enables IP forwarding if set to 1 and disables IP forwarding if set to 0 (which
is the default). If IP forwarding is enabled, BalanceNG routes IP packets between all
confgured networks. Packets which are not locally addressable are being forwarded to the
default gateway (see "gateway") if specifed.
Network virtual ("virt") addresses should be preferably used as routing destinations since
those addresses are shared between all nodes of the virtual VRRP router.
Example (on a Sun X2100 running Solaris 10):
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 105 / 146
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" ipforwar&ing !
in"erface bge0
in"erface nge0
ne"work ! O
a&&r !0.!00.!.0
9ask ;55.;55.;55.0
real !0.!00.!.H!
vir" !0.!00.!.H0
in"erface bge0
P
ne"work ; O
a&&r !0.!00.;.0
9ask ;55.;55.;55.0
real !0.!00.;.H!
vir" !0.!00.;.H0
in"erface nge0
P
regis"er ne"works !4;
enable ne"works !4;
:: en& of config0ra"ion
bng#
$.$.6.12 set localdsr
Synopsis: se" local&sr 0N!
This boolean parameter allows if set to 1 operating BalanceNG on a target machine itself in
DSR mode. Usually BalanceNG refuses to represent an IP address which is already present
on one of the local interfaces. If localdsr is set to one this check is exempted for virtual server
IP addresses which then may be present as a local loopback alias at the same time on the
same machine. The localdsr parameter is set to 0 (off) by default.
Example:
bng# se" local&sr !
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
re9ark IL#& bng.conf4v !.! ;0!4:;3:0! !35E3! roo" >?p
se" local&sr !
:: en& of config0ra"ion
bng#
$.$.6.15 set local.irt
Synopsis: se" localvir" 0N!
"set localvirt 1" allows to have "network virt" addresses active on the host operating system at
the same time together with BalanceNG. This is required for example if BalanceNG operates
as a VRRP daemon attracting traffc to a local interface. This localvirt parameter is set to 0
(off) by default.
Example:
bng# se" localvir" !
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 106 / 146 Grünwald Germany / All Rights Reserved
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
re9ark IL#& bng.conf4v !.! ;0!4:;3:0! !35E3! roo" >?p
se" localvir" !
:: en& of config0ra"ion
bng#
$.$.6.16 set *ultithreading
Synopsis: se" 90l"i"hrea&ing 7val0e8N&efa0l"
This boolean parameter activates multithreading mode if set to 1 (active). The default value is
0 (not activated). If this parameter is changed, BalanceNG needs to be restarted (e.g. by "bng
restart") to activate the change. A BalanceNG reload alone (e.g. by "bng reload") has no
further effect (the parameter is changed, but the currently running scheduler remains the
same).
When the multithreading scheduler is running, dumping packets with the "dump" command is
not functional due to effciency reasons. Adding an interface needs a "save" and "bng restart"
to take effect.
$.$.6.E set natdli*it
Synopsis: se" na"&li9i" 7val0e8N&efa0l"
This parameter controls the maximum number of NAT entries displayed per protocol (TCP,
UDP) at the "show nat" command. The default of this parameter is 10.
$.$.6.1 set natscan
Synopsis: se" na"scan 7val0e8N&efa0l"
This parameter specifes the number of NAT entries being checked and reclaimed per second
on a not busy BalanceNG system. The default of this parameter is 10.
$.$.6. set natsAnc
Synopsis: se" na"s/nc !N0
This boolean parameter enables syncing of NAT table entries from the master to the backup
BalanceNG node if set to 1 (which is the default).
$.$.6.$ set natsAnci.
Synopsis: se" na"s/nciv 7val0e8N&efa0l"
This parameter controls the interval at which active NAT entries are being re-synced /
refreshed between the master and the backup BalanceNG node (is natsync is enabled and
set to 1). The default value of this parameter is 10 seconds.
$.$.6., set natti*eout
Synopsis: se" na""i9eo0" 7val0e8N&efa0l"
This parameter controls the lifetime of an unused NAT entry in the BalanceNG NAT table in
seconds. The default of this parameter is 600 seconds (10 minutes).
$.$.6./ set out*tu
Synopsis: se" o0"9"0 7val0e8N&efa0l"
This parameter limits the maximum packet size to the specifed number of bytes. Packets
which exceed the specifed number of bytes are simply truncated to the maximum cutting off
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 107 / 146
the exceeding trailer. If set to 0 this mechanism is disabled. This parameter may be set to
1514 bytes (the maximum) if an unwanted FCS (Ethernet frame checksum) is passed from
the OS to BalanceNG on the reading side.
$.$.6.1 set "threadstac-siMe
Synopsis: se" p"hrea&s"acksize 7val0e8N&efa0l"
This parameter controls the stack size of any POSIX thread. If this parameter is changed
during runtime, a "save" and "bng restart" is needed to take effect. The default is 204800
bytes.
$.$.6.2 set "s.relearn
Synopsis: se" psvrelearn 7val0e8N&efa0l"
This parameter enables passive updates to the ARP table if set to 1. The default value is 0
(disabled).
$.$.6.5 set *a+sAnc"s
Synopsis: se" 9a?s/ncps 7val0e8N&efa0l"
This parameter controls the maximum number of new session table entries per second being
sent from the current VRRP master to the VRRP backup node. The default value is 0, which
is interpreted as an unlimited number of synchronization packets. This parameter may be
safely set to any value in order to prevent unwanted synchronization traffc in case of a DoS
(Denial of Service) or DDoS (Distributed Denial of Service) attack.
Since this parameter is only valid for freshly created session table entries, the usual session
synchronization takes place afterwards ensuring a proper state of the VRRP backup session
table.
Example:
bng# se" 9a?s/ncps !000
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
re9ark IL#& bng.conf4v !.! ;0!4:;3:0! !35E3! roo" >?p
se" 9a?s/ncps !000
:: en& of config0ra"ion
bng#
$.$.6.6 set send"robes
Synopsis: se" sen&probes 7val0e8N&efa0l"
This boolean parameter controls whether ARP request probes are sent out periodically to
probe for potential IP address confict. This parameter is off (0) by default.
Example:
bng# se" sen&probes !
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
hcpor"offse" !0;4
sessionscan ;
vrrppree9p" !
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 108 / 146 Grünwald Germany / All Rights Reserved
vrrp9as"er&own !0
sen&probes !
P
:: en& of config0ra"ion
bng#
$.$.6.$E set sessionautoresAnc
Synopsis: se" sessiona0"ores/nc 7val0e8N&efa0l"
This boolean parameter controls the resynchronization behavior when the parameter
sessionsyncack is also active at the same time. If sessionautoresync is set to 1 (active), then
the current VRRP master starts a complete resynchronization of the session table towards a
freshly started (or restarted) backup node. The resynchronization process is the same as a
"resync" command would have been given on the CLI of the VRRP master.
$.$.6.$1 set sessionarrti*eout
Synopsis: se" sessionarr"i9eo0" 7val0e8N&efa0l"
This boolean parameter controls how long a freshly started backup is attempting to request
for resynchronization from the current VRRP master. The parameters sessionautoresync and
sessionsyncack must both be also active (1) in order to have an effect.
If sessionarrtimeout is set to 0, the backup will request for resynchronization infnitely (until it
receives a session autoresync request acknowledge). The default of this parameter is 60 (one
minute), the maximum is 3600 seconds (one hour).
$.$.6.$ set sessiongcli*it
Synopsis: se" sessiongcli9i" 7val0e8N&efa0l"
This parameter controls how many outdated session table entries per second may be
automatically reclaimed by the internal garbage collection mechanism. The default is 100,000,
so it may take about 10 seconds to reclaim 1,000,000 outdated entries on an idle BalanceNG
system.
$.$.6.$$ set sessiondli*it
Synopsis: se" session&li9i" 7val0e8N&efa0l"
This parameter controls the number of session table entries being displayed interactively by
the "show session" command. This parameter has a minimum and default of 10, and a
maximum of 1000 entries.
Example:
bng# se" session&li9i" ;0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
session&li9i" ;0
P
:: en& of config0ra"ion
bng#
$.$.6.$, set sessionscan
Synopsis: se" sessionscan 7val0e8N&efa0l"
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 109 / 146
This parameter controls how many sessions are internally scanned and tested for timeout per
second. Additionally BalanceNG performs the same session timeout test every time a session
is being looked up in the session table.
The minimum is one per second, the maximum is 20 per second, the default is 10 per
second.
Example:
bng# se" sessionscan ;
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
hcpor"offse" !0;4
sessionscan ;
vrrppree9p" !
vrrp9as"er&own !0
P
:: en& of config0ra"ion
bng#
$.$.6.$/ set sessionscanbu"
Synopsis: se" sessionscanb0p 7val0e8N&efa0l"
This parameter controls how many sessions are internally scanned and tested for timeout per
second if the node is in VRRP "backup" state.
The minimum is one per second, the maximum is 1000 per second, the default is 100 per
second.
$.$.6.$1 set sessionsAnc
Synopsis: se" sessions/nc 7val0e8N&efa0l"
This boolean parameter activated session table synchronization and state replication from the
current active master node to the backup node(s). It has to be set to 1 on both the master and
the backup to be active.
The default value of this parameter is 1 (active).
Session table synchronization uses a BalanceNG specifc VRRP extension, where session
table information is being broadcasted in a controlled manner (see parameter sessionsynciv
below).
It is recommended to set the parameter vrrppreempt to 0 at the same time sessionsync is set
to 1 (both is the default in current BalanceNG releases).
Example:
bng# se" sessions/nc !
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
sessions/nc !
vrrppree9p" 0
P
:: en& of config0ra"ion
bng#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 110 / 146 Grünwald Germany / All Rights Reserved
$.$.6.$2 set sessionsAncac-
Synopsis: se" sessions/ncack 7val0e8N&efa0l"
This parameter controls the acknowledgement of single session-table entries during the
continuous synchronization process. The default value is 0 (off). If set to 1 (on), the behavior
is as follows:
The current VRRP master node accepts VRRP extension type 6 packets and updates the
local session table entry and counters accordingly.
The current VRRP backup node acknowledges each VRRP extension type 4 packet by
sending the acknowledgment (type 6) back directly after the local session table update.
Example:
bng# se" sessions/ncack !
bng#
$.$.6.$5 set sessionsAncetA"e
Synopsis: se" sessions/nce"/pe 7val0e8N&efa0l"
This parameter controls the Ethertype (the two bytes directly following the Ethernet source
address) of session synchronization packets and the session synchronization
acknowledgement packets.
If this parameter is set to 0 (the default), the standard Ethertype 0x08, 0x00 is used.
If this parameter is set to 1, a non-standard Ethertype of 0x8b, 0x00 is used instead.
Example:
bng# se" sessions/nce"/pe !
$.$.6.$6 set sessionsAnci.
Synopsis: se" sessions/nciv 7val0e8N&efa0l"
This parameter controls how often the information of a current actively used session is being
notifed to listening backup nodes (in seconds). The default value is 10 seconds. It could be
increased to lower the number of notifcation packets in the network.
Example:
bng# se" sessions/nciv !0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
vrrppree9p" 0
sessions/nc !
sessions/nciv ;0
P
:: en& of config0ra"ion
bng#
$.$.6.,E set sessionti*eout
Synopsis: se" session"i9eo0" 7val0e8N&efa0l"
This parameter controls how long a n inactive session is being remembered by BalanceNG.
After having reached this timeout threshold the session will be removed from the session
table at the next opportunity.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 111 / 146
The minimum value of this parameter is 10 seconds, the maximum 172800 seconds (48
hours). The default value is 600 (10 minutes).
Example:
bng# se" session"i9eo0" )0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
se" O
session"i9eo0" )0
hcpor"offse" !0;4
sessionscan ;
vrrppree9p" !
vrrp9as"er&own !0
P
:: en& of config0ra"ion
bng#
$.$.6.,1 set stic-Atarget
Synopsis: se" s"ick/"arge" 7val0e8N&efa0l"
This boolean parameter controls the update of the layer 2 forwarding table when packets from
known targets are received. If set to 1 (the default), the forwarding table is not updated if a
packet from a known target is received on a different additional interface. If set to 0, the
forwarding table will be updated.
$.$.6., set strictrouting
Synopsis: se" s"ric"ro0"ing 7val0e8N&efa0l"
This boolean parameter controls the processing of incoming packets. If set to "1", packets are
only accepted for forwarding if they are received at the current VRRP Ethernet address.
VRRP needs to be enabled for this parameter. The default value of this parameter is "1"
(enabled). The parameter setting is necessary if there are multiple BalanceNG instances
running on one machine listening on the same IPv4 network and if BalanceNG runs
connected to a VMware vswitch in a virtual environment.
The functionality controlled by this parameter is integrated in the following modules:
– The "classic" BalanceNG V2 compatibility module (only on routing packets)
– The "strict" experimental module
– The "slb" and "llb" modules.
Example:
bng# se" s"ric"ro0"ing !
$.$.6.,$ set sAncac-bdelaA
Synopsis: se" s/ncackb&ela/ 7val0e8N&efa0l"
This parameter controls an initial delay, after which a freshly started node in VRRP backup
state accepts session table synchronization requests. The default value of this parameter is
10 seconds.
This parameter is effective only if sessionsyncack is set to 1 (enabled).
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 112 / 146 Grünwald Germany / All Rights Reserved
$.$.6.,, set sAncac-*a+"s
Synopsis: se" s/ncack9a?ps 7val0e8N&efa0l"
This parameter controls the maximum number of session table sync requests per second
issued by the VRRP master. The default value is 2000 session table entries per second.
Please consider to establish a separate sync interface for higher values of this parameter.
This parameter is effective only if sessionsyncack is set to 1 (enabled).
$.$.6.,/ set sAncac-resend
Synopsis: se" s/ncackresen& 7val0e8N&efa0l"
This parameter controls the number of seconds after which a session sync request is resent
again (timeout).
This parameter is effective only if sessionsyncack is set to 1 (enabled).
$.$.6.,1 set sAncac-&siMe
Synopsis: se" s/ncackwsize 7val0e8N&efa0l"
This parameter controls the number of session table entry sync requests sent out once per
second by the VRRP master.
This parameter is effective only if sessionsyncack is set to 1 (enabled).
$.$.6.,2 set .rr"*asterdo&n
Synopsis: se" vrrp9as"er&own 7val0e8N&efa0l"
This parameter controls the time interval in seconds after which a VRRP backup not receiving
Master advertisements will declare the master to be down. This parameter implements the
"Master_Down_Interval" of RFC3768 (see Reference /3/).
The minimum and default of this parameter is 3 seconds, the maximum is10 seconds.
Example:
bng# se" vrrp9as"er&own !0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
re9ark IL#& bng.conf4v !.! ;0!4:;3:0! !35E3! roo" >?p
se" O
hcpor"offse" !0;4
vrrp9as"er&own !0
P
:: en& of config0ra"ion
bng#
$.$.6.,5 set .rr""ree*"t
Synopsis: se" vrrppree9p" 7val0e8N&efa0l"
This parameter controls whether a higher priority VRRP Backup node preempts a lower
priority Master. This is a boolean parameter with 1 = TRUE and 0 = FALSE. The default of
this "ara*eter is E <"ree*"tion NnotN acti.e>.
This parameter implements the parameter "Preempt_Mode" of RFC3768 (see Reference /3/).
Here a potentially simpler explanation:
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 113 / 146
If a previously failed VRRP master (with a priority lower than 255) comes back into operation
it will stay gently in background as a VRRP backup node if vrrppreempt equals 0. If
vrrppreempt equals 1 it will force to be master again as quickly as possible.
Note: If session state replication is being used with setting sessionsync to 1, it is a good idea
to set vrrppreempt to 0 at the same time. This allows the new joining node (the previous
master) to learn back the currently active session table.
Note vrrppreempt defaults to 0 and sessionsync to 1 for administration convenience (sessions
are being synced per default).
Example:
bng# se" vrrppree9p" 0
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
re9ark IL#& bng.conf4v !.! ;0!4:;3:0! !35E3! roo" >?p
se" O
hcpor"offse" !0;4
vrrppree9p" 0
vrrp9as"er&own !0
P
:: en& of config0ra"ion
bng#
$.$.6.,6 set .rr""ree*"tts
Synopsis: se" vrrppree9p""s 7val0e8N&efa0l"
This parameter (VRRP Preemption Threshold) allows further control of the preemption
behaviour of a higher priority backup. If vrrppreempt is set to 1 on a higher priority backup, it
immediately tries to become VRRP master of the VR. If this parameter is not equal to 0, it is
subtracted from the local priority before that comparison.
Together with the VRRP tracking features, this allows fne tuning of the failover if external
resources are failing on the master still being available on the backup.
$.$.6./E set .rr"state"lugin
Synopsis: se" vrrps"a"epl0gin 7val0e8N&efa0l"
Iif this boolean parameter is set to 1 (active), a VRRP state change is reported to all server
plugins (see "server <n> plugin" for more information). The default value is 0 (inactive).
If this parameter is active (1) and a node becomes backup, the word "BACKUP" is written to
stdin of all server plugins and a the word "MASTER" if a node becomes VRRP master.
The plugin must acknowledge the receipt of the state change information by sending back a
line containing one single character (a "0") and a line feed as fast as "ossible.
$.$.$E snatrange Ffro*G FtoG
Synopsis: sna"range 7fro98 7"o8
no sna"range
This command specifes a range of IP4 addresses which will be used for source NAT (SNAT)
processing if the "slb" module is active and if SNAT is enabled for a specifc virtual server (see
"server <n> snat").
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 114 / 146 Grünwald Germany / All Rights Reserved
$.$.$1 softdisable target FnG
Synopsis: sof"&isable "arge" 7n8
sof"&isable "arge"s 7n!847n;84 ...
This command sets one or more specifed enabled targets into a special "softdisable" state.
Targets in that state are still working for already existing sessions, but no new sessions will be
allocated by the load balancing target selection methods.
This is very useful for smoothly taking a target machine out of service for maintenance and
other service activities. As soon as the session count of the target is 0 (displayed at "show
target <n>") the target machine can be safely taken into maintenance.
A target in "softdisable" state may be taken back into normal load balancing distribution with
the "enable "arge"" command (e.g. "enable "arge" !").
The softdisable state may be entered administratively during runtime only and is not part of
the confguration and the confguration fle.
Example:
bng# show "arge" !
"arge" !
ipa&&r !H;.!H.;.E0
por" an/
ne"work !
pro"ocol an/
sessions 3(!
"rackval 0
s"a"0s opera"ional
arp 0p
ping 0p
psen" 4!;3
bsen" !;35;)
prcv& ;345
brcv& ;!345)
bng# sof"&is "arge" !
bng# show "arge" !
"arge" !
ipa&&r !H;.!H.;.E0
por" an/
ne"work !
pro"ocol an/
sof"&is Cac"iveC
sessions 3(!
"rackval 0
s"a"0s opera"ional
arp 0p
ping 0p
psen" 4;34
bsen" ;34454
prcv& 3345
brcv& 3;345)
bng#
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 115 / 146
$.$.$ target FnG
Synopsis: "arge" 7n8 7s0bco99an&8 7val0e8
This command is used to confgure the parameters of a BalanceNG target. In general this is
only possible if the target is in the "unregistered" state (see the server and target state
explanations at the "regis"er" command).
The target index may range from 1 to 1024, such allowing a total of 1024 target sections per
BalanceNG instance.
BalanceNG is capable of handling 1024 independent targets. Each target may be referenced
by the targets list of a specifc server one or multiple times.
$.$.$.1 target FnG agent
Synopsis: "arge" 7n8 agen" 7para9e"ers8NIoffI
Activates the agen" healthcheck and load collector of the specifed target using the supplied
parameters (or switches the agen" healthcheck off when "off" is supplied).
The agent healthcheck communicates with the bngagent UDP protocol with a bngagent
program running on the physical target machine (see the bngagent chapter for more
informations).
The parameter list consists of three numerical values, separated by commas. The frst value
is the UDP port being addressed on the real target machine. The second parameter is the
interval in seconds to perform the agent healthcheck. The third parameter specifes the
number of seconds with no answer to declare the target inoperational.
Example 1 (checking every 10 seconds on port 2000, 30 seconds of missing replies for
declaring target inoperational):
bng# "arge" ! agen" ;0004!0430
Example 2 (switching agent healthcheck off):
bng# "arge" ! agen" off
$.$.$. target FnG agent1
Synopsis: "arge" 7n8 agen") 7para9e"ers8NIoffI
Activates the IPv6 agent healthcheck and load collector of the specifed target using the
supplied parameters (or switches the agen" healthcheck off when "off" is supplied).
The agent6 healthcheck communicates with the bngagent UDP over IPv6 protocol with a
bngagent program running on the physical target machine (see the bngagent chapter for
more informations). The
The parameter list consists of three numerical values, separated by commas. The frst value
is the UDP port being addressed on the real target machine. The second parameter is the
interval in seconds to perform the agent healthcheck. The third parameter specifes the
number of seconds with no answer to declare the target inoperational.
Either "target <n> agent" or "target <n> agent6" may be specifed, it's not possible to run both
at the same time.
Example (checking every 10 seconds on port 2000, 30 seconds of missing replies for
declaring target inoperational):
bng# "arge" ! agen") ;0004!0430
The bngagent needs to be running in IPv6 mode on the target server and may be started like
this:
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 116 / 146 Grünwald Germany / All Rights Reserved
# bngagen" -) ;000
$.$.$.$ target FnG ascri"t
Synopsis: "arge" 7n8 ascrip" 7scrip"847in"erval847"i9eo0"8
This command allows local execution of an agent script or program. The script just needs to
print one single line containing the determined integer agent value.
Before the script invocation string is passed to popen(), a set of symbols or variables is
literally replaced once in the string (as it's done with "target <n> script").
The symbols and their replacements are as follows:
S/9bol ,eplace9en"
--------------------------------------------------
Lipa&&rL #$v4 a&&ress of "he "arge"
Lipa&&r)L #$v) a&&ress of "he "arge"
Lpor"L $or" n09ber of "he "arge" if specifie&
'I0I o"herwise.
Ls"a"0sL <eal"hcheck s"a"0s
L"arge"L N09ber of "he "arge"
Please note, that it's possible either to use "target <n> agent" or "target <n> ascript", but not
both at the same time. Additionally, "target <n> ascript" should be used in conjunction with
additional healthchecks (like "target <n> script").
Example:
The following line
"arge" ! ascrip" ^:op":BalanceNG:sn9ploa&.sh Lipa&&rL_4!04)00
calls the snmpload.sh script which is part of the BalanceNG distribution (located either in
/opt/BalanceNG or directly in the Linux tarball distribution).
The snmpload.sh script allows to retrieve the CPU load from a Windows system, here's the
script source code:
#:bin:sh
=+%@>SKMsn9pwalk -v! -c p0blic -F 5v L! .!.3.).!.;.!.;5.3.3.!.;
;8:&ev:n0llM
if 2 IL3I JK I0I 6
"hen
echo !0!
e?i" 0
fi
S@BK0
-F@NTK0
for =+%@> in L=+%@>S
&o
-F@NTKMe?pr L-F@NT * !M
S@BKMe?pr LS@B * L=+%@>M
&one
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 117 / 146
if 2 IL-F@NTI K 0 6
"hen
echo !0!
e?i" 0
else
,>S@%TKMe?pr LS@B : L-F@NTM
,>S@%TKMe?pr L,>S@%T * !M
echo L,>S@%T
e?i" 0
fi
$.$.$., target FnG alert
Synopsis: "arge" 7n8 aler" 7aler"scrip"8
This command specifes an external script or program which is called or executed as soon
and every time the associated target gets down or inoperational. The alertscript has to be
specifed in double quotes and will be executed by a helper thread with the system() C-library
function call. The call of this external script happens only once at every state change (e.g.
from "operational" to "down" or from "initial" to "down").
This mechanism could be useful for e.g. sending a SNMP trap to a network management
system or for sending an email if a target goes down (gets "inoperational").
Before the alertscript string is passed to system() a set of symbols or variables is literally
replaced once in the string. The symbols and their replacements are as follows:
S/9bol ,eplace9en"
--------------------------------------------------
Lipa&&rL #$v4 a&&ress of "he "arge"
Lipa&&r)L #$v) a&&ress of "he "arge"
Lpor"L $or" n09ber of "he "arge" if specifie&
'I0I o"herwise.
Ls"a"0sL <eal"hcheck s"a"0s
L"arge"L N09ber of "he "arge"
Example:
# bng con"rol
BalanceNG connec"e& "o $#A !));4
bng# "arge" ! O
bng* ipa&&r !0.!.;.;
bng* ping ;4!0
bng* aler" I:0sr:local:sbin:aler"9ail Lipa&&rL L"arge"LI
bng* P
bng# co99i" "arge" !
$.$.$./ target FnG aoffset
S/nopsis "arge" 7n8 aoffse" 7offse"8
This command is a synonym for "target <n> offset".
$.$.$.1 target FnG ascale
S/nopsis target <n> ascale <scale>
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 118 / 146 Grünwald Germany / All Rights Reserved
This command is a synonym for "target <n> scale".
$.$.$.2 target FnG autodisable
Synopsis: target <n> autodisable on|off
If the autodisable feature is set to "on" for a specifc target, this target will be automatically
disabled s soon as it gets inoperational or "down" according to the associated health checks.
This automatic operation is the same as entering "disable target <n>" at the same time.
The autodisable feature is switched off per default (and is not visible in the confguration in
that state).
Example:
No&e+# e&i" "arge" !
No&e+# "arge" ! a0"o&isable on
No&e+# co99i" "arge" !
...
No&e+# show log
...
;0!4:;3:0! ;;!4;5 5 "arge" ! &own 'arp0p4ping0p4"cpopen&own.
;0!4:;3:0! ;;!4;5 5 "arge" ! a0"o9a"icall/ &isable& 'a0"o&isableKon.
No&e+# show "arge"s
# ipa&&r por" pr" ne" srv sessions s"a"0s na9e
--- ---------------- ---- --- --- --- -------- ----------- ---------------
! !0.!0.;.;! 53 an/ ! ! 0 &isable& "es"!
No&e+#
$.$.$.5 target FnG autodisablecount
Synopsis: target <n> autodisablecount <value>
target <n> autodisablecount default
This command controls the number of target state transitions from "operational" to "down"
until a target is automatically disabled (target <n> autodisable needs to be active). The default
of this value is 1, the maximum 100000.
Example:
No&e+# e&i" "arge" !
No&e+# "arge" ! a0"o&isable on
No&e+# "arge" ! a0"o&isableco0n" !0
No&e+# co99i" "arge" !
No&e+# show conf "arge" !
"arge" ! O
ipa&&r !H;.!H.;.30
por" (0
pro"ocol "cp
"cpopen (0434!0
a0"o&isable on
a0"o&isableco0n" !0
P
$.$.$.6 target FnG dsr
Synopsis: target <n> dsr enable|disable
"target <n> dsr enable" enables the "Direct Server Return" feature for the specifed
target, "target <n> dsr disable" disables the DSR feature.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 119 / 146
This feature is disabled per default, and not shown in the confg fle if disabled.
If DSR is enabled for the specifed target packets to a virtual server are forwarded to the
target Layer 2 address with the virtual server destination IP address unchanged. The virtual
server address has to be added as an alias to the Loopback ("lo") Interface of the Target
machine.
Example:
bng# "arge" ! O
bng* ipa&&r !0.!.!.4
bng* por" (0
bng* pro"ocol "cp
bng* "cpopen (0434!0
bng* &sr enable
bng* P
$.$.$.1E target FnG i"addr
Synopsis: target <n> ipaddr <IPv4 address>
target <n> ipaddr none
This specifes the IPv4 address of the target with the specifed index <n>, "none" removes the
current IPv4 address.
Example:
bng# "arge" ; ipa&&r !0.!.!.3
bng# "arge" 3 O
bng* ipa&&r !0.!.!.4
bng* P
$.$.$.11 target FnG i"addr1
Synopsis: target <n> ipaddr6 <IPv6 address>
target <n> ipaddr6 none
This specifes the IPv6 address of the target with the specifed index <n>, "none" removes the
current IPv6 address.
Example:
bng# "arge" ; ipa&&r) fe(0;304(fffeE34&0;
bng#
$.$.$.1 target FnG lgr"
Synopsis: "arge" 7n8 lgrp 7+-W8NnoneNoff
This command associates the target with a specifc location group (or removes that
association with "none" or "off"). Please take a look at "ipdb", "lgrp" and "server <n> ipdb" for
further information about location based server load balancing.
Example:
bng# lgrp + I@S4GBI
bng# e&i" "arge" !
bng# "arge" ! lgrp +
bng# co99i" "arge" !
bng# show conf
...
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 120 / 146 Grünwald Germany / All Rights Reserved
lgrp O
+ I@S4GBI
B IC4J+I
P
...
"arge" ! O
ipa&&r !H;.!H.;.E!
por" 53
lgrp +
ping 54!;
"cpopen 53454!;
&sr enable
P
...
bng# show lgrp +
grp + 'solve&.
"?" @S4GB
ke/ &escrip"ion
--- ------------------------------------
GB @N#T>A Z#NGAFB
@S @N#T>A ST+T>S
--- ------------------------------------
; "o"al en"ries
bng#
$.$.$.1$ target FnG *a+agent
Synopsis: "arge" 7n8 9a?agen" 7"hreshol&8N0
This command assigns a maximum score threshold for target <n> and works together with
the "agent" directive. If a target total and absolute agent score exceeds the supplied threshold
this particular target is silently taken out of the current load balancing distribution. A value of 0
(default) sets this threshold to "unlimited".
Example:
bng# "arge" ; 9a?agen" ;000
bng#
$.$.$.1, target FnG *a+gr"sessions
Synopsis: "arge" 7n8 9a?grpsessions 7"hreshol&8N0
This command assigns a maximum session threshold for target <n>, where all sessions of the
targets sessiongroup are counted together (see target <n> sessiongroup). If the sum of all
sessions of targets belonging to the same group exceeds that value, this particular target is
silently taken out of the current load balancing distribution. A value of 0 (default) sets this
threshold to "unlimited".
Example:
bng# "arge" ; sessiongro0p ;
bng# "arge" ; 9a?grpsessions 5000
$.$.$.1/ target FnG *a+sessions
Synopsis: "arge" 7n8 9a?sessions 7"hreshol&8N0
This command assigns a maximum session threshold for target <n>. If a target total and
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 121 / 146
absolute number of sessions exceeds the supplied threshold this particular target is silently
taken out of the current load balancing distribution. A value of 0 (default) sets this threshold to
"unlimited".
Example:
bng# "arge" ; 9a?sessions ;000
bng#
$.$.$.11 target FnG na*e
Synopsis: "arge" 7n8 na9e 7na9e8NInoneI
Assigns a target a name for informational purposes. The string "none" as the name
arguments deletes the name from the specifed target.
The target name may be embedded in double quotes to specify a name containing spaces.
Specifying an empty string in double quotes also removes the current name defnition.
Example:
bng# e&i" "arge" !
bng# "arge" ! na9e "es"-"arge"-!
bng# co99i" "arge" !
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
bng# show "arge"s
# ipa&&r por" pr" ne" srv s"a"0s na9e
-----------------------------------------------------------------
! !0.!.!.3 an/ an/ ; 0 &own "es"-"arge"-!
bng#
$.$.$.12 target FnG offset
Synopsis: "arge" 7n8 offse" 7offse"8
This command allows together with ""arge" 7n8 ascale" the modifcation of the return
value of bngagent by applying a linear function to it. This function looks like this:
<e,,ecti%e agent data> - <returned agent data> . <target ascale> / <target ao,,set>
The aoffse" parameter has a default of 0 (where it is not displayed in the confguration fle).
The ascale parameter has a default of 1.0 (also not being displayed).
Both aoffse" and ascale always have to be positive. If the unsigned integer return value is
being scaled down to integer 0, then this result will be replaced by 1.
The following recommendation can be made:
• A more powerful target machine should become a scale s*aller than the less powerful
machines.
• A less powerful machine which should e.g. not be used from the very beginning should be
supplied with a aoffse" 8 0. A machine with the default aoffse" of 0 takes will receive
traffc / load from the very beginning.
The following example shows how easily the effective agent value may be modifed by
applying ascale and aoffset parameters. This together with the agent distribution method
allows a very expressive optimization of load distribution even to very different machines.
Example:
roo"[bng!` # :e"c:ini".&:bng con"rol
BalanceNG connec"e& "o $#A H;;
bng# show "arge" !
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 122 / 146 Grünwald Germany / All Rights Reserved
"arge" !
ipa&&r !0.!.!.!
por" an/
ne"work ;
pro"ocol an/
s"a"0s opera"ional
arp 0p
agen" 4
effDagen" 4
bng# e&i" "arge" !
bng# "arge" ! scale ;.0
bng# co99i" "arge" !
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
bng# show "arge" !
"arge" !
ipa&&r !0.!.!.!
por" an/
ne"work ;
pro"ocol an/
s"a"0s opera"ional
arp 0p
agen" ;
effDagen" 4
bng# e&i" "arge" !
bng# "arge" ! offse" !0
bng# co99i" "arge" !
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
bng# show "arge" !
"arge" !
ipa&&r !0.!.!.!
por" an/
ne"work ;
pro"ocol an/
s"a"0s opera"ional
arp 0p
agen" !
effDagen" !;
bng#
$.$.$.15 target FnG "ing
Synopsis: "arge" 7n8 ping 7para9e"ers8NIoffI
Activates the ping healthcheck of the target or switches it off (by supplying "off"). The
parameters consist of two values, separated by a comma. The frst value is the interval in
seconds to send an ICMP echo request packet to the target. The second value is the time to
declare a target inoperational if no ICMP echo response packet is received in that time.
Example:
bng# "arge" ; ipa&&r !0.!.!.;
bng# "arge" ; ping ;4!0
bng# co99i" "arge" ;
bng# show "arge" ;
"arge" ;
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 123 / 146
ipa&&r !0.!.!.;
por" an/
ne"work ;
pro"ocol an/
s"a"0s opera"ional
arp 0p
ping 0p
bng#
$.$.$.16 target FnG "ing1
Synopsis: "arge" 7n8 ping) 7para9e"ers8NIoffI
Activated the ping6 (IPv6) healthcheck of the target or switches it off (by supplying "off"). The
parameters consist of two values, separated by a comma. The frst value is the interval in
seconds to send an ICMP echo request packet to the target. The second value is the time to
declare a target inoperational if no ICMP echo response packet is received in that time. The
target needs to have an IPv6 address specifed.
Example:
bng# "arge" ; ipa&&r) ;00!AB(!
bng# "arge" ; ping) 34!0
$.$.$.E target FnG "ort
Synopsis: "arge" 7n8 por" 7por"8NIan/I
With this command a specifc port can be associated to a target. Supplying "any" reverts this
back to "any" port. An associated port of a target restricts load balancing actions to this port
and allows TCP and UDP port translation (server uses different port than the associated
target).
Together with the "target <n> protocol" command the load balancing actions may be
additionally restricted to just one protocol family on that port (TCP or UDP).
Example:
bng# "arge" 4 ipa&&r !0.!.!.5
bng# "arge" 4 por" (0(0
bng# "arge" 4 pro"ocol "cp
bng# "arge" 4 ping ;4;0
bng# "arge" 4 "cpopen (0(0454;0
bng# co99i" "arge" 4
U+,N#NG "arge" 4 in enable& s"a"e b0" no" reference&
bng# show "arge" 4
"arge" 4
ipa&&r !0.!.!.5
por" (0(0
ne"work ;
pro"ocol "cp
s"a"0s &own
arp &own
ping &own
"cpopen &own
bng#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 124 / 146 Grünwald Germany / All Rights Reserved
$.$.$.1 target FnG "rotocol
Synopsis: "arge" 7n8 pro"ocol I"cpINI0&pIN_sc"p_NIan/I
Restricts load balancing participation of the specifed target either to TCP, UDP or SCTP (or
reverts back to the default of any protocol by specifying "any").
Together with ""arge" 7n8 por"" the matching rules may be restricted to packets from a
specifc port and protocol.
Example:
bng# "arge" 4 pro"ocol "cp
bng# co99i" "arge" 4
$.$.$. target FnG "seudo
Synopsis: "arge" 7n8 pse0&o IenableINI&isable_
This directive declares the target to be a special pseudo target. A pseudo target needs no
associated server. A ping (IPv4 echo request) health-check ("target <n> ping") is sent with the
VRRP MAC source address and the "network <n> virt" IPv4 source address only if the node is
currently VRRP master. A pseudo target may be useful in order to keep the forwarding tables
of external devices updated in respect to the VRRP virtual router MAC address.
$.$.$.$ target FnG router
Synopsis: "arge" 7n8 ro0"er 7#$v4-a&&ress8
This target specifes a target specifc gateway where all target related traffc should be
directed instead of expecting the target locally reachable.
Such a router (gateway) specifcation is valid for all internal health checks and all target
related load balancing traffc and allows to address indirectly reachable services in
BalanceNG load balancing.
Example:
bng# e&i" "arge" !
bng# "arge" ! ro0"er !H;.!H.;.;54
bng# co99i" "arge" !
$.$.$., target FnG scale
Synopsis: "arge" 7n8 ascale 7scale8
This target parameter allows together with aoffse" the modifcation of the bngagent return
value in terms of a linear function. Please see the more detailed explanation and example at
the ""arge" 7n8 aoffse"" command.
Example:
bng# e&i" "arge" !
bng# "arge" ! scale ;.0
bng# co99i" "arge" !
U+,N#NG "arge" ! in enable& s"a"e b0" no" reference&
bng# show "arge" !
"arge" !
ipa&&r !0.!.!.!
por" an/
ne"work ;
pro"ocol an/
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 125 / 146
s"a"0s opera"ional
arp 0p
agen" ;
effDagen" 4
bng# show conf
:: config0ra"ion "aken S0n +0g ;4 ;;5)40 ;00(
:: BalanceNG 3.504 'crea"e& ;0!4:;3:0!.
in"erface e"h0
in"erface e"h!
ne"work ! O
a&&r !0.55.55.0
9ask ;55.;55.;55.0
real !0.55.55.!E0
vir" !0.55.55.!E!
in"erface e"h0
P
ne"work ; O
a&&r !0.!.!.0
9ask ;55.;55.;55.0
real !0.!.!.!E0
vir" !0.!.!.!E!
in"erface e"h!
P
regis"er ne"works !4;
enable ne"works !4;
"arge" ! O
ipa&&r !0.!.!.!
agen" 50004540
offse" !0
scale ;
P
regis"er "arge" !
enable "arge" !
:: en& of config0ra"ion
bng#
$.$.$./ target FnG screate
Synopsis: "arge" 7n8 screa"e enableN&isable
This command enables or disables session creation initiated by target originated traffc for the
"slb" module. The default for this setting is "disabled" (where no setting is shown in the
confguration fle).
Example:
# bng c"l
BalanceNG connec"e& "o $#A 54;H
bng# e&i" "arge" !
bng# "arge" ! screa"e enable
bng# co99i" "arge" !
bng#
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 126 / 146 Grünwald Germany / All Rights Reserved
$.$.$.1 target FnG scri"t
Synopsis: "arge" 7n8 scrip" 7heal"checkscrip"847in"erval847"i9eo0"8
This command specifes an external health check script which will be called at the given
interval in seconds. If the script returns with an exit code not equal to zero (0) or if the
invocation of that script fails or if that script does not return within the specifed timeout the
target status will change to "inoperational" or "down".
The script is being executed by a helper thread using the system() library function. The
external script is not aware of the TCP/IP stack of BalanceNG and operates under the host
operating system as usual.
With that mechanism arbitrary any custom health check method can be interfaced or
implemented easily.
Before the healthcheckscript string is passed to system() a set of symbols or variables is
literally replaced once in the string. The symbols and their replacements are as follows:
S/9bol ,eplace9en"
--------------------------------------------------
Lipa&&rL #$v4 a&&ress of "he "arge"
Lipa&&r)L #$v) a&&ress of "he "arge"
Lpor"L $or" n09ber of "he "arge" if specifie&
'I0I o"herwise.
L"arge"L N09ber of "he "arge"
Many different programs can be easily interfaced that way (e.g. "ping", "wget, "mon") or any
other custom script or program.
Example:
This example calls an external monitor script to implement a HTTP lookup of a specifc URL
(http.monitor from the "mon" package, available at http://www.kernel.org/software/mon). The
script is called every two seconds, the target gets inoperational/down if the script fails (returns
something else than 0) or if it does not return within 7 seconds.
# .:bng con"rol
BalanceNG connec"e& "o $#A !));4
bng# e&i" "arge" !
bng# "arge" ! scrip" I:0sr:lib:9on:9on.&:h""p.9oni"or -p Lpor"L
-0 :heal"check.cgi Lipa&&rLI4;4H
bng# co99i" "arge" !
$.$.$.2 target FnG scri"t1
Synopsis: "arge" 7n8 scrip") 7heal"checkscrip"847in"erval847"i9eo0"8
This command implements a second scripting health-check (in addition to target N script)
which may be used to separate external IPv4 and IPv6 scripts. Parameters and usage is the
same as "target N script" (see above).
$.$.$.5 target FnG sessiongrou"
Synopsis: "arge" 7n8 sessiongro0p &efa0l"N7val0e8
Targets may be optionally grouped in "target session groups". Per default all targets belong to
the target sessiongroup 0. The sessiongroup parameter may be specifed in the rage from 0
to 100. Together with "target <n> maxgrpsessions" this parameter allows a simple way to limit
number of sessions per target group to a desired value.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 127 / 146
Example:
bng# e&i" "arge" 4
bng# "arge" 4 sessiongro0p ;
bng# "arge" 4 9a?grpsessions 5000
bng# co99i" "arge" 4
bng#
$.$.$.6 target FnG sessionid FhandlerG
This command associates a specifc session handler to a particular target. The "slb" (Server
Load Balancing) Module needs to be part of the current module chain.
$.$.$.6.1 si"
The sessionid is based on SIP/UDP Call-ID only.
$.$.$.6. src
The sessionid is based only on the source IP address.
$.$.$.6.$ srcLdst"ort
The sessionid is based on the source IP address and the destination port.
$.$.$.6., srcL"ort
The sessionid is based on the source IP address and the source port.
$.$.$.6./ srcL"orts
The sessionid is based on the source IP address and both the source and destination ports.
$.$.$.6.1 dst
The sessionid is based only on the destination IP address.
$.$.$.6.2 dstL"ort
The sessionid is based on the destination IP address and the destination port.
$.$.$.6.5 dstL"orts
The sessionid is based on the destination IP address and both the source and destination
ports.
$.$.$.6.6 dstLsrc"ort
The sessionid is based on the source IP address and the source port.
$.$.$.$E target FnG tc"o"en
Synopsis: "arge" 7n8 "cpopen 7para9e"ers8NIoffI
Activates a simple TCP open healthcheck (or switches it of with "off"). The parameter list
expects three numeric parameters separated by commas: The frst is the actual port to test
(which may be different than the target load balancing port), the second is the interval to
check in seconds and the third is the interval to declare the target down when no response is
received in that period.
Example:
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 128 / 146 Grünwald Germany / All Rights Reserved
bng# e&i" "arge" 4
bng# "arge" 4 "cpopen (04;4!0
bng# co99i" "arge" 4
bng#
$.$.$.$1 target FnG tc"o"en1
Synopsis: "arge" 7n8 "cpopen) 7para9e"ers8NIoffI
Activates a simple IPv6 TCP open healthcheck (or switches it of with "off"). As with "target
<n> tcpopen", the parameter list expects three numeric parameters separated by commas:
The frst is the actual port to test (which may be different than the target load balancing port),
the second is the interval to check in seconds and the third is the interval to declare the target
down when no response is received in that period. A IPv6 address needs to be specifed for
the target.
Example:
bng# e&i" "arge" 4
bng# "arge" 4 ipa&&r) ;00!&b(ffff!;
bng# "arge" 4 "cpopen) (04;4!0
bng# co99i" "arge" 4
bng#
$.$.$.$ target FnG u"alert
Synopsis: "arge" 7n8 0paler" 70paler"scrip"8
This command specifes an external script or program which is called or executed as soon
and every time the associated target gets "up" or operational. The upalertscript has to be
specifed in double quotes and will be executed by a helper thread with the system() C-library
function call. The call of this external script happens only once at every state change (e.g.
from "down" to "operational" or from "initial" to "operational").
This mechanism could be useful for e.g. sending a SNMP trap to a network management
system or for sending an email if a target goes up (gets "operational" again).
Before the upalertscript string is passed to system() a set of symbols or variables is literally
replaced once in the string. The symbols and their replacements are as follows:
S/9bol ,eplace9en"
--------------------------------------------------
Lipa&&rL #$v4 a&&ress of "he "arge"
Lipa&&r)L #$v) a&&ress of "he "arge"
Lpor"L $or" n09ber of "he "arge" if specifie&
'I0I o"herwise.
Ls"a"0sL <eal"hcheck s"a"0s
L"arge"L N09ber of "he "arge"
Example:
# bng con"rol
BalanceNG connec"e& "o $#A !));H
bng# "arge" ! O
bng* ipa&&r !0.!.;.;
bng* ping ;4!0
bng* 0paler" I:0sr:local:sbin:0p9ail Lipa&&rL L"arge"LI
bng* P
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 129 / 146
bng# co99i" "arge" !
$.$.$.$$ target FnG trac-.al
Synopsis: "arge" 7n8 "rackval 7val0e8
This command associates a tracking value to the target. The default of this value is 0. If
VRRP tracking is enabled and the VRRP priority is less than 255 and a target is enabled and
down (not operational) the current VRRP priority is degraded by the tracking value "trackval"
of the target.
Note: Tracking is enabled with "vrrp tracking enable".
Example:
bng# show "arge" !
"arge" !
ipa&&r !H;.!H.;.E0
por" an/
ne"work !
pro"ocol an/
sessions 0
"rackval 0
s"a"0s opera"ional
arp 0p
ping 0p
bng# e&i" "arge" !
bng# "arge" ! "rackval 4
bng# co99i" "arge" !
bng# show "arge" !
"arge" !
ipa&&r !H;.!H.;.E0
por" an/
ne"work !
pro"ocol an/
sessions 0
"rackval 4
s"a"0s opera"ional
arp 0p
ping 0p
bng#
$.$.$.$, target FnG .ia
Synopsis: "arge" 7n8 via 7ipa&&r8
This command may be used as a synonym for "target <n> router".
$.$.$.$/ target FnG &eight
Synopsis: "arge" 7n8 weigh" 7val0e8
This command associates a certain weight to a target, which is valid if the server distribution
method "random" is used. The default weight of a target is 1 and is not displayed on "show
conf". A target weight is valid in the range of 1-100 inclusively and may refect a percentage
value.
The following examples instructs BalanceNG to choose direct 75% of new sessions to target
2 and 25% of new sessions to target 1 (if target 1 and 2 are being referenced by a server with
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 130 / 146 Grünwald Germany / All Rights Reserved
distribution method "random").
Example:
bng# "arge" ! weigh" !0
bng# "arge" ; weigh" 30
bng# co99i" "arge"s !4;
bng#
$.$.$$ tnat
Synopsis: "na" 7"arge" a&&r8 7N+T a&&r8 7pro"ocol8 7&es" por"8
This command specifes selectively 1:1 Network Address Translation (NAT) for a specifc
destination port and protocol. This command is revertable using the "no" special command.
The "target addr" should be the address of a target. The "NAT addr" should be an exclusively
reserved address in the outbound network (one reservation / allocation per tnat-entry). The
parameter "protocol" may be either "udp" or "tcp".
The destination port can either be supplied specifcally or the keyword "anA" may be used to
express all ports of the specifed protocol.
This command allows the target to communicate to the "outside" world by NATting its address
to the specifed address in the outbound network if and only if the given protocol and port
matches.
Tnat is applied internally after the packets have been checked for load balancing.
Note4 Another common used approach to offer outbound connectivity for the targets would be
the declaration of a server reversely to offer services to the targets in the outbound direction.
Common uses are e.g. HTTP-requests from the targets to the "Internet" or DNS queries to a
DNS server in a local network.
The Addresses of all tnat-entries are represented by all BalanceNG nodes with the same vrid
(Virtual Router Identifer), existing outbound connections from targets via "tnat" will therefore
survive any VRRP master switchover.
Different port/protocol tuples may be translated to the same outbound NAT address.
Example:
bng# "na" !0.!.!.! !E;.!)(.!.;30 "cp ;;
bng# "na" !0.!.!.! !E;.!)(.!.;30 0&p 53
bng# show vrrp
s"a"e B+ST>,
vri& !
priori"/ ;55
ip00 !E;.!)(.!.;;;
ip0! !E;.!)(.!.;30
ip0; !0.!.!.;54
$.$.$, unregister
Synopsis: 0nregis"er 7"arge"2s6 N server2s68 7lis"8
This is the counterpart command to the "regis"er" command. Please see the more detailed
state explanations there.
This command is used to transfer one or more targets or servers from the "registered" state to
the "unregistered" state. Target and server parameters and confgurations can only be
changed in the "unregistered" state.
Example:
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 131 / 146
bng# 0nregis"er "arge" !
bng# 0nregis"er servers !4;
$.$.$/ .rr"
Synopsis: vrrp 7s0bco99an&8 7val0e8
This command allows the confguration of the VRRP parameters. VRRP becomes activated
as soon as all three VRRP parameters are defned (vrid, priority and network).
Using a "{" as a second argument opens a vrrp block which can be closed interactively by
entering a "}" or an empty line.
Example:
bng# vrrp vri& !
bng# vrrp priori"/ ;55
bng# vrrp ne"work 3
bng# show vrrp
s"a"e B+ST>,
vri& !
priori"/ ;55
ip00 !E;.!)(.!.!0
bng#
$.$.$/.1 .rr" bscri"t
Synopsis: vrrp bscrip" 7scrip"8
This setting defnes an external notifcation script or program which is called if the VRRP
virtual router enters the BACKUP state. The script is executed in background by a separate
helper thread. Setting the script parameter to nothing ("") disables this setting.
Example:
No&e+# show vrrp
s"a"e B+ST>,
vri& !4
priori"/ ;00
"racking priori"/ no" &egra&e&
ipa&&r0 !H;.!H.;.)4
No&e+# vrrp bscrip" I:ho9e:"ools:back0pDno"if/I
No&e+# show vrrp
s"a"e B+ST>,
vri& !4
priori"/ ;00
"racking priori"/ no" &egra&e&
bscrip" I:ho9e:"ools:vrrpDback0pDno"if/I
ipa&&r0 !H;.!H.;.)4
No&e+#
$.$.$/. .rr" *scri"t
Synopsis: vrrp 9scrip" 7scrip"8
This setting defnes an external MASTER state notifcation script accordingly to "vrrp bscript".
The script is called when BalanceNG enters the MASTER VRRP state. Setting the script
parameter to nothing ("") disables this setting again.
Example:
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 132 / 146 Grünwald Germany / All Rights Reserved
No&e+# show vrrp
s"a"e B+ST>,
vri& !4
priori"/ ;00
"racking priori"/ no" &egra&e&
bscrip" I:ho9e:"ools:back0pDno"if/I
ipa&&r0 !H;.!H.;.)4
No&e+# vrrp 9scrip" I:ho9e:"ools:9as"erDno"if/I
No&e+# show vrrp
s"a"e B+ST>,
vri& !4
priori"/ ;00
"racking priori"/ no" &egra&e&
9scrip" I:ho9e:"ools:9as"erDno"if/I
bscrip" I:ho9e:"ools:back0pDno"if/I
ipa&&r0 !H;.!H.;.)4
No&e+#
$.$.$/.$ .rr" net&or-
Synopsis: vrrp ne"work 7i&8
This defnes the Network which will be used for VRRP communications. The following
network parameters will be used for VRRP:
• VRRP advertisements will be sent out only on the interfaces associated to that network
• The VRRP primary address will be the "real" address of the network declaration.
Note: A network being referenced by the VRRP declaration using this command may be used
as usual (there's no requirement to defne an explicit VRRP only network).
Example:
bng# vrrp ne"work 3
bng# show vrrp
s"a"e B+ST>,
vri& !
priori"/ ;55
ip00 !E;.!)(.!.!0
bng#
$.$.$/., .rr" "rioritA
Synopsis: vrrp priori"/ 7val0e8Nnone
Sets the priority of the VRRP node to the specifed value (or to unspecifed if "none" is
supplied). The priority must be in the range 1-255. The VRRP master priority is 255, the
default backup node priority is 100.
Example1 (declare node to become VRRP master):
bng# vrrp vri& !
bng# vrrp priori"/ ;55
bng# vrrp ne"work 3
Example2 (declare node to be a backup router with the default backup priority of 100):
bng# vrrp vri& !
bng# vrrp priori"/ !00
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 133 / 146
bng# vrrp ne"work 3
$.$.$/./ .rr" trac-ing
Synopsis: vrrp "racking enable
vrrp "racking &isable
vrrp "racking &efa0l"
This command enables or disables VRRP tracking, respectively. VRRP tracking is disabled by
default. If VRRP tracking is enabled and the VRRP priority is below 255 (which would be the
so called "VRRP address owner") then the VRRP is degraded by the sum of all tracking
values (see ""arge" 7n8 "rackval" and "ga"ewa/ "rackval") of all objects (targets or
gateway) which are both enabled and down/inoperational.
With VRRP tracking a controlled failover to the backup BalanceNG node can be specifed in
case that the current master node loses connectivity to important objects which are still
reachable and accessible by the backup node.
Example:
bng# vrrp priori"/ !00
bng# vrrp ne"work !
bng# vrrp vri& !
bng# show vrrp
s"a"e B+ST>,
vri& !
priori"/ !00
"racking &isable& '&efa0l".
ip00 !H;.!H.;.!(E
bng# vrrp "racking enable
bng# show vrrp
s"a"e B+ST>,
vri& !
priori"/ !00
"racking enable&
local priori"/ no" &egra&e&
ip00 !H;.!H.;.!(E
bng#
$.$.$/.1 .rr" .rid
Synopsis: vrrp vri& 7val0e8Nnone
Specifes the Virtual Router Identifer of the Virtual Router of this node. All nodes in the same
subnet sharing the same vrid represent all together the Virtual Router.
The supplied value must be in the range 1-255, supplying "none" sets the vrid to "unspecifed"
and such disables VRRP operation. See Reference /3/ for more Information about the VRRP
protocol.
Example:
bng# vrrp vri& !
bng# vrrp priori"/ ;55
bng# vrrp ne"work 3
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 134 / 146 Grünwald Germany / All Rights Reserved
, SN07 Su""ort
BalanceNG supports SNMP by interfacing to the Net-SNMP server and comes with its own
Set of Management Information Bases (MIBs).
BalanceNG supports read only SNMP access only, traps my be set out by calling snmptrap or
snmp_trapsend from "alert" and "upalert" target confgurations.
The BalanceNG MIB for instance 0 (as available for BalanceNG release 2) is located in the
enterprise specifc subtree of Inlab Software GmbH at:
iso<1>.org<$>.dod<1>.internet<1>."ri.ate<,>.enter"rises<1>.Inlab<221>.BalanceNG<1>.
The instance specifc MIBs for instances 0 to 128 are located in the enterprise specifc
subtree of Inlab Software GmbH at:
iso<1>.org<$>.dod<1>.internet<1>."ri.ate<,>.enter"rises<1>.Inlab<221>.BalanceNG<>.FInsta
nce Nu*berG.
All available MIBs are located in the "0IBS" directory in each distribution (either
3o"t3BalanceNG30IBS oder relatively as .30IBS as in the tarball distribution).
,.1 Interfacing to Net:SN07
An installed Net-SNMP software is required for interfacing to BalanceNG. This modern SNMP
system is part of almost all current Linux systems and is standard also on Solaris 10.
Further information is available at the Net-SNMP website at this URL:
htt"433net:sn*".sourceforge.net3
The needed Debian and Ubuntu packages are snmpd and snmp (tiny-snmpd does not work
for some reason).
The following readonly "com2sec" mapping is recommended (in /etc/snmp/snmpd.conf), just
uncomment as follows:
# sec.na9e so0rce co990ni"/
#co9;sec paranoi& &efa0l" p0blic
co&)sec readonly de,ault public
#co9;sec rea&wri"e &efa0l" priva"e
Additionally, the following line needs to be present in /etc/snmp/snmpd.conf in order to
establish the interface between snmpd and BalanceNG standard instance 0 MIB:
pass .!.3.).!.4.!.;HH!.! :sbin:bng
If multiple instances need to be accessed by SNMP the multi-instance OID has to be
specifed additionally as follows:
pass .!.3.).!.4.!.;HH!.; :sbin:bng
Note: There's no need to change /etc/default/snmpd anymore (snmpd runs now as user
snmp).
A typical "snmpget" command line looks like this (retrieving the "Release" string):
L sn9pge" -v! -c p0blic localhos" .!.3.).!.4.!.;HH!.!.!
B+%+N->NG-B#B,elease K ST,#NG I3.!H)I
Retrieving the same "Release" string from BalanceNG instance 7 (for example) may be
invoked as follows:
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 135 / 146
L sn9pge" -v! -c p0blic localhos" .!.3.).!.4.!.;HH!.!.!
B+%+N->NG-#NST+N->H-B#B,elease K ST,#NG I3.!H)I
A complete "snmpwalk" of the BalanceNG 2.x MIB can be invoked like this:
sn9pwalk -v! -c p0blic localhos" .!.3.).!.4.!.;HH!.!
The BALANCENG-MIBs may be copied to the /usr/share/snmp/mibs directory (for
Ubuntu/Debian Linux) like this:
# c& :op":BalanceNG:B#BS
# cp C."?" :0sr:share:sn9p:9ibs

The following environment variable setting makes the BalanceNG MIB available to the snmpd
tools:
e?por" B#BSK+%%
Note the difference between the two "snmpget" invocations below:
L sn9pge" -v! -c p0blic localhos" .!.3.).!.4.!.;HH!.!.!
SNB$v;-SB#en"erprises.;HH!.!.! K ST,#NG I;.;;(I
L e?por" B#BSK+%%
L sn9pge" -v! -c p0blic localhos" .!.3.).!.4.!.;HH!.!.!
B+%+N->NG-B#B,elease K ST,#NG I;.;;(I
You may also setup a local snmp.conf like this to make this setting permanent:
L 9k&ir -p L<FB>:.sn9p
L echo I9ibs +%%I 88 L<FB>:.sn9p:sn9p.conf
,. Accessing the SN07 interface directlA
The following command line options are used to access the BalanceNG MIB objects:
-g <oid> GET the specifed OID
-n <oid> GET the next OID starting from the specifed OID
-s <oid> <value> SET the OID to the specifed value (not supported with bng)
Example:
The following simple shell script retrieves the current state of the VRRP using that interface:
#J:bin:sh
=+%@>KM:0sr:bin:bng -g .!.3.).!.4.!.;HH!.!.;! N "ail -!M
case L=+%@> in
0. ST+T>KIFSSI QQ
!. ST+T>KI#N#T#+%#W>I QQ
;. ST+T>KIB+ST>,I QQ
3. ST+T>KIB+-Z@$I QQ
C. ST+T>KI@NZNFUNI QQ
esac
echo I=,,$ s"a"e is LST+T>I
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 136 / 146 Grünwald Germany / All Rights Reserved
,.$ Testing &ith sn*"get and sn*"&al-
The installation may be tested by issuing snmpget and snmpwalk commands on a client
machine (which my be the BalanceNG node itself):
Example:
To return the number of current sessions from BalanceNG node "castor" you may enter the
following on a Solaris 10 system:
# :0sr:sfw:bin:sn9pge" -v! -c p0blic cas"or B+%+N->NG-B#BSessions
B+%+N->NG-B#BSessions K Ga0ge3; !!;(
#
There are 1128 current sessions active.
A walk over instance 0 using the BalanceNG V2 OID may be invoked like this:
L sn9pwalk -v! -c p0blic localhos" .!.3.).!.4.!.;HH!.!
A "walk" over all active (running) instances using the newer multi-instance OID may be
invoked like this:
L sn9pwalk -v! -c p0blic localhos" .!.3.).!.4.!.;HH!.;
,., 0(TG rele.ant *etrics
The following metrics would be relevant for collecting with MRTG:
Sessions 'Ga0ge.
!.3.).!.4.!.;HH!.!.E
N09ber of c0rren" "o"al session "able en"ries
0nter,aceSent1ackets
!.3.).!.4.!.;HH!.!.40.5.G
N09ber of packe"s sen" o0" on "his in"erface
0nter,aceSentBytes
!.3.).!.4.!.;HH!.!.40.).G
N09ber of b/"es sen" o0" on "his in"erface
0nter,ace2ecei%ed1ackets
!.3.).!.4.!.;HH!.!.40.H.G
N09ber of packe"s receive& on "his in"erface
0nter,ace2ecei%edBytes
!.3.).!.4.!.;HH!.!.40.(.G
N09ber of b/"es receive& on "his in"erface
Ser%erSessions 'Ga0ge.
!.3.).!.4.!.;HH!.!.)0.!3.G
-0rren" n09ber of vir"0al server sessions4 &efine& "o be
"he s09 of "he sessions of all associa"e& "arge"s
Ser%erSent1ackets
!.3.).!.4.!.;HH!.!.)0.!4.G
N09ber of packe"s sen" "o "he clien"s4 &efine& "o be "he s09 of
packe"s being receive& fro9 all associa"e& "arge"s
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 137 / 146
Ser%erSentBytes
!.3.).!.4.!.;HH!.!.)0.!5 G
N09ber of b/"es sen" "o "he clien"s4 &efine& "o be "he s09 of
b/"es being receive& fro9 all associa"e& "arge"s
Ser%er2ecei%ed1ackets
!.3.).!.4.!.;HH!.!.)0.!) G
N09ber of packe"s receive& fro9 "he clien"s b/ "his vir"0al
server4 &efine& "o be "he s09 of packe"s being sen" "o all
associa"e& "arge"s
Ser%er2ecei%edBytes
!.3.).!.4.!.;HH!.!.)0.!H.G
N09ber of b/"es receive& fro9 "he clien"s b/ "his vir"0al server4
&efine& "o be "he s09 of b/"es being sen" "o all associa"e&
"arge"s
3argetSessions 'Ga0ge.
!.3.).!.4.!.;HH!.!.H0.;5.G
-0rren" n09ber of "arge" 'real server. sessions
3argetSent1ackets
!.3.).!.4.!.;HH!.!.H0.;).G
N09ber of packe"s sen" "o "arge" 'real server.
3argetSentBytes
!.3.).!.4.!.;HH!.!.H0.;H.G
N09ber of b/"es receive& fro9 "arge" 'real server.
3arget2ecei%ed1ackets
!.3.).!.4.!.;HH!.!.H0.;(.G
N09ber of packe"s receive& fro9 "arge" 'real server.
3arget2ecei%edBytes
!.3.).!.4.!.;HH!.!.H0.;E.G
N09ber of b/"es receive& fro9 "arge" 'real server.
3arget4gent5ata 'Ga0ge.
!.3.).!.4.!.;HH!.!.H0.30.G
$erfor9ance &a"a as re"0rne& fro9 bngagen" fee&back agen"
3arget3otalBand#idt! 'Ga0ge.
!.3.).!.4.!.;HH!.!.H0.3!.G
-0rren" "o"al ban&wi&"h of "arge" in b/"es per secon&
3arget0nco&ingBand#idt! 'Ga0ge.
!.3.).!.4.!.;HH!.!.H0.3;.G
-0rren" inco9ing ban&wi&"h of "arge" in b/"es per secon&
3arget6utgoingBand#idt! 'Ga0ge.
!.3.).!.4.!.;HH!.!.H0.33.G
-0rren" o0"going ban&wi&"h of "arge" in b/"es per secon&
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 138 / 146 Grünwald Germany / All Rights Reserved
/ Logging
BalanceNG uses the s/slog interface to send logging message to the Operating System
syslog facility. It uses the identifcation "BalanceNG" to openlog'.. Logging may be
collected centrally by confguring :e"c:s/slog.conf appropriately and by maintaining a
central log server machine.
The last 20 syslog messages are being collected in a cyclic buffer and can be investigated
using the "show log" command.
BalanceNG uses a set of syslog messages to report about "normal, but signifcant conditions"
and uses the syslog level %FGDNFT#-> exclusively for that purpose.
The following messages may be logged that way:
t!is %irtual router is no# 74S382
The node participates in VRRP and has just become the MASTER VRRP router with
the confgured VRID (Virtual Router Identifer).
t!is %irtual router is no# B49:;1
The node participates in VRRP and has been superseded my a higher priority node. It
has entered BACKUP state.
%rrp o,, and in state 0N0304<0=8
VRRP has been administratively switched off.
target <nu&ber> operational
The target with the specifed index has just become operational because all
confgured health checks succeed. An "upalert" script is called (if defned for that
target).
target <nu&ber> do#n
The target with the specifed index has become inoperational (down). This can be
either caused by failing health checks or by taking the target administratively out of
"enabled" state (with the "&isable" command). An "alert" script is called (if defned
for that target).
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 139 / 146
1 Bngagent
Bngagent is a small UDP server program which runs on a UNIX target machine. Using a
simple UDP protocol (the Bngagent Protocol) the "agent" health check method of BalanceNG
is capable to talk to this agent.
The source code of Bngagent is made available to the customers on order to enable them to
port is to the various UNIX based machines that they want to monitor.
Precompiled binaries of Bngagent are made available for Linux/x86, Solaris10/x86 and
Solaris/SPARC (9+10)..
1.1 Co*"iling Bngagent
Recommended example compilation command lines for compiling bngagent are:
Linu+4 gcc -o bngagen" bngagen".c
Solaris4 gcc -o bngagen" bngagen".c -lnsl -lsocke"
%7=O4 gcc -o bngagen" bngagen".c -9pa-risc-!-0
1. Starting and Sto""ing of Bngagent
The usage information of Bngagent (when called with no argument) is as follows:
# bngagen"
L,evision 3.E L
bngagen" is an open so0rce par" of "he BalanceNG pro&0c"
-op/righ" '-. ;005-;00E4;0!0 b/ #nlab Sof"ware G9b<4 Gr0enwal&4 Ger9an/
+ll righ"s reserve& - 9ore infos a" h""p::www.BalanceNG.ne"
0sage
server bngagen" 7op"ions8 por"
re50es" '"es". bngagen" 7op"ions8 -r a&&ress por"
op"ions
-0 re"0rn ! 9in0"e loa& avg 'server4&efa0l".
-! re"0rn 5 9in0"e loa& avg 'server.
-; re"0rn !5 9in0"e loa& avg 'server.
-) 0se #$v) ins"ea& of #$v4
-f s"a/ in foregro0n& 'server.
-b 7a&&ress8 specif/ bin& a&&ress 'bo"h.
-c 7co99an&8 specif/ co99an& 'server.
-& enable &eb0g an& foregro0n& 'bo"h.
-" 7"arge"i&8 specif/ "arge"i& 're50es".
#
Bngagent with the port number as argument puts itself into background and starts listening for
UDP packets being sent out by BalanceNG:
# bngagen" 43E
#
Starting bngagent in IPv6 mode works like this:
# bngagen" -) 43E
#
You may choose any available UDP port for that, if you want to use a privileged port below
1024 please use port 439 which is allowed to be used by the author for that purpose.
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 140 / 146 Grünwald Germany / All Rights Reserved
Stopping might be performed by using the "pkill" tool, e.g.:
# pkill bngagen"
#
The option -f forces Bngagent to stay in foreground, the option -& enables debugging output
and does an implicit -f.
Bngagent with no -c Argument calls ge"loa&avg'. and returns the 1 minute load average
of the machine multiplied by 100 back to BalanceNG for further processing (per default).
Option -! makes bngagent return the 5 minute load average and the option -; makes it
return the 15 minute load average.
Thus BalanceNG is immediately capable to take the system load of the target machines into
account.
You may pass control to a external script using the -c option. If an BalanceNG request is
being received by the Bngagent calls the external script and expects one line on stdout from
that script (at minimum). This value has to be in the unsigned integer range from 0 to 2^32.
Returning 0 means for BalanceNG that the target's service has become totally unavailable
and will force the target to become inoperational immediately. Otherwise BalanceNG with the
"agent" method will choose the target with the lowest Bngagent return value.
You may test a running bngagent instance by invoking another bngagent with the -r option
(request mode). This is especially useful during the development of specifc bngagent scripts.
An example might look as follows:
# .:bngagen" -c 1pgrep ssh& N wc -l1 5000
# .:bngagen" -r localhos"5000
"arge" i& 0 val0e !
# .:bngagen" -r localhos"500!
C"i9eo0"C
#
Compiling Bngagent can be done by a simple command.
For Linux you could use:
L gcc -o bngagen" bngagen".c
L
Solaris usually requires the "nsl" and "socket" libraries:
L gcc -o bngagen" bngagen".c -lnsl -lsocke"
L
We started to add precompiled binaries of bngagent to the main distribution. Please take a
look into the "bngagen"-binaries" directory.
1.$ The Bngagent =87 7rotocol
1.$.1 The Bngagent 7rotocol (e)uest
The Bngagent request packet simply consists of an unsigned short in network order which
represents the target id (or target number) for which information is being requested. The total
data length encapsulated in UDP is two bytes:
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 141 / 146
B/"e 0 B/"e !
*----------------*
N Targe" #& N
*----------------*
There's no authentication provided.
1.$. The Bngagent 7rotocol (e"lA
The reply sends the received Target Id back in a two byte unsigned short and additionally
returns the return value as a unsigned integer in four bytes. All data is in network order. The
total length of the Bngagent reply packet encapsulated in UDP is 6 bytes.
B/"e 0 B/"e ! B/"e ; B/"e 3 B/"e 4 B/"e 5
*----------------* *---------------------------------*
N Targe" #& N N Bngagen" re"0rn =al0e N
*----------------* *---------------------------------*
BalanceNG will choose the target with the lowest Bngagent return value when a new session
has to be created. Return 0 as the Bngagent return value means that the target is currently
unavailable (e.g. the service requested is down).
Sending back the Target Id allows multiple Bngagents to run on one host for different targets.
BalanceNG is that way capable to assign the replies based to their respective targets.
1., Writing Bngagent Scri"ts
A script or program being called by bngagent with the "-c" option should just put out one line
on stdout and then exit immediately. The line should contain one number either "0" for
"service unavailable" or any other positive integer in the 32 bit unsigned int range.
As mentioned before the BalanceNG agent distribution method will 1) disable any target
where the agent reports "0" and 2) will direct new sessions to the target with the lowest
Bngagent return value.
One very simple two line example is to count the number of processes:
#J:bin:sh
pgrep h""p& N wc -l
More complicated health checks should be implemented as scripts or programs to be handled
by Bngagent.
1./ Bngagent Source Code
The source code of bngagent is part of the BalanceNG distribution. It is being distributed
under the BalanceNG license.
2 Technical Bac-ground Infor*ation
2.1 BalanceNG I7., 0AC Addresses
In order to represent virtual IP-Addresses BalanceNG has to represent unique Mac
addresses or Ethernet addresses on the local network.
The Ethernet address of a virtual IP address which is under control of VRRP uses the
standard VRRP Ethernet address 00:00:5e:00:<router-id>:00 (as specifed in RFC 3768). This
Ethernet address is used uniquely for *all* Ethernet addresses under VRRP control.
All other addresses (and also generally when VRRP is switched off) are taken from the
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 142 / 146 Grünwald Germany / All Rights Reserved
"locally administered" Mac Address space.
Locally Administered addresses are generally assigned usually by the network administrator
instead of the hardware vendor. Locally Administered addresses have the second bit of their
frst octet set to one (value 02 in printed format.)
Possible locally administered ("private") Mac addresses are therefore:
C;-CC-CC-CC-CC-CC
C)-CC-CC-CC-CC-CC
C+-CC-CC-CC-CC-CC
C>-CC-CC-CC-CC-CC
Historically some of the areas out of "*2", "*A" and "*E" have been used in the past by several
vendors, so taking addresses out of the "*6" area is absolutely save in that sense.
BalanceNG uses a prefx of "06:00" as the frst two octets of a virtual Ethernet address and
maps the IPv4 IP-address into the remaining 4 octets.
Example: An IP-Address of 172.17.2.188 represented by BalanceNG would "own" the
Ethernet address "06:00:ac:11:02:bc" on Ethernet level.
The BalanceNG "show arphash" shows the internal associations in all rows where the "vip"
fag is set, e.g.:
bng# show arphash
ipa&&r e"ha&&r ne" flags
-------------------------------------------------
!H;.!H.;.E0 00e0(!5(ef;f 0
!H;.!H.;.!(( 0)00ac!!0;bc ! vip fi?
!H;.!H.;.!(E 0)00ac!!0;b& ! vip
bng#
2. BalanceNG I7.1 0AC Addresses
BalanceNG uses the prefx "06:01" for IPv6 MAC Addresses, followed by the instance in the
third octet. The remaining 3 octets are mapped from the BalanceNG nodeid.
2.$ J((7 e+tensions
2.$.1 TA"e 4 BalanceNG J Session Table SAnc Ad.ertise*ent
BalanceNG V2 uses a VRRP extension by using a VRRP packet type 2, which is unknown
and undefned by the VRRP version 2 standard.
Note: This packet type has been used with BalanceNG V2 to synchronize the session table
and is no longer in use with BalanceNG V3. The BNG V3 session table synchronization is
handled by VRRP extension packet types 4 and 6.
The session table information is packed into the space of 4 IP addresses which allows easy
reading with network analyzers. The packing of session table information is as follows:
#$ a&&ress 0 Session so0rce #$ a&&ress
#$ a&&ress ! Session so0rce por" in "he lower ; oc"e"s 'no" a real #$ a&&ress.
#$ a&&ress ; Server n09ber in "he higher ; oc"e"s4
Targe" n09ber in "he lower ; oc"e"s
#$ a&&ress 3 Server specific session "i9eo0" '0 if no" se"..
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 143 / 146
Here an example of a session announcement as it could appear in the Ethereal packet
analyzer (Session 172.17.2.4 port any -> 172.17.2.189 port 22; Target 1):
Sra9e !E 'H0 b/"es on wire4 H0 b/"es cap"0re&.
>"herne" ##4 Src #>TS-=,,$-vir"0al-ro0"er-=,#AD0a '00005e000!0a.4
As" 0!005e0000!; '0!005e0000!;.
#n"erne" $ro"ocol4 Src !H;.!H.;.!(( '!H;.!H.;.!((.4 As" ;;4.0.0.!( ';;4.0.0.!(.
=ir"0al ,o0"er ,e&0n&anc/ $ro"ocol
=ersion ;4 $acke" "/pe ; '@nknown.
=ir"0al ,"r #A !0
$riori"/ ;55 'This =,,$ ro0"er owns "he vir"0al ro0"er1s #$ a&&ress'es..
-o0n" #$ +&&rs 5
+0"h T/pe No +0"hen"ica"ion '0.
+&ver #n" !
-hecks09 0?(!f3 2correc"6
#$ +&&ress !H;.!H.;.4 '!H;.!H.;.4.
#$ +&&ress 0.0.0.0 '0.0.0.0.
#$ +&&ress 0.!.0.! '0.!.0.!.
#$ +&&ress 0.0.0.0 '0.0.0.0.
#$ +&&ress 0.0.0.0 '0.0.0.0.
Session table information is being broadcasted by the current active master node only for
active sessions and controlled by the "sessionsynciv" parameter to keep the additional traffc
low.
2.$. TA"e $4 BalanceNG J NAT State SAnc Ad.ertise*ent
<TBD>
2.$.$ TA"e ,4 BalanceNG J$ Session Table SAnc Ad.ertise*ent
<TBD>
2.$., TA"e /4 BalanceNG J$ GNAT State SAnc Ad.ertise*ent
<TBD>
2.$./ TA"e 14 BalanceNG J$ Session Table SAnc ACP
<TBD>
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 144 / 146 Grünwald Germany / All Rights Reserved
5 Third 7artA Soft&are Co"Aright Notices
5.1 L8NS <8NS LibrarA>
BalanceNG V3 may be statically linked to the "LDNS" DNS library (available at the following
URL: http://www.nlnetlabs.nl/ldns/ ). The "LDNS" DNS library copyright notice is as follows:
-op/righ" 'c. ;0054;00)4 N%ne"%abs
+ll righ"s reserve&.
,e&is"rib0"ion an& 0se in so0rce an& binar/ for9s4 wi"h or wi"ho0"
9o&ifica"ion4 are per9i""e& provi&e& "ha" "he following con&i"ions are 9e"
C ,e&is"rib0"ions of so0rce co&e 90s" re"ain "he above cop/righ" no"ice4
"his lis" of con&i"ions an& "he following &isclai9er.
C ,e&is"rib0"ions in binar/ for9 90s" repro&0ce "he above cop/righ"
no"ice4 "his lis" of con&i"ions an& "he following &isclai9er in "he
&oc09en"a"ion an&:or o"her 9a"erials provi&e& wi"h "he &is"rib0"ion.
C Nei"her "he na9e of N%ne"%abs nor "he na9es of i"s
con"rib0"ors 9a/ be 0se& "o en&orse or pro9o"e pro&0c"s &erive& fro9 "his
sof"ware wi"ho0" specific prior wri""en per9ission.
T<#S SFSTU+,> #S $,F=#A>A BV T<> -F$V,#G<T <F%A>,S +NA -FNT,#B@TF,S I+S #SI
+NA +NV >G$,>SS F, #B$%#>A U+,,+NT#>S4 #N-%@A#NG4 B@T NFT %#B#T>A TF4 T<>
#B$%#>A U+,,+NT#>S FS B>,-<+NT+B#%#TV +NA S#TN>SS SF, + $+,T#-@%+, $@,$FS>
+,> A#S-%+#B>A. #N NF >=>NT S<+%% T<> -F$V,#G<T FUN>, F, -FNT,#B@TF,S B>
%#+B%> SF, +NV A#,>-T4 #NA#,>-T4 #N-#A>NT+%4 S$>-#+%4 >G>B$%+,V4 F,
-FNS>\@>NT#+% A+B+G>S '#N-%@A#NG4 B@T NFT %#B#T>A TF4 $,F-@,>B>NT FS
S@BST#T@T> GFFAS F, S>,=#->SQ %FSS FS @S>4 A+T+4 F, $,FS#TSQ F, B@S#N>SS
#NT>,,@$T#FN. <FU>=>, -+@S>A +NA FN +NV T<>F,V FS %#+B#%#TV4 U<>T<>, #N
-FNT,+-T4 ST,#-T %#+B#%#TV4 F, TF,T '#N-%@A#NG N>G%#G>N-> F, FT<>,U#S>.
+,#S#NG #N +NV U+V F@T FS T<> @S> FS T<#S SFSTU+,>4 >=>N #S +A=#S>A FS T<>
$FSS#B#%#TV FS S@-< A+B+G>.
BalanceNG V3 User and Reference Manual Date: Jan 23, 2014
© Copyright 2005-2013,2014 by Inlab Software GmbH
Grünwald, Germany / All Rights Reserved Page 145 / 146
6 (eferences
/1/ Radia Perlman: Interconnections Second Edition
Addison Wesley, ISBN 0201634481
/2/ Rich Seifert: The Switch Book
Wiley & Sons, ISBN 0471345865
/3/ R. Hinden et. al.: Virtual Router Redundancy Protocol (VRRP)
RFC3768
Date: Jan 23, 2014 BalanceNG V3 User and Reference Manual
© Copyright 2005-2013,2014 by Inlab Software GmbH
Page 146 / 146 Grünwald Germany / All Rights Reserved

Sponsor Documents

Or use your account on DocShare.tips

Hide

Forgot your password?

Or register your new account on DocShare.tips

Hide

Lost your password? Please enter your email address. You will receive a link to create a new password.

Back to log-in

Close