BalanceNG Release 1.x - Free and Open Source Software
BalanceNG Release 1.x - Free and Open Source Software
BalanceNG Release 1.x - Free and Open Source Software
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
<strong>BalanceNG</strong> ® <strong>Release</strong> <strong>1.x</strong>A Modern <strong>Software</strong> IP Load Balancing SolutionUser <strong>and</strong> Reference ManualComm<strong>and</strong> Set <strong>BalanceNG</strong> 1.840 <strong>and</strong> higherStatus: CURRENTVersion: 1.840.0Date: Apr 29, 2007Author: Thomas ObermairSW-Date: 2007/04/29Inlab <strong>Software</strong> GmbHJosef-Würth-Str. 382031 GrünwaldGermanyTel.: +49 89 6412795Fax: +49 89 6411160Email: office@inlab.deHome: http://www.inlab.de
Table of Contents1 Introduction....................................................................................................81.1 What is <strong>BalanceNG</strong> ? .............................................................................81.2 <strong>BalanceNG</strong> Features <strong>and</strong> Specifications................................................81.3 Hardware <strong>and</strong> OS Requirements............................................................91.3.1 Linux..........................................................................................................91.3.2 Solaris.......................................................................................................91.4 <strong>BalanceNG</strong> Core Concepts..................................................................101.4.1 Interfaces................................................................................................101.4.2 Networks.................................................................................................101.4.3 Servers....................................................................................................101.4.4 Targets....................................................................................................101.4.5 Configuration...........................................................................................101.5 <strong>BalanceNG</strong> Design ..............................................................................112 Initial Implementation...................................................................................122.1 Hardware selection...............................................................................122.2 Network Setup......................................................................................122.3 Installation............................................................................................142.3.1 Installation on Solaris...............................................................................142.3.2 Installation on Linux.................................................................................152.4 Making <strong>BalanceNG</strong> Turnkey................................................................162.4.1 Making <strong>BalanceNG</strong> Turnkey on Solaris..................................................162.4.2 Making <strong>BalanceNG</strong> Turnkey on Linux....................................................162.5 Determining the Nodeid <strong>and</strong> Licensing................................................172.6 “Basic license” restrictions....................................................................183 Comm<strong>and</strong> Reference...................................................................................193.1 Comm<strong>and</strong> Line Interface .....................................................................193.1.1 bng..........................................................................................................193.1.2 bng start [instance]..................................................................................193.1.3 bng stop [instance]..................................................................................203.1.4 bng restart [instance]..............................................................................203.1.5 bng status [instance]...............................................................................203.1.6 bng control [instance]..............................................................................213.1.7 bng auxctl [instance]...............................................................................223.2 Administrative <strong>and</strong> Informational Comm<strong>and</strong>s......................................223.2.1 benchmark..............................................................................................223.2.2 check.......................................................................................................233.2.3 help ........................................................................................................233.2.4 help .......................................................................................243.2.5 save.........................................................................................................263.2.6 sessiondump...........................................................................................263.2.7 show........................................................................................................273.2.7.1 show ?.............................................................................................27Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 2 / 143Grünwald Germany / All Rights Reserved
3.2.7.2 show arphash..................................................................................273.2.7.3 show benchmark.............................................................................283.2.7.4 show conf .......................................................................................283.2.7.5 show conf ........................................................................293.2.7.6 show gateway..................................................................................293.2.7.7 show ifstat.......................................................................................303.2.7.8 show instance..................................................................................313.2.7.9 show interfaces ..............................................................................313.2.7.10 show license..................................................................................313.2.7.11 show log .......................................................................................323.2.7.12 show machash..............................................................................323.2.7.13 show nat........................................................................................333.2.7.14 show nodeid..................................................................................333.2.7.15 show parameters...........................................................................343.2.7.16 show server ............................................................................343.2.7.17 show servers.................................................................................353.2.7.18 show sessions...............................................................................353.2.7.19 show stinfo....................................................................................363.2.7.20 show targets .................................................................................363.2.7.21 show target .............................................................................373.2.7.22 show targetregistry........................................................................373.2.7.23 show uptime..................................................................................383.2.7.24 show vips.......................................................................................383.2.7.25 show version.................................................................................383.2.7.26 show vrrp.......................................................................................393.2.8 shutdown.................................................................................................393.2.9 snapshot..................................................................................................393.2.10 stop.......................................................................................................393.3 Configuration Comm<strong>and</strong>s.....................................................................403.3.1 arp...........................................................................................................403.3.2 commit.....................................................................................................413.3.3 disable.....................................................................................................423.3.4 dump.......................................................................................................433.3.5 edit..........................................................................................................433.3.6 enable.....................................................................................................443.3.7 gateway...................................................................................................463.3.7.1 gateway ..........................................................................463.3.7.2 gateway alert .....................................................................463.3.7.3 gateway arp ,...................................................463.3.7.4 gateway ipaddr ...............................................................473.3.7.5 gateway ping ,.................................................473.3.7.6 gateway trackval ................................................................483.3.7.7 gateway upalert .................................................................483.3.8 hostname................................................................................................483.3.9 interface .................................................................................................493.3.10 l2switch.................................................................................................513.3.11 license...................................................................................................51<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 3 / 143
3.3.12 network ..........................................................................................523.3.12.1 network addr..........................................................................523.3.12.2 network interface[s]................................................................533.3.12.3 network mask.........................................................................533.3.12.4 network name.........................................................................533.3.12.5 network nat.............................................................................543.3.12.6 network real............................................................................553.3.12.7 network virt.............................................................................553.3.13 no .........................................................................................................553.3.14 register..................................................................................................563.3.15 remark...................................................................................................593.3.16 server....................................................................................................603.3.16.1 server backup[s].....................................................................603.3.16.2 server failover ........................................................................613.3.16.3 server ipaddr..........................................................................613.3.16.4 server method........................................................................633.3.16.4.1 rr....................................................................................................633.3.16.4.2 hash..............................................................................................633.3.16.4.3 r<strong>and</strong>om..........................................................................................643.3.16.4.4 agent.............................................................................................643.3.16.4.5 bw.................................................................................................643.3.16.4.6 bwin..............................................................................................653.3.16.4.7 bwout............................................................................................653.3.16.4.8 rndagent........................................................................................653.3.16.4.9 session..........................................................................................653.3.16.5 server name...........................................................................663.3.16.6 server plugin...........................................................................673.3.16.7 server port..............................................................................683.3.16.8 server ports ,..........................................................703.3.16.9 server portrel..........................................................................703.3.16.10 server protocol.....................................................................713.3.16.11 server stimeout |default...........................................723.3.16.12 server target[s].....................................................................723.3.17 set.........................................................................................................733.3.17.1 set arplookup.................................................................................733.3.17.2 set arprefresh................................................................................743.3.17.3 set arptimeout................................................................................753.3.17.4 set bmduration...............................................................................753.3.17.5 set bmpsize...................................................................................753.3.17.6 set bmwsize...................................................................................753.3.17.7 set debugscope.............................................................................753.3.17.8 set dumprotation............................................................................763.3.17.9 set gratarpremind..........................................................................763.3.17.10 set hcportoffset............................................................................773.3.17.11 set ipforwarding...........................................................................773.3.17.12 set localdsr..................................................................................783.3.17.13 set localvirt..................................................................................783.3.17.14 set natdlimit.................................................................................78Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 4 / 143Grünwald Germany / All Rights Reserved
3.3.17.15 set natscan..................................................................................793.3.17.16 set natsync..................................................................................793.3.17.17 set natsynciv................................................................................793.3.17.18 set nattimeout..............................................................................793.3.17.19 set vrrpmasterdown.....................................................................793.3.17.20 set vrrppreempt...........................................................................803.3.17.21 set sendprobes............................................................................803.3.17.22 set sessiondlimit..........................................................................813.3.17.23 set sessionscan...........................................................................813.3.17.24 set sessionsync...........................................................................813.3.17.25 set sessionsynciv........................................................................823.3.17.26 set sessiontimeout ......................................................................823.3.18 softdisable target ...........................................................................833.3.19 target.....................................................................................................843.3.19.1 target agent............................................................................843.3.19.2 target alert..............................................................................843.3.19.3 target aoffset..........................................................................853.3.19.4 target ascale...........................................................................853.3.19.5 target dsr................................................................................853.3.19.6 target ipaddr...........................................................................863.3.19.7 target maxagent.....................................................................863.3.19.8 target maxsessions................................................................863.3.19.9 target name............................................................................863.3.19.10 target offset..........................................................................873.3.19.11 target ping ...........................................................................883.3.19.12 target port ............................................................................883.3.19.13 target protocol......................................................................893.3.19.14 target scale...........................................................................893.3.19.15 target script..........................................................................903.3.19.16 target tcpopen......................................................................913.3.19.17 target upalert .......................................................................913.3.19.18 target trackval.......................................................................923.3.19.19 target weight.........................................................................933.3.20 tnat........................................................................................................933.3.21 unregister..............................................................................................943.3.22 vip..........................................................................................................943.3.23 vrrp........................................................................................................943.3.23.1 vrrp bscript ....................................................................................953.3.23.2 vrrp mscript....................................................................................953.3.23.3 vrrp network ..................................................................................963.3.23.4 vrrp priority....................................................................................963.3.23.5 vrrp tracking...................................................................................973.3.23.6 vrrp vrid.........................................................................................974 SNMP Support.............................................................................................994.1 Interfacing to Net-SNMP......................................................................994.2 Accessing the SNMP interface directly..............................................1004.3 Testing with snmpget <strong>and</strong> snmpwalk.................................................100<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 5 / 143
4.4 MRTG relevant metrics......................................................................1014.5 The <strong>BalanceNG</strong> MIB..........................................................................1035 Logging .....................................................................................................1096 Bngagent...................................................................................................1106.1 Compiling Bngagent ..........................................................................1106.2 Starting <strong>and</strong> Stopping of Bngagent....................................................1106.3 The Bngagent UDP Protocol..............................................................1126.3.1 The Bngagent Protocol Request...........................................................1126.3.2 The Bngagent Protocol Reply...............................................................1126.4 Writing Bngagent Scripts....................................................................1126.5 Bngagent <strong>Source</strong> Code......................................................................1137 Application Examples ...............................................................................1187.1 Balancing to 4 Targets with VRRP redundancy.................................1187.1.1 Network Data <strong>and</strong> Addresses...............................................................1187.1.2 Configuration of <strong>BalanceNG</strong> Master.....................................................1197.1.3 Configuration of <strong>BalanceNG</strong> Backup....................................................1237.1.4 Checking the Status..............................................................................1247.1.5 Configuration Variations .......................................................................1277.1.6 General Configuration Guidelines <strong>and</strong> Rules........................................1277.2 Single Legged / One Node Operation ...............................................1277.2.1 The Initial Network................................................................................1277.2.2 Load balancing to two targets with one single legged <strong>BalanceNG</strong> node....1287.2.3 The Configuration File ..........................................................................1297.3 Load Balancing in Dual Legged Switching Mode..............................1307.3.1 The initial network.................................................................................1307.3.2 Dual Legged Switching Mode...............................................................1317.3.3 The Configuration File...........................................................................1327.4 Operating <strong>BalanceNG</strong> as a Layer 2 Switch.......................................1337.5 Load Balancing in Direct Server Return Mode (DSR).......................1337.5.1 The Initial Network ...............................................................................1337.5.2 Load balancing to two targets in DSR-Mode........................................1347.5.3 The Configuration File...........................................................................1357.6 Direct Server Return Example with bngagent <strong>and</strong> VRRP.................1367.6.1 The Network Setup...............................................................................1367.6.2 Establishing the Loopback Aliases.......................................................1377.6.3 Starting bngagent on both Targets.......................................................1387.6.4 The Master <strong>and</strong> Backup configuration files...........................................1387.6.4.1 The Master Configuration File.......................................................1387.6.4.2 The Backup Configuration File......................................................1408 Technical Background Information.............................................................1418.1 <strong>BalanceNG</strong> Ethernet Addresses........................................................1418.2 Implementation of <strong>BalanceNG</strong> Session Table Synchronization .......1429 References.................................................................................................143Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 6 / 143Grünwald Germany / All Rights Reserved
Legal Notices© Copyright 2006, 2007 by Inlab <strong>Software</strong> GmbH, Josef-Wuerth-Str. 3, Gruenwald, Germany. All Rights Reserved /Alle Rechte vorbehalten.This product or document is protected by copyright <strong>and</strong> distributed under licenses restricting its use, copying,distribution, <strong>and</strong> decompilation. No part of this product or document may be reproduced in any form by any meanswithout prior written authorization of Inlab <strong>Software</strong> GmbH.<strong>BalanceNG</strong> is a trademark of Inlab <strong>Software</strong> GmbH. Gentoo is a trademark by Gentoo Technologies, Inc. Debian isa registered trademark of <strong>Software</strong> In The Public Interest, Inc. <strong>Free</strong>BSD is a registered trademark of Walnut CreekCDROM, Inc. Linux is a registered trademark of Linus Torvalds. All other trademarks <strong>and</strong> registered trademarksmentioned 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 THEEXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 7 / 143
1 Introduction1.1 What is <strong>BalanceNG</strong> ?<strong>BalanceNG</strong> (Balance Next Generation) is a <strong>Software</strong> Load Balancing Solution utilizing its ownnetwork stacks <strong>and</strong> functionality. In fact, <strong>BalanceNG</strong> uses the underlying operating systemonly for accessing the physical interfaces, all TCP/IP <strong>and</strong> other functionality (like ARP <strong>and</strong>ICMP) is being processed internally.<strong>BalanceNG</strong> runs as a user mode program using the PF_PACKET API on Linux <strong>and</strong> the DLPIAPI on Solaris to access the network interfaces as directly as possible.With <strong>BalanceNG</strong> the Network or Data center Administrator is capable to build high availabilitycapable load balancing devices at a very low <strong>and</strong> very competitive price (compared todedicated hardware boxes / Load Balancing Appliances).At the heart of <strong>BalanceNG</strong>'s is Inlab's Ethernet Switch solution ("switch") which basicallyconverts a multi-homed system into an Ethernet Switch. This base implementation has beenused for several years in many products <strong>and</strong> test setups.1.2 <strong>BalanceNG</strong> Features <strong>and</strong> Specifications• Layer 2 (Ethernet) based load balancer.• Available for Linux-x86 (2.4 <strong>and</strong> 2.6 kernels), Solaris 9 (SPARC) <strong>and</strong> Solaris 10 (SPARC<strong>and</strong> x86).• Linux distribution independent.• Capable to run in multiple instances on the same host.• Session persistence based on client address <strong>and</strong> optional source port.• Backup targets (hosts) specifiable in case of failure of all primary targets.• Health checking via: PING, TCP Socket <strong>Open</strong> <strong>and</strong> freely customizable UDP Health CheckAgent (supplied in <strong>Source</strong>-Code).• External target specific health check scripts.• Alert/Upalert notification scripts (e.g. for sending email or sending a SNMP trap to anetwork management system).• Distribution methods: Round Robin, Simple Weighted Round Robin, R<strong>and</strong>om, WeightedR<strong>and</strong>om, Client Address Hashing, Least Session, Least B<strong>and</strong>width <strong>and</strong> Least Resourcebased on agent supplied information.• Unchanged client addresses on IP-level.• Supports DSR (Direct Server Return) configurations.• Small, very fast <strong>and</strong> reliable.• Simple to implement <strong>and</strong> administer.• Simple "init script style" arguments like "start", "stop" <strong>and</strong> "status" (<strong>and</strong> "control" forinteractive configuration <strong>and</strong> control).• Interactive communications mode with comm<strong>and</strong> line editing.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 8 / 143Grünwald Germany / All Rights Reserved
• Pcap packet dumping with automated dumpfile rotation (e.g. to implement a "transparentforensic logging bridge").• Multi-node High Availability capability using st<strong>and</strong>ard VRRP (Virtual Router RedundancyProtocol).• Session table synchronization <strong>and</strong> connection state replication using a <strong>BalanceNG</strong>-specificVRRP extension.• "All service load balancing" based on client IP address enables most protocols to besupported (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 <strong>and</strong> up to 1024 targets (real servers).1.3 Hardware <strong>and</strong> OS Requirements1.3.1 Linux<strong>BalanceNG</strong> runs under most x86 Linux implementations using Kernel revisions 2.4 or 2.6.<strong>BalanceNG</strong> is distribution independent <strong>and</strong> should run on any distribution supporting 2.4 / 2.6kernels.Known distributions which support <strong>BalanceNG</strong> are:• Gentoo Linux• Redhat / Fedora• Debian• Slackware• Devil-Linux• SUSE Linux (Novell)All network adapter cards which are either compiled into the kernel or available as a moduleare supported.There is no package manager dependency as <strong>BalanceNG</strong> comprises a single, statically linkedbinary that can be installed manually anywhere on the host systemMemory recommendation: 128 Megabytes minimum, 512 Megabytes recommended.Processor minimum requirement: 1Ghz for 2 x 1000BaseT interfaces <strong>and</strong> a 100BaseTmanagement network1.3.2 Solaris<strong>BalanceNG</strong> is supported on the following Solaris platforms:• Solaris 9 (SPARC)• Solaris 10 (SPARC)• Solaris 10 (x86)<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 9 / 143
1.4 <strong>BalanceNG</strong> Core ConceptsIn order to underst<strong>and</strong> the simplicity of <strong>BalanceNG</strong> it's important to know about the<strong>BalanceNG</strong> core concepts, here the basics:1.4.1 InterfacesInterfaces are the physical hardware interfaces to one or more networks. They are named likethe underlaying Linux kernel names them (like eth0, eth1 <strong>and</strong> so on).<strong>BalanceNG</strong> uses the interfaces that it is allowed to use, this is done by issuing the keyword"interface" together with the Linux interface name.Interfaces don't have to be "up" or configured, <strong>BalanceNG</strong> performs all necessaryadministrative tasks automatically. Also it is neither required or necessary to configureinterface addresses in the Linux operating system.1.4.2 NetworksNetworks are IPv4 network definitions the have a network address <strong>and</strong> a network mask.Additionally one or more interfaces are being referenced by the <strong>BalanceNG</strong> network definition.On a UNIX system an interface has one or more associated network definitions <strong>and</strong>addresses, in the <strong>BalanceNG</strong> world this relation is reversed: One network definition (<strong>and</strong> theaddresses) are associated to one or many interfaces.Each network definition additionally has to have two required IPv4 addresses: The "real"address being used for ARP-requests <strong>and</strong> healthchecks <strong>and</strong> the "virt" address beingaddressable as a routing endpoint for external devices. The "real" network address has to benode specific, the "virt" address has to be shared between multiple <strong>BalanceNG</strong> nodes in aVRRP HA configuration.1.4.3 ServersServers are the addressable "virtual Servers" in the <strong>BalanceNG</strong> world. Servers are "virtual" or"artificial" IP addresses represented by <strong>BalanceNG</strong>. Network requests to those servers aredistributed among the targets according to the load balancing definitions.Servers may be defined in any <strong>BalanceNG</strong> network referencing targets in any <strong>BalanceNG</strong>network.Note: <strong>BalanceNG</strong> servers would be called "virtual servers" by other load balancing softwarevendors.1.4.4 Targets<strong>BalanceNG</strong> represents one or more virtual servers <strong>and</strong> distributes the requests among a setof targets associated with each virtual server.Note: <strong>BalanceNG</strong> targets would be called "real servers" by other load balancing softwarevendors.1.4.5 ConfigurationThe behaviour <strong>and</strong> actions of <strong>BalanceNG</strong> are controlled by its internal configuration. Thisconfiguration may be altered in interactive mode by entering configuration comm<strong>and</strong>s. AnDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 10 / 143Grünwald Germany / All Rights Reserved
external representation of this configuration may be saved to /etc/bng.conf, <strong>BalanceNG</strong> loadsan existing configuration in /etc/bng.conf automatically at startup.A <strong>BalanceNG</strong> configuration consists of the following sections in exactly that order:1. hostname, remark, license2. parameter settings ("set"-section)3. interfaces section4. vrrp-section5. network definitions6. network register/enable section7. gateway section8. server definitions9. server register/enable section10. target section11. target register/enable section1.5 <strong>BalanceNG</strong> Design<strong>BalanceNG</strong> is implemented in C based on a monolithic switching engine. <strong>BalanceNG</strong> alsouses multithreading (POSIX threads / pthreads) to operate different helper threads whichcommunicate with the core switching engine.These threads are used for the target specific health check scripts <strong>and</strong> the alert/upalert scripts(see the "target script", target alert" <strong>and</strong> "target upalert" comm<strong>and</strong>s).<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 11 / 143
2 Initial Implementation2.1 Hardware selection<strong>BalanceNG</strong> runs under nearly all Linux x86 systems with a 2.4 or 2.6 kernel, hence thechoice of hardware is extensive. Please bear in mind that in any case the <strong>BalanceNG</strong>licensing (Full License) is hardware dependent, therefore it is recommended that the finaldeployment hardware be purchased prior to license purchase.For pre-implementation <strong>and</strong> evaluation testing, you may use the test license implicitly suppliedwith 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 <strong>and</strong> then as many 100/1000BaseTinterfaces for traffic as required. We have found that Intel Gigabit Adapter Cards (or chipsets) work very well.• If gigabit performance is required select a machine with two (or more) on board gigabitinterfaces avoiding PCI b<strong>and</strong>width problems. Use the fastest processor you can get.• Install the Linux distribution of choice. You may utilize one of the special embedded Linuxdistributions which do not require a hard disk. We have been using "DevilLinux"successfully in our Test Lab, see http://www.devil-linux.org.• 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” comm<strong>and</strong> <strong>and</strong> take a look at thebenchmark results page at http://www.inlab.de/balanceng/bmresults.html .2.2 Network SetupA common setup of <strong>BalanceNG</strong> comprises the following topology (pictured below): A localIPv4 network connected via a router to an external network (e.g. the Internet) <strong>and</strong> via one ormore <strong>BalanceNG</strong> nodes to the target network.We refer to the the network connected to the Router the "Access Network", <strong>and</strong> the network towhich the Targets are connected the "Target Network".Running <strong>BalanceNG</strong> "single legged" allows integration of <strong>BalanceNG</strong> into an already existingnetwork installation.Note: The real physical servers are called "Targets" in the <strong>BalanceNG</strong> world.Note: Talking about "Servers" within <strong>BalanceNG</strong> refers to "Virtual Servers" being presented by<strong>BalanceNG</strong>.<strong>BalanceNG</strong> Servers perform load balancing over one or more <strong>BalanceNG</strong> Targets.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 12 / 143Grünwald Germany / All Rights Reserved
Figure 1: Common <strong>BalanceNG</strong> Network SetupFigure 2: "Single Legged" Network setup<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 13 / 143
2.3 Installation2.3.1 Installation on Solaris<strong>BalanceNG</strong> for Solaris is distributed as a st<strong>and</strong>ard, platform independent package which hasto be installed with the “pkgadd” comm<strong>and</strong> of Solaris.Note: <strong>BalanceNG</strong> 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<strong>BalanceNG</strong>-1.840-Solaris-pkg.gz# gunzip <strong>BalanceNG</strong>-1.840-Solaris-pkg.gz# pkgadd -d <strong>BalanceNG</strong>-1.840-Solaris-pkgThe following packages are available:1 <strong>BalanceNG</strong> <strong>BalanceNG</strong> - <strong>Software</strong> IP Load Balancer(i386+SPARC) 1.840Select package(s) you wish to process (or 'all' to processall packages). (default: all) [?,??,q]:Processing package instance from <strong>BalanceNG</strong> - <strong>Software</strong> IP Load Balancer(i386+SPARC) 1.840Copyright (C) 2007 by Inlab <strong>Software</strong> GmbH, Gruenwald, Germany.All rights reserved / Alle Rechte vorbehalten.Visit http://www.<strong>BalanceNG</strong>.net for further information.## Executing checkinstall script.Using as the package base directory.## Processing package information.## Processing system information.## Verifying disk space requirements.## Checking for conflicts with packages already installed.## Checking for setuid/setgid programs.This package contains scripts which will be executed with super-userpermission during the process of installing this package.Do you want to continue with the installation of [y,n,?] yInstalling <strong>BalanceNG</strong> - <strong>Software</strong> IP Load Balancer as ## Installing part 1 of 1./opt/<strong>BalanceNG</strong>/BALANCENG-MIB.txt/opt/<strong>BalanceNG</strong>/LICENSE/opt/<strong>BalanceNG</strong>/README/opt/<strong>BalanceNG</strong>/bng-Solaris-i386/opt/<strong>BalanceNG</strong>/bng-Solaris-sparc/opt/<strong>BalanceNG</strong>/bng-initscript/opt/<strong>BalanceNG</strong>/bngagent-Linux-i386/opt/<strong>BalanceNG</strong>/bngagent-Solaris-i386/opt/<strong>BalanceNG</strong>/bngagent-Solaris-sparc/opt/<strong>BalanceNG</strong>/bngagent.c/opt/<strong>BalanceNG</strong>/bngfilt32-i386/opt/<strong>BalanceNG</strong>/bngfilt64-i386/opt/<strong>BalanceNG</strong>/bngfilt64-sparc/opt/<strong>BalanceNG</strong>/contrib/BngAgentService.zip/opt/<strong>BalanceNG</strong>/contrib/READMEDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 14 / 143Grünwald Germany / All Rights Reserved
[ verifying class ]## Executing postinstall script.Installation of was successful.#The results of this installation are:1. The <strong>BalanceNG</strong> binary is available as /usr/bin/bng2. The bngfilt STREAMS module is installed3. The /etc/init.d scripts are setup to start <strong>BalanceNG</strong> on reboot (if /etc/bng.conf exists)4. The remaining distribution files are available in the directory /opt/<strong>BalanceNG</strong>.The removal of <strong>BalanceNG</strong> is done by a simple “pkgrm <strong>BalanceNG</strong>”.2.3.2 Installation on LinuxThe Linux Distribution of <strong>BalanceNG</strong> is a tar archive, containing the <strong>BalanceNG</strong> binary.The download file is a "gzipped" tar archive (<strong>BalanceNG</strong>---.tar.gz) located wherever you downloaded it.Please extract this tar archive using the "tar" comm<strong>and</strong> as follows (example, assuming<strong>BalanceNG</strong> 1.840 for Linux downloaded into /tmp):# cd /tmp# ls <strong>BalanceNG</strong>*<strong>BalanceNG</strong>-1.840-Linux-x86.tar.gz# tar xvfz <strong>BalanceNG</strong>-1.840-Linux-x86.tar.gz./<strong>BalanceNG</strong>-1.840-Linux-x86/./<strong>BalanceNG</strong>-1.840-Linux-x86/README./<strong>BalanceNG</strong>-1.840-Linux-x86/LICENSE./<strong>BalanceNG</strong>-1.840-Linux-x86/bng./<strong>BalanceNG</strong>-1.840-Linux-x86/bngagent./<strong>BalanceNG</strong>-1.840-Linux-x86/bngagent.c./<strong>BalanceNG</strong>-1.840-Linux-x86/bngagent-binaries/./<strong>BalanceNG</strong>-1.840-Linux-x86/bngagent-binaries/bngagent-1.42-Solaris9-SPARC./<strong>BalanceNG</strong>-1.840-Linux-x86/bngagent-binaries/bngagent-1.42-Linux-x86./<strong>BalanceNG</strong>-1.840-Linux-x86/bngagent-binaries/bngagent-1.42-Solaris10-x86./<strong>BalanceNG</strong>-1.840-Linux-x86/bngfilt-binaries/./<strong>BalanceNG</strong>-1.840-Linux-x86/bngfilt-binaries/bngfilt32-SPARC./<strong>BalanceNG</strong>-1.840-Linux-x86/bngfilt-binaries/bngfilt32-X86./<strong>BalanceNG</strong>-1.840-Linux-x86/bngfilt-binaries/bngfilt64-SPARC./<strong>BalanceNG</strong>-1.840-Linux-x86/bngfilt-binaries/bngfilt64-X86./<strong>BalanceNG</strong>-1.840-Linux-x86/bngfilt-binaries/README./<strong>BalanceNG</strong>-1.840-Linux-x86/contrib/./<strong>BalanceNG</strong>-1.840-Linux-x86/contrib/BngAgentService.zip./<strong>BalanceNG</strong>-1.840-Linux-x86/contrib/README#The files extracted are:READMELICENSEbngbngagent[.c]Describes where to obtain <strong>BalanceNG</strong>Is a copy of the End User License AgreementIs the <strong>BalanceNG</strong> application executable binaryAre the executable <strong>and</strong> source for the <strong>BalanceNG</strong> agent<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 15 / 143
Additional directories of the distribution are:bngagent-binariesbngfilt-binariescontribPrecompiled bngagent binaries for different platformsSolaris bngfilt STREAMS module binariesCustomer contributions without warranty <strong>and</strong> supportNote: The distribution may contain additional directories <strong>and</strong> files which are not mentionedhere.The executable “bng” should be copied to a suitable location. Since <strong>BalanceNG</strong> is init-scriptcompatible we recommend to copy it to /etc/init.d, the default location for init scripts, asfollows:# cp ./<strong>BalanceNG</strong>-1.840/bng /etc/init.dFinally you could verify the modes <strong>and</strong> ownership which should be as follows:# ls -l /etc/init.d/bng-rwxr-xr-x 1 root root 214268 Apr 2 22:07 /etc/init.d/bng#NOTE: 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.2.4 Making <strong>BalanceNG</strong> Turnkey2.4.1 Making <strong>BalanceNG</strong> Turnkey on SolarisThere are no further actions required on Solaris, the /etc/init.d/-Scripts are all setup.<strong>BalanceNG</strong> is started during reboot if a configuration file is present in /etc/bng.conf .2.4.2 Making <strong>BalanceNG</strong> Turnkey on LinuxIf you wish to have <strong>BalanceNG</strong> started automatically at system boot (Turnkey), you mustconfigure your system to execute “bng start” on boot.The st<strong>and</strong>ard method is to provide a link from the binary “bng” wherever it is located to therequired run-level directory. This is normally achieved as follows:• Linking /etc/init.d/bng to a run-level directory <strong>and</strong> name, for example on a Fedora 3release "ln -s /etc/init.d/bng /etc/rc5.d/S11bng".Some Linux distributions do not support this method, please see table below, or refer to yourdistribution's documentation.In the Linux realm we recommend the following:LinuxDistributionGentoo LinuxNotesinstalling binary in /usr/sbinadding the line "/usr/sbin/bng start" to /etc/init.d/local.startadding the line "/usr/sbin/bng stop" to /etc/init.d/local.stopDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 16 / 143Grünwald Germany / All Rights Reserved
LinuxDistributionNotesFedora LinuxRedhat LinuxDevilLinuxst<strong>and</strong>ard methodst<strong>and</strong>ard methodst<strong>and</strong>ard methoddon't forget to invoke "save-config" saving to configuration mediaDebian LinuxUbuntu Linuxst<strong>and</strong>ard methodst<strong>and</strong>ard methodTable 1: Turnkey Installation Notes2.5 Determining the Nodeid <strong>and</strong> LicensingTo obtain a full license for <strong>BalanceNG</strong> you require the nodeid of your hardware. The nodeid isa 6 byte hexadecimal number similar to an Ethernet address (the actual nodeid is derived fromseveral system parameters: The MAC address of Ethernet interface 0 (eth0), CPU <strong>and</strong> PCIbusparameters).To determine the nodeid of your installation:Start <strong>BalanceNG</strong>:# bng start<strong>BalanceNG</strong>: starting up ...#<strong>Open</strong> the interactive mode of <strong>BalanceNG</strong> using:# bng control<strong>BalanceNG</strong>: connected to PID 8692bng#Enter the comm<strong>and</strong> to display the nodeid of the current machine:bng# show nodeidba:e9:75:26:36:abbng#Note that the nodeid of all instances is the same. Retrieving the nodeid of instance 2 looks likethis:# bng start 2<strong>BalanceNG</strong>: starting up instance 2 ...#<strong>Open</strong> the interactive mode of <strong>BalanceNG</strong> using:# bng control 2<strong>BalanceNG</strong>: connected to instance 2 PID 27816bng#Enter the comm<strong>and</strong> to display the nodeid of the current <strong>BalanceNG</strong> instance 2:bng# show nodeid<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 17 / 143
a:e9:75:26:36:abbng#This allows you to use the same licensing key for all instances, currently there's a theoreticallimit of 128 concurrent <strong>BalanceNG</strong> instances on the same host machine.When you receive the license key(s) for your node(s), use the “license” comm<strong>and</strong> on eachnode to apply the relevant license. Use the “save” comm<strong>and</strong> to save the license informationto /etc/bng.conf. An example license session is shown below:# bng control<strong>BalanceNG</strong>: connected to PID 8692bng# license betaB048 45f296fc9b387f7576b49d0ceab3f92ebng# show licensestatus: valid full licenseserial: betaB048nodeid: 2a:e2:9f:38:da:20type "show version" for version <strong>and</strong> Copyright informationbng# saveokbng# ... byeNow your <strong>BalanceNG</strong> installation is fully licensed <strong>and</strong> ready for operation.2.6 “Basic license” restrictionsYou may use <strong>BalanceNG</strong> for an evaluation for an unlimited <strong>and</strong> unspecified period of time(please check the LICENSE file or the license on the <strong>BalanceNG</strong> web site).For this “Basic License” the following restrictions are enforced:• You may only specify <strong>and</strong> activate ONE virtual server (server 1) for testing load balancingfeatures (The fully licensed <strong>BalanceNG</strong> supports up to 512 virtual servers).• You may only specify <strong>and</strong> activate TWO targets for testing load balancing features (Thefully licensed <strong>BalanceNG</strong> supports up to 1024 targets / real servers).• VRRP (Virtual Router Redundancy Protocol) High Availability functions are disabled.There are free advanced dual node test licenses available which enable VRRP <strong>and</strong> allowunrestricted number of servers <strong>and</strong> targets. Please consult the <strong>BalanceNG</strong> web site(http://www.<strong>BalanceNG</strong>.net) for details.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 18 / 143Grünwald Germany / All Rights Reserved
3 Comm<strong>and</strong> Reference3.1 Comm<strong>and</strong> Line InterfaceThe Comm<strong>and</strong> Line Interface is designed in such a way, that <strong>BalanceNG</strong> may be directlylinked as an init-Script e.g. from /etc/init.d/bng -> /etc/rc5.d/S90bng. There is noneed to implement additional init scripts.The <strong>BalanceNG</strong> binary is called "bng" <strong>and</strong> should be installed in /etc/init.d (anotherpossibility is installing it to /usr/sbin linked to /etc/init.d).Invoking <strong>BalanceNG</strong> requires root permissions (euid == 0) since <strong>BalanceNG</strong> has to be ableto directly control the network interfaces.3.1.1 bngInvoking <strong>BalanceNG</strong> with no option displays the usage information together with someCopyright information.Example:# /etc/init.d/bng______ __ _______ _______| __ \.---.-.| |.---.-.-----.----.-----.| | | __|| __
## /etc/init.d/bng start 41<strong>BalanceNG</strong>: starting up instance 41 ...#If there's already a <strong>BalanceNG</strong> running on this machine the output may look like as follows:Example:# /etc/init.d/bng start<strong>BalanceNG</strong>: already running with PID 7914#3.1.3 bng stop [instance]This stops the current running <strong>BalanceNG</strong> process (or the specified instance), the output maylook like this:Example:# /etc/init.d/bng stop<strong>BalanceNG</strong>: shutdown of PID 7914 complete## ./bng stop 41<strong>BalanceNG</strong>: shutdown of instance 41 PID 27231 complete#3.1.4 bng restart [instance]This restarts <strong>BalanceNG</strong> (or the specified instance) <strong>and</strong> is equivalent to execute "bng stop"<strong>and</strong> "bng start" .Example:# /etc/init.d/bng restart<strong>BalanceNG</strong>: shutdown of PID 7919 complete<strong>BalanceNG</strong>: starting up ...## /etc/init.d/bng restart 41<strong>BalanceNG</strong>: shutdown of instance 41 PID 27419 complete<strong>BalanceNG</strong>: starting up instance 41 ...#3.1.5 bng status [instance]This provides information about the current status of <strong>BalanceNG</strong> (or the specified instance).Example:# /etc/init.d/bng status<strong>BalanceNG</strong>: running with PID 7921# /etc/init.d/bng stop<strong>BalanceNG</strong>: shutdown of PID 7921 completeDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 20 / 143Grünwald Germany / All Rights Reserved
# /etc/init.d/bng status<strong>BalanceNG</strong>: not running## /etc/init.d/bng status 41<strong>BalanceNG</strong>: instance 41 running with PID 27423# /etc/init.d/bng stop 41<strong>BalanceNG</strong>: shutdown of instance 41 PID 27423 complete# /etc/init.d/bng status 41<strong>BalanceNG</strong>: instance 41 not running#3.1.6 bng control [instance]This invokes the interactive configuration mode of <strong>BalanceNG</strong> (or the instance if specified).The shell invocation “bng control” may be abbreviated as “bng ctl”.This is indicated by a prompt, the default is: "bng#".Example:# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 7928bng## /etc/init.d/bng restart 41<strong>BalanceNG</strong>: not yet running<strong>BalanceNG</strong>: starting up instance 41 ...# /etc/init.d/bng control 41<strong>BalanceNG</strong>: connected to instance 41 PID 27479bng#Typing EOF (Ctrl-D) exits the interactive configuration mode.The interactive configuration mode allows simple comm<strong>and</strong> line editing using the arrow-keys.This is only active is an interactive terminal is detected on stdin, otherwise the comm<strong>and</strong> lineediting option is switches off to allow automated programs to operate on the comm<strong>and</strong> line.The following comm<strong>and</strong> line editing capabilities are currently supported:arrow uparrow downarrow leftarrow rightbackspace, ^H or DEL^D^U^Wmove up to previous comm<strong>and</strong> linemove down to next comm<strong>and</strong> line in historymove cursor leftmove cursor rightdelete character before cursorexit to operating system shellerase all characters left of cursorerase word left of cursor<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 21 / 143
If the lexical scanning process finds the token "//" this token <strong>and</strong> the rest of the line is ignored(this is being used for adding timestamps <strong>and</strong> version stamps to the configuration file).It's also possible to pipe a comm<strong>and</strong> into <strong>BalanceNG</strong> invoked with "bng control" like this:# echo "show targets" | bng controlbng# show targets# ipaddr port prt net srv sessions status name--------------------------------------------------------------------------1 172.17.2.90 any any 1 1 0 operationalbng##In general comm<strong>and</strong>s may be abbreviated interactively as long as there are no ambiguities.3.1.7 bng auxctl [instance]This connects to a second, auxiliary control interface of the instance if specified. This interfaceis intended to be reserved for external programs <strong>and</strong> user interfaces offering exactly the samefunctionality as “bng control”.3.2 Administrative <strong>and</strong> Informational Comm<strong>and</strong>s3.2.1 benchmarkSynopsis:benchmark This comm<strong>and</strong> executes a hardware, OS <strong>and</strong> network benchmark in the backgroundcontrolled by the parameters “bmduration”, “bmpsize” <strong>and</strong> “bmwsize” (see “set” comm<strong>and</strong>below). The results <strong>and</strong>/or status can be shown with “show benchmark”.Example:bng# benchmark eth0 eth1bng# show benchmarkbenchmark active <strong>and</strong> running:duration (seconds) : 300packetsize : 1514window size : 16packets sent : 212921packets received : 212905seconds remaining : 294bng# show benchmarkbenchmark finished with the following results:duration (seconds) : 300packetsize : 1514window size : 16packets sent : 10797158packets received : 10797142lost packets : 0packets per second : 35990bytes per second : 54489577bng#Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 22 / 143Grünwald Germany / All Rights Reserved
3.2.2 checkSynopsis:checkA check of the current active configuration is performed. This is especially targeted towardsthe configuration of Servers <strong>and</strong> 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 allThis function is implicitly called when Servers or Targets are entering the enabled state.Example (no Warning):bng1# checkbng1#Example (with Warnings):bng1# checkWARNING: target 1 already referenced from server 1WARNING: target 1 reference from server 8 ignoredWARNING: target 2 already referenced from server 1WARNING: target 2 reference from server 8 ignoredbng1#3.2.3 helpSynopsis:helpDisplays the main help information about available comm<strong>and</strong>s.Example:bng# helparp benchmark checkcommit disable dump edit enable gateway gateway ipaddr helphelp hostname interface l2switchlicense network no register remark saveserver sessiondump set show shutdowndeclare IP address to be ARP-resolvedperform <strong>BalanceNG</strong> loopback benchmarkperform configuration checkregister <strong>and</strong> enable networks/servers/targetsdisable networks/servers/targetspcap dump traffic on to disable+unregister networks/servers/targetsenable networks/servers/targetsspecify default gateway ipaddress (old syntax)specify default gateway ipaddressdisplay this informationdisplay topic specific information, ? for listspecify name of this <strong>BalanceNG</strong> instancemake interface available for <strong>BalanceNG</strong>enable layer 2 switchingspecify serno <strong>and</strong> license keymodify network , see "help network"revert comm<strong>and</strong>register networks/servers/targetsspecify configuration remarkssave current configurationmodify server , see "help server"dump all sessions to fileset parameter to specific valueshow item, show ? for item listalias for stop<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 23 / 143
snapshot collect all relevant service data in filesoftdisable target don't create new sessions for target(s)stopstop background process <strong>and</strong> exittarget modify target , see "help target"tnat target NAT for outbound communicationsunregister unregister networks/servers/targetsvip represent VIP using ARPvrrp vrrp settings, see "help vrrp"bng#3.2.4 help Synopsis: help Displays subtopic based help information.Example:bng# help ?available help topics:? show this list of available help topicsvrrpvrrp comm<strong>and</strong>snetworknetwork comm<strong>and</strong>sgatewaydefault gateway comm<strong>and</strong>sservervirtual server comm<strong>and</strong>sshowinformation about items to showtargettarget (real server) comm<strong>and</strong>scleditcomm<strong>and</strong> line editing functionalitybng# help vrrpvrrp bscript specify BACKUP state notify scriptvrrp mscript specify MASTER state notify scriptvrrp network specify network for advertisementsvrrp network noneremove network declarationvrrp priority specify vrrp priorityvrrp priority noneremove vrrp priorityvrrp tracking enableenable vrrp trackingvrrp tracking disabledisable vrrp tracking (default)vrrp tracking defaultset vrrp tracking to default (disabled)vrrp vrid specify vrrp virtual router idvrrp vrid noneremove vrrp vridbng# help networknetwork addr specify network addressnetwork interface [,] specify one or more interfacesnetwork interface none remove all interface declarationsnetwork mask specify network masknetwork name "name" specify network namenetwork nat insidedeclare network to be nat insidenetwork nat outside declare network to be nat outsidenetwork nat offdeclare network not to participate in natnetwork real specify service address (ARP, VRRP)network virt specify virtual address (routing dest.)bng# help gatewaygateway alert specify gateway alert notification scriptgateway arp ,perform arp healthcheck (ival,tout)gateway arp offdisable arp healthcheckgateway ipaddr specify default gateway ip addressgateway ping ,perform ping healthcheck (ival,tout)gateway ping offdisable ping healthcheckgateway trackval specify tracking value for gateway (default=0)gateway trackval default reset gateway tracking value to default (0)gateway upalert specify gateway upalert notification scriptno gatewayremove gateway declarationbng# help serverserver backup specify one single backup targetserver backups ,... specify multiple backup targetsserver backup noneremove all backup target declarationsserver failover normal enable normal failover h<strong>and</strong>ling (default)server failover backup enable backup failover h<strong>and</strong>lingserver ipaddr specify virtual server ip address (any=LLB)server method agent use agent feedback distributionserver method bwuse least total b<strong>and</strong>width distributionDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 24 / 143Grünwald Germany / All Rights Reserved
server method bwinuse least incoming b<strong>and</strong>width distributionserver method bwout use least outgoing b<strong>and</strong>width distributionserver method hashuse hash based distributionserver method r<strong>and</strong>om use r<strong>and</strong>om distributionserver method rruse round robin distribution (default)server method session use least session distributionserver name "name"specify server nameserver name ""remove server name (set to empty)server plugin "comm<strong>and</strong>" specify external server pluginserver plugin ""delete server plugin (set to empty)server port specify port (default=0, all ports)server ports , specify two related server portsserver portrel onenable port relevance for sessionsserver portrel offdisable port relevance for sessions (default)server protocol any enable any protocol for server (default)server protocol tcp restrict server operation to tcpserver protocol udp restrict server operation to udpserver stimeout set server specific session timeout (seconds)server stimeout default disable server specific session timeoutserver target specify one single targetserver targets ,... specify multiple targets for serverserver target noneremove all target declarations from serverbng# help showshow arphashshow arp hashtableshow benchmarkshow benchmark status <strong>and</strong> resultsshow confshow current configurationshow gatewayshow gateway info <strong>and</strong> statusshow ifstatshow interface statisticsshow instanceshow current instance numbershow interfacessame as ifstatshow licenseshow license informationshow logshow recent log messagesshow machashshow learned mac addressesshow natshow network address translationsshow networksshow specified networksshow network show network informationshow nodeidshow licensing nodeidshow parametersshow settable parameter datashow server show status of server show serversshow server overviewshow sessionsshow session table informationshow stinfoshow session hashtable informationshow targetsshow target overviewshow target show status of target show uptimeshow uptime in secondsshow vipsshow vips <strong>and</strong> their mac-addressesshow versiondisplay version informationshow vrrpdisplay VRRP statusbng# help targettarget agent ,, perform agent operation (port,ival,tout)target agent offremove/disable agent operationtarget alert specify external alert scripttarget alert nonedisable/remove external alert scripttarget dsr enableenable direct server return operationtarget dsr disabledisable direct server return operationtarget ipaddr specify target ip addresstarget maxagent specify maximum agent return value, 0=no limittarget maxsessions specify maximum number of sessions, 0=no limittarget name "name"specify target nametarget name ""remove target name (set to empty)target offset specify linear modification offset (default=0)target ping , perform ping healthcheck (ival,tout)target ping offremove/disable ping healthchecktarget port specify target port (0=default)target protocol any accept all protocols (default)target protocol tcp accept tcp onlytarget protocol udp accept udp onlytarget scale specify linear modif. scale (default=1.0)target script ,, call external healthcheck script (ival,tout)target script offdisable/remove external healthcheck scripttarget tcpopen ,, perform tcpopen healthcheck (port,ival,tout)target tcpopen offremove/disable tcpopen healthchecktarget trackval assign target tracking value (default=0)target trackval default set target tracking value to default (0)target upalert specify external upalert script<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 25 / 143
target upalert nonetarget weight bng# help cleditarrow uparrow downarrow leftarrow rightbackspace, ^H or DEL^D^U^Wbng#disable/remove external upalert scriptspecify weight for r<strong>and</strong>om method, 1=defaultmove up to previous comm<strong>and</strong> linemove down to next comm<strong>and</strong> line in historymove cursor leftmove cursor rightdelete character before cursorexit to operating system shellerase all characters left of cursorerase word left of cursor3.2.5 saveSynopsis:saveThis saves the current configuration (as shown by "show conf") to the configuration file of<strong>BalanceNG</strong> in /etc/bng.conf .Example:bng# saveokbng#3.2.6 sessiondumpSynopsis:sessiondump The comm<strong>and</strong> dumps the complete session table information into the specified file in asciireadable text format (as displayed by the “show sessions” comm<strong>and</strong>).Note: During the dumping process the internal packet forwarding mechanism is paused, whichmay cause a noticeable delay of packet processing at very large session tables.Example:bng@testnode# sessiondump /tmp/test.txtdumping 17 sessions to /tmp/test.txt ...... done.bng@testnode# ... byetestnode# cat /tmp/test.txthash ip-address port srv tgt age stout-------- --------------- ----- --- --- ---- -------7479774 172.17.2.4 32823 4 1 33 1200007479773 172.17.2.4 32822 4 1 34 1200007479772 172.17.2.4 32821 4 1 34 1200007479771 172.17.2.4 32820 4 1 34 1200007479770 172.17.2.4 32819 4 1 34 1200007479769 172.17.2.4 32818 4 1 35 1200007479768 172.17.2.4 32817 4 1 35 1200007479767 172.17.2.4 32816 4 1 35 1200007479766 172.17.2.4 32815 4 1 36 1200007479765 172.17.2.4 32814 4 1 36 1200007479764 172.17.2.4 32813 4 1 36 1200007479763 172.17.2.4 32812 4 1 37 1200007479762 172.17.2.4 32811 4 1 37 1200007479761 172.17.2.4 32810 4 1 38 1200007479760 172.17.2.4 32809 4 1 38 120000Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 26 / 143Grünwald Germany / All Rights Reserved
7479759 172.17.2.4 32808 4 1 39 1200007475751 172.17.2.4 32901 4 1 60 120000testnode#3.2.7 showSynopsis:show The comm<strong>and</strong> show displays various informations about the current running <strong>BalanceNG</strong>process.3.2.7.1 show ?Synopsis: show ?This informational comm<strong>and</strong> displays which items may be specified using the show comm<strong>and</strong>(replacing the ?).Example:bng# show ?show arphashshow benchmarkshow confshow gatewayshow ifstatshow instanceshow interfacesshow licenseshow logshow machashshow natshow networksshow network show nodeidshow parametersshow server show serversshow sessionsshow stinfoshow targetsshow target show uptimeshow vipsshow versionshow vrrpbng#3.2.7.2 show arphashSynopsis:show arphashshow arp hashtableshow benchmark status <strong>and</strong> resultsshow current configurationshow gateway info <strong>and</strong> statusshow interface statisticsshow current instance numbersame as ifstatshow license informationshow recent log messagesshow learned mac addressesshow network address translationsshow specified networksshow network informationshow licensing nodeidshow settable parameter datashow status of server show server overviewshow session table informationshow session hashtable informationshow target overviewshow status of target show uptime in secondsshow vips <strong>and</strong> their mac-addressesdisplay version informationdisplay VRRP statusDisplays the current ARP hash of <strong>BalanceNG</strong>. The output consists of several columns: TheIP-address, the MAC address (00:00:00:00:00:00 if not yet resolved) <strong>and</strong> several flags.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 27 / 143
Static entries are usually self generated <strong>and</strong> maintained entries (like <strong>BalanceNG</strong> virtualservers), dynamic entries are usually <strong>BalanceNG</strong> targets.Example:bng1# show arphashipaddr ethaddr tgt net cntr age flags--------------- ----------------- ---- --- ----- ----- -----------172.17.2.61 06:00:ac:11:02:3d - 1 - - vip fix172.17.2.64 00:00:5e:00:01:0e - 1 - - vip172.17.2.91 00:e0:81:5d:2a:65 1 - 203 192bng1#3.2.7.3 show benchmarkSynopsis:show benchmarkDisplays the current benchmark status <strong>and</strong> the results (if finished).Example:bng# show benchmarkbenchmark active <strong>and</strong> running:duration (seconds) : 300packetsize : 1514window size : 16packets sent : 212921packets received : 212905seconds remaining : 294bng# show benchmarkbenchmark finished with the following results:duration (seconds) : 300packetsize : 1514window size : 16packets sent : 10797158packets received : 10797142lost packets : 0packets per second : 35990bytes per second : 544895773.2.7.4 show confSynopsis:show confDisplays the current active configuration of <strong>BalanceNG</strong> as it would be saved to"/etc/bng.conf" using the save comm<strong>and</strong>.Example:bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 28 / 143Grünwald Germany / All Rights Reserved
mask 255.255.255.0real 10.2.2.20virt 10.2.2.30interface eth0}register network 1enable network 1// end of configurationbng#3.2.7.5 show conf Synopsis:show conf This comm<strong>and</strong> displays specific sections of the configuration file intended for automaticaccess by programs layered on top of <strong>BalanceNG</strong> (like Web-UI's). Currently supportedsections by this comm<strong>and</strong> are “gateway”, “vrrp” <strong>and</strong> “parameters”.Example:# bng control<strong>BalanceNG</strong>: connected to PID 15873NodeA# show gatewayipaddr: 172.17.2.254total status: operationalNodeA# show conf gatewaygateway {ipaddr 172.17.2.254}NodeA# show conf vrrpvrrp {vrid 14priority 200network 1tracking enablemscript "/usr/bin/logger -p daemon.notice VRRP MASTER"bscript "/usr/bin/logger -p daemon.notice VRRP BACKUP"}NodeA# show conf parametersset {vrrppreempt 1localdsr 1}NodeA#3.2.7.6 show gatewaySynopsis:show gatewayDisplays informations about the gateway <strong>and</strong> its current state (see "gateway" setupcomm<strong>and</strong>s).Example:<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 29 / 143
ng# show gatewayipaddr: 172.17.2.254total status: operationalping status: uptrackval: 4bng#3.2.7.7 show ifstatSynopsis:show ifstatDisplays informations about the Ethernet interfaces which are currently under control of<strong>BalanceNG</strong>.The following data is shown:• 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 tothe current active dump file (see the dump comm<strong>and</strong>). This is being used to trigger automaticdumpfile rotation as soon as this number of bytes exceeds the parameter dumprotation(see also the set comm<strong>and</strong> for more informations about parameters).Example:bng1# show ifstatinterface eth0received:packets 269bytes 26177sent:packets 8bytes 350dumped:bytes 0interface eth1received:packets 182bytes 15083sent:packets 446bytes 33736dumped:bytes 0bng1#Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 30 / 143Grünwald Germany / All Rights Reserved
3.2.7.8 show instanceSynopsis:show instanceThis shows the number of the current <strong>BalanceNG</strong> instance.# bng start 41<strong>BalanceNG</strong>: starting up instance 41 ...# bng control 41<strong>BalanceNG</strong>: connected to instance 41 PID 27231bng# show instancethis is <strong>BalanceNG</strong> instance 41bng#3.2.7.9 show interfacesSynopsis:show interfacesThis is a synonym <strong>and</strong> equivalent to "show ifstat".3.2.7.10 show licenseSynopsis:show licenseThis shows the current licensing status of <strong>BalanceNG</strong> on the current host machine (node). Ifthe current configuration contains a valid license for the nodeid of the machine then the outputcould look like follows:bng# show licensestatus: valid full licenseserial: TEST0611021nodeid: 2a:e2:9f:38:da:20type "show version" for version <strong>and</strong> Copyright informationbng#An unspecified license information or an invalid license key shows up as follows:bng# show licensestatus: no or invalid license, trial restrictions applynodeid: 2a:e2:9f:38:da:20type "show version" for version <strong>and</strong> Copyright informationbng#A automatic OEM licensing on specific OEM hardware looks like this:bng# show licensestatus: valid full OEM licensenodeid: 2a:e2:9f:38:da:20type "show version" for version <strong>and</strong> Copyright informationbng#There's the possibility to obtain promotional full licenses. This license allows testing of VRRP<strong>and</strong> allows unrestricted number of virtual servers. This license could show up as follows:test# show licensestatus: valid testing license (will terminate in 93 minutes)serial: TEST123/1.770nodeid: 2a:e2:9f:38:da:20type "show version" for version <strong>and</strong> Copyright information<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 31 / 143
test#The license configuration is at the top in the configuration output or file (after "hostname" <strong>and</strong>"remark" entries if present). See the license <strong>and</strong> nodeid configuration comm<strong>and</strong> for furtherreference.3.2.7.11 show logSynopsis:show logDisplays the most recent log messages as they have been sent to the syslog. Up to 20 logmessages are stored in a cyclic buffer.Errors found in the initial startup file (/etc/bng.conf) are also reported to the syslog <strong>and</strong> may bedisplayed here for further analysis.Example:bng1# show log2007/10/11 21:25:18 6 main interface is bge02007/10/11 21:25:18 6 <strong>BalanceNG</strong> 1.672: starting background operation2007/10/11 21:25:18 6 loading /etc/bng.conf2007/10/11 21:25:18 6 configuration taken Sun Oct 1 15:58:39 20072007/10/11 21:25:18 6 configuration saved by <strong>BalanceNG</strong> 1.643 (created 2007/10/01)2007/10/11 21:25:18 5 this virtual router is now BACKUP2007/10/11 21:25:18 6 /etc/bng.conf successfully loaded2007/10/11 21:25:22 5 this virtual router is now MASTER2007/10/11 21:25:24 5 target 1 operationalbng1#3.2.7.12 show machashSynopsis:show machashDisplays the learned MAC addresses <strong>and</strong> their associated interfaces. For security reasons<strong>BalanceNG</strong> restricts the amount of different MAC addresses to 10000 (<strong>and</strong> will stop anyfurther learning in that case).If the MAC address belongs to a target the target number is show in the “tg” column of theoutput.Example:bng# show machashethaddrtg ifc----------------- -- ----00:04:13:25:06:97 bge000:0a:8a:f8:cb:01 bge000:14:4f:48:82:50 bge000:04:13:22:1b:03 bge000:14:bf:66:70:36 bge000:00:5e:00:01:09 bge000:0c:f1:9c:90:e8 bge000:14:38:95:7a:04 bge006:00:ac:11:02:54 bge000:0b:82:00:a8:fe bge000:20:e0:69:ad:4c bge000:11:50:c3:54:ce bge0Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 32 / 143Grünwald Germany / All Rights Reserved
00:e0:81:5d:2a:65 bge000:02:2d:15:ac:53 bge000:04:13:25:06:96 bge000:40:63:c9:f5:b5 bge000:0e:0c:6c:ba:59 1 bge0bng#3.2.7.13 show natSynopsis:show natDisplays the current active NAT table contents (Network Address Translation). The NAT tablecontains separate entries for TCP <strong>and</strong> UDP network address translations.Examples:bng# show natTCP: 0 entriesUDP: 0 entriesbng#bng# show natTCP: 1 entryip-address iport oport age--------------- ----- ----- ----172.17.2.4 32853 20012 3UDP: 2 entriesip-address iport oport age--------------- ----- ----- ----172.17.2.4 32768 20573 3172.17.2.4 123 20572 159bng#3.2.7.14 show nodeidSynopsis:show nodeidDisplay the nodeid of the current <strong>BalanceNG</strong> instance, which is a 6 byte identification beingrepresented in Ethernet address format. This nodeid is being used to identify the <strong>BalanceNG</strong>instance for licensing purposes.The nodeid is derived from the Ethernet address of the eth0 interface, the instance number<strong>and</strong> other system parameters.Example:bng# show nodeid13:e3:ac:12:9d:47bng#The nodeid can change due to hardware replacement or extensions (e.g. due Ethernetinterface "reordering"). Please goto http://www.inlab.de for further licensing information <strong>and</strong>relicensing procedures.Note: Each <strong>BalanceNG</strong> instance has a separate <strong>and</strong> different nodeid.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 33 / 143
See also "license" <strong>and</strong> "show license".3.2.7.15 show parametersSynopsis:show parametersThis shows the settable parameter of <strong>BalanceNG</strong>. Please see the set comm<strong>and</strong> for detailedparameter explanations.Example:bng# show parametersname min max default current-------------- ---------- ---------- ---------- ----------sendprobes 0 1 0 0dumprotation 1 1048576 1024 1024arplookup 5 60 10 10arprefresh 60 3600 300 300arptimeout 0 86400 0 0hcportoffset 1024 65535 30000 30000vrrppreempt 0 1 0 1vrrpmasterdown 3 10 3 3gratarpremind 0 120 0 0ipforwarding 0 1 0 0sessiontimeout 10 172800 600 600sessionscan 1 20 10 10sessionsync 0 1 1 1sessionsynciv 10 120 10 10sessiondlimit 10 1000 10 10bmduration 10 3600 300 300bmpsize 20 1514 1514 1514bmwsize 1 100 16 16nattimeout 10 172800 600 600natscan 1 20 10 10natsync 0 1 1 1natsynciv 10 120 10 10natdlimit 10 100 10 10localdsr 0 1 0 1localvirt 0 1 0 0debugscope 0 2 0 0Each parameter has a predefined minimum, maximum <strong>and</strong> default value. The NAT-specificparameters are currently not used <strong>and</strong> for future releases of <strong>BalanceNG</strong>.3.2.7.16 show server Synopsis:show server Shows information about one particular server <strong>and</strong> its current state.Example:bng# show server 1server 1ipaddr 10.55.55.222Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 34 / 143Grünwald Germany / All Rights Reserved
network 1port anyprotocol anystatus enabledmethod rrportrel ontargets 1,(5)bng#3.2.7.17 show serversSynopsis:show serversThis shows an overview of configured servers <strong>and</strong> their current state including the states ofthe associated targets.A target or backup target as a number is operational according to it's health checks, a targetor backup target in round parentheses is not available due to health check failures, a target orbackup target in square brackets is disabled by purpose.Only enabled <strong>and</strong> previously registered server definitions are shown.Example:bng# show servers# ipaddr port prt net S targets {backups}------------------------------------------------------------1 10.55.55.222 any any 1 e 1,2,3,4,(5),[6] {}2 10.55.55.226 any any 1 e 8,9,(10),(11) {20}bng#In this example targets 1,2,3 <strong>and</strong> 4 of server 1 are operational. The health checks of target 5are failing <strong>and</strong> target 6 is disabled.Target 8 <strong>and</strong> 9 of server 2 are operational, 10 <strong>and</strong> 11 have currently failing health checks.There's an operational backup target 20 available which would be addressed as soon asthere's no ordinary target available.3.2.7.18 show sessionsSynopsis:show sessions []Information about current active sessions is displayed.The number of active sessions is displayed together with the first ten active sessions (whichare usually the latest ones).It is normal for the session tables to become very huge. The session table entry timeout isstored with each session table entry (column “stout”).An optional second argument restricts the output to the specified IP address. The number ofdisplayed session table entries is restricted by the “sessiondlimit” parameter.bng# show sessions5 sessionshash ip-address port srv tgt age stout-------- --------------- ----- --- --- ---- -------<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 35 / 143
12197156 10.55.55.12 51296 1 1 969 60011951140 10.55.55.12 51295 1 4 969 60011705124 10.55.55.12 51294 1 3 957 60011459108 10.55.55.12 51293 1 2 970 60011213092 10.55.55.12 51292 1 1 970 6ßßbng#bng@testnode# show sessions 172.17.2.4hash ip-address port srv tgt age stout-------- --------------- ----- --- --- ---- -------7479774 172.17.2.4 32823 4 1 548 1200007479773 172.17.2.4 32822 4 1 549 1200007479772 172.17.2.4 32821 4 1 549 1200007479771 172.17.2.4 32820 4 1 549 1200007479770 172.17.2.4 32819 4 1 549 1200007479769 172.17.2.4 32818 4 1 550 1200007479768 172.17.2.4 32817 4 1 550 1200007479767 172.17.2.4 32816 4 1 550 1200007479766 172.17.2.4 32815 4 1 551 1200007479765 172.17.2.4 32814 4 1 551 1200007479764 172.17.2.4 32813 4 1 551 120000... remaining sessions not shownbng@testnode#3.2.7.19 show stinfoSynopsis:show stinfoDisplays information about the infernal session hashtable. Session entries are pre-allocated inchunks, the number of current allocated chunks is displayed. The maximum length of bucketlist entries should be minimal.Example:bng# show stinfocurrent number of sessions: 13411allocated 1 chunks of 65536 entriesmaximum length of bucket list: 13.2.7.20 show targetsSynopsis:show targetsDisplays information about current registered <strong>and</strong> enabled targets <strong>and</strong> their current healthcheck status.Example:bng1# show targets# ipaddr port prt net srv sessions status name--------------------------------------------------------------------------1 172.17.2.90 80 tcp 1 1 1288 operational2 172.17.2.91 80 tcp 1 1 1311 operational3 172.17.2.92 80 tcp 1 1 1301 operational4 172.17.2.93 80 tcp 1 1 1291 operationalDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 36 / 143Grünwald Germany / All Rights Reserved
3.2.7.21 show target Synopsis:show target Displays more detailed information about one specific target.Example:bng# show target 1target 1status operational (arp:up,script:up)ipaddr 172.17.2.91port anynetwork 1protocol anysessions 0trackval 20psent 0bsent 0prcvd 17brcvd 4862bwin 0bwout 0bw 0bng#3.2.7.22 show targetregistrySynopsis:show targetregistryDisplays more detailed information about current registered targets <strong>and</strong> their current healthcheck status. This is a view from the internal target registry indented for debugging purposes.This comm<strong>and</strong> is usually not needed <strong>and</strong> therefor not included in the output of the "help"comm<strong>and</strong>.Example:bng# show targetregistrytarget 2ipaddr 172.17.2.5port anynetwork 1protocol anystatus downarp upagent downtarget 1ipaddr 172.17.2.4port anynetwork 1protocol anystatus downarp upagent downbng#<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 37 / 143
3.2.7.23 show uptimeSynopsis:show uptimeDisplay the uptime of the currently running <strong>BalanceNG</strong> process in seconds.Example:bng# show uptimecurrent uptime is 10812 secondsbng#3.2.7.24 show vipsSynopsis:show vipsDisplays current configured virtual IP addresses, their associated Ethernet addresses <strong>and</strong> theassociated network.Example:bng1# show vipsipaddr ethaddr n-----------------------------------10.1.1.100 06:00:0a:01:01:64 210.55.55.222 00:00:5e:00:01:01 110.55.55.221 00:00:5e:00:01:01 110.55.55.220 06:00:52:81:05:dc 110.55.55.230 00:00:5e:00:01:01 110.55.55.234 00:00:5e:00:01:01 110.1.1.254 00:00:5e:00:01:01 2bng1#3.2.7.25 show versionSynopsis:show versionDisplay the current version / release of this <strong>BalanceNG</strong> process.Example:bng# show version______ __ _______ _______| __ \.---.-.| |.---.-.-----.----.-----.| | | __|| __
3.2.7.26 show vrrpSynopsis:show vrrpDisplays the current VRRP configuration <strong>and</strong> the current state of the VRRP node (as definedin rfc3768 with an additional "OFF"-State when deactivated).Example 1 (node is master for 2 virtual addresses):bng# show vrrpstate MASTERvrid 1priority 200ip00 10.2.2.3ip01 10.2.2.4Example 2 (vrrp is not active):bng# show vrrpstate OFFExample 3 (node is backup for 2 virtual addresses):bng# show vrrpstate BACKUPvrid 1priority 200ip00 10.2.2.3ip01 10.2.2.43.2.8 shutdownSynopsis:shutdownThis is an alias for "stop.3.2.9 snapshotSynopsis:snapshot This comm<strong>and</strong> collects various important system data in text format into the supplied file. Thisfile is intended to be sent to support staff for in detail analysis in case of problems.Example:bng# snapshot /tmp/snapshot.txtcollecting OS data ...... done.dumping configuration ...... done.collecting BNG data ...... done.dumping sessiontable ...... done.bng#3.2.10 stopSynopsis:stop<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 39 / 143
Immediately stops the <strong>BalanceNG</strong> program. This has the same effect as "bng stop" on thecomm<strong>and</strong> line. There's no additional confirmation required.Example:bng# stopok<strong>BalanceNG</strong>: no peer available#3.3 Configuration Comm<strong>and</strong>sThe comm<strong>and</strong> described in this chapter are actually changing the current configuration of<strong>BalanceNG</strong> immediately.Some comm<strong>and</strong>s are revertable using the "no" special comm<strong>and</strong>.3.3.1 arpSynopsis:[no] arp This comm<strong>and</strong> 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 comm<strong>and</strong> line with the "no" prefix.If the mac address is unknown, the retrieval will be tried all "arplookup" seconds (default 10seconds). See also parameter summary at the set comm<strong>and</strong>.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 <strong>and</strong> enabled) an implicit (<strong>and</strong> invisible) arpcomm<strong>and</strong> line is inserted for the target ip address into the running configuration.A target always has an implicit "base" ARP health check, which times out after "arptimeout"seconds (default 0, which disables this permanent healthcheck).ARP requests are being issued on all associated interfaces with an anonymous IP-<strong>Source</strong>address per default.Note: You usually don't have to enter arp comm<strong>and</strong> lines into the configuration, the requiredadministrative ARP resolving for targets <strong>and</strong> Servers is done automatically by <strong>BalanceNG</strong>.Example:NodeA# show arphashipaddr ethaddr tgt net cntr age flags--------------- ----------------- ---- --- ----- ----- -----------172.17.2.61 06:00:ac:11:02:3d - 1 - - vip fix172.17.2.64 00:00:5e:00:01:0e - 1 - - vip172.17.2.91 00:e0:81:5d:2a:65 1 - 119 108NodeA# arp 172.17.2.74NodeA# show arphashipaddr ethaddr tgt net cntr age flags--------------- ----------------- ---- --- ----- ----- -----------172.17.2.61 06:00:ac:11:02:3d - 1 - - vip fix172.17.2.64 00:00:5e:00:01:0e - 1 - - vip172.17.2.74 00:00:00:00:00:00 - - 2 - visDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 40 / 143Grünwald Germany / All Rights Reserved
172.17.2.91 00:e0:81:5d:2a:65 1 - 158 147NodeA#3.3.2 commitSynopsis:commit [network(s)|server(s)|target(s)] This comm<strong>and</strong> registers <strong>and</strong> enables one or more networks, servers or targets at once."commit " is equivalent to "register " <strong>and</strong> thenexecuting "enable ".The network, server or target numbers in the list are separated by commas. This comm<strong>and</strong> ismeant to be an abbreviation for interactive use.See also the Server <strong>and</strong> Target state description at the "register" comm<strong>and</strong>.Example:test# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 7957bng# interface eth0interface eth0 successfully attachedbng# network 1 addr 10.2.2.0bng# network 1 mask 255.255.255.0bng# network 1 real 10.2.2.20bng# network 1 virt 10.2.2.21bng# network 1 interface eth0bng# commit network 1bng# target 1 ipaddr 10.2.2.10bng# target 2 ipaddr 10.2.2.20bng# commit targets 1,2WARNING: target 1 in enabled state but not referencedWARNING: target 2 in enabled state but not referencedbng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}register network 1enable network 1target 1 {ipaddr 10.2.2.10}target 2 {ipaddr 10.2.2.20}register targets 1,2enable targets 1,2// end of configuration<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 41 / 143
ng#3.3.3 disableSynopsis:disable [network(s)|server(s)|target(s)] This comm<strong>and</strong> immediately disables the specified networks, servers or targets. The server'svirtual IP addresses are immediately unreachable, targets are immediately taken out of anyload balancing distribution, networks are completely taken out of <strong>BalanceNG</strong> processing. Thecorresponding "enable"-entries are removed from the running configuration.Note: The networks, servers or targets remain "registered", for changing <strong>and</strong> editingparameters they first have to be taken to the "unregistered" state using the "unregister"comm<strong>and</strong> (not necessary for networks, they may be edited <strong>and</strong> changed in the registeredstate).See also the Server <strong>and</strong> Target state description at the "register" comm<strong>and</strong>.Example:bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}register network 1enable network 1target 1 {ipaddr 10.2.2.10}target 2 {ipaddr 10.2.2.20}register targets 1,2enable targets 1,2// end of configurationbng# disable targets 1,2bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}register network 1Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 42 / 143Grünwald Germany / All Rights Reserved
enable network 1target 1 {ipaddr 10.2.2.10}target 2 {ipaddr 10.2.2.20}register targets 1,2// end of configurationbng# show targets# ipaddr port prt net srv status------------------------------------------------------------1 10.2.2.10 any any 1 0 disabled2 10.2.2.20 any any 1 0 disabledbng#3.3.4 dumpSynopsis: dump This immediately starts dumping of all traffic going through to dumpfiles in thegiven directory. Both inbound <strong>and</strong> outbound packets are being recorded.<strong>BalanceNG</strong> stores the packets in "pcap" format, the data can be immediately investigatedusing usual tools e.g. like snoop, tcpdump, netgrep <strong>and</strong> ethereal.The filename is build up as follows (containing the time of creation):"eth".E.g. it could look like:eth0.20070318140703There's an automatic logfile rotation build in which closes the file <strong>and</strong> opens a new one with anew timestamp. When this happens is controlled by the parameter "dumprotation" whichspecifies a byte threshold (see "set" <strong>and</strong> "show parameters").Using dump <strong>BalanceNG</strong> may be used as a "transparent logging switch / bridge" to record alltraffic for security purposes <strong>and</strong> later analysis (<strong>BalanceNG</strong> should be set into Layer 2switching mode using the comm<strong>and</strong> "l2switch").Example:bng# dump eth0 /bigscratch3.3.5 editSynopsis:edit [network(s)|server(s)|target(s)] This comm<strong>and</strong> disables <strong>and</strong> unregisters one or more networks, servers or targets at once."edit " is equivalent to "disable " <strong>and</strong> then executing"unregister ".The item numbers in the list are separated by commas.See also the Server <strong>and</strong> Target state description at the "register" comm<strong>and</strong>.Example:<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 43 / 143
ng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}register network 1enable network 1target 1 {ipaddr 10.2.2.10}target 2 {ipaddr 10.2.2.20}register targets 1,2enable targets 1,2// end of configurationbng# edit targets 1,2bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}register network 1enable network 1// end of configurationbng# show targets# ipaddr port prt net srv status------------------------------------------------------------bng#3.3.6 enableSynopsis:enable [network(s)|server(s)|target(s)] This comm<strong>and</strong> enables the specified networks, servers or targets. Targets in "enabled" mode(or state) immediately participate in load balancing distributions. Servers in "enabled" modestart answering ARP requests <strong>and</strong> ICP-ECHO requests ("pings"). Both servers <strong>and</strong> targetshave to be members of enabled networks.If a virtual network address is locally occupied <strong>and</strong> used by the operating system an errormessage is generated <strong>and</strong> the enabling is refused. This applies to “server ipaddr”, “networkDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 44 / 143Grünwald Germany / All Rights Reserved
eal” <strong>and</strong> “network virt” addresses (which must not be used in parallel by the underlyingoperating system).This comm<strong>and</strong> is revertable by the appropriate "disable" comm<strong>and</strong>.See the Server <strong>and</strong> Target state description at the "register" comm<strong>and</strong>.Example:bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}register network 1enable network 1target 1 {ipaddr 10.2.2.10}target 2 {ipaddr 10.2.2.20}register targets 1,2// end of configurationbng# show targets# ipaddr port prt net srv status------------------------------------------------------------1 10.2.2.10 any any 1 0 disabled2 10.2.2.20 any any 1 0 disabledbng# enable targets 1,2WARNING: target 1 in enabled state but not referencedWARNING: target 2 in enabled state but not referencedbng# show targets# ipaddr port prt net srv status------------------------------------------------------------1 10.2.2.10 any any 1 0 down2 10.2.2.20 any any 1 0 downbng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 45 / 143
egister network 1enable network 1target 1 {ipaddr 10.2.2.10}target 2 {ipaddr 10.2.2.20}register targets 1,2enable targets 1,2// end of configurationbng#3.3.7 gateway3.3.7.1 gateway Synopsis:gateway This comm<strong>and</strong> is a synonym for "gateway ipaddr " <strong>and</strong> is implemented tomaintain backwards compatibility to older releases of <strong>BalanceNG</strong>.3.3.7.2 gateway alert Synopsis:gateway alert This comm<strong>and</strong> specifies an external notification script which is called as soon as the specifiedgateway becomes down (not operational). For removing the script the empty string (“”) needsto be specified.Example:bng# gateway alert "/usr/bin/logger -p daemon.notice GATEWAY IS DOWN"bng#3.3.7.3 gateway arp ,Synopsis:gateway arp ,gateway arp offgateway arp disableThis comm<strong>and</strong> establishes an "arp" healthcheck of the gateway. An arp request is sent outevery seconds, the gateway state changes to "down" if an arp reply has not beenreceived for seconds. The special form "gateway arp off" (or "gateway arp disable")removes the arp healthcheck from the configuration.The arp gateway health check may exist in parallel to the arp ping healthcheck.Example:bng# gateway arp 2,5bng# show gatewayipaddr: 172.17.2.254total status: operationalping status: uparp status: upDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 46 / 143Grünwald Germany / All Rights Reserved
3.3.7.4 gateway ipaddr Synopsis:gateway ipaddr Specifies the default gateway towards the external world (e.g. "Internet"). If an IP4-address isnot locally connected (not part of a local network definition) the packet is being sent to thisgateway address for routing.ARP-resolution of the gateway address is being processed automatically by <strong>BalanceNG</strong>.The comm<strong>and</strong> "no gateway" removes the gateway declaration from the currentconfiguration.Example:bng# gateway ipaddr 10.2.2.254bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.20virt 10.2.2.21interface eth0}register network 1enable network 1gateway {ipaddr 10.2.2.254}target 1 {ipaddr 10.2.2.10}target 2 {ipaddr 10.2.2.20}register targets 1,2enable targets 1,2// end of configurationbng#3.3.7.5 gateway ping ,Synopsis:gateway ping ,gateway ping offgateway ping disableThis comm<strong>and</strong> establishes a "ping" healthcheck of the gateway. An ICMP echo request is sentout every seconds, the gateway state changes to "down" if an ICMP echo reply hasnot been received for seconds. The special form "gateway ping off" (or "gatewayping disable") removes the ping healthcheck from the configuration.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 47 / 143
The ping gateway health check may exist in parallel to the arp healthcheck.Example:bng# gateway ping 1,3bng# show gatewayipaddr: 172.17.2.254total status: operationalping status: uparp status: up3.3.7.6 gateway trackval Synopsis:gateway trackval gateway trackval defaultThis comm<strong>and</strong> associates a tracking value to the gateway. If the gateway state changes to"down" (according to the current active health checks) <strong>and</strong> VRRP is active <strong>and</strong> the currentpriority is not equal to 255 then the current priority is degraded by the tracking value of thegateway. The default value is 0, the special form "gateway trackval default" resets thegateway tracking value to 0.Example:bng# show gatewayipaddr: 172.17.2.254total status: operationalping status: upbng# gateway trackval 4bng# show gatewayipaddr: 172.17.2.254total status: operationalping status: uptrackval: 4bng#3.3.7.7 gateway upalert Synopsis:gateway upalert This comm<strong>and</strong> specifies an external notification script which is called as soon as the specifiedgateway becomes operational. For removing the script the empty string (“”) needs to bespecified.Example:bng# gateway upalert "/usr/bin/logger -p daemon.notice GATEWAY IS UP"bng#3.3.8 hostnameSynopsis:[no] hostname This sets the current hostname of the <strong>BalanceNG</strong> instance to the specified name <strong>and</strong> changesthe interactive comm<strong>and</strong> line prompt to that name followed by a "#". This is just forinformational purposes <strong>and</strong> does not change functionality.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 48 / 143Grünwald Germany / All Rights Reserved
This comm<strong>and</strong> may be reverted by the "no" keyword, changing the name to "undefined" <strong>and</strong>changing the interactive comm<strong>and</strong> line prompt back to the default (which is "bng#").The hostname may contain spaces, in that case the hostname must be embedded in doublequotes. Specifying an empty string in double quotes also sets the hostname to the initial"undefined" state.Example:# bng control<strong>BalanceNG</strong>: connected to PID 8660bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)// end of configurationbng# hostname test1test1# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)hostname test1// end of configurationtest1# no hostname test1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)// end of configurationbng# hostname "LoadBalancer Side A"LoadBalancer Side A# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)hostname "LoadBalancer Side A"// end of configurationLoadBalancer Side A# hostname ""bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)// end of configurationbng#3.3.9 interfaceSynopsis:interface This configurational comm<strong>and</strong> declares the interface to be used by <strong>BalanceNG</strong> (tells<strong>BalanceNG</strong> to provide its services on that interface).This comm<strong>and</strong> may be reverted by prepending “no” to it (e.g. “no interface eth0” for detachinginterface eth0 from <strong>BalanceNG</strong>). Reverting is possible as long as the interface is notreferenced by a network in registered or enabled state. Note: Reverting leaves the interface inpromiscuous mode.<strong>BalanceNG</strong> immediately takes control over the specified interface putting it into promiscuousmode.Note: Although Interfaces may be used by <strong>BalanceNG</strong> stack <strong>and</strong> the Operating System hostTCP/IP stack in parallel it is not necessary to specify any other interface parameters on the<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 49 / 143
Host machine.The statistic counters are all set to zero (see "show ifstat").The interface specifier is identical to the Linux name of that interface (like "eth0", "eth1" <strong>and</strong>so on).Example:# ifconfig -aeth0 Link encap:Ethernet HWaddr 00:0E:0C:6C:BA:59inet addr:10.55.55.12 Bcast:10.55.55.255 Mask:255.255.255.0UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1RX packets:5045 errors:0 dropped:0 overruns:0 frame:0TX packets:3111 errors:0 dropped:0 overruns:0 carrier:0collisions:0 txqueuelen:1000RX bytes:740063 (722.7 Kb) TX bytes:1215602 (1.1 Mb)Base address:0xc000 Memory:df020000-df040000eth1loLink encap:Ethernet HWaddr 00:0E:0C:6C:BA:5BBROADCAST MULTICAST MTU:1500 Metric:1RX packets:0 errors:0 dropped:0 overruns:0 frame:0TX packets:0 errors:0 dropped:0 overruns:0 carrier:0collisions:0 txqueuelen:1000RX bytes:0 (0.0 b) TX bytes:0 (0.0 b)Base address:0xc400 Memory:df040000-df060000Link encap:Local Loopbackinet addr:127.0.0.1 Mask:255.0.0.0UP LOOPBACK RUNNING MTU:16436 Metric:1RX packets:97 errors:0 dropped:0 overruns:0 frame:0TX packets:97 errors:0 dropped:0 overruns:0 carrier:0collisions:0 txqueuelen:0RX bytes:6179 (6.0 Kb) TX bytes:6179 (6.0 Kb)# /etc/init.d/bng start<strong>BalanceNG</strong>: starting up ...# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8012bng# interface eth0interface eth0 successfully attachedbng# interface eth1interface eth1 successfully attachedbng# show ifstatinterface eth0received:packets 3bytes 180sent:packets 0bytes 0dumped:bytes 0interface eth1received:packets 3bytes 210sent:Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 50 / 143Grünwald Germany / All Rights Reserved
packets 0bytes 0dumped:bytes 0bng#3.3.10 l2switchSynopsis:[no] l2switchThis comm<strong>and</strong> either enables or disables layer 2 switching mode. Layer 2 switching is initiallyoff, that means particularly:• No forwarding of packets with layer 2 broadcast or multicast destination address• No forwarding of packets to unknown layer 2 destination addresses (on all ports)• No forwarding of packets, that are not part of the load balancing process.Switching Layer 2 mode on means that the packets mentioned above are h<strong>and</strong>led like theywould be processed in a normal "dumb" switch.The layer 2 switching mode can be useful if you want to implement a "transparent loggingbridge" together with the "dump" comm<strong>and</strong>.Example:# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8016bng# interface eth0interface eth0 successfully attachedbng# interface eth1interface eth1 successfully attachedbng# l2switchbng# dump eth1 /tmpbng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0interface eth1dump eth1 /tmpl2switch// end of configurationbng#"l2switch" appears in the configuration file only if enabled.3.3.11 licenseSynopsis:license This comm<strong>and</strong> fully activates <strong>BalanceNG</strong> using the purchased license for exactly this node.The serial number <strong>and</strong> license key is being provided by Inlab <strong>Software</strong> GmbH. The licensekeyis only valid for exactly one specific node identified by its nodeid (see also "shownodeid").<strong>BalanceNG</strong> with no or without valid licensing information is operational with Basic Licensing<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 51 / 143
estrictions, Please take a look at the summary chapter at above.The effect of the "license" comm<strong>and</strong> can be examined with "show license".Example:bng# show licenseno license specifiedbng# show nodeidfa:e9:55:26:66:a8bng# license beta123 e0bf3035c3c673ee725eae1bbb30c31bbng# show licensestatus: valid full licenseserial: TEST0611021nodeid: 2a:e2:9f:38:da:20type "show version" for version <strong>and</strong> Copyright informationbng#3.3.12 network Synopsis:network This comm<strong>and</strong> family is used to specify network definitions in the <strong>BalanceNG</strong> configuration.The special subcomm<strong>and</strong> "{" opens a network definition block interactively, so that the first twoarguments can be omitted until the block is closed with a corresponding "}". A currently openblock is indicated by a "+"-sign at the end of the comm<strong>and</strong> line prompt (instead of a "#").A network ca only be enable, if "addr", "mask", "real" <strong>and</strong> "virt" parameters are all specifiedcorrectly.Example:bng# network 1 {bng+ addr 10.3.3.0bng+ mask 255.255.255.0bng+ real 10.3.3.10bng+ virt 10.3.3.20bng+ }bng#3.3.12.1 network addrSynopsis:network addr This comm<strong>and</strong> specifies the network address of the specified network. The host part of thenetwork must be all "0" bits (determined by the "mask" specification).This address is not a virtual IP address (not "pingable") <strong>and</strong> has to be specified equally on allparticipating VRRP nodes.Example:bng# network 2 addr 10.20.0.0bng# commit network 2mask of network 2 not specifiedbng#Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 52 / 143Grünwald Germany / All Rights Reserved
3.3.12.2 network interface[s]Synopsis:network interface[s] This comm<strong>and</strong> associates one or more interfaces to the network with the given number. Allinterfaces in the list have to be activated using the "interface" comm<strong>and</strong> before. Multiplenetworks may share the same interfaces (or interface).In general network activities will be restricted on the specified interfaces, e.g.:• ARP-requests will be sent out only to the specified interfaces for IP addresses in thenetwork• ARP-requests are only accepted (<strong>and</strong> 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 VRRPnetwork.Example:bng# interface eth0interface eth0 successfully attachedbng# interface eth1interface eth1 successfully attachedbng# network 2 interface eth0bng# show networks# name S netaddr netmask real addr virt addr interfaces------------------------------------------------------------------------------------2 D 10.20.0.0 0.0.0.0 0.0.0.0 0.0.0.0 eth0bng# network 2 interface eth0,eth1bng# show networks# name S netaddr netmask real addr virt addr interfaces------------------------------------------------------------------------------------2 D 10.20.0.0 0.0.0.0 0.0.0.0 0.0.0.0 eth0,eth1bng#3.3.12.3 network maskSynopsis:network mask This specifies the IP4 netmask for the given network.Example:bng# interface eth1interface eth1 successfully attachedbng# network 3 addr 10.20.0.0bng# network 3 mask 255.255.0.0bng# commit network 3virt of network 3 not specifiedbng#3.3.12.4 network nameSynopsis:network name This comm<strong>and</strong> specifies an optional name for the given network. Specifying "none" removesthe current name definition. The network name may be embedded in double quotes to specifya name containing spaces. Specifying an empty string in double quotes also removes the<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 53 / 143
current name definition.Example:bng# network 3 name test123bng# show networks# name S netaddr netmask real addr virt addr interfaces------------------------------------------------------------------------------------3 test123 D 10.20.0.0 255.255.0.0 0.0.0.0 0.0.0.0 -bng# network 3 name nonebng# show networks# name S netaddr netmask real addr virt addr interfaces------------------------------------------------------------------------------------3 D 10.20.0.0 255.255.0.0 0.0.0.0 0.0.0.0 -bng#3.3.12.5 network natSynopsis:network nat inside|outside|offThis network parameter controls the participation of the network in NAT (network addresstranslation). If “network nat” is set to “inside”, all IP addresses in that network are beingtranslated 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 networkwith “nat inside” <strong>and</strong> one network with “nat outside” exist <strong>and</strong> are enabled.NAT table entries are synced per default between master <strong>and</strong> backup nodes (if VRRP isactive). See the NAT parameters for more information.Example:nat-test# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)hostname nat-testlicense test123 660a24a35167cc8e69acfe223cc2d360interface bge0interface nge0network 1 {addr 10.135.110.0mask 255.255.255.0real 10.135.110.61virt 10.135.110.62nat outsideinterface bge0}network 2 {addr 10.17.2.0mask 255.255.255.0real 10.17.2.61virt 10.17.2.62nat insideinterface nge0}register networks 1,2enable networks 1,2gateway {ipaddr 10.135.110.254ping 5,12}// end of configurationnet-test#Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 54 / 143Grünwald Germany / All Rights Reserved
3.3.12.6 network realSynopsis:network real This specifies a "real" IP address for the given network. The IP address has to be "inside" thenetwork (according to the address <strong>and</strong> netmask settings). This address is a "pingable" virtualIP address (active on the networks interfaces). It has to be unique for each <strong>BalanceNG</strong> nodein a VRRP setup (it will not hop at a VRRP failover).The specification of a "real" address is not m<strong>and</strong>atory (0.0.0.0 with a meaning of "notspecified"). A real address has to be specified to make ARP-lookups <strong>and</strong> health checks work(since 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# network 3 real 10.20.3.3bng# show networks# name S netaddr netmask real addr virt addr interfaces------------------------------------------------------------------------------------3 D 10.20.0.0 255.255.0.0 10.20.3.3 0.0.0.0 -bng#3.3.12.7 network virtSynopsis:network virt This specifies the virtual address in the given network. This is a "pingable" address that isbeing shared between all VRRP nodes.The specification of a network "virt" address is not m<strong>and</strong>atory (using 0.0.0.0 as "unspecified").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 specific routing rule.Example:bng# network 3 virt 10.20.4.4bng# enable network 3bng# show networks# name S netaddr netmask real addr virt addr interfaces------------------------------------------------------------------------------------3 E 10.20.0.0 255.255.0.0 10.20.3.3 10.20.4.4 -bng#3.3.13 noSynopsis:no This special comm<strong>and</strong> reverts another comm<strong>and</strong> <strong>and</strong> eventually removes the configurationcomm<strong>and</strong> out of the current configuration. This applies to a subset of comm<strong>and</strong>s, the followingcomm<strong>and</strong>s are revertable by "no" (in alphabetical order):arp, dump, gateway, hostname, license, tnat <strong>and</strong> vip.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 55 / 143
The arguments of the original comm<strong>and</strong> are only checked if necessary when reverting it with"no".Example:bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)// end of configurationbng#bng# vip 192.168.1.100bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)vip 192.168.1.100// end of configurationbng# no vip 192.168.1.100bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)// end of configurationbng#3.3.14 registerSynopsis:register The specified list of networks, targets or servers (or just one of them) is taken from the"unregistered" state to the "registered state".Target <strong>and</strong> Server: Definitions <strong>and</strong> StatesA "Network" in <strong>BalanceNG</strong> associates the network parameters to a set of physical interfaces.A "Server" in <strong>BalanceNG</strong> is a "virtual Server" <strong>and</strong> an addressable virtual "Host" that is capableto forward <strong>and</strong> load balance requests to the so called "real servers", the Targets.A "Target" in <strong>BalanceNG</strong> is associated with a real existing address in the Target Network.One Server is associated to one or more Targets <strong>and</strong> performs load balancing between themaccording to the specified load balancing methods.Both Servers <strong>and</strong> Targets are associated automatically to a network according to theaddressing.Each Network, Server or Target is inside in <strong>BalanceNG</strong> in one of three states. See the statediagram below:Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 56 / 143Grünwald Germany / All Rights Reserved
unregistered(Start)registerunregisterregisterededitcommitdisableenableenabledFigure 4: Server <strong>and</strong> Target StatesThe states are defined as follows:"unregistered"-StateEach Target or Server is initially in that state. The Target or Server is unknown for<strong>BalanceNG</strong> <strong>and</strong> there's no associated functionality. The Entity (Target or Server) doesnot appear in the configuration. This state allows parameters <strong>and</strong> settings of theTarget or Server to be edited <strong>and</strong> changed.The comm<strong>and</strong> "register" registers the Target or Server <strong>and</strong> it's internal statechanges to registered.Using the abbreviation comm<strong>and</strong> "commit" the Target or Server may also beimmediately taken to the "enabled"-State."registered"-StateIn this state the entities (Target or Servers) are registered at the internaladministrative data structures of <strong>BalanceNG</strong>. They appear in the configuration (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:Networks:• Network is visible in "show networks"Targets:• Health checks are not being executed• Targets are not being addressed by their associated Servers (they appear insquare brackets at "show servers").• ARP resolving is not being performedServers:• ARP request are not answered<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 57 / 143
• ICMP echo requests are not answered ("pings")• Requests to Services are ignored• No VRRP sharing of Server addressThe comm<strong>and</strong> "enable" puts the entity into "enabled" state, the comm<strong>and</strong>"unregister" puts it back into "unregistered" state."enabled"-stateExamples:In that state the entities are functional, that means the following:Networks:• "real" <strong>and</strong> "virt" addresses are pingable <strong>and</strong> usable by all other processing.• VRRP is usable on the VRRP networkTargets:• ARP resolving of the targets IP-address is performed• Health checks are being executed according to the definitions• Targets participate in load balancing is their health checks succeedServers:• 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)<strong>BalanceNG</strong>: connected to PID 8158bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)// end of configurationbng#bng# network 1 addr 10.3.3.0bng# network 1 mask 255.255.255.0bng# network 1 real 10.3.3.1bng# network 1 virt 10.3.3.2bng# register network 1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)network 1 {addr 10.3.3.0mask 255.255.255.0real 10.3.3.1virt 10.3.3.2interface noneDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 58 / 143Grünwald Germany / All Rights Reserved
}register network 1// end of configurationbng#bng# target 1 ipaddr 10.3.3.10bng# register target 1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)network 1 {addr 10.3.3.0mask 255.255.255.0real 10.3.3.1virt 10.3.3.2interface none}register network 1target 1 {ipaddr 10.3.3.10}register target 1// end of configurationbng#3.3.15 remarkSynopsis:remark ""This comm<strong>and</strong> is available to allow adding custom remarks to the configuration file. This mightbe helpful e.g. for version tracking, configuration management <strong>and</strong> more.The following example shows how the remark configuration comm<strong>and</strong> could be used totransport the Id of RCS (Revision Control System).Example:# /etc/init.d/bng restart<strong>BalanceNG</strong>: not yet running<strong>BalanceNG</strong>: starting up ...# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8673bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)// end of configurationbng# remark "$Id$"bng# saveokbng# ... bye# ci -l /etc/bng.conf/etc/bng.conf,v
<strong>BalanceNG</strong> configuration Side A>>initial revision: 1.1done# /etc/init.d/bng restart<strong>BalanceNG</strong>: shutdown of PID 8673 complete<strong>BalanceNG</strong>: starting up ...# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8683bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)remark "$Id: bng.conf,v 1.1 03/19/2006 11:17 root Exp root $"// end of configurationbng#3.3.16 serverSynopsis:server This comm<strong>and</strong> is used to configure the parameters of a <strong>BalanceNG</strong> server. In general this isonly possible if the Server is in the "unregistered" state (see the explanations at the"register" comm<strong>and</strong>).<strong>BalanceNG</strong> is capable of h<strong>and</strong>ling 64 independent Servers. Each server has one or multipleassociated Targets where the load is being distributed to.3.3.16.1 server backup[s]Synopsis:server backup[s] |"none"This comm<strong>and</strong> assigns one or more backup targets to the Server with the specified number.Backup targets are being addressed if either there's no available addressable operationaltarget available or if the "first choice" target fails <strong>and</strong> the Server's failover mode is "backup"(see "server failover").The list of backup targets contains of the backup target numbers separated by commas.The comm<strong>and</strong> "server backup none" deletes the list of backup targets completely. Ifthere are multiple backup targets available <strong>BalanceNG</strong> always uses a Round Robindistribution among them.The specification of a backup target together with "failover backup" allows theconfiguration of "N+1" high availability, where the overall load capacity of the target clusterremains the same even if one target fails.Example:<strong>BalanceNG</strong>: connected to PID 8169bng# server 1 targets 1,2bng# server 1 ipaddr 10.11.40.12bng# server 1 backup 3bng# commit server 1WARNING: server 1 has no matching networkbng# show conf// configuration taken Tue Oct 10 21:39:59 2006Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 60 / 143Grünwald Germany / All Rights Reserved
<strong>BalanceNG</strong> 1.840 (created 2007/04/29)server 1 {ipaddr 10.11.40.12targets 1,2backup 3}register server 1enable server 1// end of configurationbng#3.3.16.2 server failoverSynopsis:server failover "backup"|"normal"This comm<strong>and</strong> allows to switch a Server from normal failover mode to "backup" failover mode(<strong>and</strong> backwards). If a client request arrives a Server <strong>BalanceNG</strong> tried to identify the first targetto try according to the defined load balancing method for that server.If this first target is not operational (either because disabled or a health check is failing) then<strong>BalanceNG</strong> usually tries to find an alternate target among the group of defined targets (failovermode "normal").If the failover mode for that server is "backup" then <strong>BalanceNG</strong> immediately selects a targetfrom the set of backup targets.Example:bng# edit server 1bng# server 1 failover backupbng# commit server 1WARNING: server 1 has no matching networkbng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)server 1 {ipaddr 10.11.40.12failover backuptargets 1,2backup 3}register server 1enable server 1// end of configurationbng#3.3.16.3 server ipaddrSynopsis:server ipaddr This comm<strong>and</strong> specifies the IP address of the Server. As soon as the Server is in "enabled"State, <strong>BalanceNG</strong> responds to ARP <strong>and</strong> ICMP ECHO (ping) requests <strong>and</strong> represents thataddress that way.If VRRP is enabled then this IP address is being shared between all <strong>BalanceNG</strong> nodes of theVRRP vrid (virtual router id).<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 61 / 143
Example:<strong>BalanceNG</strong>: connected to PID 8172bng# server 1 ipaddr 10.11.40.12bng# server 1 target 1bng# register server 1bng# enable server 1WARNING: server 1 has no matching networkbng# show server 1server 1ipaddr 10.11.40.12network 0port anyprotocol anystatus enabledmethod rrportrel offtarget [1]bng#If a special keyword "any" is supplied as the address, <strong>BalanceNG</strong> enters Link Load Balancingmode <strong>and</strong> performs routing using the targets as Layer 3 routing endpoints.The following example shows a configuration which offers a virtual router with the privateaddress 10.10.10.71 to a network <strong>and</strong> distributes the traffic evenly to two different outboundrouters.Example:bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)license INLAB01 d94e1a73b75478f4e1751b29253bf2deset ipforwarding 1interface eth0interface eth1vrrp {vrid 10priority 255network 2tracking enable}network 1 {name "Router Network"addr 172.17.2.0mask 255.255.255.0real 172.17.2.70virt 172.17.2.71interface eth0}network 2 {name "Internal Network"addr 10.10.10.0mask 255.255.255.0Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 62 / 143Grünwald Germany / All Rights Reserved
eal 10.10.10.70virt 10.10.10.71interface eth1}register networks 1,2enable networks 1,2server 1 {name "<strong>BalanceNG</strong> virtual router"ipaddr anymethod sessiontargets 1,2}register server 1enable server 1target 1 {name "Outbound Router 1"ipaddr 172.17.2.254ping 2,5}target 2 {name "Outbound Router 2"ipaddr 172.17.2.253ping 2,5}register targets 1,2enable targets 1,2// end of configuration3.3.16.4 server methodSynopsis:server method "rr"|"hash"|"r<strong>and</strong>om"|"agent"This comm<strong>and</strong> specifies which load balancing method should be active for the specifiedServer. The load balancing method determines which target to choose for new <strong>and</strong> currentlyunknown sessions.The following four methods are available:3.3.16.4.1 rrThis is the default "Round Robin" distribution method. Targets are chosen cyclically. A simpleweighting can be implemented by adding the same target twice or multiple times to theservers target list. If the method "rr" is active there's no output in the configuration file sincethis is the default method.3.3.16.4.2 hashUsing a hash function with the client source IP address as the key each possible client sourceaddress is being associated with the same target in a target set. This method may be used toachieve a session persistence which "survives" even VRRP failover. Simple weighting ispossible here too by specifying the same target multiple times.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 63 / 143
3.3.16.4.3 r<strong>and</strong>omOne target out of the set is chosen r<strong>and</strong>omly. A weighting is possible using the “target weight” keyword (see there). The default target weight is 1.3.3.16.4.4 agentAll targets of a Servers target set have to be specified with "agent" as one of the healthchecks. 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.Example:<strong>BalanceNG</strong>: connected to PID 8175bng# server 1 ipaddr 10.2.2.1bng# server 1 method hashbng# server 1 targets 1,1,2bng# commit server 1WARNING: server 1 has no matching networkbng# show servers# ipaddr port prt net S targets {backups}------------------------------------------------------------1 10.2.2.1 any any 0 e [1],[1],[2] {}bng# show server 1server 1ipaddr 10.2.2.1network 0port anyprotocol anystatus enabledmethod hashportrel offtargets [1],[1],[2]bng#3.3.16.4.5 bwThis method chooses the target which consumes the least current total b<strong>and</strong>width among alltargets of the server. The current total b<strong>and</strong>width value may be modified virtually by the“offset” <strong>and</strong> “scale” parameters of the target allowing arbitrary weighting <strong>and</strong> preferencesettings.Example:bng# edit server 1bng# server 1 method bwbng# commit server 1bng# show server 1server 1ipaddr 172.17.2.189network 1port 22protocol tcpstatus enabledmethod bwDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 64 / 143Grünwald Germany / All Rights Reserved
portrel offtarget 1bng#3.3.16.4.6 bwinThis method operates like method “bw”, but only the incoming b<strong>and</strong>width is taken intoaccount.3.3.16.4.7 bwoutThis method operates like method “bw”, but only the outgoing b<strong>and</strong>width is taken into account.3.3.16.4.8 rndagentThis method takes the scores collected by the <strong>BalanceNG</strong> agent (bngagent) into accountsimilar to the “agent” method. The difference is, that internally a weight is calculated per target<strong>and</strong> that the next session is choses by a weighted r<strong>and</strong>om algorithm.The weight 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# edit server 1bng# server 1 method rndagentbng# commit server 1bng# show server 1server 1ipaddr 172.17.2.189network 1port 22protocol tcpstatus enabledmethod rndagentportrel offtarget 1bng#3.3.16.4.9 sessionThis method chooses the target with the least number of current sessions as target for thecurrent new session.Example:bng# edit server 1bng# server 1 method sessionbng# commit server 1bng# show server 1server 1ipaddr 172.17.2.189<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 65 / 143
network 1port 22protocol tcpstatus enabledmethod sessionportrel offtarget 1bng#The session distribution method may be modified by the target “offset” <strong>and</strong> “scale” parametersallowing weighting by applying a linear function to the current number of sessions.3.3.16.5 server nameSynopsis:server name |"none"Assigns a server a name for informational purposes. The string "none" as the namearguments deletes the name from the specified 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 definition.Example:bng# edit server 1bng# server 1 name test44bng# commit server 1WARNING: server 1 has no matching networkbng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)server 1 {name test44ipaddr 10.2.2.1method hashtargets 1,1,2}register server 1enable server 1// end of configurationbng# edit server 1bng# server 1 name nonebng# commit server 1WARNING: server 1 has no matching networkbng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)server 1 {ipaddr 10.2.2.1method hashtargets 1,1,2}register server 1enable server 1Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 66 / 143Grünwald Germany / All Rights Reserved
ng#end of configuration3.3.16.6 server pluginSynopsis:server plugin |"none"|""This comm<strong>and</strong> connects the session creation mechanism of the virtual server to a pluginprogram or script. The plugin script path has to be specified 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 <strong>and</strong> stdout <strong>and</strong> receives sessioninformation as a line in readable ASCII format containing the following five parametersseparated by a single blank:1. Protocol “UDP” or “TCP”2. <strong>Source</strong> IP Address Ipv4 address in numerical dot notation3. <strong>Source</strong> Port decimal number4. Destination IP Address Ipv4 address (usually that of the virtual server)5. Destination Port decimal numberThe result of the plugin is delivered back to <strong>BalanceNG</strong> by stdout by printing one lineconsisting of a number in readable ASCII. The semantics are as follows:Return ValueMeaning-1 This session request is denied, drop the packet0 This session request is OK, proceed as usual>= 1 The session should be directed to the target with thisspecific number (target has to be among the target set ofthe virtual server).WARNING: Server plugins should be as fast as possible since the <strong>BalanceNG</strong> core switchingengine actually waits until the plugin returned it's result value.<strong>BalanceNG</strong> assumes an ultra fast, 100% working component at this very critical interface.Plugins are started once at "server enable" <strong>and</strong> killed at "server disable".Example:Here's a simple example of a server plugin written in perl. This example implements a filterwhich allows session only from source IP addresses originating from 10.10.10.0/24.IMPORTANT: Setting the autoflush (IO::H<strong>and</strong>le) functionality is required for perl scripts toallow a line-by-line communication with <strong>BalanceNG</strong> (<strong>BalanceNG</strong> could stall otherwise).#!/usr/bin/perluse IO::H<strong>and</strong>le;<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 67 / 143
autoflush STDOUT 1;while ($request = ) {chomp $request;($proto, $saddr, $sport, $daddr, $dport) = split /\s+/, $request;if($saddr=~ m/10\.10\.10\.\d+/) {printf("0\n");} else {printf("-1\n");}}This script is connected using the “plugin” keyword inside a server block:server 1 {ipaddr 172.17.2.64port 80protocol tcpplugin /home/bng/filter.plmethod sessiontargets 1,2}3.3.16.7 server portSynopsis:server port |"any"This comm<strong>and</strong> restricts the services being offered by the <strong>BalanceNG</strong> Server to a specific port.Per default any port (<strong>and</strong> any protocol) is being load balanced to the associated targets. If aspecific port is specified, then a new session is only created if the destination port towards theServer matches this port.The specification of a port may be removed / reverted to the default by applying the keyword"any".If the port is specified using this comm<strong>and</strong>, but the protocol is "any" then new sessions will becreated for both UDP <strong>and</strong> TCP packets.A server with a specified port <strong>and</strong> an associated target with a different port means that a porttranslation takes place.Example (round robin load balancing port 8080 to two targets port 80):# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8178bng# interface eth0interface eth0 successfully attachedbng# interface eth1interface eth1 successfully attachedbng# network 1 {bng+ addr 10.2.2.0bng+ mask 255.255.255.0bng+ real 10.2.2.100bng+ virt 10.2.2.101bng+ interface eth0bng+ }Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 68 / 143Grünwald Germany / All Rights Reserved
ng# network 2 {bng+ addr 192.168.1.0bng+ mask 255.255.255.0bng+ real 192.168.1.100bng+ virt 192.168.1.101bng+ interface eth1bng+ }bng# commit networks 1,2bng# target 1 ipaddr 10.2.2.1bng# target 1 port 80bng# target 1 protocol tcpbng# target 1 tcpopen 80,10,30bng# commit target 1WARNING: target 1 in enabled state but not referencedbng# target 2 ipaddr 10.2.2.2bng# target 2 port 80bng# target 2 protocol tcpbng# target 2 tcpopen 80,10,30bng# commit target 2WARNING: target 1 in enabled state but not referencedWARNING: target 2 in enabled state but not referencedbng# server 1 ipaddr 192.168.1.1bng# server 1 port 8080bng# server 1 protocol tcpbng# server 1 targets 1,2bng# commit server 1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0interface eth1network 1 {addr 10.2.2.0mask 255.255.255.0real 10.2.2.100virt 10.2.2.101interface eth0}network 2 {addr 192.168.1.0mask 255.255.255.0real 192.168.1.100virt 192.168.1.101interface eth1}register networks 1,2enable networks 1,2server 1 {ipaddr 192.168.1.1port 8080protocol tcptargets 1,2<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 69 / 143
}register server 1enable server 1target 1 {ipaddr 10.2.2.1port 80protocol tcptcpopen 80,10,30}target 2 {ipaddr 10.2.2.2port 80protocol tcptcpopen 80,10,30}register targets 1,2enable targets 1,2// end of configurationbng#3.3.16.8 server ports ,Synopsis:server ports ,This comm<strong>and</strong> specifies two related ports for a server. <strong>BalanceNG</strong> directs connections toeach of the ports always to the same target <strong>and</strong> manages sessions accordingly. This is usefulto combine e.g. port 80 <strong>and</strong> 443 in order to maintain the same target during a switchover fromHTTP to SSL-HTTP.Port relevance of the server has to be switched off <strong>and</strong> the associated targets must have "portany" specified.Example:bng# edit server 1bng# server 1 ports 80,443bng# commit server 1bng# show server 1server 1ipaddr 172.17.2.189network 1ports 80,443protocol anystatus enabledmethod rrportrel offtarget 1bng#3.3.16.9 server portrelSynopsis: server portrel on|offThis comm<strong>and</strong> switches server specific "port relevance" on or off. "Off"is the default which isDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 70 / 143Grünwald Germany / All Rights Reserved
not displayed in the configuration file.When off, load balancing sessions are being created based only on the source IP address ofthe client host addressing the server.When on, also the source port is taken into account, a new connection from a different sourceport from a already known client will cause a new session to be created (with an alternatetarget, depending on the LB method). Connection persistence is then h<strong>and</strong>led on connectionlevel, not on client IP address level.This is useful when many different connections from a limited set of IP addresses have to beload-balanced to the targets (e.g. one big HTTP-proxy).Example:bng# show server 1server 1ipaddr 192.168.1.1network 2port 8080protocol tcpstatus enabledmethod rrportrel offtargets (1),(2)bng# edit server 1bng# server 1 portrel onbng# commit server 1bng# show server 1server 1ipaddr 192.168.1.1network 2port 8080protocol tcpstatus enabledmethod rrportrel ontargets (1),(2)bng#3.3.16.10 server protocolSynopsis:server protocol any|tcp|udpThis comm<strong>and</strong> either restricts the server load balanced connections to tcp, udp or to any(both) of these protocols. This comm<strong>and</strong> may be used with "server port" in anycombination.Example:bng# edit server 1bng# server 1 ipaddr 10.2.2.4bng# server 1 protocol anybng# commit server 1bng# show server 1server 1<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 71 / 143
ipaddr 10.2.2.4network 1port 8080protocol anystatus enabledmethod rrportrel ontargets (1),(2)bng#3.3.16.11 server stimeout |defaultSynopsis:server stimeout |defaultThis comm<strong>and</strong> sets a server specific session timeout in seconds. A value of 0 or the string“default” disables the server specific sessions timeout, in that case the global session timeoutis valid for all sessions (see the parameter “sessiontimeout”).The minimum value is 10 seconds, the maximum value is 172880 seconds (48 hours).Example:bng# show server 4server 4ipaddr 172.17.2.82network 1port 22protocol tcpstatus enabledmethod rrportrel offtarget 1bng# edit server 4bng# server 4 stimeout 120bng# commit server 4bng#3.3.16.12 server target[s]Synopsis:server target[s] |noneThis comm<strong>and</strong> associates one or more targets to the specified server. The "virtual" serverthen distributes the requests to the operational targets in that set according to the specifiedload balancing method.One or more target can be specified. The same target may appear multiple times to allow asimple weighting of the distribution.Either the singular or plural of "target" may be used.Specifying "none" as list parameter completely empties the list of associated targets.Example:bng# edit server 1Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 72 / 143Grünwald Germany / All Rights Reserved
ng# server 1 targets 1,2,3,4,5,6,7,8bng# commit server 1bng# show server 1server 1ipaddr 10.2.2.4network 1port 8080protocol anystatus enabledmethod rrportrel ontargets (1),(2),[3],[4],[5],[6],[7],[8]bng# show servers# ipaddr port prt net S targets {backups}------------------------------------------------------------1 10.2.2.4 8080 any 1 e (1),(2),[3],[4],[5],[6],[7],[8] {}bng#3.3.17 setSynopsis:set |"default"<strong>BalanceNG</strong> uses a set of internal parameters. Using set these parameters may be changed.All parameters are numeric with a minimum, a maximum <strong>and</strong> a default. If the parameter iscurrently set to the default value then no "set" line appears in the configuration file (see "showparameters").A special set block may be opened by specifying "{" as the first argument to set.The comm<strong>and</strong> "set default" sets the specified parameter back to itsdefault value.3.3.17.1 set arplookupSynopsis:set arplookup |defaultThis parameter controls how often (interval in seconds) an still unknown mac address is beingrequested using the ARP protocol. The minimum of this parameter is 5, the maximum 60 <strong>and</strong>the default value is 10 seconds.Example:<strong>BalanceNG</strong>: connected to PID 8182bng# set arplookup 40bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set arplookup 40// end of configurationbng# show parametersname min max default current-------------- ---------- ---------- ---------- ----------sendprobes 0 1 0 0dumprotation 1 1048576 1024 1024arplookup 5 60 10 10arprefresh 60 3600 300 300arptimeout 0 86400 0 0<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 73 / 143
hcportoffset 1024 65535 30000 30000vrrppreempt 0 1 0 0vrrpmasterdown 3 10 3 3gratarpremind 0 120 0 0ipforwarding 0 1 0 0sessiontimeout 10 172800 600 600sessionscan 1 20 10 10sessionsync 0 1 1 1sessionsynciv 10 120 10 10sessiondlimit 10 1000 10 10bmduration 10 3600 300 300bmpsize 20 1514 1514 1514bmwsize 1 100 16 16nattimeout 10 172800 600 600natscan 1 20 10 10natsync 0 1 1 1natsynciv 10 120 10 10natdlimit 10 100 10 10localdsr 0 1 0 1bng# set arprefresh 180bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {arplookup 40arprefresh 180}// end of configurationbng#3.3.17.2 set arprefreshSynopsis:set arprefresh |defaultThis parameter controls how often an already known mac address is being reexamined usingthe ARP-Protocol (interval in seconds). The minimum of this parameter is 60, the maximum300 <strong>and</strong> the default value is 120 seconds.This parameter determines how e.g. fast a changed mac address of a target is beingrecognized by <strong>BalanceNG</strong>.Example:bng# set arprefresh 240bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {arplookup 40arprefresh 240}// end of configurationbng#Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 74 / 143Grünwald Germany / All Rights Reserved
3.3.17.3 set arptimeoutSynopsis:set arptimeout |defaultAll targets in "enabled" state have an associated IP address, for which the mac / Ethernetaddress has to be determined using the ARP protocol. This action can be regarded as a basichealth 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 targethas to become not operational.The special value of 0 disables this particular implicit healthcheck.The minimum of this parameter is 0, the maximum 86400 <strong>and</strong> the default value is 0 seconds(disabled).bng# set arptimeout 60bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {arplookup 40arprefresh 240arptimeout 60}// end of configurationbng#3.3.17.4 set bmdurationSynopsis:set bmduration |defaultThis sets the benchmark duration in seconds (see benchmark comm<strong>and</strong>).3.3.17.5 set bmpsizeSynopsis:set bmpsize |defaultThis sets the packet size in bytes being used for benchmarking (see benchmark comm<strong>and</strong>).3.3.17.6 set bmwsizeSynopsis:set bmwsize |defaultThis parameter controls the number of packets being sent out at the beginning of thebenchmark (“window size”).3.3.17.7 set debugscopeSynopsis:set debugscope |defaultThis parameter sets the scope for additional built in debug messages. The default is 0 (nodebug messages). The following debug scopes are currently defined:0 No debug messages1 Target script debug messages<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 75 / 143
3.3.17.8 set dumprotationSynopsis:set dumprotation |defaultThis parameter controls the dumpfile rotation of the files generated by the "dump" comm<strong>and</strong>.The parameter dumprotation specifies the maximum size threshold of one dumpfile inmegabytes.Specifying "default" as parameter restores the current value to the default value.The minimum of this parameter is 1 (one Megabyte), the maximum 1048576 (one Terabyte)<strong>and</strong> the default value is 1024 (one Gigabyte).Example:# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8191bng# interface eth0interface eth0 successfully attachedbng# interface eth1interface eth1 successfully attachedbng# set dumprotation 100bng# l2switchbng# dump eth1 /databng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set dumprotation 100interface eth0interface eth1dump eth1 /tmpl2switch// end of configurationbng#The example above sets up a transparent bridge between eth0 <strong>and</strong> eth1 <strong>and</strong> dumps all dataon eth1 to the directory /data (e.g. a large volume) with the dumprotation parameter set to100 Megabytes.3.3.17.9 set gratarpremindSynopsis:set gratarpremind |defaultThis parameters specifies an interval in minutes at which additional "reminding" gratuitousARP requests are being sent out by <strong>BalanceNG</strong>. A value of "0" disables this feature (default).If VRRP is active only the current VRRP master will send out additional gratuitous arprequests.Example:# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8194bng# set gratarpremind 30bng# show conf// configuration taken Tue Oct 10 21:39:59 2006Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 76 / 143Grünwald Germany / All Rights Reserved
1. // <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set gratarpremind 30// end of configurationbng#3.3.17.10 set hcportoffsetSynopsis:set hcportoffset |defaultThis parameter controls the offset of the source port being used for tcpopen <strong>and</strong> agenthealth checks. To calculate the source port the target index is simply added to this offset.The minimum of this parameter is 1024 (the first usually non privileged port), the maximum65535 (maximum of unsigned short) <strong>and</strong> the default value is 30000.Example:# /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 8194bng# set hcportoffset 1024bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set hcportoffset 1024// end of configurationbng#3.3.17.11 set ipforwardingSynopsis:set ipforwarding |defaultThis parameter enables IP forwarding if set to 1 <strong>and</strong> disables IP forwarding if set to 0 (which isthe default). If IP forwarding is enabled, <strong>BalanceNG</strong> routes IP packets between all configurednetworks. Packets which are not locally addressable are being forwarded to the defaultgateway (see "gateway") if specified.Network virtual ("virt") addresses should be preferably used as routing destinations sincethose addresses are shared between all nodes of the virtual VRRP router.Example (on a Sun X2100 running Solaris 10):bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set ipforwarding 1interface bge0interface nge0network 1 {addr 10.100.1.0mask 255.255.255.0real 10.100.1.71virt 10.100.1.70interface bge0}network 2 {addr 10.100.2.0<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 77 / 143
mask 255.255.255.0real 10.100.2.71virt 10.100.2.70interface nge0}register networks 1,2enable networks 1,2// end of configurationbng#3.3.17.12 set localdsrSynopsis: set localdsr 0|1This boolean parameter allows if set to 1 operating <strong>BalanceNG</strong> on a target machine itself inDSR mode. Usually <strong>BalanceNG</strong> refuses to represent an IP address which is already presenton one of the local interfaces. If localdsr is set to one this check is exempted for virtual serverIP addresses which then may be present as a local loopback alias at the same time on thesame machine. The localdsr parameter is set to 0 (off) by default.Example:bng# set localdsr 1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)remark "$Id: bng.conf,v 1.1 2007/04/29 13:59:31 root Expset localdsr 1// end of configurationbng#3.3.17.13 set localvirtSynopsis: set localvirt 0|1“set localvirt 1” allows to have “network virt” addresses active on the host operating system atthe same time together with <strong>BalanceNG</strong>. This is required for example if <strong>BalanceNG</strong> operatesas a VRRP daemon attracting traffic to a local interface. This localvirt parameter is set to 0(off) by default.Example:bng# set localvirt 1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)remark "$Id: bng.conf,v 1.1 2007/04/29 13:59:31 root Expset localvirt 1// end of configurationbng#3.3.17.14 set natdlimitSynopsis:set natdlimit |defaultThis parameter controls the maximum number of NAT entries displayed per protocol (TCP,Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 78 / 143Grünwald Germany / All Rights Reserved
UDP) at the “show nat” comm<strong>and</strong>. The default of this parameter is 10.3.3.17.15 set natscanSynopsis:set natscan |defaultThis parameter specifies the number of NAT entries being checked <strong>and</strong> reclaimed per secondon a not busy <strong>BalanceNG</strong> system. The default of this parameter is 10.3.3.17.16 set natsyncSynopsis: set natsync 1|0This boolean parameter enables syncing of NAT table entries from the master to the backup<strong>BalanceNG</strong> node if set to 1 (which is the default).3.3.17.17 set natsyncivSynopsis:set natsynciv |defaultThis parameter controls the interval at which active NAT entries are being re-synced /refreshed between the master <strong>and</strong> the backup <strong>BalanceNG</strong> node (is natsync is enabled <strong>and</strong>set to 1). The default value of this parameter is 10 seconds.3.3.17.18 set nattimeoutSynopsis:set nattimeout |defaultThis parameter controls the lifetime of an unused NAT entry in the <strong>BalanceNG</strong> NAT table inseconds. The default of this parameter is 600 seconds (10 minutes).3.3.17.19 set vrrpmasterdownSynopsis:set vrrpmasterdown |defaultThis parameter controls the time interval in seconds after which a VRRP backup not receivingMaster advertisements will declare the master to be down. This parameter implements the"Master_Down_Interval" of RFC3768 (see Reference /3/).The minimum <strong>and</strong> default of this parameter is 3 seconds, the maximum is10 seconds.Example:bng# set vrrpmasterdown 10bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)remark "$Id: bng.conf,v 1.1 2007/04/29 13:59:31 root Expset {hcportoffset 1024vrrpmasterdown 10}// end of configurationbng#<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 79 / 143
3.3.17.20 set vrrppreemptSynopsis:set vrrppreempt |defaultThis parameter controls whether a higher priority VRRP Backup node preempts a lowerpriority Master. This is a boolean parameter with 1 = TRUE <strong>and</strong> 0 = FALSE. The default ofthis parameter is 0 (preemption *not* active).This parameter implements the parameter "Preempt_Mode" of RFC3768 (see Reference /3/).Here a potentially simpler explanation:If a previously failed VRRP master (with a priority lower than 255) comes back into operation itwill stay gently in background as a VRRP backup node if vrrppreempt equals 0. If vrrppreemptequals 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 ideato set vrrppreempt to 0 at the same time. This allows the new joining node (the previousmaster) to learn back the currently active session table.Note vrrppreempt defaults to 0 <strong>and</strong> sessionsync to 1 for administration convenience (sessionsare being synced per default).Example:bng# set vrrppreempt 0bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)remark "$Id: bng.conf,v 1.1 2007/04/29 13:59:31 root Expset {hcportoffset 1024vrrppreempt 0vrrpmasterdown 10}// end of configurationbng#3.3.17.21 set sendprobesSynopsis:set sendprobes |defaultThis boolean parameter controls whether ARP request probes are sent out periodically toprobe for potential IP address conflict. This parameter is off (0) by default.Example:bng# set sendprobes 1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {hcportoffset 1024sessionscan 2vrrppreempt 1vrrpmasterdown 10sendprobes 1}Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 80 / 143Grünwald Germany / All Rights Reserved
ng#end of configuration3.3.17.22 set sessiondlimitSynopsis:set sessiondlimit |defaultThis parameter controls the number of session table entries being displayed interactively bythe “show session” comm<strong>and</strong>. This parameter has a minimum <strong>and</strong> default of 10, <strong>and</strong> amaximum of 1000 entries.Example:bng# set sessiondlimit 20bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {sessiondlimit 20}// end of configurationbng#3.3.17.23 set sessionscanSynopsis:set sessionscan |defaultThis parameter controls how many sessions are internally scanned <strong>and</strong> tested for timeout persecond. Additionally <strong>BalanceNG</strong> performs the same session timeout test every time a sessionis being looked up in the session table.The minimum is one per second, the maximum is 20 per second, the default is10 persecond.Example:bng# set sessionscan 2bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {hcportoffset 1024sessionscan 2vrrppreempt 1vrrpmasterdown 10}// end of configurationbng#3.3.17.24 set sessionsyncSynopsis:set sessionsync |defaultThis boolean parameter activated session table synchronization <strong>and</strong> state replication from thecurrent active master node to the backup node(s). It has to be set to 1 on both the master <strong>and</strong>the backup to be active.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 81 / 143
The default value of this parameter is 1 (active).Session table synchronization uses a <strong>BalanceNG</strong> specific VRRP extension, where sessiontable information is being broadcasted in a controlled manner (see parameter sessionsyncivbelow).It is recommended to set the parameter vrrppreempt to 0 at the same time sessionsync is setto 1 (both is the default in current <strong>BalanceNG</strong> releases).Example:bng# set sessionsync 1bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {sessionsync 1vrrppreempt 0}// end of configurationbng#3.3.17.25 set sessionsyncivSynopsis:set sessionsynciv |defaultThis parameter controls how often the information of a current actively used session is beingnotified to listening backup nodes (in seconds). The default value is 10 seconds. It could beincreased to lower the number of notification packets in the network.Example:bng# set sessionsynciv 10bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {vrrppreempt 0sessionsync 1sessionsynciv 20}// end of configurationbng#3.3.17.26 set sessiontimeoutSynopsis:set sessiontimeout |defaultThis parameter controls how long a n inactive session is being remembered by <strong>BalanceNG</strong>.After having reached this timeout threshold the session will be removed from the session tableat the next opportunity.The minimum value of this parameter is 10 seconds, the maximum 172800 seconds (48hours). The default value is 600 (10 minutes).Example:bng# set sessiontimeout 60Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 82 / 143Grünwald Germany / All Rights Reserved
ng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)set {sessiontimeout 60hcportoffset 1024sessionscan 2vrrppreempt 1vrrpmasterdown 10}// end of configurationbng#3.3.18 softdisable target Synopsis:softdisable target softdisable targets ,, ...This comm<strong>and</strong> sets one or more specified enabled targets into a special "softdisable" state.Targets in that state are still working for already existing sessions, but no new sessions will beallocated by the load balancing target selection methods.This is very useful for smoothly taking a target machine out of service for maintenance <strong>and</strong>other service activities. As soon as the session count of the target is 0 (displayed at "showtarget ") the target machine can be safely taken into maintenance.A target in "softdisable" state may be taken back into normal load balancing distribution withthe "enable target" comm<strong>and</strong> (e.g. "enable target 1").The softdisable state may be entered administratively during runtime only <strong>and</strong> is not part ofthe configuration <strong>and</strong> the configuration file.Example:bng# show target 1target 1ipaddr 172.17.2.90port anynetwork 1protocol anysessions 381trackval 0status operationalarp upping uppsent 4123bsent 123526prcvd 2345brcvd 213456bng# softdis target 1bng# show target 1target 1ipaddr 172.17.2.90port anynetwork 1<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 83 / 143
protocol anysoftdis *active*sessions 381trackval 0status operationalarp upping uppsent 4234bsent 234454prcvd 3345brcvd 323456bng#3.3.19 targetSynopsis:target This comm<strong>and</strong> is used to configure the parameters of a <strong>BalanceNG</strong> target. In general this isonly possible if the target is in the "unregistered" state (see the server <strong>and</strong> target stateexplanations at the "register" comm<strong>and</strong>).<strong>BalanceNG</strong> is capable of h<strong>and</strong>ling 128 independent targets. Each target may be referenced bythe targets list of a specific server one or multiple times.3.3.19.1 target agentSynopsis:target agent |"off"Activates the agent healthcheck of the specified target using the supplied parameters (orswitches the agent healthcheck off when "off" is supplied).The agent healthcheck communicates with the bngagent UDP protocol with a bngagentprogram running on the physical target machine (see the bngagent chapter for moreinformations).The parameter list consists of three numerical values, separated by commas. The first value isthe UDP port being addressed on the real target machine. The second parameter is theinterval in seconds to perform the agent healthcheck. The third parameter specifies thenumber of seconds with no answer to declare the target inoperational.Example 1 (checking every 10 seconds on port 2000, 30 seconds of missing replies fordeclaring target inoperational):bng# target 1 agent 2000,10,30Example 2 (switching agent healthcheck off):bng# target 1 agent off3.3.19.2 target alertSynopsis:target alert This comm<strong>and</strong> specifies an external script or program which is called or executed as soon<strong>and</strong> every time the associated target gets down or inoperational. The alertscript has to bespecified in double quotes <strong>and</strong> will be executed by a helper thread with the system() C-libraryDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 84 / 143Grünwald Germany / All Rights Reserved
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 managementsystem 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 literallyreplaced once in the string. The symbols <strong>and</strong> their replacements are as follows:Symbol Replacement--------------------------------------------------$ipaddr$ IP address of the target$port$ Port number of the target if specified("0" otherwise)$status$ Healthcheck status$target$ Number of the targetExample:# bng control<strong>BalanceNG</strong>: connected to PID 16624bng# target 1 {bng+ ipaddr 10.1.2.2bng+ ping 2,10bng+ alert "/usr/local/sbin/alertmail $ipaddr$ $target$"bng+ }bng# commit target 13.3.19.3 target aoffsetSynopsis:target aoffset This comm<strong>and</strong> is a synonym for "target offset".3.3.19.4 target ascaleSynopsis:target ascale This comm<strong>and</strong> is a synonym for "target scale".3.3.19.5 target dsrSynopsis:target dsr |"target dsr enable" enables the "Direct Server Return" feature for the specifiedtarget, "target dsr disable" disables the DSR feature.This feature is disabled per default, <strong>and</strong> not shown in the config file if disabled.If DSR is enabled for the specified target packets to a virtual server are forwarded to thetarget Layer 2 address with the virtual server destination IP address unchanged. The virtualserver address has to be added as an alias to the Loopback ("lo") Interface of the Targetmachine.Example:<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 85 / 143
ng# target 1 {bng+ ipaddr 10.1.1.4bng+ port 80bng+ protocol tcpbng+ tcpopen 80,3,10bng+ dsr enablebng+ }3.3.19.6 target ipaddrSynopsis:target ipaddr This specifies the IP address of the target with the specified index .Example:bng# target 2 ipaddr 10.1.1.3bng# target 3 {bng+ ipaddr 10.1.1.4bng+ }3.3.19.7 target maxagentSynopsis:target maxagent |0This comm<strong>and</strong> assigns a maximum score threshold for target <strong>and</strong> works together with the“agent” directive. If a target total <strong>and</strong> absolute agent score exceeds the supplied threshold thisparticular target is silently taken out of the current load balancing distribution. A value of 0(default) sets this threshold to “unlimited”.Example:bng# target 2 maxagent 2000bng#3.3.19.8 target maxsessionsSynopsis:target maxagent |0This comm<strong>and</strong> assigns a maximum session threshold for target . If a target total <strong>and</strong>absolute number of sessions exceeds the supplied threshold this particular target is silentlytaken out of the current load balancing distribution. A value of 0 (default) sets this threshold to“unlimited”.Example:bng# target 2 maxsessions 2000bng#3.3.19.9 target nameSynopsis:target name |"none"Assigns a target a name for informational purposes. The string "none" as the namearguments deletes the name from the specified 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 definition.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 86 / 143Grünwald Germany / All Rights Reserved
Example:bng# edit target 1bng# target 1 name test-target-1bng# commit target 1WARNING: target 1 in enabled state but not referencedbng# show targets# ipaddr port prt net srv status name-----------------------------------------------------------------1 10.1.1.3 any any 2 0 down test-target-1bng#3.3.19.10 target offsetSynopsis:target offset This comm<strong>and</strong> allows together with "target ascale" the modification of the returnvalue of bngagent by applying a linear function to it. This function looks like this: = * + The aoffset parameter has a default of 0 (where it is not displayed in the configuration file).The ascale parameter has a default of 1.0 (also not being displayed).Both aoffset <strong>and</strong> ascale always have to be positive. If the unsigned integer return value isbeing 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 smaller than the less powerfulmachines.• A less powerful machine which should e.g. not be used from the very beginning should besupplied with a aoffset > 0. A machine with the default aoffset of 0 takes will receivetraffic / load from the very beginning.The following example shows how easily the effective agent value may be modified byapplying ascale <strong>and</strong> aoffset parameters. This together with the agent distribution methodallows a very expressive optimization of load distribution even to very different machines.Example:root@bng1:~ # /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 722bng# show target 1target 1ipaddr 10.1.1.1port anynetwork 2protocol anystatus operationalarp upagent 4eff_agent 4bng# edit target 1bng# target 1 scale 2.0bng# commit target 1WARNING: target 1 in enabled state but not referenced<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 87 / 143
ng# show target 1target 1ipaddr 10.1.1.1port anynetwork 2protocol anystatus operationalarp upagent 2eff_agent 4bng# edit target 1bng# target 1 offset 10bng# commit target 1WARNING: target 1 in enabled state but not referencedbng# show target 1target 1ipaddr 10.1.1.1port anynetwork 2protocol anystatus operationalarp upagent 1eff_agent 12bng#3.3.19.11 target pingSynopsis:target ping |"off"Activated the ping healthcheck of the target or switches it off (by supplying "off"). Theparameters consist of two values, separated by a comma. The first value is the interval inseconds to send an ICMP echo request packet to the target. The second value is the time todeclare a target inoperational if no ICMP echo response packet is received in that time.Example:bng# target 2 ipaddr 10.1.1.2bng# target 2 ping 2,10bng# commit target 2bng# show target 2target 2ipaddr 10.1.1.2port anynetwork 2protocol anystatus operationalarp upping upbng#3.3.19.12 target portSynopsis:target port |"any"Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 88 / 143Grünwald Germany / All Rights Reserved
With this comm<strong>and</strong> a specific port can be associated to a target. Supplying "any" reverts thisback to "any" port. An associated port of a target restricts load balancing actions to this port<strong>and</strong> allows TCP <strong>and</strong> UDP port translation (server uses different port than the associatedtarget).Together with the "target protocol" comm<strong>and</strong> the load balancing actions may beadditionally restricted to just one protocol family on that port (TCP or UDP).Example:bng# target 4 ipaddr 10.1.1.5bng# target 4 port 8080bng# target 4 protocol tcpbng# target 4 ping 2,20bng# target 4 tcpopen 8080,5,20bng# commit target 4WARNING: target 4 in enabled state but not referencedbng# show target 4target 4ipaddr 10.1.1.5port 8080network 2protocol tcpstatus downarp downping downtcpopen downbng#3.3.19.13 target protocolSynopsis:target protocol "tcp"|"udp"|"any"Restricts load balancing participation of the specified target either to TCP or to UDP (orreverts back to the default of any protocol by specifying "any").Together with "target port" the matching rules may be restricted to packets from aspecific port <strong>and</strong> protocol.Example:bng# target 4 protocol tcpbng# commit target 43.3.19.14 target scaleSynopsis:target ascale This target parameter allows together with aoffset the modification of the bngagent returnvalue in terms of a linear function. Please see the more detailed explanation <strong>and</strong> example atthe "target aoffset" comm<strong>and</strong>.Example:bng# edit target 1bng# target 1 scale 2.0bng# commit target 1<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 89 / 143
WARNING: target 1 in enabled state but not referencedbng# show target 1target 1ipaddr 10.1.1.1port anynetwork 2protocol anystatus operationalarp upagent 2eff_agent 4bng# show conf// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0interface eth1network 1 {addr 10.55.55.0mask 255.255.255.0real 10.55.55.190virt 10.55.55.191interface eth0}network 2 {addr 10.1.1.0mask 255.255.255.0real 10.1.1.190virt 10.1.1.191interface eth1}register networks 1,2enable networks 1,2target 1 {ipaddr 10.1.1.1agent 5000,5,0offset 10scale 2}register target 1enable target 1// end of configurationbng#3.3.19.15 target scriptSynopsis:target script ,,This comm<strong>and</strong> specifies an external health check script which will be called at the giveninterval in seconds. If the script returns with an exit code not equal to zero (0) or if theinvocation of that script fails or if that script does not return within the specified timeout thetarget status will change to "inoperational" or "down".The script is being executed by a helper thread using the system() library function. TheDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 90 / 143Grünwald Germany / All Rights Reserved
external script is not aware of the TCP/IP stack of <strong>BalanceNG</strong> <strong>and</strong> operates under the hostoperating system as usual.With that mechanism arbitrary any custom health check method can be interfaced orimplemented easily.Before the healthcheckscript string is passed to system() a set of symbols or variables isliterally replaced once in the string. The symbols <strong>and</strong> their replacements are as follows:Symbol Replacement--------------------------------------------------$ipaddr$ IP address of the target$port$ Port number of the target if specified("0" otherwise)$target$ Number of the targetMany different programs can be easily interfaced that way (e.g. "ping", "wget, "mon") or anyother custom script or program.Example:This example calls an external monitor script to implement a HTTP lookup of a specific URL(http.monitor from the "mon" package, available at http://www.kernel.org/software/mon). Thescript is called every two seconds, the target gets inoperational/down if the script fails (returnssomething else than 0) or if it does not return within 7 seconds.# ./bng control<strong>BalanceNG</strong>: connected to PID 16624bng# edit target 1bng# target 1 script "/usr/lib/mon/mon.d/http.monitor -p $port$ -u/healtcheck.cgi $ipaddr$",2,7bng# commit target 13.3.19.16 target tcpopenSynopsis:target tcpopen |"off"Activates a simple TCP open healthcheck (or switches it of with "off"). The parameter listexpects three numeric parameters separated by commas: The first is the actual port to test(which may be different than the target load balancing port), the second is the interval to checkin seconds <strong>and</strong> the third is the interval to declare the target down when no response isreceived in that period.Example:bng# edit target 4bng# target 4 tcpopen 80,2,10bng# commit target 4bng#3.3.19.17 target upalertSynopsis: target upalert This comm<strong>and</strong> specifies an external script or program which is called or executed as soon<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 91 / 143
<strong>and</strong> every time the associated target gets "up" or operational. The upalertscript has to bespecified in double quotes <strong>and</strong> will be executed by a helper thread with the system() C-libraryfunction 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 managementsystem 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 literallyreplaced once in the string. The symbols <strong>and</strong> their replacements are as follows:Symbol Replacement--------------------------------------------------$ipaddr$ IP address of the target$port$ Port number of the target if specified("0" otherwise)$status$ Healthcheck status$target$ Number of the targetExample:# bng control<strong>BalanceNG</strong>: connected to PID 16627bng# target 1 {bng+ ipaddr 10.1.2.2bng+ ping 2,10bng+ upalert "/usr/local/sbin/upmail $ipaddr$ $target$"bng+ }bng# commit target 13.3.19.18 target trackvalSynopsis:target trackval This comm<strong>and</strong> associates a tracking value to the target. The default of this value is 0. If VRRPtracking is enabled <strong>and</strong> the VRRP priority is less than 255 <strong>and</strong> a target is enabled <strong>and</strong> down(not operational) the current VRRP priority is degraded by the tracking value "trackval" of thetarget.Example:bng# show target 1target 1ipaddr 172.17.2.90port anynetwork 1protocol anysessions 0trackval 0status operationalarp upping upbng# edit target 1bng# target 1 trackval 4bng# commit target 1Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 92 / 143Grünwald Germany / All Rights Reserved
ng# show target 1target 1ipaddr 172.17.2.90port anynetwork 1protocol anysessions 0trackval 4status operationalarp upping upbng#3.3.19.19 target weightSynopsis:target weight This comm<strong>and</strong> associates a certain weight to a target, which is valid if the server distributionmethod “r<strong>and</strong>om” is used. The default weight of a target is 1 <strong>and</strong> is not displayed on “showconf”. A target weight is valid in the range of 1-100 inclusively <strong>and</strong> may reflect a percentagevalue.The following examples instructs <strong>BalanceNG</strong> to choose direct 75% of new sessions to target 2<strong>and</strong> 25% of new sessions to target 1 (if target 1 <strong>and</strong> 2 are being referenced by a server withdistribution method “r<strong>and</strong>om”).Example:bng# target 1 weight 10bng# target 2 weight 30bng# commit targets 1,2bng#3.3.20 tnatSynopsis:tnat This comm<strong>and</strong> specifies selectively 1:1 Network Address Translation (NAT) for a specificdestination port <strong>and</strong> protocol. This comm<strong>and</strong> is revertable using the "no" special comm<strong>and</strong>.The "target addr" should be the address of a target. The "localnet addr" should be anexclusively reserved address in the "localnet" (one reservation / allocation per tnat-entry). Theparameter "protocol" may be either "udp" or "tcp". The destination port has to be suppliedspecifically.This comm<strong>and</strong> allows the target to communicate to the "outside" world by NATting its addressto the specified address in the localnet if <strong>and</strong> only if the given protocol <strong>and</strong> port matches.Note: Another common used approach to offer outbound connectivity for the targets would bethe declaration of a server reversely to offer services to the targets.Common uses are e.g. HTTP-requests from the targets to the "Internet" or DNS queries to aDNS server in a local network.The Addresses of all tnat-entries are represented by all <strong>BalanceNG</strong> nodes with the same vrid(Virtual Router Identifier), existing outbound connections from targets via "tnat" will thereforesurvive any VRRP master switchover.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 93 / 143
Different port/protocol tuples may be translated to the same localnet address.Example:bng# tnat 10.1.1.1 192.168.1.230 tcp 22bng# tnat 10.1.1.1 192.168.1.230 udp 53bng# show vrrpstate MASTERvrid 1priority 255ip00 192.168.1.222ip01 192.168.1.230ip02 10.1.1.2543.3.21 unregisterSynopsis:unregister This is the counterpart comm<strong>and</strong> to the "register" comm<strong>and</strong>. Please see the more detailedstate explanations there.This comm<strong>and</strong> is used to transfer one or more targets or servers from the "registered" state tothe "unregistered" state. Target <strong>and</strong> server parameters <strong>and</strong> configurations can only bechanged in the "unregistered" state.Example:bng# unregister target 1bng# unregister servers 1,23.3.22 vipSynopsis:vip This comm<strong>and</strong> instructs <strong>BalanceNG</strong> to represent a virtual IP address by answering to ARPrequests <strong>and</strong> ICMP ECHO ("ping") requests. An ip address defined that way participates inVRRP failover.Usually all needed virtual IP addresses are managed by <strong>BalanceNG</strong> internally <strong>and</strong> do notappear in the configuration file.This comm<strong>and</strong> may be useful for representing another routing endpoint, but is probably rarelyused.Example:bng# vip 10.2.2.3bng# show conf// configuration taken Tue Oct 10 21:39:59 20061. // <strong>BalanceNG</strong> 1.840 (created 2007/04/29)vip 10.2.2.3// end of configurationbng#3.3.23 vrrpSynopsis:vrrp Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 94 / 143Grünwald Germany / All Rights Reserved
This comm<strong>and</strong> allows the configuration of the VRRP parameters. VRRP becomes activated assoon as all three VRRP parameters are defined (vrid, priority <strong>and</strong> network).Using a "{" as a second argument opens a vrrp block which can be closed interactively byentering a "}" or an empty line.Example:bng# vrrp vrid 1bng# vrrp priority 255bng# vrrp network 3bng# show vrrpstate MASTERvrid 1priority 255ip00 192.168.1.10bng#3.3.23.1 vrrp bscriptSynopsis:vrrp bscript This setting defines an external notification script or program which is called if the VRRPvirtual router enters the BACKUP state. The script is executed in background by a separatehelper thread. Setting the script parameter to nothing (“”) disables this setting.Example:NodeA# show vrrpstate MASTERvrid 14priority 200tracking priority not degradedipaddr0 172.17.2.64NodeA# vrrp bscript "/home/tools/backup_notify"NodeA# show vrrpstate MASTERvrid 14priority 200tracking priority not degradedbscript "/home/tools/vrrp_backup_notify"ipaddr0 172.17.2.64NodeA#3.3.23.2 vrrp mscriptSynopsis:vrrp mscript This setting defines an external MASTER state notification script accordingly to “vrrp bscript”.The script is called when <strong>BalanceNG</strong> enters the MASTER VRRP state. Setting the scriptparameter to nothing (“”) disables this setting again.Example:NodeA# show vrrpstate MASTERvrid 14<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 95 / 143
priority 200tracking priority not degradedbscript "/home/tools/backup_notify"ipaddr0 172.17.2.64NodeA# vrrp mscript "/home/tools/master_notify"NodeA# show vrrpstate MASTERvrid 14priority 200tracking priority not degradedmscript "/home/tools/master_notify"bscript "/home/tools/backup_notify"ipaddr0 172.17.2.64NodeA#3.3.23.3 vrrp networkSynopsis:vrrp network This defines the Network which will be used for VRRP communications. The following networkparameters 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 comm<strong>and</strong> may be usedas usual (there's no requirement to define an explicit VRRP only network).Example:bng# vrrp network 3bng# show vrrpstate MASTERvrid 1priority 255ip00 192.168.1.10bng#3.3.23.4 vrrp prioritySynopsis:vrrp priority |noneSets the priority of the VRRP node to the specified value (or to unspecified if "none" issupplied). The priority must be in the range 1-255. The VRRP master priority is 255, thedefault backup node priority is 100.Example1 (declare node to become VRRP master):bng# vrrp vrid 1bng# vrrp priority 255bng# vrrp network 3Example2 (declare node to be a backup router with the default backup priority of 100):bng# vrrp vrid 1bng# vrrp priority 100Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 96 / 143Grünwald Germany / All Rights Reserved
ng# vrrp network 33.3.23.5 vrrp trackingSynopsis:vrrp tracking enablevrrp tracking disablevrrp tracking defaultThis comm<strong>and</strong> enables or disables VRRP tracking, respectively. VRRP tracking is disabled bydefault. If VRRP tracking is enabled <strong>and</strong> the VRRP priority is below 255 (which would be theso called "VRRP address owner") then the VRRP is degraded by the sum of all trackingvalues (see "target trackval" <strong>and</strong> "gateway trackval") of all objects (targets orgateway) which are both enabled <strong>and</strong> down/inoperational.With VRRP tracking a controlled failover to the backup <strong>BalanceNG</strong> node can be specified incase that the current master node loses connectivity to important objects which are stillreachable <strong>and</strong> accessible by the backup node.Example:bng# vrrp priority 100bng# vrrp network 1bng# vrrp vrid 1bng# show vrrpstate MASTERvrid 1priority 100tracking disabled (default)ip00 172.17.2.189bng# vrrp tracking enablebng# show vrrpstate MASTERvrid 1priority 100tracking enabledlocal priority not degradedip00 172.17.2.189bng#3.3.23.6 vrrp vridSynopsis:vrrp vrid |noneSpecifies the Virtual Router Identifier of the Virtual Router of this node. All nodes in the samesubnet 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 "unspecified"<strong>and</strong> such disables VRRP operation. See Reference /3/ for more Information about the VRRPprotocol.Example:bng# vrrp vrid 1bng# vrrp priority 255bng# vrrp network 3<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 97 / 143
Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 98 / 143Grünwald Germany / All Rights Reserved
4 SNMP Support<strong>BalanceNG</strong> supports SNMP by interfacing to the Net-SNMP server <strong>and</strong> comes with its ownManagement Information Base (MIB). This file is part of the distribution, is part of thisdocument <strong>and</strong> may also be downloaded separately from the documentation area on the<strong>BalanceNG</strong> website.<strong>BalanceNG</strong> supports read only SNMP access only, traps my be set out by calling snmptrap orsnmp_trapsend from "alert" <strong>and</strong> "upalert" target configurations.The <strong>BalanceNG</strong> MIB is located in the enterprise specific subtree of Inlab <strong>Software</strong> GmbH at:iso(1).org(3).dod(6).internet(1).private(4).enterprises(1).Inlab(2771).<strong>BalanceNG</strong>(1).4.1 Interfacing to Net-SNMPAn installed Net-SNMP software is required for interfacing to <strong>BalanceNG</strong>. This modern SNMPsystem is part of almost all current Linux systems <strong>and</strong> is st<strong>and</strong>ard also on Solaris 10.Further information is available at the Net-SNMP website at this URL:http://net-snmp.sourceforge.net/Interfacing to Net-SNMP on the <strong>BalanceNG</strong> host machine (the machine where <strong>BalanceNG</strong>runs on) consists of the following steps (you may leave out Step 2 for a Net-SNMP clientmachine):Step 1: Copying the <strong>BalanceNG</strong> MIB fileThe file BALANCENG-MIB.txt has to be copied to the Net-SNMP MIB file location, thedirectory may be found at the following locations:Linux:Solaris 10:Step 2: Changing snmpd.conf/usr/share/snmp/mibs/etc/sma/snmp/mibsThe <strong>BalanceNG</strong> binary itself represents the interface to Net-SNMP using the Net-SNMP"pass" interface (<strong>and</strong> using a separate thread internally). To activate this SNMP interface justadd the following line to the Net-SMNPD configuration file (change the bng path if necessary):pass .1.3.6.1.4.1.2771.1 /usr/sbin/bngThe location if the snmpd.conf file is here:Linux:Solaris 10:/etc/snmp/etc/sma/snmpIf Net-SNMP is not yet configured on your system you may use a minimal snmpd.conf file likethis:syslocation Anywheresyscontact Mr. Nobodysysservices 12rocommunity publicagentuser nobodyagentaddress 161# <strong>BalanceNG</strong> interface<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 99 / 143
pass .1.3.6.1.4.1.2771.1 /usr/sbin/bngStep 3: Creating snmp.confIn order to make the SNMP user comm<strong>and</strong>s aware of the additional MIB it's recommended toadd the following line to snmp.conf (or create the file if not yet present):Linux file location:Line to add:/etc/snmp/snmp.confmibfile /usr/share/snmp/mibs/BALANCENG-MIB.txtSolaris 10 file location:Line to add:/etc/sma/snmp/snmp.confmibfile /etc/sma/snmp/mibs/BALANCENG-MIB.txt4.2 Accessing the SNMP interface directlyThe following comm<strong>and</strong> line options are used to access the <strong>BalanceNG</strong> MIB objects:-g GET the specified OID-n GET the next OID starting from the specified OID-s SET the OID to the specified value (not supported with bng)An optional -i parameter allows to specify the <strong>BalanceNG</strong> instance if it is different from 0.-i Example:The following simple shell script retrieves the current state of the VRRP using that interface:#!/bin/shVALUE=`/usr/bin/bng -g .1.3.6.1.4.1.2771.1.21 | tail -1`case $VALUE in0) STATE="OFF" ;;1) STATE="INITIALIZE" ;;2) STATE="MASTER" ;;3) STATE="BACKUP" ;;*) STATE="UNKNOWN" ;;esacecho "VRRP state is $STATE"4.3 Testing with snmpget <strong>and</strong> snmpwalkThe installation may be tested by issuing snmpget <strong>and</strong> snmpwalk comm<strong>and</strong>s on a clientmachine (which my be the <strong>BalanceNG</strong> node itself):Example:To return the number of current sessions from <strong>BalanceNG</strong> node "castor" you may enter thefollowing on a Solaris 10 system:# /usr/sfw/bin/snmpget -v1 -c public castor BALANCENG-MIB::SessionsBALANCENG-MIB::Sessions = Gauge32: 1128#Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 100 / 143Grünwald Germany / All Rights Reserved
There are 1128 current sessions active.Example:To "walk" the entire current active <strong>BalanceNG</strong> MIB of node "pollux" you may enter thefollowing:# /usr/sfw/bin/snmpwalk -v1 -c public pollux <strong>BalanceNG</strong>BALANCENG-MIB::<strong>Release</strong> = STRING: "1.503"BALANCENG-MIB::NodeId = STRING: "ba:e9:75:24:34:ab"BALANCENG-MIB::LicenseStatus = INTEGER: full(2)BALANCENG-MIB::SerialNumber = STRING: "betaB048"BALANCENG-MIB::Hostname = ""BALANCENG-MIB::Uptime = Timeticks: (186300) 0:31:03.00BALANCENG-MIB::L2Switch = INTEGER: disabled(0)BALANCENG-MIB::Remark = STRING: "test configuration, DSR to onetarget"BALANCENG-MIB::Sessions = Gauge32: 0BALANCENG-MIB::GatewayIPAddr = IpAddress: 172.17.2.254BALANCENG-MIB::GatewayArpInterval = INTEGER: 0BALANCENG-MIB::GatewayArpTimeout = INTEGER: 0BALANCENG-MIB::GatewayPingInterval = INTEGER: 2BALANCENG-MIB::GatewayPingTimeout = INTEGER: 10BALANCENG-MIB::GatewayTrackval = INTEGER: 4BALANCENG-MIB::GatewayStatus = INTEGER: operational(2)BALANCENG-MIB::VRRPVrid = INTEGER: 0BALANCENG-MIB::VRRPPriority = INTEGER: 0BALANCENG-MIB::VRRPNetwork = INTEGER: 0BALANCENG-MIB::VRRPTracking = INTEGER: unspecified(0)BALANCENG-MIB::VRRPStatus = INTEGER: off(0)BALANCENG-MIB::InterfaceIndex.1 = INTEGER: 1BALANCENG-MIB::InterfaceName.1 = STRING: "eth0"BALANCENG-MIB::InterfaceDumpDirectory.1 = ""BALANCENG-MIB::InterfaceDumpBytes.1 = Counter32: 0BALANCENG-MIB::InterfaceSentPackets.1 = Counter32: 3660BALANCENG-MIB::InterfaceSentBytes.1 = Counter32: 410959BALANCENG-MIB::InterfaceReceivedPackets.1 = Counter32: 8465BALANCENG-MIB::InterfaceReceivedBytes.1 = Counter32: 1306625BALANCENG-MIB::NetworkIndex.1 = INTEGER: 1BALANCENG-MIB::NetworkStatus.1 = INTEGER: enabled(1)BALANCENG-MIB::NetworkName.1 = ""BALANCENG-MIB::NetworkAddr.1 = IpAddress: 172.17.2.0BALANCENG-MIB::NetworkMask.1 = IpAddress: 255.255.255.0BALANCENG-MIB::NetworkReal.1 = IpAddress: 172.17.2.188BALANCENG-MIB::NetworkVirt.1 = IpAddress: 0.0.0.0BALANCENG-MIB::NetworkInterfaces.1 = STRING: "eth0"BALANCENG-MIB::ServerIndex.1 = INTEGER: 1BALANCENG-MIB::ServerStatus.1 = INTEGER: enabled(1)BALANCENG-MIB::ServerName.1 = ""BALANCENG-MIB::ServerIpAddr.1 = IpAddress: 172.17.2.189BALANCENG-MIB::ServerPort.1 = INTEGER: 22BALANCENG-MIB::ServerPort2.1 = INTEGER: 0BALANCENG-MIB::ServerProtocol.1 = INTEGER: any(0)BALANCENG-MIB::ServerMethod.1 = INTEGER: rr(0)BALANCENG-MIB::ServerPortrel.1 = INTEGER: off(0)BALANCENG-MIB::ServerFailover.1 = INTEGER: normal(0)BALANCENG-MIB::ServerTargetlist.1 = STRING: "1"BALANCENG-MIB::ServerBackuplist.1 = ""BALANCENG-MIB::ServerSessions.1 = Gauge32: 0BALANCENG-MIB::ServerSentPackets.1 = INTEGER: 1815BALANCENG-MIB::ServerSentBytes.1 = INTEGER: 233177BALANCENG-MIB::ServerReceivedPackets.1 = INTEGER: 0BALANCENG-MIB::ServerReceivedBytes.1 = INTEGER: 0BALANCENG-MIB::TargetIndex.1 = INTEGER: 1BALANCENG-MIB::TargetStatus.1 = INTEGER: operational(2)BALANCENG-MIB::TargetName.1 = ""BALANCENG-MIB::TargetIpAddr.1 = IpAddress: 172.17.2.90BALANCENG-MIB::TargetPort.1 = INTEGER: 0BALANCENG-MIB::TargetProtocol.1 = INTEGER: any(0)BALANCENG-MIB::TargetDSR.1 = INTEGER: enabled(1)BALANCENG-MIB::TargetSoftdisable.1 = INTEGER: inactive(0)BALANCENG-MIB::TargetTrackval.1 = INTEGER: 0BALANCENG-MIB::TargetAgentPort.1 = INTEGER: 0BALANCENG-MIB::TargetAgentInterval.1 = INTEGER: 0BALANCENG-MIB::TargetAgentTimeout.1 = INTEGER: 0BALANCENG-MIB::TargetAgentOffset.1 = INTEGER: 0BALANCENG-MIB::TargetAgentScale.1 = STRING: "1"BALANCENG-MIB::TargetPingInterval.1 = INTEGER: 2BALANCENG-MIB::TargetPingTimeout.1 = INTEGER: 3BALANCENG-MIB::TargetTcp<strong>Open</strong>Port.1 = INTEGER: 0BALANCENG-MIB::TargetTcp<strong>Open</strong>Interval.1 = INTEGER: 0BALANCENG-MIB::TargetTcp<strong>Open</strong>Timeout.1 = INTEGER: 0BALANCENG-MIB::TargetScript.1 = ""BALANCENG-MIB::TargetScriptInterval.1 = INTEGER: 0BALANCENG-MIB::TargetScriptTimeout.1 = INTEGER: 0BALANCENG-MIB::TargetAlertScript.1 = ""BALANCENG-MIB::TargetUpalertScript.1 = ""BALANCENG-MIB::TargetSessions.1 = Gauge32: 0BALANCENG-MIB::TargetSentPackets.1 = Counter32: 0BALANCENG-MIB::TargetSentBytes.1 = Counter32: 0BALANCENG-MIB::TargetReceivedPackets.1 = Counter32: 1877BALANCENG-MIB::TargetReceivedBytes.1 = Counter32: 240799BALANCENG-MIB::ParameterName.1 = STRING: "dumprotation"BALANCENG-MIB::ParameterName.2 = STRING: "sessiontimeout"BALANCENG-MIB::ParameterName.3 = STRING: "arplookup"BALANCENG-MIB::ParameterName.4 = STRING: "arprefresh"BALANCENG-MIB::ParameterName.5 = STRING: "arptimeout"BALANCENG-MIB::ParameterName.6 = STRING: "hcportoffset"BALANCENG-MIB::ParameterName.7 = STRING: "sessionscan"BALANCENG-MIB::ParameterName.8 = STRING: "vrrppreempt"BALANCENG-MIB::ParameterName.9 = STRING: "vrrpmasterdown"BALANCENG-MIB::ParameterName.10 = STRING: "gratarpremind"BALANCENG-MIB::ParameterName.11 = STRING: "ipforwarding"BALANCENG-MIB::ParameterMin.1 = INTEGER: 1BALANCENG-MIB::ParameterMin.2 = INTEGER: 60BALANCENG-MIB::ParameterMin.3 = INTEGER: 5BALANCENG-MIB::ParameterMin.4 = INTEGER: 60BALANCENG-MIB::ParameterMin.5 = INTEGER: 60BALANCENG-MIB::ParameterMin.6 = INTEGER: 1024BALANCENG-MIB::ParameterMin.7 = INTEGER: 1BALANCENG-MIB::ParameterMin.8 = INTEGER: 0BALANCENG-MIB::ParameterMin.9 = INTEGER: 3BALANCENG-MIB::ParameterMin.10 = INTEGER: 0BALANCENG-MIB::ParameterMin.11 = INTEGER: 0BALANCENG-MIB::ParameterMax.1 = INTEGER: 1BALANCENG-MIB::ParameterMax.2 = INTEGER: 60BALANCENG-MIB::ParameterMax.3 = INTEGER: 5BALANCENG-MIB::ParameterMax.4 = INTEGER: 60BALANCENG-MIB::ParameterMax.5 = INTEGER: 60BALANCENG-MIB::ParameterMax.6 = INTEGER: 1024BALANCENG-MIB::ParameterMax.7 = INTEGER: 1BALANCENG-MIB::ParameterMax.8 = INTEGER: 0BALANCENG-MIB::ParameterMax.9 = INTEGER: 3BALANCENG-MIB::ParameterMax.10 = INTEGER: 0BALANCENG-MIB::ParameterMax.11 = INTEGER: 0BALANCENG-MIB::ParameterDefault.1 = INTEGER: 1024BALANCENG-MIB::ParameterDefault.2 = INTEGER: 600BALANCENG-MIB::ParameterDefault.3 = INTEGER: 10BALANCENG-MIB::ParameterDefault.4 = INTEGER: 120BALANCENG-MIB::ParameterDefault.5 = INTEGER: 300BALANCENG-MIB::ParameterDefault.6 = INTEGER: 30000BALANCENG-MIB::ParameterDefault.7 = INTEGER: 10BALANCENG-MIB::ParameterDefault.8 = INTEGER: 1BALANCENG-MIB::ParameterDefault.9 = INTEGER: 3BALANCENG-MIB::ParameterDefault.10 = INTEGER: 0BALANCENG-MIB::ParameterDefault.11 = INTEGER: 0BALANCENG-MIB::ParameterCurrent.1 = INTEGER: 1024BALANCENG-MIB::ParameterCurrent.2 = INTEGER: 600BALANCENG-MIB::ParameterCurrent.3 = INTEGER: 10BALANCENG-MIB::ParameterCurrent.4 = INTEGER: 120BALANCENG-MIB::ParameterCurrent.5 = INTEGER: 300BALANCENG-MIB::ParameterCurrent.6 = INTEGER: 30000BALANCENG-MIB::ParameterCurrent.7 = INTEGER: 10BALANCENG-MIB::ParameterCurrent.8 = INTEGER: 1BALANCENG-MIB::ParameterCurrent.9 = INTEGER: 3BALANCENG-MIB::ParameterCurrent.10 = INTEGER: 0BALANCENG-MIB::ParameterCurrent.11 = INTEGER: 0#4.4 MRTG relevant metricsThe following metrics would be relevant for collecting with MRTG:Sessions (Gauge)1.3.6.1.4.1.2771.1.9Number of current total session table entries<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 101 / 143
InterfaceSentPackets1.3.6.1.4.1.2771.1.40.5.XNumber of packets sent out on this interfaceInterfaceSentBytes1.3.6.1.4.1.2771.1.40.6.XNumber of bytes sent out on this interfaceInterfaceReceivedPackets1.3.6.1.4.1.2771.1.40.7.XNumber of packets received on this interfaceInterfaceReceivedBytes1.3.6.1.4.1.2771.1.40.8.XNumber of bytes received on this interfaceServerSessions (Gauge)1.3.6.1.4.1.2771.1.60.13.XCurrent number of virtual server sessions, defined to bethe sum of the sessions of all associated targetsServerSentPackets1.3.6.1.4.1.2771.1.60.14.XNumber of packets sent to the clients, defined to be the sum ofpackets being received from all associated targetsServerSentBytes1.3.6.1.4.1.2771.1.60.15 XNumber of bytes sent to the clients, defined to be the sum ofbytes being received from all associated targetsServerReceivedPackets1.3.6.1.4.1.2771.1.60.16 XNumber of packets received from the clients by this virtualserver, defined to be the sum of packets being sent to allassociated targetsServerReceivedBytes1.3.6.1.4.1.2771.1.60.17.XNumber of bytes received from the clients by this virtual server,defined to be the sum of bytes being sent to all associatedtargetsTargetSessions (Gauge)1.3.6.1.4.1.2771.1.70.25.XCurrent number of target (real server) sessionsTargetSentPackets1.3.6.1.4.1.2771.1.70.26.XNumber of packets sent to target (real server)TargetSentBytesDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 102 / 143Grünwald Germany / All Rights Reserved
1.3.6.1.4.1.2771.1.70.27.XNumber of bytes received from target (real server)TargetReceivedPackets1.3.6.1.4.1.2771.1.70.28.XNumber of packets received from target (real server)TargetReceivedBytes1.3.6.1.4.1.2771.1.70.29.XNumber of bytes received from target (real server)TargetAgentData (Gauge)1.3.6.1.4.1.2771.1.70.30.XPerformance data as returned from bngagent feedback agentTargetTotalB<strong>and</strong>width (Gauge)1.3.6.1.4.1.2771.1.70.31.XCurrent total b<strong>and</strong>width of target in bytes per secondTargetIncomingB<strong>and</strong>width (Gauge)1.3.6.1.4.1.2771.1.70.32.XCurrent incoming b<strong>and</strong>width of target in bytes per secondTargetOutgoingB<strong>and</strong>width (Gauge)1.3.6.1.4.1.2771.1.70.33.XCurrent outgoing b<strong>and</strong>width of target in bytes per second4.5 The <strong>BalanceNG</strong> MIB-- COPYRIGHT NOTICE-- Copyright (C) 2006,2007 by Inlab <strong>Software</strong> GmbH, Gruenwald,Germany.-- All rights reserved / Alle Rechte vorbehalten.-- $Id: BALANCENG-MIB.txt,v 1.45 2007/04/11 13:41:17 tommy Exp $-- BALANCENG-MIB { iso(1) org(3) dod(6) internet(1) private(4)-- enterprises(1) Inlab(2771) }BALANCENG-MIB DEFINITIONS ::= BEGINIMPORTS MODULE-IDENTITY, enterprises FROM RFC1155-SMIDisplayStringFROM RFC1213-MIBOBJECT-TYPEFROM RFC-1212TRAP-TYPEFROM RFC-1215;InlabMODULE-IDENTITYLAST-UPDATED "200604010000Z"ORGANIZATION "Inlab <strong>Software</strong> GmbH, http://www.inlab.de"CONTACT-INFO"Inlab <strong>Software</strong> GmbHJosef-Wuerth-Str. 382031 GruenwaldGermany"DESCRIPTION"Top-Level of the Inlab enterprise MIB tree"::= { enterprises 2771 }<strong>BalanceNG</strong> OBJECT IDENTIFIER ::= { Inlab 1 }<strong>Release</strong> OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"release of running <strong>BalanceNG</strong> program"::= { <strong>BalanceNG</strong> 1 }NodeId OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"NodeId of <strong>BalanceNG</strong> host"::= { <strong>BalanceNG</strong> 2 }LicenseStatus OBJECT-TYPESYNTAX INTEGER {unlicensed(0),promotional(1),full(2)}ACCESS read-onlySTATUS currentDESCRIPTION"Current licensing Status"::= { <strong>BalanceNG</strong> 3 }SerialNumber OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"<strong>BalanceNG</strong> license serial number"::= { <strong>BalanceNG</strong> 4 }Hostname OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"hostname of <strong>BalanceNG</strong> instance (hostname configurationkeyword)"::= { <strong>BalanceNG</strong> 5 }Uptime OBJECT-TYPESYNTAX TimeTicksACCESS read-onlySTATUS currentDESCRIPTION"<strong>BalanceNG</strong> uptime in 1/100 seconds"::= { <strong>BalanceNG</strong> 6 }L2Switch OBJECT-TYPESYNTAX INTEGER {disabled(0),enabled(1)}ACCESS read-onlySTATUS currentDESCRIPTION"l2switch mode, enabled if active"<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 103 / 143
::= { <strong>BalanceNG</strong> 7 }Remark OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"configuration file remark"::= { <strong>BalanceNG</strong> 8 }Sessions OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Number of current total session table entries"::= { <strong>BalanceNG</strong> 9 }---- Gateway Settings <strong>and</strong> Status--GatewayIPAddr OBJECT-TYPESYNTAX IpAddressACCESS read-onlySTATUS currentDESCRIPTION"IP address of gateway, 0.0.0.0 if unspecified"::= { <strong>BalanceNG</strong> 10 }GatewayArpInterval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Gateway ARP healthcheck interval, 0 if unspecified"::= { <strong>BalanceNG</strong> 11 }GatewayArpTimeout OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Gateway ARP healthcheck timeout, 0 if unspecified"::= { <strong>BalanceNG</strong> 12 }GatewayPingInterval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Gateway ping healthcheck interval, 0 if unspecified"::= { <strong>BalanceNG</strong> 13 }GatewayPingTimeout OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Gateway ping healthcheck timeout, 0 if unspecified"::= { <strong>BalanceNG</strong> 14 }GatewayTrackval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Gateway tracking value for VRRP"::= { <strong>BalanceNG</strong> 15 }GatewayStatus OBJECT-TYPESYNTAX INTEGER {unspecified(0),down(1),operational(2)}ACCESS read-onlySTATUS currentDESCRIPTION"Gateway status"::= { <strong>BalanceNG</strong> 16 }---- VRRP Settings <strong>and</strong> Status--VRRPVrid OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"VRRP Virtual Router Id, 0 if unspecified"::= { <strong>BalanceNG</strong> 17 }VRRPPriority OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"VRRP Priority, 0 if unspecified"::= { <strong>BalanceNG</strong> 18 }VRRPNetwork OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Network for VRRP advertisements, 0 if unspecified"::= { <strong>BalanceNG</strong> 19 }VRRPTracking OBJECT-TYPESYNTAX INTEGER {unspecified(0),disabled(1),enabled(2)}ACCESS read-onlySTATUS currentDESCRIPTION"VRRP tracking option, 0 if unspecified or VRRP off"::= { <strong>BalanceNG</strong> 20 }VRRPStatus OBJECT-TYPESYNTAX INTEGER {off(0),initialize(1),master(2),backup(3)}ACCESS read-onlySTATUS currentDESCRIPTION"VRRP status"::= { <strong>BalanceNG</strong> 21 }VRRPMScript OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"External VRRP master notification script, empty ifundefined"::= { <strong>BalanceNG</strong> 22 }VRRPBScript OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"External VRRP backup notification script, empty ifundefined"::= { <strong>BalanceNG</strong> 23 }GatewayAlertScript OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"External gateway down notification script, empty ifundefined"::= { <strong>BalanceNG</strong> 24 }GatewayUpalertScript OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"External gateway operational notification script, emptyif undefined"::= { <strong>BalanceNG</strong> 25 }---- Interface Information--InterfaceInfo OBJECT-TYPESYNTAX SEQUENCE OF InterfaceEntryACCESS not-accessibleSTATUS m<strong>and</strong>atoryDESCRIPTION"Interface Information"::= { <strong>BalanceNG</strong> 40 }InterfaceEntry ::= SEQUENCE {InterfaceIndex INTEGER,InterfaceName OCTET STRING,InterfaceDumpDirectory OCTET STRING,InterfaceDumpBytes COUNTER32,InterfaceSentPackets COUNTER32,InterfaceSentBytes COUNTER32,InterfaceReceivedPackets COUNTER32,InterfaceReceivedBytes COUNTER32}InterfaceIndex OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Interface Index"::= { InterfaceInfo 1 }InterfaceName OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Interface name on operating system level"Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 104 / 143Grünwald Germany / All Rights Reserved
::= { InterfaceInfo 2 }InterfaceDumpDirectory OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Dumpfilename, empty if inactive"::= { InterfaceInfo 3 }InterfaceDumpBytes OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of bytes dumped"::= { InterfaceInfo 4 }InterfaceSentPackets OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of packets sent out on this interface"::= { InterfaceInfo 5 }InterfaceSentBytes OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of bytes sent out on this interface"::= { InterfaceInfo 6 }InterfaceReceivedPackets OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of packets received on this interface"::= { InterfaceInfo 7 }InterfaceReceivedBytes OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of bytes received on this interface"::= { InterfaceInfo 8 }---- Network Information--NetworkInfo OBJECT-TYPESYNTAX SEQUENCE OF NetworkEntryACCESS not-accessibleSTATUS m<strong>and</strong>atoryDESCRIPTION"Network Informations"::= { <strong>BalanceNG</strong> 50 }NetworkEntry ::= SEQUENCE {NetworkIndexNetworkStatusNetworkNameNetworkAddrNetworkMaskNetworkRealNetworkVirtNetworkInterfaces}NetworkIndex OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Network Index"::= { NetworkInfo 1 }NetworkStatus OBJECT-TYPESYNTAX INTEGER {disabled(0),enabled(1)}ACCESS read-onlySTATUS currentDESCRIPTION"Network enable status"::= { NetworkInfo 2 }NetworkName OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Network name"::= { NetworkInfo 3 }NetworkAddr OBJECT-TYPESYNTAX IpAddressACCESS read-onlySTATUS currentINTEGER,INTEGER,OCTET STRING,IpAddress,IpAddress,IpAddress,IpAddress,OCTET STRINGDESCRIPTION"Network address"::= { NetworkInfo 4 }NetworkMask OBJECT-TYPESYNTAX IpAddressACCESS read-onlySTATUS currentDESCRIPTION"Network netmask"::= { NetworkInfo 5 }NetworkReal OBJECT-TYPESYNTAX IpAddressACCESS read-onlySTATUS currentDESCRIPTION"Network real address"::= { NetworkInfo 6 }NetworkVirt OBJECT-TYPESYNTAX IpAddressACCESS read-onlySTATUS currentDESCRIPTION"Network virtual address"::= { NetworkInfo 7 }NetworkInterfaces OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Network interface list as string, empty if no interfaceassociated."::= { NetworkInfo 8 }---- Server Information--ServerInfo OBJECT-TYPESYNTAX SEQUENCE OF ServerEntryACCESS not-accessibleSTATUS m<strong>and</strong>atoryDESCRIPTION"Server information"::= { <strong>BalanceNG</strong> 60 }ServerEntry ::= SEQUENCE {ServerIndexServerStatusServerNameServerIpAddrServerPortServerPort2ServerProtocolServerMethodServerPortrelServerFailoverServerTargetlistServerBackuplistServerSessionsServerSentPacketsServerSentBytesServerReceivedPacketsServerReceivedBytesServerSessionTimeout}ServerIndex OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"The Server number"::= { ServerInfo 1 }ServerStatus OBJECT-TYPESYNTAX INTEGER {disabled(0),enabled(1)}ACCESS read-onlySTATUS currentDESCRIPTION"Server enable status"::= { ServerInfo 2 }ServerName OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Server name"::= { ServerInfo 3 }ServerIpAddr OBJECT-TYPESYNTAX IpAddressACCESS read-onlySTATUS currentDESCRIPTION"Server IP address"::= { ServerInfo 4 }INTEGER,INTEGER,OCTET STRING,IpAddress,INTEGER,INTEGER,INTEGER,INTEGER,INTEGER,INTEGER,OCTET STRING,OCTET STRING,Gauge32,COUNTER32,COUNTER32,COUNTER32,COUNTER32,INTEGER<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 105 / 143
ServerPort OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Server primary port, 0 if undefined (any)"::= { ServerInfo 5 }ServerPort2 OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Server secondary port, 0 if undefined"::= { ServerInfo 6 }ServerProtocol OBJECT-TYPESYNTAX INTEGER {any(0),tcp(1),udp(2)}ACCESS read-onlySTATUS currentDESCRIPTION"Server protocol definition"::= { ServerInfo 7 }ServerMethod OBJECT-TYPESYNTAX INTEGER {rr(0),hash(1),r<strong>and</strong>om(2),agent(3),session(4),bwin(5),bwout(6),bw(7),rndagent(8)}ACCESS read-onlySTATUS currentDESCRIPTION"Server load balancing method"::= { ServerInfo 8 }ServerPortrel OBJECT-TYPESYNTAX INTEGER {off(0),on(1)}ACCESS read-onlySTATUS currentDESCRIPTION"Server Port Relevance feature, off=default"::= { ServerInfo 9 }ServerFailover OBJECT-TYPESYNTAX INTEGER {normal(0),backup(1)}ACCESS read-onlySTATUS currentDESCRIPTION"Server failover behaviour, backup switchesimmediately tobackup target"::= { ServerInfo 10 }ServerTargetlist OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Server list of targets"::= { ServerInfo 11 }ServerBackuplist OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Server list of backup targets"::= { ServerInfo 12 }ServerSessions OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Current number of virtual server sessions, defined to bethe sum of the sessions of all associated targets"::= { ServerInfo 13 }ServerSentPackets OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTIONthe sum of"Number of packets sent to the clients, defined to bepackets being received from all associated targets"::= { ServerInfo 14 }ServerSentBytes OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of bytes sent to the clients, defined to bethe sum ofbytes being received from all associated targets"::= { ServerInfo 15 }ServerReceivedPackets OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of packets received from the clients by thisvirtualserver, defined to be the sum of packets being sentto allassociated targets"::= { ServerInfo 16 }ServerReceivedBytes OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of bytes received from the clients by thisvirtual server,defined to be the sum of bytes being sent to allassociated targets"::= { ServerInfo 17 }ServerSessionTimeout OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Server specific session timeout in seconds, 0 ifunspecified"::= { ServerInfo 18 }---- Target Information--TargetInfo OBJECT-TYPESYNTAX SEQUENCE OF TargetEntryACCESS not-accessibleSTATUS m<strong>and</strong>atoryDESCRIPTION"Target information"::= { <strong>BalanceNG</strong> 70 }TargetEntry ::= SEQUENCE {TargetIndexINTEGER,TargetStatusINTEGER,TargetNameOCTET STRING,TargetIpAddrIpAddress,TargetPortINTEGER,TargetProtocolINTEGER,TargetDSRINTEGER,TargetSoftdisable INTEGER,TargetTrackvalINTEGER,TargetAgentPortINTEGER,TargetAgentInterval INTEGER,TargetAgentTimeout INTEGER,TargetAgentOffset INTEGER,TargetAgentScale OCTET STRING,TargetPingInterval INTEGER,TargetPingTimeout INTEGER,TargetTcp<strong>Open</strong>Port INTEGER,TargetTcp<strong>Open</strong>Interval INTEGER,TargetTcp<strong>Open</strong>Timeout INTEGER,TargetScriptOCTET STRING,TargetScriptInterval INTEGER,TargetScriptTimeout INTEGER,TargetAlertScript OCTET STRING,TargetUpalertScript OCTET STRING,TargetSessionsGauge32,TargetSentPackets COUNTER32,TargetSentBytesCOUNTER32,TargetReceivedPackets COUNTER32,TargetReceivedBytes COUNTER32,TargetAgentDataGauge32,TargetIncomingB<strong>and</strong>width Gauge32,TargetOutgoingB<strong>and</strong>width Gauge32,TargetWeightGauge32,TargetMaxSessions Gauge32,TargetMaxAgentGauge32}TargetIndex OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"The target number"::= { TargetInfo 1 }TargetStatus OBJECT-TYPESYNTAX INTEGER {Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 106 / 143Grünwald Germany / All Rights Reserved
disabled(0),down(1),operational(2)}ACCESS read-onlySTATUS currentDESCRIPTION"Target status"::= { TargetInfo 2 }TargetName OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Target name"::= { TargetInfo 3 }TargetIpAddr OBJECT-TYPESYNTAX IpAddressACCESS read-onlySTATUS currentDESCRIPTION"Target IP address"::= { TargetInfo 4 }TargetPort OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Target port, 0 if undefined (any)"::= { TargetInfo 5 }TargetProtocol OBJECT-TYPESYNTAX INTEGER {any(0),tcp(1),udp(2)}ACCESS read-onlySTATUS currentDESCRIPTION"Target protocol definition"::= { TargetInfo 6 }TargetDSR OBJECT-TYPESYNTAX INTEGER {disabled(0),enabled(1)}ACCESS read-onlySTATUS currentDESCRIPTION"Target Direct Server Return (DSR) operation"::= { TargetInfo 7 }TargetSoftdisable OBJECT-TYPESYNTAX INTEGER {inactive(0),active(1)}ACCESS read-onlySTATUS currentDESCRIPTION"Target softdisable (accepting no new sessions ifactive)"::= { TargetInfo 8 }TargetTrackval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Tracking value for VRRP tracking (0=default)"::= { TargetInfo 9 }TargetAgentPort OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Target agent port, 0 if undefined (agentcommunication inactive)"::= { TargetInfo 10 }TargetAgentInterval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Agent interval, 0 if undefined"::= { TargetInfo 11 }TargetAgentTimeout OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Agent timeout, 0 if undefined"::= { TargetInfo 12 }TargetAgentOffset OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Agent return value offset, default=0"::= { TargetInfo 13 }TargetAgentScale OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Agent return value scale, default=1.0 (double asstring)"::= { TargetInfo 14 }TargetPingInterval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Ping healthcheck interval, 0 if undefined"::= { TargetInfo 15 }TargetPingTimeout OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Ping healthcheck timeout, 0 if undefined"::= { TargetInfo 16 }TargetTcp<strong>Open</strong>Port OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"TCPopen healthcheck port, 0 if undefined"::= { TargetInfo 17 }TargetTcp<strong>Open</strong>Interval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"TCPopen healthcheck interval, 0 if undefined"::= { TargetInfo 18 }TargetTcp<strong>Open</strong>Timeout OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"TCPopen healthcheck timeout, 0 if undefined"::= { TargetInfo 19 }TargetScript OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"External healthcheck script, empty if undefined"::= { TargetInfo 20 }TargetScriptInterval OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"External healthcheck interval, 0 if undefined"::= { TargetInfo 21 }TargetScriptTimeout OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"External healthcheck timeout, 0 if undefined"::= { TargetInfo 22 }TargetAlertScript OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"External alert script, empty if undefined"::= { TargetInfo 23 }TargetUpalertScript OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"External upalert script, empty if undefined"::= { TargetInfo 24 }TargetSessions OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Current number of target (real server) sessions"::= { TargetInfo 25 }TargetSentPackets OBJECT-TYPE<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 107 / 143
SYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of packets sent to target (real server)"::= { TargetInfo 26 }TargetSentBytes OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of bytes received from target (real server)"::= { TargetInfo 27 }TargetReceivedPackets OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of packets received from target (realserver)"::= { TargetInfo 28 }TargetReceivedBytes OBJECT-TYPESYNTAX COUNTER32ACCESS read-onlySTATUS currentDESCRIPTION"Number of bytes received from target (real server)"::= { TargetInfo 29 }TargetAgentData OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Performance data as returned from bngagent feedbackagent"::= { TargetInfo 30 }TargetTotalB<strong>and</strong>width OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Current total b<strong>and</strong>width of target in bytes persecond"::= { TargetInfo 31 }TargetIncomingB<strong>and</strong>width OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Current incoming b<strong>and</strong>width of target in bytes persecond"::= { TargetInfo 32 }TargetOutgoingB<strong>and</strong>width OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Current outgoing b<strong>and</strong>width of target in bytes persecond"::= { TargetInfo 33 }TargetWeight OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Target weight for weighted r<strong>and</strong>om method, default=1"::= { TargetInfo 34 }TargetMaxSessions OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Maximum absolute number of sessions a target isallowed to receive"::= { TargetInfo 35 }TargetMaxAgent OBJECT-TYPESYNTAX Gauge32ACCESS read-onlySTATUS currentDESCRIPTION"Maximum absolute agent return value that a targetmay have for new session"::= { TargetInfo 36 }---- Parameter Information--DESCRIPTION"Parameter information"::= { <strong>BalanceNG</strong> 80 }ParameterEntry ::= SEQUENCE {ParameterNameParameterMinParameterMaxParameterDefaultParameterCurrent}ParameterName OBJECT-TYPESYNTAX OCTET STRINGACCESS read-onlySTATUS currentDESCRIPTION"Name of parameter"::= { ParameterInfo 1 }INTEGER,INTEGERParameterMin OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Minimum parameter value"::= { ParameterInfo 2 }ParameterMax OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Maximum parameter value"::= { ParameterInfo 3 }ParameterDefault OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Default parameter value"::= { ParameterInfo 4 }ParameterCurrent OBJECT-TYPESYNTAX INTEGERACCESS read-onlySTATUS currentDESCRIPTION"Current parameter value"::= { ParameterInfo 5 }---- Traps--<strong>BalanceNG</strong>Traps OBJECT IDENTIFIER ::= { <strong>BalanceNG</strong> 90 }GatewayDown NOTIFICATION-TYPESTATUS currentDESCRIPTION"Gateway down notification"::= { <strong>BalanceNG</strong>Traps 1 }GatewayOperational NOTIFICATION-TYPESTATUS currentDESCRIPTION"Gateway up notification"::= { <strong>BalanceNG</strong>Traps 2 }TargetDown NOTIFICATION-TYPEOBJECTS { TargetIndex }STATUS currentDESCRIPTION"Target down notification"::= { <strong>BalanceNG</strong>Traps 3 }TargetOperational NOTIFICATION-TYPEOBJECTS { TargetIndex }STATUS currentDESCRIPTION"Target operational notification"::= { <strong>BalanceNG</strong>Traps 4 }VRRPNowMaster NOTIFICATION-TYPEOBJECTS { VRRPVrid }STATUS currentDESCRIPTION"VRRP master notification"::= { <strong>BalanceNG</strong>Traps 5 }VRRPNowBACKUP NOTIFICATION-TYPEOBJECTS { VRRPVrid }STATUS currentDESCRIPTION"VRRP backup notification"::= { <strong>BalanceNG</strong>Traps 6 }OCTET STRING,INTEGER,INTEGER,ParameterInfo OBJECT-TYPESYNTAX SEQUENCE OF ParameterEntryACCESS not-accessibleSTATUS m<strong>and</strong>atoryENDDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 108 / 143Grünwald Germany / All Rights Reserved
5 Logging<strong>BalanceNG</strong> uses the syslog interface to send logging message to the Operating Systemsyslog facility. It uses the identification "<strong>BalanceNG</strong>" to openlog(). Logging may be collectedcentrally by configuring /etc/syslog.conf appropriately <strong>and</strong> by maintaining a central logserver machine.The last 20 syslog messages are being collected in a cyclic buffer <strong>and</strong> can be investigatedusing the "show log" comm<strong>and</strong>.<strong>BalanceNG</strong> uses a set of syslog messages to report about "normal, but significant conditions"<strong>and</strong> uses the syslog level LOG_NOTICE exclusively for that purpose.The following messages may be logged that way:this virtual router is now MASTERThe node participates in VRRP <strong>and</strong> has just become the MASTER VRRP router withthe configured VRID (Virtual Router Identifier).this virtual router is now BACKUPThe node participates in VRRP <strong>and</strong> has been superseded my a higher priority node. Ithas entered BACKUP state.vrrp off <strong>and</strong> in state INITIALIZEVRRP has been administratively switched off.target operationalThe target with the specified index has just become operational because allconfigured health checks succeed. An "upalert" script is called (if defined for thattarget).target downThe target with the specified index has become inoperational (down). This can beeither caused by failing health checks or by taking the target administratively out of"enabled" state (with the "disable" comm<strong>and</strong>). An "alert" script is called (if definedfor that target).<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 109 / 143
6 BngagentBngagent is a small UDP server program which runs on a UNIX target machine. Using asimple UDP protocol (the Bngagent Protocol) the "agent" health check method of <strong>BalanceNG</strong>is capable to talk to this agent.The source code of Bngagent is made available to the customers on order to enable them toport is to the various UNIX based machines that they want to monitor.Precompiled binaries of Bngagent are made available for Linux/x86, Solaris10/x86 <strong>and</strong>Solaris/SPARC (9+10)..6.1 Compiling BngagentRecommended example compilation comm<strong>and</strong> lines for compiling bngagent are:Linux:Solaris:HPUX:gcc -o bngagent bngagent.cgcc -o bngagent bngagent.c -lnsl -lsocketgcc -o bngagent bngagent.c -mpa-risc-1-06.2 Starting <strong>and</strong> Stopping of BngagentThe usage information of Bngagent (when called with no argument) is as follows:# bngagent$Revision: 1.34 $ - bngagent is part of the <strong>BalanceNG</strong> productCopyright (C) 2005 by Inlab <strong>Software</strong> GmbH, Gruenwald, GermanyAll rights reserved - more infos at: http://www.<strong>BalanceNG</strong>.net#usage:server bngagent portrequest (test) bngagent -r address:portoptions:-0 return 1 minute load avg (server,default)-1 return 5 minute load avg (server)-2 return 15 minute load avg (server)-f stay in foreground (server)-b specify bind address (both)-c specify comm<strong>and</strong> (server)-d enable debug <strong>and</strong> foreground (both)-t specify targetid (request)Bngagent with the port number as argument puts itself into background <strong>and</strong> starts listening forUDP packets being sent out by <strong>BalanceNG</strong>:# bngagent 439#You may choose any available UDP port for that, if you want to use a privileged port below1024 please use port 439 which is allowed to be used by the author for that purpose.Stopping might be performed by using the "pkill" tool, e.g.:Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 110 / 143Grünwald Germany / All Rights Reserved
# pkill bngagent#The option -f forces Bngagent to stay in foreground, the option -d enables debugging output<strong>and</strong> does an implicit -f.The option -b allows binding to a specific address if multiple are available.Bngagent with no -c Argument calls getloadavg() <strong>and</strong> returns the 1 minute load averageof the machine multiplied by 100 back to <strong>BalanceNG</strong> for further processing (per default).Option -1 makes bngagent return the 5 minute load average <strong>and</strong> the option -2 makes itreturn the 15 minute load average.Thus <strong>BalanceNG</strong> is immediately capable to take the system load of the target machines intoaccount.You may pass control to a external script using the -c option. If an <strong>BalanceNG</strong> request isbeing received by the Bngagent calls the external script <strong>and</strong> expects one line on stdout fromthat script (at minimum). This value has to be in the unsigned integer range from 0 to 2^32.Returning 0 means for <strong>BalanceNG</strong> that the target's service has become totally unavailable<strong>and</strong> will force the target to become inoperational immediately. Otherwise <strong>BalanceNG</strong> 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 specific bngagent scripts.An example might look as follows:# ./bngagent -c 'pgrep sshd | wc -l' 5000# ./bngagent -r localhost:5000target id: 0 value: 1# ./bngagent -r localhost:5001*timeout*#Compiling Bngagent can be done by a simple comm<strong>and</strong>.For Linux you could use:$ gcc -o bngagent bngagent.c$Solaris usually requires the "nsl" <strong>and</strong> "socket" libraries:$ gcc -o bngagent bngagent.c -lnsl -lsocket$We started to add precompiled binaries of bngagent to the main distribution. Please take alook into the "bngagent-binaries" directory.<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 111 / 143
6.3 The Bngagent UDP Protocol6.3.1 The Bngagent Protocol RequestThe Bngagent request packet simply consists of an unsigned short in network order whichrepresents the target id (or target number) for which information is being requested. The totaldata length encapsulated in UDP is two bytes:Byte 0 Byte 1+----------------+| Target Id |+----------------+There's no authentication provided.6.3.2 The Bngagent Protocol ReplyThe reply sends the received Target Id back in a two byte unsigned short <strong>and</strong> additionallyreturns the return value as a unsigned integer in four bytes. All data is in network order. Thetotal length of the Bngagent reply packet encapsulated in UDP is 6 bytes.Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5+----------------+ +---------------------------------+| Target Id | | Bngagent return Value |+----------------+ +---------------------------------+<strong>BalanceNG</strong> will choose the target with the lowest Bngagent return value when a new sessionhas to be created. Return 0 as the Bngagent return value means that the target is currentlyunavailable (e.g. the service requested is down).Sending back the Target Id allows multiple Bngagents to run on one host for different targets.<strong>BalanceNG</strong> is that way capable to assign the replies based to their respective targets.6.4 Writing Bngagent ScriptsA script or program being called by bngagent with the "-c" option should just put out one lineon stdout <strong>and</strong> then exit immediately. The line should contain one number either "0" for "serviceunavailable" or any other positive integer in the 32 bit unsigned int range.As mentioned before the <strong>BalanceNG</strong> agent distribution method will 1) disable any targetwhere the agent reports "0" <strong>and</strong> 2) will direct new sessions to the target with the lowestBngagent return value.One very simple two line example is to count the number of processes:#!/bin/shpgrep httpd | wc -lMore complicated health checks should be implemented as scripts or programs to be h<strong>and</strong>ledby Bngagent.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 112 / 143Grünwald Germany / All Rights Reserved
6.5 Bngagent <strong>Source</strong> CodeThe source code of bngagent is part of the <strong>BalanceNG</strong> distribution. It is being distributedunder the <strong>BalanceNG</strong> license./** Copyright (C) 2006 by Inlab <strong>Software</strong> GmbH, Gruenwald, Germany* All Rights Reserved / Alle Rechte vorbehalten** Use of <strong>and</strong> access to this source code requires either a written* permission of Inlab <strong>Software</strong> GmbH (source code license) or has* to be covered by a valid written contractual agreement.** $RCSfile: bngagent.c,v $* $Revision: 1.44 $* $Date: 2006/11/29 18:00:21 $*/#include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #define MAXBYTES 64#define MAXLINE 64static int foreground=0;static int debugflag=0;static int testflag=0;#ifdef __hpux#include getloadavg (double *ave,int na) {struct pst_dynamic pstd;int i;if (pstat_getdynamic(&pstd,sizeof(struct pst_dynamic),(size_t)1,0)
eak;}return (3);}#elseint getloadavg(double*, int);#endifvoid usage() {fprintf(stderr,"\n");fprintf(stderr," $Revision: 1.43 $\n");fprintf(stderr," bngagent is an open source part of the <strong>BalanceNG</strong> product\n");fprintf(stderr," Copyright (C) 2006 by Inlab <strong>Software</strong> GmbH, Gruenwald, Germany\n");fprintf(stderr," All rights reserved - more infos at: http://www.<strong>BalanceNG</strong>.net\n");fprintf(stderr,"\n");fprintf(stderr," usage:\n");fprintf(stderr," server bngagent port\n");fprintf(stderr," request (test) bngagent -r address:port\n");fprintf(stderr," options:\n");fprintf(stderr," -0 return 1 minute load avg (server,default)\n");fprintf(stderr," -1 return 5 minute load avg (server)\n");fprintf(stderr," -2 return 15 minute load avg (server)\n");fprintf(stderr," -f stay in foreground (server)\n");fprintf(stderr," -b specify bind address (both)\n");fprintf(stderr," -c specify comm<strong>and</strong> (server)\n");fprintf(stderr," -d enable debug <strong>and</strong> foreground (both)\n");fprintf(stderr," -t specify targetid (request)\n");fprintf(stderr,"\n");exit(EX_USAGE);}static void daemonize() {int fd,childpid;if ((childpid = fork()) < 0) {fprintf(stderr,"cannot fork\n");exit(EX_OSERR);} else {if (childpid > 0) {exit(EX_OK);}}#ifdef __hpux(void) setsid();#else#ifdef BSDsetpgid(getpid(), 0);#elsesetpgrp();#endif{int fd;if((fd = open("/dev/tty", O_RDWR)) != -1) {if(ioctl(fd, TIOCNOTTY) < 0) {fprintf(stderr, "error: cannot ioctl(IOCNOTTY)");exit(EX_OSERR);}close(fd);}}#endifopenlog("bngagent", LOG_ODELAY | LOG_PID | LOG_CONS, LOG_DAEMON);if((fd=open("/dev/null", O_RDWR, 0)) < 0) {syslog(LOG_CRIT, "unable to open /dev/null");exit(EX_OSERR);}if(dup2(fd, 0) < 0)syslog(LOG_ERR, "Unable to set /dev/null as stdin");if(dup2(fd, 1) < 0)syslog(LOG_ERR, "Unable to set /dev/null as stdout");if(dup2(fd, 2) < 0)syslog(LOG_ERR, "Unable to set /dev/null as stderr");Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 114 / 143Grünwald Germany / All Rights Reserved
close(fd);chdir("/");}static char*static char*static char*static structstatic intstatic structstatic intstatic intbindhost=NULL;comm<strong>and</strong>=NULL;targetid=NULL;sockaddr_in addr, tr_sockaddr;sd, tr_sockaddr_len;in_addr tr_ipaddr;tr_port;laindex=0;static void prepare_testrequest(char* destination) {struct hostent* he;struct servent* sp;char *server_cp, *port_cp;server_cp = strtok(destination, ":");port_cp = strtok(NULL, ":");if(server_cp == NULL || port_cp == NULL) {usage();}he=gethostbyname(server_cp);if(he == NULL) {if ((tr_ipaddr.s_addr = inet_addr(server_cp)) == (unsigned int) -1) {fprintf(stderr, "unknown or invalid IP address [%s]\n", server_cp);usage();}} else {memcpy(&tr_ipaddr, he->h_addr, he->h_length);}sp = getservbyname(port_cp,"udp");if(sp == NULL) {tr_port=atoi(port_cp);} else {tr_port=ntohs(sp->s_port);}if(tr_port == 0) {fprintf(stderr, "unknown or invalid port [%s]\n", port_cp);usage();}}static void testrequest_timeout() {printf("*timeout*\n");exit(EX_OK);}static void perform_testrequest() {int rc;static unsigned char buffer[MAXBYTES];unsigned char intbuffer[4];tr_sockaddr.sin_port = htons(tr_port);tr_sockaddr.sin_family = AF_INET;memcpy(&tr_sockaddr.sin_addr,&tr_ipaddr,sizeof(tr_sockaddr.sin_addr));bzero(buffer, MAXBYTES);if(targetid != NULL) {*((unsigned short*) buffer) = htons(atoi(targetid));}rc=sendto(sd, buffer, sizeof(unsigned short), 0,(struct sockaddr*)&tr_sockaddr, sizeof(tr_sockaddr));if(rc < 0) {perror("sendto");exit(EX_OSERR);}signal(SIGALRM,testrequest_timeout);alarm(1);tr_sockaddr_len=sizeof(tr_sockaddr);rc = recvfrom(sd, buffer, sizeof(buffer), 0,(struct sockaddr*)&tr_sockaddr, &tr_sockaddr_len);<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 115 / 143
if(rc == 6) {memcpy(intbuffer, buffer+sizeof(unsigned short), sizeof(unsigned int));printf("target id: %u value: %u\n", ntohs(*((unsigned short*) buffer)),ntohl(*((unsigned int*) intbuffer)));} else {printf("invalid length %d returned\n", rc);}exit(EX_OK);}int main(int argc, char** argv) {int c,port;struct servent* sp;unsigned char buffer[MAXBYTES];unsigned char intbuffer[4];while((c = getopt(argc,argv,"012b:fdc:rt:")) != EOF) {switch(c) {case 'b':bindhost=strdup(optarg);break;case 'f':foreground=1;break;case 'd':debugflag=1;foreground=1;break;case 'c':comm<strong>and</strong>=strdup(optarg);break;case 't':targetid=strdup(optarg);break;case 'r':testflag=1;break;case '0':laindex=0;break;case '1':laindex=1;break;case '2':laindex=2;break;case '?':default:usage();}}argc -= optind;argv += optind;if(argc != 1) {usage();}if(testflag) {prepare_testrequest(argv[0]); /* prepare test request */}if(testflag) {port=0; /* port will be reassigned */} else {sp=getservbyname(argv[0],"udp");if(sp==NULL) {port=atoi(argv[0]);if(port==0) {fprintf(stderr, "error: invalid port specifier\n");exit(EX_USAGE);}} else {port=ntohs(sp->s_port);Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 116 / 143Grünwald Germany / All Rights Reserved
}}if(debugflag)fprintf(stderr,"we will listen on port %d\n",port);sd=socket(PF_INET, SOCK_DGRAM, 0);bzero(&addr, sizeof(addr));addr.sin_family = AF_INET;addr.sin_port = htons(port);if(bindhost == NULL) {addr.sin_addr.s_addr = INADDR_ANY;} else {struct hostent *he;he = gethostbyname(bindhost);if(he == NULL) {int taddr;if((taddr = inet_addr(bindhost)) == -1) {fprintf(stderr,"unknown or invalid address [%s]\n",bindhost);exit(EX_USAGE);} else {addr.sin_addr.s_addr = taddr;}} else {memcpy(&addr.sin_addr, he->h_addr, he->h_length);}}if(bind(sd, (struct sockaddr*)&addr, sizeof(addr)) != 0) {perror("bind");exit(EX_OSERR);}if(testflag) {perform_testrequest();exit(EX_OK);}if(!foreground)daemonize();for(;;) {int bytes, addr_len=sizeof(addr);unsigned int returnvalue;FILE *pipe;char line[MAXLINE];bytes = recvfrom(sd, buffer, sizeof(buffer), 0,(struct sockaddr*)&addr, &addr_len);if(debugflag) {fprintf(stderr,"packet from %s:%d (%d bytes) target %d\n",inet_ntoa(addr.sin_addr),ntohs(addr.sin_port),bytes,ntohs(*((unsigned short*) buffer)));}if(comm<strong>and</strong> != NULL) {if(debugflag)fprintf(stderr,"executing script or comm<strong>and</strong> [%s]\n", comm<strong>and</strong>);if((pipe=popen(comm<strong>and</strong>,"r")) == NULL) {fprintf(stderr,"error popen()\n");exit(EX_OSERR);}if(fgets(line,MAXLINE,pipe) == NULL) {fprintf(stderr,"error fgets()\n");exit(EX_OSERR);}pclose(pipe);returnvalue=atoi(line);} else {double values[3];if(getloadavg(values, 3) != 3) {<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 117 / 143
}}values[0]=0.0;values[1]=0.0;values[2]=0.0;}if(debugflag) {if(laindex==0)fprintf(stderr,"1-minute system-load: %f\n",values[0]);if(laindex==1)fprintf(stderr,"5-minute system-load: %f\n",values[1]);if(laindex==2)fprintf(stderr,"15-minute system-load: %f\n",values[2]);}if(values[laindex] < 0.0)values[laindex]=0.0;returnvalue=(unsigned int) (values[laindex]*100.0);/* 0 would mean service unavailable, so we return at least 1 */if(returnvalue == 0)returnvalue++;}if(debugflag)fprintf(stderr,"about to return %d\n", returnvalue);/* avoiding alignment problems */returnvalue = htonl(returnvalue);*((unsigned int*) intbuffer)=returnvalue;memcpy(buffer+sizeof(unsigned short), intbuffer, sizeof(unsigned int));sendto(sd, buffer, sizeof(unsigned short)+sizeof(unsigned int), 0,(struct sockaddr*)&addr, sizeof(addr));7 Application Examples7.1 Balancing to 4 Targets with VRRP redundancy7.1.1 Network Data <strong>and</strong> AddressesIn this chapter we will present a basic configuration of <strong>BalanceNG</strong> to load-balance InternetHTTP requests to 4 Target servers offering a web-service using HTTP on port 80.(For further information relating to the various configuration comm<strong>and</strong>s please see"Comm<strong>and</strong> Reference" 3.0 .)This example will also work with the evaluation restrictions on one node (simply omit theVRRP <strong>and</strong> licensing section).This diagram shows the network design <strong>and</strong> addressing schema used in the example:Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 118 / 143Grünwald Germany / All Rights Reserved
InternetRouterRouter address in Access Network:10.55.55.254Access NetworkAccess Network Parameters:10.55.55.0/24Netmask: 255.255.255.0Broadcast: 10.55.55.255Gateway: 10.55.55.254<strong>BalanceNG</strong> Master<strong>BalanceNG</strong> BackupVRRP VRID 1VRRP communication overTarget NetworkTarget NetworkTarget Network Parameters:10.1.1.0/24Netmask: 255.255.255.0Broadcast: 10.1.1.255Gateway: 10.1.1.2544 Targets, all running st<strong>and</strong>ardWeb/HTML service on port 8010.1.1.1 10.1.1.2 10.1.1.3 10.1.1.4Figure 3: Example Network Parameters <strong>and</strong> AddressesTo produce the configuration for both <strong>BalanceNG</strong> nodes the following additional information isrequired:Hostname of Master-Node:Hostname of Backup-Node:bng1bng2Target NAT 1:1 addresses: 10.55.55.230,231,232,233Virtual Server Address: 10.55.55.2227.1.2 Configuration of <strong>BalanceNG</strong> MasterThe completed configuration for the <strong>BalanceNG</strong> Master-Node in this Example appears as:// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)hostname bng1license bng1 d3d2552987d59725943e267b847893b9interface eth0interface eth1<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 119 / 143
vrrp {vrid 1priority 255network 2}network 1 {name accessaddr 10.55.55.0mask 255.255.255.0real 10.55.55.220virt 10.55.55.221interface eth0}network 2 {name targetaddr 10.1.1.0mask 255.255.255.0real 10.1.1.100virt 10.1.1.254interface eth1}register networks 1,2enable networks 1,2gateway {ipaddr 10.55.55.254}tnat {10.1.1.4 10.55.55.233 udp 5310.1.1.2 10.55.55.231 udp 5310.1.1.3 10.55.55.232 udp 5310.1.1.1 10.55.55.230 udp 53}server 1 {ipaddr 10.55.55.222portrel ontargets 1,2,3,4}register server 1enable server 1target 1 {ipaddr 10.1.1.1ping 2,10tcpopen 80,5,20}target 2 {ipaddr 10.1.1.2ping 2,10tcpopen 80,5,20}target 3 {ipaddr 10.1.1.3ping 2,10Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 120 / 143Grünwald Germany / All Rights Reserved
tcpopen 80,5,20}target 4 {ipaddr 10.1.1.4ping 2,10tcpopen 80,5,20}register targets 1,2,3,4enable targets 1,2,3,4// end of configurationThe following is a detailed explanation of each configuration line:hostname bng1This defines the hostname of this node (changes the interactive prompt).license bng1 d3d2552987d59725943e267b847893b9This line specifies the license key enabling this <strong>BalanceNG</strong> installation.interface eth0interface eth1Both interfaces eth0 <strong>and</strong> eth1 will be controlled by <strong>BalanceNG</strong>.gateway ipaddr 10.55.55.254The default gateway to the "outside world" (Internet) will be 10.55.55.254.vrrp {vrid 1priority 255network 2}This node will be the Master (priority 255) of the virtual router 1 (vrid 1). VRRP will usenetwork 2 for communication (<strong>and</strong> the interfaces associated to network 2). The VRRPprimary address will be the "real" address of network 2.network 1 {name accessaddr 10.55.55.0mask 255.255.255.0real 10.55.55.220virt 10.55.55.221interface eth0}This declares the access network <strong>and</strong> associates interface eth0 to it. The "real"address will be used for ARP-requests in that network, the virtual address ("virt") isavailable as a routing address. Note: The "virt" address is being shared by theMASTER <strong>and</strong> BACKUP node, the "real" address is unique for each node. Thisnetwork is named as "access" using the "name" subcomm<strong>and</strong>.network 2 {name targetaddr 10.1.1.0mask 255.255.255.0real 10.1.1.100<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 121 / 143
}virt 10.1.1.254interface eth1This declares the target network <strong>and</strong> associates interface eth1 to it. The real addresswill be used for ARP-requests <strong>and</strong> also for health-checks (which are performed byboth nodes in parallel). The virtual address ("virt") offers the default-gateway to thetargets <strong>and</strong> is shared (the same) on both VRRP nodes.register networks 1,2enable networks 1,2Both networks need to be registered <strong>and</strong> enabled to be operative.tnat {10.1.1.4 10.55.55.233 udp 5310.1.1.2 10.55.55.231 udp 5310.1.1.3 10.55.55.232 udp 5310.1.1.1 10.55.55.230 udp 53}Each target gets the capability to resolve DNS queries by associating a unique NATaddress to each target using the "tnat" comm<strong>and</strong>.server 1 {ipaddr 10.55.55.222portrel ontargets 1,2,3,4}This is the central server declaration. It will represent the IP address "ipaddr" onnetwork 1 <strong>and</strong> will distribute all traffic (TCP <strong>and</strong> UDP) to the targets 1,2,3 <strong>and</strong> 4. Thissetup is the "all service local balancing" configuration <strong>and</strong> could be restricted <strong>and</strong>modified using the "port" <strong>and</strong> "protocol" keywords. Since "portrel" is "on", also thesource port will be considered for session h<strong>and</strong>ling (creating a new session for adifferent TCP source port <strong>and</strong> selecting a potentially different target). The server willuse the default "rr" (Round Robin) load balancing method.register server 1enable server 1Server 1 has to be registered <strong>and</strong> enabled to be operational.target 1 {ipaddr 10.1.1.1ping 2,10tcpopen 80,5,20}target 2 {ipaddr 10.1.1.2ping 2,10tcpopen 80,5,20}target 3 {ipaddr 10.1.1.3ping 2,10tcpopen 80,5,20}target 4 {ipaddr 10.1.1.4Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 122 / 143Grünwald Germany / All Rights Reserved
}ping 2,10tcpopen 80,5,20The target are all being checked by pinging every 2 seconds (<strong>and</strong> becoming "down" ifthere's no answer for 10 seconds). Additionally the tcpopen healthcheck is performedto port 80 every 5 seconds. If tcpopen is not successful during 20 seconds therespective target will be considered "down".register targets 1,2,3,4enable targets 1,2,3,4All 4 targets have to be registered <strong>and</strong> enabled to be addressable.As mentioned above this configuration actually will forward any request to any port to one ofthe targets (this may be changed using the port, protocol, server <strong>and</strong> target subcomm<strong>and</strong>s).7.1.3 Configuration of <strong>BalanceNG</strong> BackupThe Configuration file of the Backup Node is similar to the master, the differences are asfollows:• The node specific addresses have to be changed as specified (these are basically thenetwork "real" addresses)• The hostname has to be different• The VRRP configuration must use a lower priority to become the Backup node.Here is the full configuration file for the Backup node:// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)hostname bng2license bng2 4f19d2e479ea415dfba34b6760494635interface eth0interface eth1vrrp {vrid 1priority 100network 2}network 1 {name accessaddr 10.55.55.0mask 255.255.255.0real 10.55.55.219virt 10.55.55.221interface eth0}network 2 {name targetaddr 10.1.1.0mask 255.255.255.0real 10.1.1.101virt 10.1.1.254interface eth1<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 123 / 143
}register networks 1,2enable networks 1,2gateway {ipaddr 10.55.55.254}tnat {10.1.1.4 10.55.55.233 udp 5310.1.1.2 10.55.55.231 udp 5310.1.1.3 10.55.55.232 udp 5310.1.1.1 10.55.55.230 udp 53}server 1 {ipaddr 10.55.55.222portrel ontargets 1,2,3,4}register server 1enable server 1target 1 {ipaddr 10.1.1.1ping 2,10tcpopen 80,5,20}target 2 {ipaddr 10.1.1.2ping 2,10tcpopen 80,5,20}target 3 {ipaddr 10.1.1.3ping 2,10tcpopen 80,5,20}target 4 {ipaddr 10.1.1.4ping 2,10tcpopen 80,5,20}register targets 1,2,3,4enable targets 1,2,3,4// end of configuration7.1.4 Checking the StatusThe status of the nodes may be checked using the "show" comm<strong>and</strong>s. A session on themaster node:root@bng1:~ # /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 723bng1# show targets# ipaddr port prt net srv status name-----------------------------------------------------------------Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 124 / 143Grünwald Germany / All Rights Reserved
1 10.1.1.1 any any 2 1 operational2 10.1.1.2 any any 2 1 operational3 10.1.1.3 any any 2 1 operational4 10.1.1.4 any any 2 1 operationalbng1# show target 1target 1ipaddr 10.1.1.1port anynetwork 2protocol anystatus operationalarp upping uptcpopen upbng1# show target 2target 2ipaddr 10.1.1.2port anynetwork 2protocol anystatus operationalarp upping uptcpopen upbng1# show target 3target 3ipaddr 10.1.1.3port anynetwork 2protocol anystatus operationalarp upping uptcpopen upbng1# show target 4target 4ipaddr 10.1.1.4port anynetwork 2protocol anystatus operationalarp upping uptcpopen upbng1# show servers# ipaddr port prt net S targets {backups}-----------------------------------------------------------------1 10.55.55.222 any any 1 e 1,2,3,4 {}bng1# show server 1server 1ipaddr 10.55.55.222network 1<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 125 / 143
port anyprotocol anystatus enabledmethod rrportrel ontargets 1,2,3,4bng1# show vrrpbng1# show server 1server 1ipaddr 10.55.55.222network 1port anyprotocol anystatus enabledmethod rrportrel ontargets 1,2,3,4bng1# show log2006/05/09 12:38:52 6 starting background operation2006/05/09 12:38:52 5 this virtual router is now MASTER2006/05/09 12:38:54 5 target 1 operational2006/05/09 12:38:54 5 target 3 operational2006/05/09 12:38:55 5 target 2 operational2006/05/09 12:38:55 5 target 4 operationalbng1# show vrrpstate MASTERvrid 1priority 255ip00 10.55.55.222ip01 10.55.55.221ip02 10.55.55.230ip03 10.55.55.231ip04 10.55.55.232ip05 10.55.55.233ip06 10.1.1.254bng1#On the Backup Node "bng2" an interactive session would appear as: (indicating that thebackup node is performing the health checks in parallel):root@bng2:~ # /etc/init.d/bng control<strong>BalanceNG</strong>: connected to PID 707bng2# show vrrpstate BACKUPvrid 1priority 100ip00 10.55.55.222ip01 10.55.55.221ip02 10.55.55.230ip03 10.55.55.231ip04 10.55.55.232ip05 10.55.55.233ip06 10.1.1.254Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 126 / 143Grünwald Germany / All Rights Reserved
ng2# show targets# ipaddr port prt net srv status name-----------------------------------------------------------------1 10.1.1.1 any any 2 1 operational2 10.1.1.2 any any 2 1 operational3 10.1.1.3 any any 2 1 operational4 10.1.1.4 any any 2 1 operationalbng2#7.1.5 Configuration VariationsThe configuration example may be modified or extended as required. Examples:• Restricting the server definition to port 80 <strong>and</strong> tcp only using "port" <strong>and</strong> "protocol". In thiscase the target definitions should also include a "port" <strong>and</strong> "protocol" declaration.• Using a different ports for the client <strong>and</strong> server would generate port translation (e.g. usingexternal port 80 <strong>and</strong> internal port 8080 would redirect requests to the logical server on port80 to one of the targets on port 8080).• Optimized load distribution may be achieved using the <strong>BalanceNG</strong> agent "bngagent".• One or more backup targets could be specified at the server using the "backup"subcomm<strong>and</strong>.7.1.6 General Configuration Guidelines <strong>and</strong> RulesPlease follow the following general Guidelines <strong>and</strong> Rules during the configuration of your<strong>BalanceNG</strong> configuration file:• Addresses that are represented virtually by <strong>BalanceNG</strong> are not addressable by the<strong>BalanceNG</strong> node itself. This is because the Operating Systems TCP/IP Stack is not"connected"to the TCP/IP stack of <strong>BalanceNG</strong>. These addresses are: All serveraddresses, all tnat destination addresses <strong>and</strong> all network addresses ("virt" <strong>and</strong> "real").• All addresses being represented by one (or multiple) nodes of <strong>BalanceNG</strong> must not beoccupied by some other device. Especially the Operating System Kernel of the <strong>BalanceNG</strong>node must not use <strong>BalanceNG</strong> virtual addresses in parallel.• Each <strong>BalanceNG</strong> VRRP node must implement <strong>and</strong> use its own distinct "real" networkaddresses.• The "virt" network addresses are being shared using VRRP <strong>and</strong> must be the same onmultiple <strong>BalanceNG</strong> nodes with the same VRID.7.2 Single Legged / One Node OperationThis very simple "single legged" example should give you a starting point for your own testsetup. You should change the example network "172.16.1.0/24" to match your own networksetup (<strong>and</strong> the server address too of course). This example can be fully tested with<strong>BalanceNG</strong> in trial mode without any licensing.7.2.1 The Initial NetworkConsider this to be the simple initial network configuration before inserting the <strong>BalanceNG</strong><strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 127 / 143
node (the network 172.16.1.0/24 should represent a public allocated address space):Figure 4: Network configuration without <strong>BalanceNG</strong>What should be working:• You should be able to ping the default gateway 172.16.1.254 from the Web Server.• Clients from the Internet are able to initiate TCP connection to port 80 on the Web Server172.16.1.10.7.2.2 Load balancing to two targets with one single legged<strong>BalanceNG</strong> nodeThe key idea for <strong>BalanceNG</strong> in a single legged configuration is to introduce another layer 3(IP) network on top of the existing layer 2 infrastructure. In this example we define thisadditional network to be 10.1.1.0/24 being an private network according to RFC 1918.<strong>BalanceNG</strong> is configured to represent the old web server IP address 172.16.1.10, loadbalancing to the two targets ("virtual servers") 10.1.1.1 <strong>and</strong> 10.1.1.2. The default gateway onthe two targets points to 10.1.1.254, which is also represented by <strong>BalanceNG</strong>.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 128 / 143Grünwald Germany / All Rights Reserved
Figure 5: Network configuration <strong>BalanceNG</strong> single legged balancing to two targets7.2.3 The Configuration FileThis is the <strong>BalanceNG</strong> configuration for this example. The <strong>BalanceNG</strong> box is connected to theswitch with the eth0 interface. The "real" addresses in the network sections are the sourceaddresses for ARP resolving. The "virt" addresses in the network sections are the routingendpoints represented by <strong>BalanceNG</strong> (the "virt" address of network 1 is not needed in thisexample, although it has to be specified as a different address).// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {name "local network"addr 172.16.1.0mask 255.255.255.0real 172.16.1.252virt 172.16.1.253interface eth0}network 2 {name "target network"addr 10.1.1.0mask 255.255.255.0real 10.1.1.253virt 10.1.1.254interface eth0}register network 1,2enable network 1,2gateway {<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 129 / 143
ipaddr 172.16.1.254}server 1 {ipaddr 172.16.1.10targets 1,2port 80}register server 1enable servers 1target 1 {ipaddr 10.1.1.1tcpopen 80,3,10}target 2 {ipaddr 10.1.1.2tcpopen 80,2,10}register targets 1,2enable targets 1,2// end of configurationWhat should be working:• You should be able to ping the default gateway 10.1.1.254 from the targets.• You should be able to ping the virtual web server 172.16.1.10 from the router.• Clients from the Internet are able to initiate TCP connection to port 80 on the virtual WebServer 172.16.1.10 (now being represented by <strong>BalanceNG</strong>).• "show servers" <strong>and</strong> "show targets" in <strong>BalanceNG</strong> interactive mode should show everythingup <strong>and</strong> operating.7.3 Load Balancing in Dual Legged Switching ModeThis example shows how to set up <strong>BalanceNG</strong> as a transparent load balancing layer 2(Ethernet) switch. You should change the example network "172.16.1.0/24" to match your ownnetwork setup (<strong>and</strong> the server address too of course). This example can be fully tested with<strong>BalanceNG</strong> in trial mode without any licensing.7.3.1 The initial networkConsider this to be the simple initial network configuration before inserting the <strong>BalanceNG</strong>node (the network 172.16.1.0/24 should represent a public allocated address space):Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 130 / 143Grünwald Germany / All Rights Reserved
What should be working:Figure 6: Network configuration without <strong>BalanceNG</strong>• You should be able to ping the default gateway 172.16.1.254 from the Web Server.• Clients from the Internet are able to initiate TCP connection to port 80 on the Web Server172.16.1.10.7.3.2 Dual Legged Switching ModeThe key idea for <strong>BalanceNG</strong> in transparent switching mode is to connect two layer 2areas with identical layer 3 network parameters. <strong>BalanceNG</strong> is configured to represent theold web server IP address 172.16.1.10, load balancing to the two targets ("virtual servers")172.16.1.100 <strong>and</strong> 172.16.1.101. There's no need to change either the default gateway or thenetwork parameters on the target machines to something else. <strong>BalanceNG</strong> needs its ownaddress for ARP resolving, this is specified as "real" address in the network section.Although this flavour of <strong>BalanceNG</strong> operation is very easy <strong>and</strong> simple to setup, it has onemajor disadvantage: High Availability (HA) with VRRP is not supported in Layer 2 DualLegged Switching Mode operation of <strong>BalanceNG</strong>. This is because VRRP allows failover of"own" IP addresses from one node to another but does not offer any failover support oflearned layer 2 MAC-Addresses of other machines (!).This is how the new network looks like:<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 131 / 143
Figure 7: Network configuration with <strong>BalanceNG</strong> operating in "layer 2 dual leggedswitching mode"7.3.3 The Configuration FileThis is the <strong>BalanceNG</strong> configuration for this example. The <strong>BalanceNG</strong> box needs twointerfaces which are both member of the same layer 3 network. The "real" address in thenetwork section is the source address for ARP resolving. Layer 2 switching mode has to beenabled with the "l2switch" configuration keyword.// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0interface eth1network 1 {name "local network"addr 172.16.1.0mask 255.255.255.0real 172.16.1.252interfaces eth0,eth1}register network 1enable network 1l2switchserver 1 {ipaddr 172.16.1.10targets 1,2port 80}register server 1enable server 1target 1 {Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 132 / 143Grünwald Germany / All Rights Reserved
ipaddr 172.16.1.100tcpopen 80,3,10}target 2 {ipaddr 172.16.1.101tcpopen 80,2,10}register targets 1,2enable targets 1,2// end of configurationWhat should be working:• You should be able to ping the default gateway (router) 172.16.1.254 from the targets.• You should be able to ping the virtual web server 172.16.1.10 from the router.• Clients from the Internet are able to initiate TCP connection to port 80 on the virtualWeb Server 172.16.1.10 (now being represented by <strong>BalanceNG</strong>).• The targets should be reachable as before, except port 80 which is masked out by<strong>and</strong> h<strong>and</strong>led by <strong>BalanceNG</strong>.• "show servers" <strong>and</strong> "show targets" in <strong>BalanceNG</strong> interactive mode should showeverything up <strong>and</strong> operating.7.4 Operating <strong>BalanceNG</strong> as a Layer 2 SwitchTo do Layer 2 switching only between a number of interfaces (eth0, eth1 <strong>and</strong> eth2) the veryshort config file looks like this:// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)hostname testinterface eth0interface eth1l2switch// end of configurationIf you want to dump all traffic for later analysis with automatic file rotation see the "dump"comm<strong>and</strong>.7.5 Load Balancing in Direct Server Return Mode (DSR)This simple "Direct Server Return" example should give you a starting point for your own testsetup. You should change the example network "172.16.1.0/24" to match your own networksetup (<strong>and</strong> the server address too). This example can be fully tested with <strong>BalanceNG</strong> in trialmode without any licensing.7.5.1 The Initial NetworkConsider this to be the simple initial network configuration before inserting the <strong>BalanceNG</strong>node (the network 172.16.1.0/24 should represent a public allocated address space):<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 133 / 143
What should be working:Figure 8: Network configuration without <strong>BalanceNG</strong>• You should be able to ping the default gateway 172.16.1.254 from the Web Server.• Clients from the Internet are able to initiate TCP connection to port 80 on the Web Server172.16.1.10.7.5.2 Load balancing to two targets in DSR-ModeThe key idea for <strong>BalanceNG</strong> in DSR mode is to configure the IP address of the VirtualServer (172.16.1.10 in this example) as an alias on the Loopback interface inside theTargets. This makes the Targets addressable on Layer 2 leaving the Virtual Server Addressunchanged. The machine must not answer any ARP requests for the virtual server address.Figure 9: Network configuration <strong>BalanceNG</strong> single legged balancing to two targetsEstablishing the Loopback AliasesUse the following comm<strong>and</strong>s to establish the Loopback-alias on the Targets:Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 134 / 143Grünwald Germany / All Rights Reserved
Linux:ifconfig lo:0 netmask 255.255.255.255 -arp upSolaris:ifconfig lo0:1 plumbifconfig lo0:1 netmask 255.255.255.255 upIn our example this would be the following comm<strong>and</strong> line (assuming a Linux operating system)executed on both Target 1 <strong>and</strong> Target 2:# ifconfig lo:0 172.16.1.10 netmask 255.255.255.255 -arp upAdditionally it might be necessary to disable invalid ARP replies (Linux only):# echo 1 > /proc/sys/net/ipv4/conf/eth0/arp_ignore# echo 2 > /proc/sys/net/ipv4/conf/eth0/arp_announceThe Packet flow in this setup is as follows:Figure 10: Packet Flow in a DSR (Direct Server Return) setup7.5.3 The Configuration FileThis is the <strong>BalanceNG</strong> configuration for this DSR example. The <strong>BalanceNG</strong> box is connectedto the switch with one interface (eth0) only. The "real" address in the network section is beingused as source address for ARP resolving <strong>and</strong> health checks.// configuration taken Tue Oct 10 21:39:59 2006// <strong>BalanceNG</strong> 1.840 (created 2007/04/29)interface eth0network 1 {name "local network"addr 172.16.1.0mask 255.255.255.0real 172.16.1.252interface eth0<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 135 / 143
}register network 1enable network 1gateway {ipaddr 172.16.1.254}server 1 {ipaddr 172.16.1.10targets 1,2port 80}register server 1enable server 1target 1 {ipaddr 172.16.1.100tcpopen 80,3,10dsr enable}target 2 {ipaddr 172.16.1.101tcpopen 80,2,10dsr enable}register targets 1,2enable targets 1,2// end of configurationWhat should be working:• You should be able to ping the default gateway 172.16.1.254 from the targets.• You should be able to ping the virtual web server 172.16.1.10 from the router.• Clients from the Internet are able to initiate TCP connection to port 80 on the virtual WebServer 172.16.1.10 (now being represented by <strong>BalanceNG</strong>).• "show servers" <strong>and</strong> "show targets" in <strong>BalanceNG</strong> interactive mode should show everythingup <strong>and</strong> operating.7.6 Direct Server Return Example with bngagent <strong>and</strong> VRRP7.6.1 The Network SetupThe network setup of this example is very simple, two <strong>BalanceNG</strong> nodes are connected“single legged” to the internal production network:Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 136 / 143Grünwald Germany / All Rights Reserved
Figure 11: Production Network Setup with DSR, session syncing, bngagent <strong>and</strong> VRRP-HAThis example is similar to the single node DSR example, but shows the following moreadvanced techniques:• Dual node HA setup with session table synchronization,• Dual port setup which associates ports 80 <strong>and</strong> 443 to the same session,• Health check with external http.monitor script,• Session creation based on system load feedback retrieved with the <strong>BalanceNG</strong> agent"bngagent".The configuration files in this example are complete <strong>and</strong> are meant to be a reference ready forproduction use. This example requires licensing to enable VRRP. Please contact us for testlicenses if needed.7.6.2 Establishing the Loopback AliasesUse the following comm<strong>and</strong>s to establish the Loopback-alias on the Targets (as in example 3):Linux:ifconfig lo:0 netmask 255.255.255.255 -arp upSolaris:ifconfig lo0:1 plumbifconfig lo0:1 netmask 255.255.255.255 upIn our example this would be the following comm<strong>and</strong> line (assuming a Linux operating system)executed on both Target 1 <strong>and</strong> Target 2:# ifconfig lo:0 172.16.1.10 netmask 255.255.255.255 -arp up<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 137 / 143
Additionally it is necessary to disable invalid ARP replies (Linux 2.6 kernel, take a look at theFAQ question Q2.09):# echo 1 > /proc/sys/net/ipv4/conf/all/arp_ignore# echo 1 > /proc/sys/net/ipv4/conf/eth0/arp_ignore# echo 2 > /proc/sys/net/ipv4/conf/all/arp_announce# echo 2 > /proc/sys/net/ipv4/conf/eth0/arp_announceIf the target is a Windows system, please follow the following steps:First, the MS Loopback Adapter has to be created as follows:• Start->Settings->Control Panel->Add/Remove Hardware• Add/troubleshoot a device->Next• Add a new device->Next• No, select from list->Next• Network Adapters->Next• Select "Microsoft" as Manufacturer->select "MS Loopback Adapter"->Next->FinishThe configuration of the just created Loopback Adapter is as follows:• Start->Settings->Control Panel->Network <strong>and</strong> Dial up Connections• Right click on new adapter selecting properties• Only "Internet Protocol" needs to be selected (remove selection of "Client for MSNetworks" <strong>and</strong> "File <strong>and</strong> Printer sharing")• TCP/IP Properties->enter IP address of virtual server (the same address as in the<strong>BalanceNG</strong> server ipaddr definition)• do not enter a default gateway• Advanced->Set Interface Metric to 254 (this step is important to stop ARP responding)• OK <strong>and</strong> save all changes.7.6.3 Starting bngagent on both TargetsThe <strong>BalanceNG</strong> feedback agent has to be started on reboot on both targets listening on port439 like this:# /usr/local/bin/bngagent 4397.6.4 The Master <strong>and</strong> Backup configuration filesNote the parameter settings of "vrrppreempt" <strong>and</strong> "sessionsync" which enable session tablesynchronization together with a master priority not equal to 255. The server definition containstwo ports 80 <strong>and</strong> 443, which declares connections to either of them to be related to the samesession. If two ports are specified in a server, the target definitions of the associated targetsmust not contain any specific port or protocol settings.7.6.4.1 The Master Configuration File// configuration taken Sun Jul 23 17:39:27 2006// <strong>BalanceNG</strong> 1.584 (created 2006/07/21)hostname masterremark "DSR configuration with dual node HA <strong>and</strong> sessionsynchronization"license MASTER-TEST d5b787e61745533a8c5858a3a5f2e855Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 138 / 143Grünwald Germany / All Rights Reserved
set {vrrppreempt 0sessionsync 1}interface eth0vrrp {vrid 9priority 200network 1}network 1 {name "local network"addr 172.16.1.0mask 255.255.255.0real 172.16.1.252interface eth0}register network 1enable network 1gateway {ipaddr 172.16.1.254}server 1 {ipaddr 172.16.1.10targets 1,2port 80,443protocol tcpmethod agent}register server 1enable server 1target 1 {ipaddr 172.16.1.100agent 439,2,5script "/usr/lib/mon/mon.d/http.monitor -p $port$ -u/index.html $ipaddr$",2,7dsr enable}target 2 {ipaddr 172.16.1.101agent 439,2,5script "/usr/lib/mon/mon.d/http.monitor -p $port$ -u/index.html $ipaddr$",2,7dsr enable}register targets 1,2enable targets 1,2// end of configuration<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 139 / 143
7.6.4.2 The Backup Configuration FileNote that the Backup Configuration File is almost the same as the Master BackupConfiguration File, only the “network 1 real” address <strong>and</strong> the “vrrp priority” differ:// configuration taken Sun Jul 23 17:39:27 2006// <strong>BalanceNG</strong> 1.584 (created 2006/07/21)hostname backupremark "DSR configuration with dual node HA <strong>and</strong> sessionsynchronization"license BACKUP-TEST 58e3b26452d39a3b59fb382c0ba03bacset {vrrppreempt 0sessionsync 1}interface eth0vrrp {vrid 9priority 100network 1}network 1 {name "local network"addr 172.16.1.0mask 255.255.255.0real 172.16.1.251interface eth0}register network 1enable network 1gateway {ipaddr 172.16.1.254}server 1 {ipaddr 172.16.1.10targets 1,2port 80,443protocol tcpmethod agent}register server 1enable server 1target 1 {ipaddr 172.16.1.100agent 439,2,5script "/usr/lib/mon/mon.d/http.monitor -p $port$ -u/index.html $ipaddr$",2,7dsr enable}target 2 {ipaddr 172.16.1.101agent 439,2,5script "/usr/lib/mon/mon.d/http.monitor -p $port$ -uDate: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 140 / 143Grünwald Germany / All Rights Reserved
index.html $ipaddr$",2,7dsr enable}register targets 1,2enable targets 1,2// end of configuration8 Technical Background Information8.1 <strong>BalanceNG</strong> Ethernet AddressesIn order to represent virtual IP-Addresses <strong>BalanceNG</strong> has to represent unique Mac addressesor Ethernet addresses on the local network.The Ethernet address of a virtual IP address which is under control of VRRP uses thest<strong>and</strong>ard VRRP Ethernet address 00:00:5e:00::00 (as specified in RFC 3768). ThisEthernet address is used uniquely for *all* Ethernet addresses under VRRP control.All other addresses (<strong>and</strong> also generally when VRRP is switched off) are taken from the"locally administered" Mac Address space.Locally Administered addresses are generally assigned usually by the network administratorinstead of the hardware vendor. Locally Administered addresses have the second bit of theirfirst octet set to one (value 02 in printed format.)Possible locally administered ("private") Mac addresses are therefore:*2-**-**-**-**-***6-**-**-**-**-***A-**-**-**-**-***E-**-**-**-**-**Historically some of the areas out of "*2", "*A" <strong>and</strong> "*E" have been used in the past by severalvendors, so taking addresses out of the "*6" area is absolutely save in that sense.<strong>BalanceNG</strong> uses a prefix of "06:00" as the first two octets of a virtual Ethernet address <strong>and</strong>maps the IPv4 IP-address into the remaining 4 octets.Example: An IP-Address of 172.17.2.188 represented by <strong>BalanceNG</strong> would "own" theEthernet address "06:00:ac:11:02:bc" on Ethernet level.The <strong>BalanceNG</strong> "show arphash" shows the internal associations in all rows where the "vip"flag is set, e.g.:bng# show arphashipaddr ethaddr net flags-------------------------------------------------172.17.2.90 00:e0:81:58:ef:2f 0172.17.2.188 06:00:ac:11:02:bc 1 vip fix172.17.2.189 06:00:ac:11:02:bd 1 vipbng#<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 141 / 143
8.2 Implementation of <strong>BalanceNG</strong> Session TableSynchronization<strong>BalanceNG</strong> uses a VRRP extension by using a VRRP packet type 2, which is unknown <strong>and</strong>undefined by the VRRP version 2 st<strong>and</strong>ard. The session table information is packed into thespace of 4 IP addresses which allows easy reading with network analyzers. The packing ofsession table information is as follows:IP address 0: Session source IP addressIP address 1: Session source port in the lower 2 octets (not a real IP address)IP address 2: Server number in the higher 2 octets,Target number in the lower 2 octetsIP address 3: Server specific session timeout (0 if not set).Here an example of a session announcement as it could appear in the Ethereal packetanalyzer (Session 172.17.2.4 port any -> 172.17.2.189 port 22; Target 1):Frame 19 (70 bytes on wire, 70 bytes captured)Ethernet II, Src: IETF-VRRP-virtual-router-VRID_0a (00:00:5e:00:01:0a),Dst: 01:00:5e:00:00:12 (01:00:5e:00:00:12)Internet Protocol, Src: 172.17.2.188 (172.17.2.188), Dst: 224.0.0.18 (224.0.0.18)Virtual Router Redundancy ProtocolVersion 2, Packet type 2 (Unknown)Virtual Rtr ID: 10Priority: 255 (This VRRP router owns the virtual router's IP address(es))Count IP Addrs: 5Auth Type: No Authentication (0)Adver Int: 1Checksum: 0x81f3 [correct]IP Address: 172.17.2.4 (172.17.2.4)IP Address: 0.0.0.0 (0.0.0.0)IP Address: 0.1.0.1 (0.1.0.1)IP Address: 0.0.0.0 (0.0.0.0)IP Address: 0.0.0.0 (0.0.0.0)Session table information is being broadcasted by the current active master node only foractive sessions <strong>and</strong> controlled by the “sessionsynciv” parameter to keep the additional trafficlow.Over all, this is a very simple <strong>and</strong> efficient method to keep the session tables of the backupnodes in sync. We call this method “best effort session table synchronization”.Date: Apr 29, 2007 <strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0© Copyright 2007 by Inlab <strong>Software</strong> GmbHPage 142 / 143Grünwald Germany / All Rights Reserved
9 References/1/ Radia Perlman: Interconnections Second EditionAddison Wesley, ISBN 0201634481/2/ Rich Seifert: The Switch BookWiley & Sons, ISBN 0471345865/3/ R. Hinden et. al.: Virtual Router Redundancy Protocol (VRRP)RFC3768<strong>BalanceNG</strong> <strong>1.x</strong> User <strong>and</strong> Reference Manual 1.840.0 Date: Apr 29, 2007© Copyright 2007 by Inlab <strong>Software</strong> GmbHGrünwald, Germany / All Rights Reserved Page 143 / 143
Change language