1VNSTATD(8) User Manuals VNSTATD(8)
2
6 vnstatd - daemon based database updating for vnStat
7
10 vnstatd [-Ddnpstv?] [--alwaysadd [mode]] [--config file] [--daemon]
11 [--debug] [-g group] [--group group] [--help] [--initdb] [--noadd]
12 [--nodaemon] [--pidfile file] [--sync] [--timestamp] [--u user] [--user
13 user] [--version]
14
17 The purpose of vnstatd is to provide a flexible and robust way for up‐
18 dating the database that vnstat(1) uses. The availability of each in‐
19 terface is automatically tracked which removes the need for additional
20 scripts to be implemented and called when an interface comes online or
21 goes offline.
22 vnstatd is the command for starting the daemon. The daemon can either
24 fork itself to run as a background process or stay attached to the ter‐
25 minal. It supports logging directly to terminal, to a user selectable
26 file or using syslog.
27 Once started, the daemon will read vnstat.conf(5) if available and then
29 check if there is a database present in the database directory that has
30 been specified in the configuration file. By default, if no database is
31 found, a database will be created during startup with entries for all
32 available interfaces excluding pseudo interfaces lo, lo0 and sit0. This
33 automatic database entry creation behaviour can be disabled using the
34 --noadd option. Alternatively, using the --alwaysadd option instructs
35 the daemon to create new database entries whenever interfaces not cur‐
36 rently in the databases become visible.
37 The daemon will proceed to track the availability of monitored inter‐
39 faces, process the interface traffic statistics and write new values to
40 the database at a configured interval. As a result, the daemon ends up
41 spending most of the time sleeping between updates.
42 When the UseUTC configuration option isn't enabled, data is stored in
44 the database using local time based on the daemon's execution environ‐
45 ment when the configuration option isn't enabled. Any changes in the
46 system clock or the system timezone configuration will result in data
47 being inserted according to the new local time without any recalcula‐
48 tion being done for already stored data. The daemon and the database in
49 essence aren't aware of the used timezone or possible daylight saving
50 time and cannot be configured to offset the timestamps to any direc‐
51 tion. If a system clock or system timezone change or daylight saving
52 time observation ending results in an already seen time period to re‐
53 peat then the existing database values get incremented with the new
54 data.
55
58 --alwaysadd [mode]
59 Enable automatic creation of new database entries for interfaces
60 not currently in the database even if the database file already
61 exists when the daemon is started. New database entries will
62 also get created for new interfaces seen while the daemon is
63 running. Pseudo interfaces lo, lo0 and sit0 are always excluded
64 from getting added. Using the option without mode defined or
65 with mode set to 1 will enable the feature. Setting mode to 0
66 will disable the feature. This command line option overrides the
67 AlwaysAddNewInterfaces configuration option when used.
68 --config file
71 Use file as configuration file instead of using automatic con‐
72 figuration file search functionality.
73 -d, --daemon
76 Fork process to background and run as a daemon.
77 -D, --debug
80 Provide additional output for debug purposes. The process will
81 stay attached to the terminal for output.
82 -g, --group group
85 Set daemon process group to group during startup. group can be
86 either the name of the group or a numerical group id. This op‐
87 tion can only be used when the process is started as root.
88 --initdb
91 Create a new empty database without interface data and exit. If
92 the database already exists then access to it is only verified.
93 The daemon will not stay running when this option is used. This
94 option cannot be used in combination with -d, --daemon or -n,
95 --nodaemon.
96 --noadd
99 Disable the automatic creation of new database entries for all
100 available interfaces if the daemon is started with no database
101 found or with a database without any interfaces. The daemon will
102 fail to start if this option is used when the database contains
103 no interfaces or doesn't exist. The daemon will create an empty
104 database if one doesn't already exist. Pseudo interfaces lo, lo0
105 and sit0 are always excluded from getting added regardless of
106 this option.
107 -n, --nodaemon
110 Stay in foreground attached to the current terminal and start
111 the update process.
112 -p, --pidfile file
115 Write the process id to file and use it for locking so that an‐
116 other instance of the daemon cannot be started if the same file
117 is specified. This option has no effect if used in combination
118 with -n, --nodaemon.
119 -s, --sync
122 Synchronize internal counters in the database with interface
123 counters for all available interfaces before starting traffic
124 monitoring. Use this option if the traffic between the previous
125 shutdown and the current startup of the daemon needs to be ig‐
126 nored. This option isn't required in normal use because the dae‐
127 mon will automatically synchronize the internal counters after a
128 system reboot, if enough time has passed since the daemon was
129 previously running or if the internal counters are clearly out
130 of sync.
131 -t, --timestamp
134 Add a timestamp to the beginning of every print from the daemon
135 when the process is running in the foreground attached to a ter‐
136 minal after having been started with the -n, --nodaemon option.
137 -u, --user user
140 Set daemon process user to user during startup. user can be ei‐
141 ther the login of the user or a numerical user id. This option
142 can only be used when the process is started as root.
143 -v, --version
146 Show current version of the daemon executable.
147 -?, --help
150 Show a command option summary.
151
154 The behaviour of the daemon is configured mainly using the configura‐
155 tion keywords UpdateInterval, PollInterval and SaveInterval in the con‐
156 figuration file.
157 UpdateInterval defines in seconds how often the interface data is
160 fetched and updated. This is similar to the run interval for alterna‐
161 tive cron based updating. However, the difference is that the data
162 doesn't directly get written to disk during updates.
163 PollInterval defines in seconds how often the list of available inter‐
166 faces is checked for possible changes. The minimum value is 2 seconds
167 and the maximum 60 seconds. PollInterval also defines the resolution
168 for other intervals.
169 SaveInterval defines in minutes how often cached interface data is
172 written to disk. A write can only occur during the updating of inter‐
173 face data. Therefore, the value should be a multiple of UpdateInterval
174 with a maximum value of 60 minutes.
175 The default values of UpdateInterval 30, SaveInterval 5 and PollInter‐
178 val 5 are usually suitable for most systems and provide a similar be‐
179 haviour as cron based updating does but with a better resolution for
180 interface changes and fast interfaces.
181 For embedded and/or low power systems more tuned configurations are
184 possible. In such cases if the interfaces are mostly static the
185 PollInterval can be increased to around 10-30 seconds and UpdateInter‐
186 val set to 60 seconds. Higher values up to 300 seconds are possible if
187 the interface speed is 10 Mbit or less. SaveInterval can be increased
188 for example to 15, 30 or even 60 minutes depending on how often the
189 data needs to be viewed.
190
193 The daemon is listening to signals SIGHUP, SIGINT and SIGTERM. Sending
194 the SIGHUP signal to the daemon will cause cached data to be written to
195 disk, a rescan of the database directory and a reload of settings from
196 the configuration file. However, the pid file location will not be
197 changed even if it's configuration setting has been modified.
198 SIGTERM and SIGINT signals will cause the daemon to write all cached
201 data to disk and then exit.
202
205 /var/lib/vnstat/
206 Default database directory.
207 /etc/vnstat.conf
210 Config file that will be used unless $HOME/.vnstatrc exists. See
211 the configuration chapter and vnstat.conf(5) for more informa‐
212 tion.
213 /var/log/vnstat/vnstat.log
216 Log file that will be used if logging to file is enable and no
217 other file is specified in the config file.
218 /var/run/vnstat/vnstat.pid
221 File used for storing the process id when running as a back‐
222 ground process and if no other file is specified in the configu‐
223 ration file or using the command line parameter.
224
227 Updates need to be executed at least as often as it is possible for the
228 interface to generate enough traffic to overflow the kernel interface
229 traffic counter. Otherwise, it is possible that some traffic won't be
230 seen. With 32-bit interface traffic counters, the maximum time between
231 two updates depends on how fast the interface can transfer 4 GiB. Note
232 that there is no guarantee that a 64-bit kernel has 64-bit interface
233 traffic counters for all interfaces. Calculated theoretical times are:
234 10 Mbit: 54 minutes
236 100 Mbit: 5 minutes
237 1000 Mbit: 30 seconds
238 Virtual and aliased interfaces cannot be monitored because the kernel
239 doesn't provide traffic information for that type of interfaces. Such
240 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
241 the actual interface being aliased.
242
245 Teemu Toivola <tst at iki dot fi>
246
249 vnstat(1), vnstati(1), vnstat.conf(5), signal(7)
250version 2.9 JANUARY 2022 VNSTATD(8)