1VNSTATD(8) User Manuals VNSTATD(8)
2
3
4
6 vnstatd - daemon based database updating for vnStat
7
8
10 vnstatd [-Ddnpsv?] [--alwaysadd] [--config file] [--daemon] [--debug]
11 [-g group] [--group group] [--help] [--noadd] [--nodaemon] [--pidfile
12 file] [--sync] [--u user] [--user user] [--version]
13
14
16 The purpose of vnstatd is to provide a flexible and robust way for
17 updating the database that vnstat(1) uses. The availability of each
18 interface is automatically tracked which removes the need for addi‐
19 tional scripts to be implemented and called when an interface comes
20 online or goes offline.
21
22 vnstatd is the command for starting the daemon. The daemon can either
23 fork itself to run as a background process or stay attached to the ter‐
24 minal. It supports logging to a user selectable file or using syslog.
25
26 Once started, the daemon will read vnstat.conf(5) if available and then
27 check if there is a database present in the database directory that has
28 been specified in the configuration file. By default, if no database is
29 found, a database will be created during startup with entries for all
30 available interfaces excluding pseudo interfaces lo, lo0 and sit0. This
31 automatic database entry creation behaviour can be disabled using the
32 --noadd option. Alternatively, it is possible to allow the daemon to
33 create new database entries whenever previously unseen interfaces
34 become visible using the --alwaysadd option.
35
36 The daemon will proceed to track the availability of monitored inter‐
37 faces, process the interface traffic statistics and write new values to
38 the database at a configured interval. As a result, the daemon ends up
39 spending most of the time sleeping between updates.
40
41
43 --alwaysadd
44 Enable automatic creation of new database entries for previously
45 unseen interfaces even if the database directory already con‐
46 tains a database when the daemon is started. New database
47 entries will also get created for new interfaces seen while the
48 daemon is running. Pseudo interfaces lo, lo0 and sit0 are
49 excluded from getting added.
50
51
52 --config file
53 Use file as configuration file instead of using automatic con‐
54 figuration file search functionality.
55
56
57 -d, --daemon
58 Fork process to background and run as a daemon.
59
60
61 -D, --debug
62 Provide additional output for debug purposes. The process will
63 stay attached to the terminal for output.
64
65
66 -g, --group group
67 Set daemon process group to group during startup. group can be
68 either the name of the group or a numerical group id. This
69 option can only be used when the process is started as root.
70
71
72 --noadd
73 Disable automatic creation of new database entries for all
74 available interfaces if the daemon is started with no database
75 found. Pseudo interfaces lo, lo0 and sit0 are excluded from get‐
76 ting added.
77
78
79 -n, --nodaemon
80 Stay in foreground attached to the current terminal and start
81 the update process.
82
83
84 -p, --pidfile file
85 Write the process id to file and use it for locking so that
86 another instance of the daemon cannot be started if the same
87 file is specified.
88
89
90 -s, --sync
91 Synchronize internal counters in the database with interface
92 counters for all available interfaces before starting traffic
93 monitoring. Use this option if the traffic between the previous
94 shutdown and the current startup of the daemon needs to be
95 ignored. This option isn't required in normal use because the
96 daemon will automatically synchronize the internal counters
97 after a system reboot, if enough time has passed since the dae‐
98 mon was previously running or if the internal counters are
99 clearly out of sync.
100
101
102 -u, --user user
103 Set daemon process user to user during startup. user can be
104 either the login of the user or a numerical user id. This option
105 can only be used when the process is started as root.
106
107
108 -v, --version
109 Show current version of the daemon executable.
110
111
112 -?, --help
113 Show a command option summary.
114
115
117 The behaviour of the daemon is configured mainly using the configura‐
118 tion keywords UpdateInterval, PollInterval and SaveInterval in the con‐
119 figuration file.
120
121
122 UpdateInterval defines in seconds how often the interface data is
123 fetched and updated. This is similar to the run interval for alterna‐
124 tive cron based updating. However, the difference is that the data
125 doesn't directly get written to disk during updates.
126
127
128 PollInterval defines in seconds how often the list of available inter‐
129 faces is checked for possible changes. The minimum value is 2 seconds
130 and the maximum 60 seconds. PollInterval also defines the resolution
131 for other intervals.
132
133
134 SaveInterval defines in minutes how often cached interface data is
135 written to disk. A write can only occur during the updating of inter‐
136 face data. Therefore, the value should be a multiple of UpdateInterval
137 with a maximum value of 60 minutes.
138
139
140 The default values of UpdateInterval 30, SaveInterval 5 and PollInter‐
141 val 5 are usually suitable for most systems and provide a similar be‐
142 haviour as cron based updating does but with a better resolution for
143 interface changes and fast interfaces.
144
145
146 For embedded and/or low power systems more tuned configurations are
147 possible. In such cases if the interfaces are mostly static the
148 PollInterval can be increased to around 10-30 seconds and UpdateInter‐
149 val set to 60 seconds. Higher values up to 300 seconds are possible if
150 the interface speed is 10 Mbit or less. SaveInterval can be increased
151 for example to 15, 30 or even 60 minutes depending on how often the
152 data needs to be viewed.
153
154
156 The daemon is listening to signals SIGHUP, SIGINT and SIGTERM. Sending
157 the SIGHUP signal to the daemon will cause cached data to be written to
158 disk, a rescan of the database directory and a reload of settings from
159 the configuration file. However, the pid file location will not be
160 changed even if it's configuration setting has been modified.
161
162
163 SIGTERM and SIGINT signals will cause the daemon to write all cached
164 data to disk and then exit.
165
166
168 /var/lib/vnstat/
169 Default database directory.
170
171
172 /etc/vnstat.conf
173 Config file that will be used unless $HOME/.vnstatrc exists. See
174 the configuration chapter and vnstat.conf(5) for more informa‐
175 tion.
176
177
178 /var/log/vnstat.log
179 Log file that will be used if logging to file is enable and no
180 other file is specified in the config file.
181
182
183 /var/run/vnstat.pid
184 File used for storing the process id if no other file is speci‐
185 fied in the configuration file or using the command line parame‐
186 ter.
187
188
190 Updates need to be executed at least as often as it is possible for the
191 interface to generate enough traffic to overflow the kernel interface
192 traffic counter. Otherwise, it is possible that some traffic won't be
193 seen. With 32-bit kernels, the maximum time between two updates depends
194 on how fast the interface can transfer 4 GiB. Calculated theoretical
195 times are:
196
197 10 Mbit: 54 minutes
198 100 Mbit: 5 minutes
199 1000 Mbit: 30 seconds
200
201 However, for 1000 Mbit interfaces updating once every minute is usually
202 a usable solution if a shorter update interval can't be used.
203
204 Virtual and aliased interfaces cannot be monitored because the kernel
205 doesn't provide traffic information for that type of interfaces. Such
206 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
207 the actual interface being aliased.
208
209
211 Teemu Toivola <tst at iki dot fi>
212
213
215 vnstat(1), vnstati(1), vnstat.conf(5), signal(7)
216
217
218
219version 2.6 JANUARY 2020 VNSTATD(8)