nlbwmon Traffic Accounting Tool

nlbwmon is a Linux-based traffic accounting tool that monitors bandwidth usage by network hosts using netlink sockets to pull information from the Linux kernel's conntrack entries. It is highly efficient because it collects statistics directly from conntrack entries and is notified by the kernel when entries are destroyed.

Key features:

• Tracks traffic by IP Version (IPv4/IPv6), IP Address, MAC address, and Layer 7 protocol (via port numbers).
• Stores statistics in a database.
• Supports multiple database generations (default is 10) to retain historical data.
• Allows custom protocol definitions to classify traffic; unmatched traffic is classified as 'Other'.

To build nlbwmon within a LEDE build environment, add the repository to your feeds.conf and update your feeds.

cp feeds.conf.default feeds.conf
echo "src-git nlbwmon https://github.com/jow-/nlbwmon.git" >> feeds.conf
./scripts/feeds update nlbwmon
./scripts/feeds install nlbwmon

When using the nlbw client, you can manipulate the output structure using grouping and ordering flags:

• -g col[,col]: Group output by specified columns (e.g., mac, fam). Prefix a column name with - to invert the order.
• -o col[,col]: Order output by specified columns. Prefix a column name with - to invert the order.
• -n: Use plain numbers instead of human-readable units (K, M, G, etc.).

# Group by MAC and Family, order by connections
lbw -c show -g mac,fam -o conn

# Group by MAC, order by connections (descending) and transfer (descending)
lbw -c show -g mac -o -conn,-tx

The nlbw client supports several commands via the -c flag to define the output format and action:

• show: Outputs statistics in a human-readable format.
• json: Outputs statistics in JSON format.
• csv: Outputs statistics in CSV format.
• list: Lists available databases. Use the -t flag with a date to select a specific database for reading.
• commit: Writes data currently stored in memory to the database file (useful before a system reboot).

The nlbwmon daemon manages the collection and storage of bandwidth statistics. You can configure its behavior using command-line flags. If using LEDE/OpenWrt, settings can also be managed via UCI or /etc/config/nlbwmon.

# Example of common daemon configuration flags
# -i: interval to save in-memory DB to file (seconds)
# -r: interval to poll conntrack entries (seconds)
# -s: network subnet to monitor
# -o: storage directory for database files
# -p: path to protocol description file
# -G: number of database generations to retain (default 10)
# -I: accounting period interval (e.g., '1' for 1st of month, '2017-01-17/14' for every 14 days)
# -P: preallocate maximum database size in memory
# -Z: gzip compress archive databases

The nlbw client utility is used to query the nlbwmon daemon for current or historical statistics. It communicates via a Unix domain socket (default: /var/run/nlbwmon.sock).

# Basic usage to show human-readable stats
lbw -c show

# Query a specific historical database using a date
lbw -t 2017-02-01 -c show

# Output in JSON format
lbw -c json

# Output in CSV format with custom separator
lbw -c csv -s ","

The client_main function serves as the primary entry point for the nlbw client utility. It accepts standard command-line arguments (argc, argv) and returns an integer exit code. This function is intended to be called to initialize and run the client logic, typically when embedding the utility into another application or providing a custom entry point.

int client_main(int argc, char **argv);

The client_main function is the entry point for the nlbw utility. It handles argument parsing, initializes protocol databases, and dispatches the requested command. If you are embedding this logic or wrapping it, ensure you provide the necessary argc and argv parameters.

Note: The function relies on an internal opt structure (likely defined in client.h or nlbwmon.h) to store socket paths and protocol database locations.

int client_main(int argc, char **argv);

When using the -g (group by) or -o (order by) options, you can specify the following field names: