vnStat vnStat-on-Merlin v2.0.12 [2026-Mar-22] - Data Usage and Data Limit Monitoring using vnStat

[Martinski]

Release Notes for vnStat-on-Merlin v2.0.8 production version now available
[2025-Jul-05]

1) IMPROVED: Modified all SQLite3 calls to capture and log errors in the system log.

2) IMPROVED: Modified SQLite3 configuration parameters to improve the processing of database records.

3) IMPROVED: Added code to create a separate logfile to capture the SQLite3 errors with more verbosity.

Debug logfile default location: /opt/share/tmp/​

4) IMPROVED: Added error-handling code when an SQLite3 database operation fails to create a file.

5) IMPROVED: When an SQLite3 operation returns error messages indicating a corrupted binary, the error-handling code will now log a separate message to the system logger and to its own debug logfile to let users know of the corrupted SQLite3 and the need to remove and reinstall its Entware package.

6) IMPROVED: New code to remove duplicate parameter key names found in the configuration file. Getting duplicate key values can cause "bad number" or "arithmetic syntax" errors.

7) IMPROVED: Modified the startup call made in the 'post-mount' script to check if the USB-attached disk partition passed as an argument has indeed Entware installed.

8) IMPROVED: Modified the call made in the 'service-event' script to check if the parameter contains the script name.

9) IMPROVED: Show the current database file size information on the WebUI page.

10) IMPROVED: Show the "JFFS Available" space information for the "Data Storage Location" option on the WebUI page.

11) FIXED: Minor cosmetic glitch related to the "Data Usage Warning" message on the WebUI page, where the "Warning Bell" image had what appeared to be a "dot" underneath it. [Reported by @Tarek Yag]

12) Miscellaneous code improvements.


The fork from @dev_null's vnStat-on-Merlin add-on is now hosted on the AMTM-OSR GitHub repo:

GitHub - AMTM-OSR/vnstat-on-merlin: vnstat-on-merlin

vnstat-on-merlin. Contribute to AMTM-OSR/vnstat-on-merlin development by creating an account on GitHub.

github.com

For some important notes about vnStat-on-Merlin, see the following post by @dev_null:

vnStat - [Release] vnStat-on-Merlin - UI, CLI and email - data use and data limit monitoring - R1 and R2

vnStat-on-Merlin - Release versions - R1 and R2 Update 18 July 2021: Upgrade! For ARM and AARCH-based routers, we've got some great news: vnStat-on-Merlin Release 2 (R2) is now available for non-MIPS devices. This version is based on vnStat 2.7, recently included as an Entware package. More...

www.snbforums.com

 

[Tarek Yag]

I'm very glad that I'm contributing to the great Merlin communities! Looking forward more contributions to vnStat very soon.
Good luck everyone, and congratulations on the first release under the AMTM-OSR repository! I'll update in a few minutes.

 

[Martinski]

Release Notes for vnStat-on-Merlin v2.0.9 production version now available
[2025-Aug-14]

1) IMPROVED: Added code to double-check and make sure that the correct custom service script installed by vnStat-on-Merlin (for vnstatd) is found and executed, and to verify that it has not been overwritten or modified (e.g. via Entware package updates). These checks are performed at startup following a reboot, every time the vnstatd service is restarted, and every 5 minutes via the pre-existing cron job that generates stats.

2) Miscellaneous code improvements.


NOTE: This release prevents a possible scenario where an Entware update of the vnstat2 package installs its own service script, which may launch a separate vnstatd process outside of the control of vnStat-on-Merlin.



The fork from @dev_null's vnStat-for-Merlin add-on is now hosted on the AMTM-OSR GitHub repo:

GitHub - AMTM-OSR/vnstat-on-merlin: vnstat-on-merlin

vnstat-on-merlin. Contribute to AMTM-OSR/vnstat-on-merlin development by creating an account on GitHub.

github.com

 

[aru]

