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

FreeBSD Manual Pages

  
 
  

home | help
VNSTAT(1)			 User Manuals			     VNSTAT(1)

NAME
       vnstat -	a console-based	network	traffic	monitor

SYNOPSIS
       vnstat  [-5bDedhlmqrstvwy?]   [--add]  [--begin	date]  [--config file]
       [--days	[limit]]  [--dbdir   [directory]]   [--debug]	[--end	 date]
       [--fiveminutes [limit]] [--help]	[-hg] [--hours [limit]]	[--hoursgraph]
       [-i interface] [--iface interface] [--iflist] [--json  [mode]  [limit]]
       [--limit	  limit]   [--live   [mode]]  [--locale	 locale]  [--longhelp]
       [--months [limit]] [--oneline  [mode]]  [--query]  [--rateunit  [mode]]
       [--remove]  [--rename  name]  [-ru [mode]] [--setalias alias] [--short]
       [--showconfig] [--style number] [--top [limit]] [-tr [time]] [--traffic
       [time]] [--version] [--xml [mode] [limit]] [--years [limit]]

DESCRIPTION
       vnStat  is a console-based network traffic monitor. It keeps a log of 5
       minute interval,	hourly,	daily, monthly and yearly network traffic  for
       the  selected  interface(s).   However,	it isn't a packet sniffer. The
       traffic information is read from	the proc(5) or sys filesystems depend-
       ing  on availability resulting in light use of system resources regard-
       less of network traffic rate. That way vnStat can be used even  without
       root permissions	on most	systems.

       The implementation is divided into two commands.	The purpose of the vn-
       stat command is to provide an interface for querying the	traffic	infor-
       mation  stored in the database whereas the daemon vnstatd(8) is respon-
       sible for data retrieval, caching  and  storage.	 Although  the	daemon
       process	is  constantly	running	 as a service, it is actually spending
       most of its time	sleeping between data updates.

