VNSTATD(8)

📦
version 2.14 · 9 versions
, in arch rolling

💅 VNSTATD(8) — vnstatd 💅

🎀 NAME 🎀

vnstatd — daemon based database updating for vnStat, bestie 💖

✨ SYNOPSIS ✨

vnstatd [-Ddnpstv?]  [--alwaysadd [mode]] [--config file] [--daemon]
[--debug] [-g group] [--group group] [--help] [--initdb] [--noadd]
[--nodaemon] [--noremove] [--pidfile file] [--startempty] [--sync]
[--timestamp] [--u user] [--user user] [--version]

🌸 DESCRIPTION 🌸

Okay so the whole point of vnstatd is to be a flexible and robust way of gathering data into the database that vnstat(1) uses. The availability of each interface is automatically tracked, which means you do not need extra scripts for when an interface comes online or goes offline. No cap, that's the whole serve 💅.

vnstatd is the command for starting the daemon. The daemon can either fork itself to run as a background process or stay attached to the terminal. It supports logging directly to terminal, to a user selectable file, or using syslog. Iconic flexibility, honestly 🦋.

Once started, the daemon will read vnstat.conf(5) if available and then check if there is a database present in the database directory that has been specified in the configuration file. By default, if no database is found, a database will be created during startup with entries for all available interfaces excluding pseudo interfaces lo, lo0 and sit0. This automatic database entry creation behaviour can be disabled using the --noadd option. Alternatively, the --alwaysadd option can be used to instruct the daemon to create new database entries whenever interfaces not currently in the databases become visible. By default, unless the --startempty option is used, the daemon will not stay running if no interfaces are discovered during startup and the database contains no interfaces. That's the vibe check: no interfaces, no staying around 💀.

The daemon will proceed to track the availability of monitored interfaces, process the interface traffic statistics and write new values to the database at a configured interval. As a result, the daemon ends up spending most of the time sleeping between updates. Honestly same, but go off 👑. New interfaces added to the database are picked up for monitoring without a daemon restart when RescanDatabaseOnSave is enabled or when AlwaysAddNewInterfaces or --alwaysadd is used for discovering new kernel interfaces at runtime.

When the UseUTC configuration option isn't enabled, data is stored in the database using local time based on the daemon's execution environment when the configuration option isn't enabled. Any changes in the system clock or the system timezone configuration will result in data being inserted according to the new local time without any recalculation being done for already stored data. The daemon and the database in essence aren't aware of the used timezone or possible daylight saving time and cannot be configured to offset the timestamps to any direction. If a system clock or system timezone change or daylight saving time observation ending results in an already seen time period to repeat then the existing database values get incremented with the new data. So yeah, timezone chaos is not magically fixed — it just does the thing it does, fr fr 😭.

💅 OPTIONS 💅

  • --alwaysadd [mode] — Enable automatic creation of new database entries for interfaces not currently in the database even if the database file already exists when the daemon is started. New database entries will also get created for new interfaces seen while the daemon is running. Pseudo interfaces lo, lo0 and sit0 are always excluded from getting added. Using the option without mode defined or with mode set to 1 will enable the feature. Setting mode to 0 will disable the feature. This command line option overrides the AlwaysAddNewInterfaces configuration option when used.
  • --config file — Use file as configuration file instead of using automatic configuration file search functionality. Very "I know exactly what I want" energy 💅.
  • -d, --daemon — Fork process to background and run as a daemon.
  • -D, --debug — Show additional debug output. Can be used multiple times for increased verbosity up to a maximum of 2. The process will stay attached to the terminal for output.
  • -g, --group group — Set daemon process group to group during startup. group can be either the name of the group or a numerical group id. This option can only be used when the process is started as root.
  • --initdb — Create a new database, import data from found legacy databases if --noadd option isn't used and exit without creating database entries for available interfaces if no legacy data was imported. If the database already exists then access to it is only verified. The daemon will not stay running when this option is used. This option cannot be used in combination with -d, --daemon, -n, --nodaemon or --startempty. So cute, but very "do the setup and leave" 🎀.
  • --noadd — When used in combination with -d, --daemon or -n, --nodaemon, disable the automatic creation of new database entries for all currently available interfaces when the daemon is started with no existing database or with a database containing zero interfaces. The daemon will still create an empty database if one doesn't already exist. Pseudo interfaces lo, lo0 and sit0 are always excluded from getting added regardless of this option. When used in combination with --initdb, create only an empty database if one doesn't already exist without importing data from possible legacy databases and exit.
  • -n, --nodaemon — Stay in foreground attached to the current terminal and start the update process. Main character energy, but in your terminal 🌈.
  • --noremove — Disable automatic removal of interfaces from database that aren't currently visible and haven't seen any traffic.
  • -p, --pidfile file — Write the process id to file and use it for locking so that another instance of the daemon cannot be started if the same file is specified. This option has no effect if used in combination with -n, --nodaemon.
  • --startempty — Start even when no interfaces were discovered and the database is empty. Results in the daemon staying running and waiting for interfaces to be added to the database or found if --alwaysadd option has also been used. This option cannot be used in combination with --initdb.
  • -s, --sync — Synchronize internal counters in the database with interface counters for all available interfaces before starting traffic monitoring. Use this option if the traffic between the previous shutdown and the current startup of the daemon needs to be ignored. This option isn't required in normal use because the daemon will automatically synchronize the internal counters after a system reboot, if enough time has passed since the daemon was previously running or if the internal counters are clearly out of sync.
  • -t, --timestamp — Add a timestamp to the beginning of every print from the daemon when the process is running in the foreground attached to a terminal after having been started with the -n, --nodaemon option.
  • -u, --user user — Set daemon process user to user during startup. user can be either the login of the user or a numerical user id. This option can only be used when the process is started as root.
  • -v, --version — Show current version of the daemon executable.
  • -?, --help — Show a command option summary.