Thanks for developing vnStat! It’s been a very reliable and lightweight tool for long-term network traffic monitoring.

Currently vnStat shows RX/TX/Total traffic, which is great for historical usage tracking.

However, for users who want to understand whether their subscribed bandwidth is being fully utilized, the raw traffic numbers are not very intuitive.

For example, if a user subscribes to a 300M/300M connection, they may want to know not only how many GB were transferred, but also what percentage of their maximum capacity was used each day.

### Benefits
- Provides a more intuitive view of how efficiently the subscribed bandwidth is used.
- Helps with capacity planning (e.g., knowing when to upgrade or downgrade).
- Could also be useful for alerts or for visualization in vnStat frontends.

I’m not sure about the feasibility of adding this directly into vnStat, or if there are already similar tools that provide this feature.

Thanks for considering this suggestion!

 

[Martinski]

Thanks for developing vnStat! It’s been a very reliable and lightweight tool for long-term network traffic monitoring.

Currently vnStat shows RX/TX/Total traffic, which is great for historical usage tracking.

However, for users who want to understand whether their subscribed bandwidth is being fully utilized, the raw traffic numbers are not very intuitive.

For example, if a user subscribes to a 300M/300M connection, they may want to know not only how many GB were transferred, but also what percentage of their maximum capacity was used each day.

### Benefits
- Provides a more intuitive view of how efficiently the subscribed bandwidth is used.
- Helps with capacity planning (e.g., knowing when to upgrade or downgrade).
- Could also be useful for alerts or for visualization in vnStat frontends.

I’m not sure about the feasibility of adding this directly into vnStat, or if there are already similar tools that provide this feature.

Thanks for considering this suggestion!

I can take a look to see if it's something feasible (when time allows), but likely not within the next month or so due to workload and other priorities. Also, there are a couple of things I'd like to finish before the end of this month, and then one little feature I may add to YazDHCP (more on that on the YazDHCP thread).

 

[Tarek Yag]

A couple of months ago, I kept some features in mind to suggest to be added to vnStat script, which would be a great addition. However, I have other priorities right now that should keep these suggestions for later.

Anyhow, after I recently started experimenting with Dual WAN in failover/failback and load-balance modes, as a result of changes on my internet setup at home. I found out that the script cannot just monitor two interfaces since I need to monitor my two WAN interfaces (now named vlan2 and vlan3 instead of eth0).

This is a missing feature that I believe should be present in the script, and it's something that we might need to give some immediate attention, although -I'm unsure, but- it could be an easy modification/fix to get it to work as it should.

For reference, in Linux, the command vnstat actually supports merging multiple interface data internally using the "+" operator as described in the command's man page. Refer to this page for complete information

-i, --iface interface
Select one specific interface and apply actions to only it. For database queries, it is possible to merge the information of two or more interfaces using the interface1+interface2+... syntax. All provided interfaces must be unique and must exist in the database when the merge syntax is used. Optionally, depending on the InterfaceMatchMethod configuration setting, interface can be replaced with alias previously set using --setalias. Merge syntax isn't supported when alias is used. The -i, --iface option is optional and interface can be used as parameter on the command line for selecting the used interface even without the option being explicitly used.

Doing some troubleshooting as usual, I made a no-brainer try to get dn-vnstat to monitor both interfaces, but I faced errors where the script didn't allow me to do so:
1- The first try when I tried to input both interfaces for monitoring "vlan2+vlan3" at script install process where it rejected it because it doesn't match the required interface name format (for dn-vnstat script itself)

Input is not a valid interface or interface not up, please try again.

2- The second try when I edited the vnstat config file from the dn-vnstat script's CLI interface to input both interfaces (again, "vlan2+vlan3"), although it somehow started merging data and displaying it correctly, but it kept outputting an error every update:

**ERROR**: Unable to get vnStat Interface ID [gnr1].

