1VNSTATD(8)                       User Manuals                       VNSTATD(8)
2
3
4

NAME

6       vnstatd - daemon based database updating for vnStat
7
8

SYNOPSIS

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
15

DESCRIPTION

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
23       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
28       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
38       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
43       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
56

OPTIONS

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
69
70       --config file
71              Use  file  as configuration file instead of using automatic con‐
72              figuration file search functionality.
73
74
75       -d, --daemon
76              Fork process to background and run as a daemon.
77
78
79       -D, --debug
80              Provide additional output for debug purposes. The  process  will
81              stay attached to the terminal for output.
82
83
84       -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
89
90       --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
97
98       --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
108
109       -n, --nodaemon
110              Stay in foreground attached to the current  terminal  and  start
111              the update process.
112
113
114       -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
120
121       -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
132
133       -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
138
139       -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
144
145       -v, --version
146              Show current version of the daemon executable.
147
148
149       -?, --help
150              Show a command option summary.
151
152

CONFIGURATION

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
158
159       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
164
165       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
170
171       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
176
177       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
182
183       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
191

SIGNALS

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
199
200       SIGTERM and SIGINT signals will cause the daemon to  write  all  cached
201       data to disk and then exit.
202
203

FILES

205       /var/lib/vnstat/
206              Default database directory.
207
208
209       /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
214
215       /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
219
220       /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
225

RESTRICTIONS

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
235              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
243

AUTHOR

245       Teemu Toivola <tst at iki dot fi>
246
247

SEE ALSO

249       vnstat(1), vnstati(1), vnstat.conf(5), signal(7)
250
251
252
253version 2.10                     OCTOBER 2022                       VNSTATD(8)
Impressum