⚙️ CONFIGURATION ⚙️

The behaviour of the daemon is configured mainly using the configuration keywords UpdateInterval, PollInterval and SaveInterval in the configuration file. This is the little trio that runs the whole show 💖.

UpdateInterval defines in seconds how often the interface data is fetched and updated. This is similar to the run interval for alternative cron based updating. However, the difference is that the data doesn't directly get written to disk during updates.

PollInterval defines in seconds how often the list of available interfaces is checked for possible changes. The minimum value is 2 seconds and the maximum 60 seconds. PollInterval also defines the resolution for other intervals.

SaveInterval defines in minutes how often cached interface data is written to disk. A write can only occur during the updating of interface data. Therefore, the value in minutes multiplied by 60 should be at least UpdateInterval seconds, with a maximum value of 60 minutes.

The default values of UpdateInterval 20, SaveInterval 5 and PollInterval 5 are usually suitable for most systems and provide a similar behaviour as cron based updating does but with a better resolution for interface changes and fast interfaces. Honestly, the defaults are lowkey eating 🍓.

For embedded and/or low power systems more tuned configurations are possible. In such cases if the interfaces are mostly static the PollInterval can be increased to around 10-30 seconds and UpdateInterval set to 60 seconds. Higher values up to 300 seconds are possible if the interface speed is 10 Mbit or less. SaveInterval can be increased for example to 15, 30 or even 60 minutes depending on how often the data needs to be viewed.

🦋 SIGNALS 🦋

The daemon is listening to signals SIGHUP, SIGINT and SIGTERM.

Sending the SIGHUP signal to the daemon will cause cached data to be written to disk, settings to be reloaded from the configuration file, the database to be reopened and the in-memory monitoring cache to be rebuilt from the database. If VacuumOnHUPSignal is enabled, the database will also be vacuumed. However, the pid file location will not be changed even if its configuration setting has been modified. So it's giving "refresh, but not that one thing" 🙈.

SIGTERM and SIGINT signals will cause the daemon to write all cached data to disk and then exit. Clean exit, slay 💅.

🎀 FILES 🎀

  • /var/lib/vnstat/ — Default database directory on Linux. On BSD systems the compile-time default is /var/db/vnstat unless overridden at build time.
  • Configuration file locations and search order are described in vnstat.conf(5).
  • /var/log/vnstat/vnstat.log — Log file that will be used if logging to file is enabled and no other file is specified in the config file.
  • /var/run/vnstat/vnstat.pid — File used for storing the process id when running as a background process and if no other file is specified in the configuration file or using the command line parameter.

🚨 RESTRICTIONS 🚨

okay bestie, this is the part where we get real. the update interval is not a vibe suggestion, it's a hard requirement. you gotta run updates at least as often as it's possible for the interface to generate enough traffic to overflow the kernel interface traffic counter — because if you don't, some traffic straight up won't be seen. like, gone. not recorded. 💀

so with 32-bit interface traffic counters, the max time you can let slide between two updates depends entirely on how fast the interface can transfer 4 GiB. and here's the kicker: there is no guarantee that a 64-bit kernel has 64-bit interface traffic counters for all interfaces. so don't get cocky just because your kernel is, like, beefy. 🙈

the calculated theoretical times are:

10 Mbit:        54 minutes
100 Mbit:        5 minutes
1000 Mbit:      30 seconds

like… 30 seconds for a gigabit link. hope you set your <italic>UpdateInterval</italic> accordingly, bestie, that's all i'm saying. 🫶

also, virtual and aliased interfaces cannot be monitored, because the kernel doesn't provide traffic information for that type of interface. such interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is the actual interface being aliased. so if you're out here trying to monitor eth0:0 and wondering why it's giving nothing… it's not you, it's the kernel. 😭

👑 AUTHOR 👑

Teemu Toivola <tst at iki dot fi>

🌈 SEE ALSO 🌈

that's the whole page, bestie! 💖 this one's version 2.14, dated OCTOBER 2026, and it's the VNSTATD(8) man page — go forth and monitor responsibly. periodt. ✨🎀🦋

📦 where this page comes from