In the end, I'm open for any workarounds/suggestions to get this to work accordingly with Dual WAN in my new network setup, before/without even making this needed script fix. And since I'm specialized in Software Engineering, I'm not very good at networking terminology, so any guidance to (maybe?) merging these two interfaces into one (for stats only?) that I can input to dn-vnstat script, would be much appreciated.

Kindly,

 

[Martinski]

Release Notes for vnStat-on-Merlin v2.0.10 production version now available
[2025-Nov-08]

1) IMPROVED: Modified code to re-initialize global parameters after the USB-attached drive has been mounted and Entware is found.

2) IMPROVED: More checks to clean up files when switching from JFFS to USB and vice versa.

3) IMPROVED: Removed old Tomato JavaScript file references.

4) Miscellaneous code improvements.



The fork from @dev_null's vnStat-on-Merlin add-on is now hosted on the AMTM-OSR GitHub repo:

GitHub - AMTM-OSR/vnstat-on-merlin: vnstat-on-merlin

vnstat-on-merlin. Contribute to AMTM-OSR/vnstat-on-merlin development by creating an account on GitHub.

github.com

 

[Martinski]

Release Notes for vnStat-on-Merlin v2.0.11 production version now available
[2025-Nov-16]

1) FIXED: Modified code to make sure we get the correct parameters when changing settings from the WebUI.
2) Miscellaneous code improvements.



The fork from @dev_null's vnStat-on-Merlin add-on is now hosted on the AMTM-OSR GitHub repo:

GitHub - AMTM-OSR/vnstat-on-merlin: vnstat-on-merlin

vnstat-on-merlin. Contribute to AMTM-OSR/vnstat-on-merlin development by creating an account on GitHub.

github.com

 

[Martinski]

Release Notes for vnStat-on-Merlin v2.0.12 production version now available
[2026-Mar-22]

1) NEW: Added code to support "Automatic Script Updates" via AMTM.

This new functionality requires AMTM 6.4 or a later version.​

2) IMPROVED: Modified format of some date parameters used in email and usage reports to follow the ISO-8601 international standard for consistency and to avoid ambiguity.

3) Improvements in CLI menu options formatting and handling.

4) Miscellaneous code improvements.



The fork from @dev_null's vnStat-on-Merlin add-on is now hosted on the AMTM-OSR GitHub repo:

GitHub - AMTM-OSR/vnstat-on-merlin: vnstat-on-merlin

vnstat-on-merlin. Contribute to AMTM-OSR/vnstat-on-merlin development by creating an account on GitHub.

github.com

 

[kriukas]

Dear developer(-s) thank you for supporting vnStat. Very useful on 5G connections, when ISP 5G connection is "unlimited" in the agreement-special part, but set "fair usage" real limit @1 TB in "common" agreement and then the next month is capped.

For reading speed simplicity, I cut this post into two parts. First is for consideration in the near future, second is simply deep examples. 4 mins reading total.

Given this situation, I would like to humbly ask, if there would be any chance to get not daily e-mails, but some solution, which monitors the "speed" and/or the "acceleration" at which the router limit is "eaten" and send e-mail warning.

The simplest solution to implement this would be an option for a weekly e-mail @1/7/14/28 day and @the last day 23:59:59 of the current month.

I can imagine the more sophisticated solutions like:

1. Your set limit divided by the days in the current month - get an e-mail.
2. Moving average statistics with regression over last X days.
3. Counting left Gb's over say 4 months and sending the e-mail with "typical left unused traffic with " estimate/write into some statistics file and donate that traffic for example to Tor node (your own script, which reads value and does the job).

I would be glad to try to help if not direct coding, but write principle algorithms and of course - testing.

--------------------------------------------------

I think such an improvement would be also security measure. For example - you have an unknown leakage of the traffic. Very simple practical example:

