Invoking BalanceNG with no option displays basic usage information together with the usual Copyright information.
# bng This is BalanceNG 5.014 (created 2022/11/08) Copyright (C) 2005-2021,2022 by Inlab Networks GmbH, Germany. All rights reserved / Alle Rechte vorbehalten. Visit load-balancer.inlab.net for further information. usage: bng [-df] start|stop|restart|status|control [instance] #
This starts a BalanceNG instance in the background as a daemon. BalanceNG reads as a first step the configuration from (if it exists) and commences with its operation. If the optional instance parameter is omitted, the default instance 0 is assumed and started. Alternatively, a specific instance can be supplied with the -i option.
Example (starting the default instance 0):
# bng start BalanceNG: starting up ... #
Example (starting instance number 41):
# bng start 41 BalanceNG: starting up instance 41 ... # bng -i 41 stop BalanceNG: shutdown of instance 41 PID 74926 complete #
If there’s already a BalanceNG instance running on this machine, the output may look as follows:
# bng start BalanceNG: already running with PID 7914 #
This stops a BalanceNG instance, the output may look like this:
# bng stop BalanceNG: shutdown of PID 7914 complete # bng stop 41 BalanceNG: shutdown of instance 41 PID 27231 complete #
This restarts a BalanceNG instance and is equivalent to execute “bng stop” and “bng start” consecutively.
# bng restart BalanceNG: shutdown of PID 7919 complete BalanceNG: starting up ... # bng restart 41 BalanceNG: shutdown of instance 41 PID 27419 complete BalanceNG: starting up instance 41 ... #
This allows to reload the configuration file and potentially updated server / target relationships on the current VRRP master. Not affected session table entries are maintained.
A reload fails, if there are any changes to the network and VRRP sections or to the “set” parameter section (and a “bng restart” is required immediately afterwards).
In that case the error message “ERROR: was unable to reload, restart required.” is reported to the log.
This invocation is equivalent to execute a “reload” command in the “bng control” CLI.
# bng reload #
This invokes the interactive configuration mode (the bng control CLI) of a BalanceNG instance, “bng control” may be abbreviated as “bng ctl”.
If the option “-e” is specified, this command exits with EX_TEMPFAIL if the same command frontend is already running.
Typing EOF (Ctrl-D) exits the interactive configuration mode.
The interactive configuration mode allows simple command line editing using the arrow-keys. This is only active is an interactive terminal is detected on stdin, otherwise the command line editing option is switched off to allow automated programs to operate on the command line.
Since only one single command channel can be active at a time, the following three additional command channels are also available (with the same functionality):
# bng control BalanceNG: connected to PID 7928 bng# ... # bng restart 41 BalanceNG: not yet running BalanceNG: starting up instance 41 ... # bng control 41 BalanceNG: connected to instance 41 PID 27479 bng# ...
This command removes the associated configuration file of the supplied instance without any further warnings. The instance needs to be down (off) for that purpose. If no instance is specified, the configuration file /etc/bng.conf of the default instance is deleted. A private configuration data file (e.g. /etc/bng.private) is not deleted by this command.
# bng -I 0 off 3 off # bng purge 3 BalanceNG: /etc/bng3.conf successfully deleted #
This provides information about the current state of a BalanceNG instance.
# bng status BalanceNG: running with PID 7921 # bng stop BalanceNG: shutdown of PID 7921 complete # bng status BalanceNG: not running # # bng status 41 BalanceNG: instance 41 running with PID 27423 # bng stop 41 BalanceNG: shutdown of instance 41 PID 27423 complete # bng status 41 BalanceNG: instance 41 not running #
There are a few bng command line options available, some of them are modifying the execution of a bng command in a way and some perform a specific action by themselves.
The -c option allows to specify a specific configuration file which is being loaded on start or restart.
In case that the configuration file cannot be opened for reading (or does not exist), the BalanceNG instance starts up with a empty default configuration with no further error message.
The path specification of the configuration file needs to be absolute since the current working directory of any BalanceNG instance is always /.
# bng -c /tmp/test001.conf start BalanceNG: starting up ... #
This option enables the output of debugging messages when applied to bng start. Additionally the backend stays in foreground and connected to the controlling TTY.
This option changes the behaviour of the four control channels in the case that the same command frontend is already running. With -e set, EX_TEMPFAIL is returned if the same command frontend is already running (otherwise the invocation is blocked waiting for the release).
This option forces the backend started with bng start to stay in foreground and connected to the controlling TTY.
This option modifies the instance to which the command is applied. This is in effect for the following cases (otherwise this option is ignored):
This command displays information about the state of all instances of BalanceNG on the system. “running” indicates a running instance, whereas “off” indicates an available configuration file.
# bng -I 0 off # bng start 3 BalanceNG: starting up instance 3 ... # bng -I 0 off 3 running # bng ctl 3 BalanceNG: connected to instance 3 PID 14277 bng# save ok bng# ... bye # bng stop 3 BalanceNG: shutdown of instance 3 PID 14277 complete # bng -I 0 off 3 off #
This command (with option) allows to check the validity of a serial number and a license key for the current node. It requires two arguments, the serial number and the license key. If the license information is valid the invocation of bng returns the return code 0 (or EX_NOPERM otherwise).
This functionality includes a delay of a few seconds in order to make brute force attacks impractical.
# bng -L ExampleTEST 3bef9fa6b31acec6f64abc162b3dcbda # echo $? 0 #
This command displays the MAC address of a BalanceNG instance, which is always allocated out of the MA-L (MAC address large) block of Inlab Networks (34-38-AF). An instance number may be specified additionally with the -i option.
Since the MAC address is instance specific this command allows to display the MAC address of a specific instance using the modifier option -i.
# bng -M 34:38:af:46:44:eb # bng -i 0 -M 34:38:af:46:44:eb # bng -i 1 -M 34:38:af:47:44:eb # bng -i 120 -M 34:38:af:3e:44:eb # bng -i 129 -M BalanceNG: invalid instance number #
This command option displays the BalanceNG nodeid of the BalanceNG host machine without the need for starting a BalanceNG instance. The nodeid is used for licensing purposes and for determining the instance specific MAC addresses.
All instances on a machine share the same nodeid.
# bng -N 2a:e2:2f:38:4a:20 #
This command displays the BalanceNG vnodeid (virtual nodeid) of the BalanceNG host machine without the need for starting a BalanceNG instance. The vnodeid is useful for licensing in virtual environments and is generated as follows (depending on the operating system):
All instances on a machine share the same vnodeid.
# bng -V c7:f9:dd:6d:a2:74 #
This command option expects two arguments, a serial number and a license key. A “license” line with those parameters is written to the file /etc/bng.global without further warning.
A preexisting file /etc/bng.global is overwritten. Possible invalid license data in /etc/bng.global may be escalated to a valid license if contained in an instance specific configuration file - if a instance specific configuration file contains invalid licensing data, but /etc/bng.global does, the valid licensing from /etc/bng.global is kept.
# bng -W ExampleTEST 3bef9fa6b31acec6f64abc162b3dcbda #