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]
The purpose of vnstatd is to provide a flexible and robust way for gathering data to the database that vnstat(1) uses. The availability of each interface is automatically tracked which removes the need for additional scripts to be implemented and called when an interface comes online or goes offline.
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.
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.
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. New interfaces added to the database will be automatically picked up for monitoring without the daemon needing to be notified.
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.
The behaviour of the daemon is configured mainly using the configuration keywords UpdateInterval, PollInterval and SaveInterval in the configuration file.
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 should be a multiple of UpdateInterval with a maximum value of 60 minutes.
The default values of UpdateInterval 30, 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.
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.
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, a rescan of the database directory and a reload of settings from the configuration file. However, the pid file location will not be changed even if it's configuration setting has been modified.
SIGTERM and SIGINT signals will cause the daemon to write all cached data to disk and then exit.
Updates need to be executed at least as often as it is possible for the interface to generate enough traffic to overflow the kernel interface traffic counter. Otherwise, it is possible that some traffic won't be seen. With 32-bit interface traffic counters, the maximum time between two updates depends on how fast the interface can transfer 4 GiB. Note that there is no guarantee that a 64-bit kernel has 64-bit interface traffic counters for all interfaces. Calculated theoretical times are:
| 10 Mbit: 54 minutes | |
| 100 Mbit: 5 minutes | |
| 1000 Mbit: 30 seconds |
Teemu Toivola <tst at iki dot fi>
vnstat(1), vnstati(1), vnstat.conf(5), signal(7)