I live in the resort town, where population booms for 3-4 months and dwindle after children school time. I setup the router add-on SpdMerlin in the summer time. Speed are very varying, because my home is near the promenade ant I get ~25-150 Mbps DL/8-20 Mbps UL, depending on the time of the day. Right after September 1, that doubles. When autumn sets in that doubles again. When the temperature is around 0C and the landlords do not heat buildings at that time, and the weather is bad - soon you get 1 Gbps/150 Mbps - at that's my modem limit! Because I measured the speed hourly (for my own conclusions on the pattern of the bandwidth), my router setup have eaten the "fair use" bandwidth and at one month I have got 1,3 Tb traffic and a warning, that my speed will be severely capped next 3 months and excess of 1 Tb will be charged per/MB, if I again will get over 1 Tb. Correction of speed measurement every 6 hours, completely solved the problem.

Second example: my mother goes to sleep "with TV". TV as usual where I live is only display, and the IPTV box provides the content. I of course set sleep TV @1 hour. But the IPTV box is completely dumb - its minimum sleep time is 4 hours if no user action from remote control is detected. But if the signal is lost - it has another timeout - and you can set it from 1 hour. The same setup is in the salon TV. In principle you have to manually switch either both the IPTV box and TV manually, or at least IPTV box. And "as usual" - the HDMI CEC implementation is sh***y - the switch-off option is available, but incompatible with wake TV/shutdown TV commands.

As the connection is wired and traffic is not capped in anyway, I have found out, that router has been eating traffic like @1-5AM, when I sometimes simply browse static news. And the IPTV boxes decoding H.264 traffic was not warm - both were hot. CO2 production in-house, paid by you. So I told mother, that because she falls asleep no later than 00:00, that she at least switch of IPTV box first, when is about to sleep. And as assurance I cut traffic from these two clients at that time for 2 hours. This forces dumb IPTV boxes to shutdown after 1 hour. Not ideal, but works.

Of course, I would have implemented the same setup physically with simple programable timer on the power outlet, so it can be bypassed in the event of emergency (national security broadcast), but thats far off.

And such examples with daily/weekly/moving average traffic IMO, must be wide: malware infiltration, mis-configuration, etc.

I am grateful and thank you, if all above was read - for atttention and time devoted. If such features would be even considered for discussion in the near future - I would be flattered .

Have a nice day!

 

[Martinski]

Dear developer(-s) thank you for supporting vnStat. Very useful on 5G connections, when ISP 5G connection is "unlimited" in the agreement-special part, but set "fair usage" real limit @1 TB in "common" agreement and then the next month is capped.
...
Given this situation, I would like to humbly ask, if there would be any chance to get not daily e-mails, but some solution, which monitors the "speed" and/or the "acceleration" at which the router limit is "eaten" and send e-mail warning.

In addition to the daily summary email notifications, vnStat-on-Merlin includes a feature that users can set up & enable to get "data usage warning emails" whenever their "bandwidth data usage" reaches specific thresholds based on the user-defined maximum monthly allowance.

Currently, there are 3 distinct thresholds hard-coded in the script for data usage warning emails: 75%, 90%, and 100% of the specified maximum monthly allowance.

Below is a screenshot showing the feature parameters on the WebUI page:

Here's a screenshot showing the CLI menu with a made-up test case that demonstrates a simple setup to get a warning email when the data usage reached or exceeded 75% of the maximum monthly allowance:

And here's the warning email that was generated:

Is the above "data usage warning emails" mechanism not sufficient for your specific use cases?

The simplest solution to implement this would be an option for a weekly e-mail @1/7/14/28 day and @the last day 23:59:59 of the current month.

I don't think sending weekly instead of daily email notifications would be any more helpful because what you really want is to get warning emails whenever your accumulated data usage exceeds the pre-defined percent thresholds based on your maximum monthly allowance, regardless of the day it happens.

P.S.
While setting up the made-up test case to get a 75% warning email, I found 2 bugs in the WebUI:

