The bngtap Utility #

bngtap is a utility which reads packets from the instance-specific BalanceNG SHM packet queue. The SHM packet queue segments appear in the Linux filesystem in the directory /dev/shm as usual. The SHM packet queue file name format in /dev/shm is bng.pq.instance.tap (e.g. bng.pq.0.tap for the default instance 0).

The SHM packet queue segments include a f2568() magic hash at the beginning to verify the type of the SHM segment and to assure that the PQueue.c versions of reader (bngtap) and writer (BalanceNG) do match.

BalanceNG writes the packets together with the capture time timestamp to the SHM packet queue either from the tap module or by enabling specific interface specific parameters (parameters starting with tap).

A packet queue can get full (when there’s no bngtap reader, for example). In this case the packet contents are lost (not in the queue) and BalanceNG packet processing just proceeds.

bngtap empties the queue from the reader side at startup per default, this can be switched off with the -n|--noreset option.

bngtap flushes the dump stream per packet with pcap_dump_flush(). This results in an immediate per packet display when piping into tcpdump or tshark.

Usage #

usage: bngtap [options] output.pcap
       options:
       -b|--blimit <n>    specify a byte limit
       -p|--plimit <n>    specify a packet limit
       -i|--instance <i>  set bng instance (default 0)
       -n|--noreset       do not empty queue on startup
       -s|--silent        silent mode
       -h|--help          show usage
       -v|--version       show version
       -c|--copyright     show copyright

Examples #

Collecting packets to a file #

$ sudo bngtap /tmp/example.pcap
...

Collecting packets from BalanceNG instance 1 to a file #

$ sudo bngtap -i 1 /tmp/instance1.pcap
...

Piping to tcpdump #

$ sudo bngtap -s - | tcpdump -r -
...

Piping to tshark #

$ sudo bngtap -s - | tshark -r -
...