Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
VNSTATD(8)			 User Manuals			    VNSTATD(8)

       vnstatd - daemon	based database updating	for vnStat

       vnstatd	[-Ddnpsv?]  [--alwaysadd] [--config file] [--daemon] [--debug]
       [-g group] [--group group] [--help] [--initdb]  [--noadd]  [--nodaemon]
       [--pidfile file]	[--sync] [--u user] [--user user] [--version]

       The  purpose of vnstatd is to provide a flexible	and robust way for up-
       dating the database that	vnstat(1) uses.	The availability of  each  in-
       terface	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 ter-
       minal.  It supports logging 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,	 it is possible	to allow the daemon to
       create new database entries whenever previously unseen  interfaces  be-
       come visible using the --alwaysadd option.

       The  daemon  will proceed to track the availability of monitored	inter-
       faces, 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.

       Data is stored in the database using local time based on	 the  daemon's
       execution  environment.	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.

	      Enable automatic creation	of new database	entries	for previously
	      unseen interfaces	even if	the database already exists  when  the
	      daemon  is  started.  New	database entries will also get created
	      for new interfaces seen while the	daemon is running. Pseudo  in-
	      terfaces	lo,  lo0  and  sit0  are  always excluded from getting

       --config	file
	      Use file as configuration	file instead of	using  automatic  con-
	      figuration file search functionality.

       -d, --daemon
	      Fork process to background and run as a daemon.

       -D, --debug
	      Provide  additional  output for debug purposes. 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 op-
	      tion can only be used when the process is	started	as root.

	      Create a new empty database without interface data and exit.  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	or -n,

	      Disable the automatic creation of	new database entries  for  all
	      available	 interfaces  if	the daemon is started with no database
	      found or with a database without any interfaces. The daemon will
	      fail  to start if	this option is used when the database contains
	      no interfaces or doesn't exist. The daemon will 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.

       -n, --nodaemon
	      Stay  in	foreground  attached to	the current terminal and start
	      the update process.

       -p, --pidfile file
	      Write the	process	id to file and use it for locking so that  an-
	      other  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.

       -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  ig-
	      nored. This option isn't required	in normal use because the dae-
	      mon 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.

       -u, --user user
	      Set daemon process user to user during startup.  user can	be ei-
	      ther 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.

       The  behaviour  of the daemon is	configured mainly using	the configura-
       tion keywords UpdateInterval, PollInterval and SaveInterval in the con-
       figuration file.

       UpdateInterval  defines	in  seconds  how  often	 the interface data is
       fetched and updated.  This is similar to	the run	interval for  alterna-
       tive  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	inter-
       faces  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	inter-
       face  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  PollInter-
       val  5  are usually suitable for	most systems and provide a similar be-
       haviour 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 UpdateInter-
       val 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.

	      Default database directory.

	      Config file that will be used unless $HOME/.vnstatrc exists. See
	      the  configuration  chapter and vnstat.conf(5) for more informa-

	      Log file that will be used if logging to file is enable  and  no
	      other file is specified in the config file.

	      File  used  for  storing	the process id when running as a back-
	      ground process and if no other file is specified in the configu-
	      ration file or using the command line parameter.

       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
       Virtual	and  aliased interfaces	cannot be monitored because the	kernel
       doesn't provide traffic information for that type of  interfaces.  Such
       interfaces  are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
       the actual interface being aliased.

       Teemu Toivola <tst at iki dot fi>

       vnstat(1), vnstati(1), vnstat.conf(5), signal(7)

version	2.7			   MAY 2021			    VNSTATD(8)


Want to link to this manual page? Use this URL:

home | help