1) A bug in the WebUI page allows users to save invalid values (less than 1 and greater than 28) for the "Start day of the month for bandwidth usage data allowance" setting.

2) A bug in the WebUI page allows users to save empty values for the "Maximum bandwidth data allowance" and the "Start day of the month for bandwidth usage data allowance" settings.

Sample screenshots showing the bugs:

I'm currently testing the fixes and will submit a PR to the development branch after testing and validation have been completed.

FYI.

 

[dev_null]

In addition to the daily summary email notifications, vnStat-on-Merlin includes a feature that users can set up & enable to get "data usage warning emails" whenever their "bandwidth data usage" reaches specific thresholds based on the user-defined maximum monthly allowance.

<<snip>


Is the above "data usage warning emails" mechanism not sufficient for your specific use cases?


I don't think sending weekly instead of daily email notifications would be any more helpful because what you really want is to get warning emails whenever your accumulated data usage exceeds the pre-defined percent thresholds based on your maximum monthly allowance, regardless of the day it happens.

Dear developer(-s) thank you for supporting vnStat. Very useful on 5G connections, when ISP 5G connection is "unlimited" in the agreement-special part, but set "fair usage" real limit @1 TB in "common" agreement and then the next month is capped.

For reading speed simplicity, I cut this post into two parts. First is for consideration in the near future, second is simply deep examples. 4 mins reading total.

Given this situation, I would like to humbly ask, if there would be any chance to get not daily e-mails, but some solution, which monitors the "speed" and/or the "acceleration" at which the router limit is "eaten" and send e-mail warning.

The simplest solution to implement this would be an option for a weekly e-mail @1/7/14/28 day and @the last day 23:59:59 of the current month.

I can imagine the more sophisticated solutions like:

1. Your set limit divided by the days in the current month - get an e-mail.
2. Moving average statistics with regression over last X days.
3. Counting left Gb's over say 4 months and sending the e-mail with "typical left unused traffic with " estimate/write into some statistics file and donate that traffic for example to Tor node (your own script, which reads value and does the job).

A bit of history here: the 1.x version of vnStat, and my original (CLI) implementation, contained a weekly option, and early iterations of dn-vnstat presented those. The 2.x vnStat eliminated the weekly usage, and @jack_yaz did his magic coding to bring it back in the UI.

To see what's being used weekly, just run the last 7 days: vnstat -d 7 (daily x 7 days), with a total usage at the bottom.

How to automate? Well, the reports are all just cru jobs, so you could very easily set up a new one in services-start or another script. Here's my super-clunky way of thinking about it:

1) Create a script that runs the vnStat 7-day total and save it as /jffs/scripts/vnstat-wk.sh (be sure to make it executable):

#!/bin/sh

vnstat -d 7 > /home/root/vnstat7.txt

2) Create a script to send an email message and save it as /jffs/scripts/div-email.sh - the below is so named because I use it to send Diversion updates to myself (again, chmod it to be executable). Note: this pulls from the AMTM email credentials, so that needs to be configured.

#!/opt/bin/sh
# ver=1.0.0
# Adapted from elorimer snbforum's script leveraging Diversion email credentials - agreed by thelonelycoder in an email to dev_null
# This script is used to email the daily/weekly/monthly vnstat usage for the vnStat on Merlin script and UI - by dev_null at snbforums
# It can also be used to email other text-derived reports by passing the mailbody parameter which would be the path to a text file
#Parameters passed#
mailsubject=$1
mailbody=$2

# Email settings (mail envelope) #
# . /opt/share/diversion/.conf/email.conf
. /jffs/addons/amtm/mail/email.conf
# PASSWORD=$(openssl aes-256-cbc -d  -in /opt/share/diversion/.conf/emailpw.enc -pass pass:ditbabot,isoi)
PASSWORD=$(/usr/sbin/openssl aes-256-cbc $emailPwEnc -d -in "/jffs/addons/amtm/mail/emailpw.enc" -pass pass:ditbabot,isoi)
# $(openssl aes-256-cbc -d  -in /jffs/addons/amtm/mail/emailpw.enc -pass pass:ditbabot,isoi)

