The bng Command

The bng Command #

BalanceNG is represented by a single binary - bng - with an absolute minimum of shared library dependencies.

Invoking BalanceNG with no option displays basic usage information together with the usual Copyright information, version, build platform and creation date.

Example:

# bng

       This is BalanceNG 6.030 RHEL9-x86_64 (2023/09/20)

  Copyright (C) 2005-2022,2023 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]

#

bng command [instance] #

bng start [instance] #

This starts a BalanceNG instance in the background as a daemon. BalanceNG reads as a first step the configuration for that instance (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
#

bng stop [instance] #

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
#

bng restart [instance] #

This restarts a BalanceNG instance and is equivalent to execute “bng stop” and “bng start” consecutively.

Example:

# 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 ...
#

bng reload [instance] #

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.

Example:

# bng reload
#

bng [-e] control [instance] #

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 [-e] auxctl [instance]
  • bng [-e] cmdctl [instance]
  • bng [-e] imsctl [instance]
# 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#
...

bng purge [instance] #

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.

Example:

# bng -I
 0 off
 3 off
# bng purge 3
BalanceNG: /etc/bng3.conf successfully deleted
#

bng status [instance] #

This provides information about the current state of a BalanceNG instance.

Example:

# 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
#

bng -option #

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.

bng -c config-file … #

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 /.

Example:

# bng -c /tmp/test001.conf start
BalanceNG: starting up ...
#

bng -d … #

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.

bng -e … #

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).

bng -f … #

This option forces the backend started with bng start to stay in foreground and connected to the controlling TTY.

bng -i instance … #

This option modifies the instance to which the command is applied. This is in effect for the following cases (otherwise this option is ignored):

  • bng start|stop|control …
  • bng -M

bng -I #

This command displays information about the state of all instances of BalanceNG on the system. running indicates a running instance, whereas off indicates an available configuration file.

Example:

# 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
#

bng -L #

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.

Example:

# bng -L ExampleTEST 3bef9fa6b31acec6f64abc162b3dcbda
# echo $?
0
#

bng -M #

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.

Example:

# 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
#

bng -N #

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.

Example:

# bng -N
2a:e2:2f:38:4a:20
#

bng -V #

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):

  • On macOS the vnodeid is identical to the HW MAC address of the en0 interface.
  • On Linux the vnodeid is solely derived from the /etc/machine-id identification file.
All instances on a machine share the same vnodeid.

Example:

# bng -V
c7:f9:dd:6d:a2:74
#

bng -W serial key #

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.

Example:

# bng -W ExampleTEST 3bef9fa6b31acec6f64abc162b3dcbda
#