nlbwmon can be used on a linux router to monitor bandwidth used by network hosts. Network statistics are collected and stored in a database. The client utility (nlbw) can query the daemon for current statistics.
By default, nlbwmon tracks bandwidth used over a one month interval, starting on the first of the month. A database is kept for each interval, up to 10 by default, after that the oldest one is deleted.
nlbwmon tracks traffic by IP Version (ipv4/ipv6), by IP Address, by MAC address, and by layer7 protocol (ie, port numbers). All tracking information is kept in the database. The default protocol file contains approximately 45 port definitions. The user can add/remove ports to this file as necessary. Any traffic that doesn't match a port definition is classified as 'Other'.
NOTE: If the user is not interested in layer7 protocol information, removing all protcools from the protocol file will classify all traffic into 'other', vastly reducing the database size.
nlbwmon uses a netlink socket to pull usage information from the linux kernel. nlbwmon collects statistic information from linux conntrack entries. This method is quite efficient compared to other methods of monitoring bandwidth usage.
Each time the conntrack entries are polled, their counters are reset (zero-on-read). When a conntrack entry is destroyed, nlbwmon is notified by the kernel, and stats are collected from that entry before it is deleted.
NOTE: an init script and config file is provided for lede, allowing these settings to be configured via uci or via /etc/config. Just take a look at /etc/config/nlbwmon.
- -i sec
- Interval used to save in-memory database to file.
- -r sec
- Interval used to poll the conntrack entries.
- -s network
- Specify network subnet to monitor.
- -o /path/to/database-folder
- Storage directory for the database files.
- -p /path/to/protocol-file
- Protocol description file, used to distinguish traffic streams by IP protocol number and port.
- -G count
- Number of database generations to retain. After the limit is reached, the oldest database files are deleted. The default is 10.
- -I interval
- Accounting period interval. May be either in the format YYYY-MM-DD/NN, to start a new accounting period exactly every NN days, beginning at the given date, or a number specifiying the day of month at which to start the next accounting period. For example:
2017-01-17/14 # every 14 days, starting Jan 17, 2017
-2 # second to the last day of the month, e.g. 30th in March
1 # first day of the month (default)
- -P
- Whether to preallocate the maximum possible database size in memory. This is mainly useful for memory constrained systems which might not be able to satisfy memory allocation after longer uptime periods. Only effective in conjunction with database_limit, ignored otherwise.
- -Z
- Whether to gzip compress archive databases. Compressing the database files makes accessing old data slightly slower but helps to reduce storage requirements.
NOTE: See the examples below to get started quickly.
- -S /path/to/domain.socket
- Path to unix domain socket. Default is /var/run/nlbwmon.sock. This should not be required unless the daemon was instructed to use another socket path for some reason.
- -c command
- Specify a command. Current commands are: show, json, csv, list, commit. See below for more information about commands.
- -p /path/to/procol-database
- Protocol description file, used to distinguish traffic streams by IP protocol number and port.
- -g col[,col]
- Group output by the specified column. Prefix column with a - to invert order.
- -o col[,col]
- Order output by the specified column. Prefix column with a - to invert order.
- -t YYYY-MM-DD
- Read data from the specified database, instead of the active database. Use the list command to view available databases.
- -n
- Use plain numbers, dont divide to get K, M, G, etc.
- -s char
- Specify the separator character when using CSV format. If no argument is provided, an empty string is assumed. Currently only applies to CSV format.
- -q char
- Specify the quote character when using CSV format. If no argument is provided, an empty string is assumed. Currently only applies to CSV format.
- -e char
- Specify the escape character when using CSV format. If no argument is provided, an empty string is assumed. Currently only applies to CSV format.
Output stats in human readable format.
Output stats in JSON format.
Output stats in CSV format.
List available databases. Select a database to read from, and specify it with the -t option.
Write data stored in memory to database file. Use just before a reboot for example.
You can easily build nlbwmon from lede by including this repository in your build environment:
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
Once the package is installed, use the "nlbw" command to dump gathered values:
root@jj:~# nlbw -c show
Fam Host ( MAC ) Layer7 Conn. > Downld. ( > Pkts. ) Upload ( Pkts. )
IPv4 10.11.12.7 (47:e1:b9) HTTPS 111 2.99 MB ( 4.38 K) 816.77 KB ( 5.86 K)
IPv6 2001:470:527e::6666:b3ff:fe47:e1b9 (47:e1:b9) HTTPS 14 546.07 KB ( 930 ) 196.05 KB ( 932 )
IPv6 2001:470:527e::6666:b3ff:fe47:e1b9 (47:e1:b9) HTTP 15 296.07 KB ( 194 ) 28.67 KB ( 329 )
IPv4 10.11.12.167 (a3:5c:1c) HTTPS 24 210.53 KB ( 299 ) 61.86 KB ( 400 )
IPv4 10.11.12.17 (2c:97:19) HTTPS 31 163.54 KB ( 481 ) 352.28 KB ( 593 )
IPv4 10.11.12.7 (47:e1:b9) other 353 104.52 KB ( 610 ) 64.79 KB ( 709 )
IPv4 10.11.12.15 (94:59:06) HTTPS 6 49.48 KB ( 85 ) 18.36 KB ( 103 )
IPv4 10.11.12.7 (47:e1:b9) HTTP 24 14.24 KB ( 152 ) 16.89 KB ( 177 )
IPv4 10.11.12.167 (a3:5c:1c) other 15 6.03 KB ( 80 ) 5.73 KB ( 68 )
IPv4 10.11.12.17 (2c:97:19) other 11 800 B ( 16 ) 3.11 KB ( 47 )
IPv6 2001:470:527e::6666:b3ff:fe47:e1b9 (47:e1:b9) IPv6-ICMP 1 728 B ( 7 ) 5.68 KB ( 56 )
IPv4 10.11.12.17 (2c:97:19) HTTP 1 456 B ( 5 ) 450 B ( 6 )
IPv4 10.11.12.7 (47:e1:b9) ICMP 1 420 B ( 5 ) 420 B ( 5 )
IPv4 10.11.12.15 (94:59:06) other 3 228 B ( 3 ) 228 B ( 3 )
IPv6 2001:470:527e::a886:c6fc:82a4:bba9 (2c:97:19) HTTP 1 80 B ( 1 ) 144 B ( 2 )
IPv6 2001:470:527e::a886:c6fc:82a4:bba9 (00:00:00) HTTP 2 0 B ( 0 ) 0 B ( 0 )
IPv6 2001:470:527e::1 (35:88:49) HTTP 18 0 B ( 0 ) 1.64 KB ( 21 )
Use -g (group) and -o (order) flags to influence output:
root@jj:~# nlbw -c show -g mac,fam -o conn
Fam MAC < Conn. Downld. ( Pkts. ) Upload ( Pkts. )
IPv6 74:81:14:2c:97:19 1 80 B ( 1 ) 144 B ( 2 )
IPv6 00:00:00:00:00:00 2 0 B ( 0 ) 0 B ( 0 )
IPv4 a0:99:9b:94:59:06 9 49.70 KB ( 88 ) 18.59 KB ( 106 )
IPv6 00:0d:b9:35:88:49 19 0 B ( 0 ) 1.64 KB ( 21 )
IPv6 64:66:b3:47:e1:b9 32 857.92 KB ( 1.16 K) 242.99 KB ( 1.34 K)
IPv4 00:f7:6f:a3:5c:1c 39 216.57 KB ( 379 ) 67.59 KB ( 468 )
IPv4 74:81:14:2c:97:19 43 164.77 KB ( 502 ) 355.83 KB ( 646 )
IPv4 64:66:b3:47:e1:b9 501 3.12 MB ( 5.19 K) 905.20 KB ( 6.79 K)
Prefix order field names with dash to invert order:
root@jj:~# nlbw -c show -g mac -o -conn,-tx
MAC > Conn. Downld. ( Pkts. ) > Upload ( Pkts. )
64:66:b3:47:e1:b9 542 3.96 MB ( 6.38 K) 1.12 MB ( 8.16 K)
74:81:14:2c:97:19 44 164.85 KB ( 503 ) 355.97 KB ( 648 )
00:f7:6f:a3:5c:1c 42 216.61 KB ( 380 ) 67.63 KB ( 469 )
00:0d:b9:35:88:49 20 0 B ( 0 ) 1.79 KB ( 23 )
a0:99:9b:94:59:06 9 49.70 KB ( 88 ) 18.59 KB ( 106 )
00:00:00:00:00:00 2 0 B ( 0 ) 0 B ( 0 )
Machine readable output, should work well with rrdcollect:
$ nlbw -c csv -g mac -o mac -q
mac conns rx_bytes rx_pkts tx_bytes tx_pkts
00:00:00:00:00:00 411 72968 751 61428 767
34:02:86:17:5e:03 598 239950465 171095 5715237 86155
ac:37:43:a1:2d:47 125 284027227 205678 6451867 107297
Read stats for a certain time period:
$ nlbw -t 2017-02-01 -c csv -g mac -o mac -q
mac conns rx_bytes rx_pkts tx_bytes tx_pkts
00:00:00:00:00:00 157 26960 205 17878 218
34:02:86:17:5e:03 327 117213007 83817 3366892 51560
Use the json query to dump the raw database values in JSON format:
root@jj:~# nlbw -c json
...