#Build email
    echo "From: \"$FRIENDLY_ROUTER_NAME\" <$FROM_ADDRESS>" >/tmp/mail.txt
    echo "To: \"$TO_NAME\" <$TO_ADDRESS>" >>/tmp/mail.txt
    echo "Subject: $mailsubject "as of $(date +"%H.%M on %F") >>/tmp/mail.txt
    echo "Date: $(date -R)" >>/tmp/mail.txt
    echo >>/tmp/mail.txt
    echo "$(cat $mailbody)" >>/tmp/mail.txt
 

#Send Email
#First parameter is subject, second is file to send
/usr/sbin/curl --url $PROTOCOL://$SMTP:$PORT \
        --mail-from "$FROM_ADDRESS" --mail-rcpt "$TO_ADDRESS" \
                    --upload-file /tmp/mail.txt \
                    --ssl-reqd \
                    --user "$USERNAME:$PASSWORD" $SSL_FLAG


rm /tmp/mail.txt


logger -s -t vnstat-email email event processed

3) Add to services-start - this will run weekly at 02:02 local every Sunday morning, adjust as needed: cru a vnstat-wkly "2 2 * * SUN sh /jffs/scripts/vnstat-wk.sh && /jffs/scripts/div-email.sh Vnstat-statsX7 /home/root/vnstat7.txt"

I'm sure there's an all-in-one way of doing this and others will correct/optimize for me. And the math ("left over") could be mathematically derived (it's much to late on a Sunday for me to attempt that, but I'm sure others can).

Best regards,

 

[Martinski]

A bit of history here: the 1.x version of vnStat, and my original (CLI) implementation, contained a weekly option, and early iterations of dn-vnstat presented those. The 2.x vnStat eliminated the weekly usage, and @jack_yaz did his magic coding to bring it back in the UI.

Thanks for the historical background WRT the previous "weekly usage" option.

To see what's being used weekly, just run the last 7 days: vnstat -d 7 (daily x 7 days), with a total usage at the bottom.

Note that the current script already generates stats for the last 8 days (previous 7 days plus today). This data is displayed on the bottom panel of the WebUI page titled "vnstat CLI" as shown in this screenshot:

And the entire text of these stats is also sent in the daily email notifications.

How to automate? Well, the reports are all just cru jobs, so you could very easily set up a new one in services-start or another script....
...
3) Add to services-start ...

Since vnstat and its supporting services are installed via Entware, the recommended best practice is to use post-mount rather than services-start because you want to double-check that Entware has been mounted and the services are indeed available.

I'll wait to see what the OP replies WRT the "data usage warning emails" feature already available. If I'm understanding correctly the OP's use cases, I believe setting up the warning emails should meet their needs.

This evening, I've also added more percent thresholds for the data usage warning emails so that in the event that the current data usage is rapidly approaching 100% of the user's maximum monthly allowance, more warning emails will be sent as the increasing data usage reaches or exceeds each threshold along the way.

 

[pdc]

I'm having a strange problem that I think might be an interaction between vnstat and tailscale. In short, I recently installed tailscale (March 25) and since then I have seen large upload numbers that correspond with when Windows (non-tailscale) clients are doing backups to a file server that is running tailscale. The router is also running tailscale, advertising subnet routes, and also acting as exit node. The file server is not using the router as an exit node as far as I know (I'm new to tailscale though). I installed tailscale using TAILMON.

The timing lines up with my daily backup scripts (5:10-5:20pm), with Sunday being a full copy. I'm not sure why Wednesday was large, but there could have been some additional downloads that got backed up.

It's all somewhat circumstantial, but might it be possible that with tailscale installed, vnstat is now somehow associating the file server traffic with WAN traffic?