OPTIONS
       --add  Create database entry for	interface specified with -i or --iface
	      option. The daemon can be	running	during this operation but will
	      not automatically	detect the addition without a restart.

       -b, --begin date
	      Begin the	list output with a specific date  /  time  defined  by
	      date  instead of the begin being selected	based on the number of
	      entries to be shown.  If date isn't available  in	 the  database
	      then  the	 closest  later	 date will be used.  date supports the
	      following	formats: YYYY-MM-DD HH:MM and YYYY-MM-DD.  This	option
	      can only be used with --json , --xml and list outputs.

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

       -d, --days [limit]
	      Show traffic statistics on a daily basis for the last days.  The
	      length  of the list will be limited to 30	entries	unless config-
	      ured otherwise or	unless the optional limit parameter  is	 used.
	      All entries stored in the	database will be shown if limit	is set
	      to 0.

       --dbdir directory
	      Use directory as database	directory instead of using the	direc-
	      tory  specified  in  the configuration file or the hardcoded de-
	      fault if no configuration	file is	available.

       -D, --debug
	      Show additional debug output.

       -e, --end date
	      End the list output with a specific date / time defined by  date
	      instead of the latest date / time	in the database. If date isn't
	      available	in the database	then the closest earlier date will  be
	      used.  date supports the following formats: YYYY-MM-DD HH:MM and
	      YYYY-MM-DD.  This	option can only	be used	with  --json  ,	 --xml
	      and  list	outputs. The top list also requires --begin to be used
	      at the same time with this option.

       -5, --fiveminutes [limit]
	      Show traffic statistics with a 5 minute resolution for the  last
	      hours.  The length of the	list will be limited to	24 entries un-
	      less configured otherwise	or unless the optional limit parameter
	      is  used.	 All  entries  stored in the database will be shown if
	      limit is set to 0.

       -h, --hours [limit]
	      Show traffic statistics on a hourly basis.  The  length  of  the
	      list  will  be limited to	24 entries unless configured otherwise
	      or unless	the optional limit  parameter  is  used.  All  entries
	      store in the database will be shown if the limit is set to 0.

       -hg, --hoursgraph
	      Show  traffic statistics on a hourly basis for the last 24 hours
	      using a bar graph	followed by a table representing the numerical
	      data.

       -i, --iface interface
	      Select  one specific interface and apply actions to only it. For
	      queries, it is possible to merge the information of two or  more
	      interfaces using the interface1+interface2+...  syntax. All pro-
	      vided interfaces must be unique and must exist in	 the  database
	      when the merge syntax is used.

       --iflist
	      Show list	of currently available interfaces.

       --json [mode] [limit]
	      Show  database  content for selected interface or	all interfaces
	      in json format. All traffic values in the	output are  in	bytes.
	      An  optional  mode parameter can be used for limiting the	output
	      to only selected information.  Everything	is shown  by  default.
	      Setting  mode  to	 'f'  will output only 5 minute	resolution en-
	      tries, 'h' hours,	'd' days, 'm' months, 'y' years	 and  't'  the
	      top  days. Alternatively or in combination with mode an optional
	      limit parameter can be used to limit the number  of  entries  in
	      the  output.  The	 --json	option can be used in combination with
	      -l, --live and -tr options without mode or limit having any  ef-
	      fect to the output. The jsonversion field	in the output contains
	      the API version information. It will be changed  only  when  the
	      names or structures of previously	existing content gets changed.
	      In comparison, the vnstatversion field exists only as extra  in-
	      formation.

       --limit limit
	      Set  the	maximum	 number	 of  shown  entries in list outputs to
	      limit.  Usage of --limit overrides the default list entry	 limit
	      values  and  the	optional  limit	parameter given	directly for a
	      list query. All entries stored in	the database will be shown  if
	      limit  is	 set  to  0.   --limit can also	be used	to control the
	      length of	--json and --xml outputs.

       -l, --live [mode]
	      Display current transfer rate for	the selected interface in real
	      time until interrupted. Statistics will be shown after interrup-
	      tion if the runtime was more than	10 seconds. An	optional  mode
	      parameter	 can be	used to	select between the displaying of pack-
	      ets per second (mode 0) and transfer counters  (mode  1)	during
	      execution.  --style can also be used to affect the layout	of the
	      output. The output will be in json format	if used	in combination
	      with --json option.

       --locale	locale
	      Use  locale instead of using the locale setting specified	in the
	      configuration file or the	system	default	 if  no	 configuration
	      file is available.

       --longhelp
	      Show complete options list.

       -m, --months [limit]
	      Show  traffic statistics on a monthly basis for the last months.
	      The length of the	list will be limited to	12 entries unless con-
	      figured  otherwise  or  unless  the  optional limit parameter is
	      used. All	entries	stored in the database will be shown if	 limit
	      is set to	0.

       --oneline [mode]
	      Show  traffic summary for	selected interface using one line with
	      a	parsable format. The output contains 15	fields with ; used  as
	      field delimiter. The 1st field contains the API version informa-
	      tion of the output that will only	be changed in future  versions
	      if  the field content or structure changes. The following	fields
	      in order 2) interface name, 3) timestamp for today,  4)  rx  for
	      today,  5)  tx for today,	6) total for today, 7) average traffic
	      rate for today, 8) timestamp for current month, 9) rx  for  cur-
	      rent  month,  10)	 tx  for  current month, 11) total for current
	      month, 12) average traffic rate for current month, 13) all  time
	      total rx,	14) all	time total tx, 15) all time total traffic.  An
	      optional mode parameter can be used to force all fields to  out-
	      put in bytes without the unit itself shown.

       -q, --query
	      Force database query mode.

       --remove
	      Delete the database entry	for the	interface specified with -i or
	      --iface and stop monitoring it. The daemon can be	running	during
	      this operation and will automatically detect the change.

       --rename	name
	      Rename  the  interface specified with -i or --iface in the data-
	      base with	new name name.	The new	name cannot already  exist  in
	      the  database.  This  operation doesn't cause any	data loss. The
	      daemon should not	be running during this operation.

       -ru, --rateunit [mode]
	      Swap the configured rate unit. If	rate has been configured to be
	      shown in bytes then rate will be shown in	bits if	this option is
	      present. In the same way,	if rate	 has  been  configured	to  be
	      shown  in	bits then rate will be shown in	bytes when this	option
	      is present. Alternatively, mode with either 0 or 1 can  be  used
	      as  parameter  for  this option in order to select between bytes
	      (0) and bits (1) regardless of the configuration file setting.

       --setalias alias
	      Set alias	as an alias for	the selected interface to be shown  in
	      queries.	The  set  alias	 can be	removed	by specifying an empty
	      string for alias.	 The daemon can	be running during this	opera-
	      tion.

       -s, --short
	      Use short	output mode. This mode is also used when more than one
	      interface	is available in	the database and no specific interface
	      is selected.

       --showconfig
	      Show current configuration using the same	format as the configu-
	      ration file itself uses.

       --style number
	      Modify the content and style of outputs. Set number to 0	for  a
	      narrower output, 1 for enabling bar column, 2 for	same as	previ-
	      ous but with average traffic rate	visible	in summary output  and
	      3	 for  enabling average traffic rate in all outputs where it is
	      supported. 4 disables the	use of terminal	control	characters  in
	      -l / --live mode.

       -t, --top [limit]
	      Show  all	 time top traffic days.	The length of the list will be
	      limited to 10 entries unless configured otherwise	or unless  the
	      optional	limit  parameter  is  used.  All entries stored	in the
	      database will be shown if	limit is set  to  0.  When  used  with
	      --begin  and  optionally	with --end, the	list will be generated
	      using the	daily data  instead  of	 separate  top	entries.   The
	      availability  of daily data defines the boundaries the date spe-
	      cific query can access.

       -tr, --traffic [time]
	      Calculate	how much traffic goes through the  selected  interface
	      during  the  given time seconds. The time	will be	5 seconds if a
	      number parameter isn't specified.	The output  will  be  in  json
	      format  if  used	in combination with --json option. However, in
	      that case, the countdown before results isn't shown.

       -v, --version
	      Show current version.

       --xml [mode] [limit]
	      Show database content for	selected interface or  all  interfaces
	      in xml format. All traffic values	in the output are in bytes. An
	      optional mode parameter can be used for limiting the  output  to
	      only selected information.  Everything is	shown by default. Set-
	      ting mode	to 'f' will output only	5 minute  resolution  entries,
	      'h' hours, 'd' days, 'm' months, 'y' years and 't' the top days.
	      Alternatively or in combination with mode	an optional limit  pa-
	      rameter  can  be used to limit the number	of entries in the out-
	      put. The xmlversion field	in the output contains the API version
	      information.  It	will  be changed only when the names or	struc-
	      tures of previously existing content gets	changed.  In  compari-
	      son, the vnstatversion field exists only as extra	information.

       -y, --years [limit]
	      Show  traffic  statistics	 on a yearly basis for the last	years.
	      The list will show all entries by	default	unless configured oth-
	      erwise  or  unless the optional limit parameter is used. All en-
	      tries stored in the database will	also be	shown if limit is  set
	      to 0.

       -?, --help
	      Show a command option summary.

FILES
       /var/lib/vnstat/
	      Default database directory.

       /etc/vnstat.conf
	      Config file that will be used unless $HOME/.vnstatrc exists. See
	      vnstat.conf(5) for more information.

EXAMPLES
       vnstat Display traffic summary for the default  interface  or  multiple
	      interfaces when more than	one is monitored.

       vnstat -i eth0+eth1+eth3
	      Display traffic summary for a merge of interfaces	eth0, eth1 and
	      eth3.

       vnstat -i eth2 --xml
	      Output all information about interface eth2 in xml format.

       vnstat --json
	      Output all information of	all monitored interfaces in json  for-
	      mat.

       vnstat -i eth0 --setalias local
	      Give  interface eth0 the alias "local". That information will be
	      later visible as a label when eth0 is queried.

       vnstat -i eth2 --remove
	      Delete database entries for interface eth2 and  stop  monitoring
	      it.

RESTRICTIONS
       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 kernels, the maximum time between two updates depends
       on  how	fast  the interface can	transfer 4 GiB.	Calculated theoretical
       times are:

	      10 Mbit:	      54 minutes
	      100 Mbit:	       5 minutes
	      1000 Mbit:      30 seconds

       However,	for 1000 Mbit interfaces updating once every minute is usually
       a usable	solution if a shorter update interval can't be used.

       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.

       Using long date output formats may cause	misalignment in	shown  columns
       if the length of	the date exceeds the fixed size	allocation.

AUTHOR
       Teemu Toivola <tst at iki dot fi>

SEE ALSO
       vnstatd(8), vnstati(1), vnstat.conf(5), proc(5),	ifconfig(8), units(7)

version	2.6			 JANUARY 2020			     VNSTAT(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | EXAMPLES | RESTRICTIONS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=vnstat&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help