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

FreeBSD Manual Pages

  
 
  

home | help
VNSTAT.CONF(5)			 User Manuals			VNSTAT.CONF(5)

NAME
       vnstat.conf - vnStat configuration file

SYNOPSIS
       /etc/vnstat.conf

DESCRIPTION
       vnstat(1),  vnstati(1)  and  vnstatd(8)	all use	the same configuration
       file for	configuration related settings.	 Some of the settings are com-
       mon  for	 all  three  programs.	The  file consists of keyword-argument
       pairs, one per line. Empty lines	and lines starting with	'#' are	inter-
       preted  as comments and not processed.  Arguments may optionally	be en-
       closed in double	quotes (") in order to represent arguments  containing
       spaces.	Arguments can be padded	with spaces or tabulator characters. A
       hardcoded default value will be used if a keyword can't be  found  from
       the  configuration  file	or if the configured value cannot be parsed or
       is outside supported value range.

       The configuration file is divided into three sections based on the  us-
       age  of each keyword. The first section contains	keywords that are con-
       sidered common for all commands,	the second section is for  daemon  re-
       lated keywords and the last section is for image	output.

COMMON KEYWORDS
       DatabaseDir
	      Specifies	 the  directory	where the database is to be stored.  A
	      full path	must be	given and a leading '/'	isn't required.

       DayFormat, MonthFormat, TopFormat
	      Formatting of date in available outputs. Uses the	same format as
	      date(1).	(vnstat	and vnstati only)

       DefaultDecimals
	      Number  of decimals to use in outputs. Value range: 0..2 (vnstat
	      and vnstati only)

       EstimateBarVisible
	      Show a visual representation of the traffic estimation  if  Out-
	      putStyle	has been configured with a value of 1 or 2 to make the
	      bar column visible.  1 = enabled,	0 = disabled.	(vnstat	 only,
	      see EstimateStyle	for vnstati)

       HourlyDecimals
	      Number  of  decimals to use in hourly graph output. Value	range:
	      0..2 (vnstat only)

       HourlySectionStyle
	      Select what kind of spacer is used for separating	the  numerical
	      sections	of  the	 hourly	 graph	output.	0 = none, 1 = '|', 2 =
	      '][', 3 =	'[ ]'.	(vnstat	only)

       Interface
	      Default interface	used when no other interface is	 specified  on
	      the command line.	Leave empty for	automatic selection. The auto-
	      matic selection will prioritize the interface with most  traffic
	      for outputs doing	database queries.  Queries not using the data-
	      base will	first check if the database is	available  and	select
	      the  interface  with  most  traffic out those that are currently
	      visible in the system. If	no database can	be read	then the first
	      available	interface will be used.	(vnstat	and vnstati only)

       List5Mins, ListHours, ListDays, ListMonths, ListYears, ListTop
	      Number of	entries	to show	in list	outputs	unless overridden from
	      the command line.	 Set to	0 to show all entries available	in the
	      database.	 (vnstat and vnstati)

       Locale Locale  setting  to be used for prints. This replaces the	LC_ALL
	      environment variable. Set	to "-" or leave	empty in order to  use
	      the system default value.	(vnstat	and vnstati only)

       OutputStyle
	      Modify  the  content  and	style of text outputs. 0 = minimal and
	      narrow output for	terminal with limited width, 1 = normal	output
	      with bar column visible, 2 = same	as 1 except rate is visible in
	      summary output, 3	= rate column is visible in all	outputs	 where
	      it is supported.	(vnstat	and vnstati only)

       QueryMode
	      Default query mode when no parameters are	given. 0 = normal, 1 =
	      days, 2 =	months,	3 = top, 5 = short,  6	=  years,  7  =	 hours
	      graph,  8	 = xml,	9 = one	line, 10 = json, 11 = hours and	12 = 5
	      minute. (vnstat only)

       RateUnit
	      Select which unit	is used	when traffic  rate  is	visible.  0  =
	      bytes, 1 = bits.	(vnstat	and vnstati only)

       RateUnitMode
	      Select  used  prefix when	traffic	rate is	shown in bits per sec-
	      ond.  IEC	binary prefixes	are calculated with powers of 1024. SI
	      decimal  prefixes	 are  calculated with powers of	1000.  0 = IEC
	      binary  prefixes	(Kibit/s...),  1   =   SI   decimal   prefixes
	      (kbit/s...).  (vnstat and	vnstati	only)

       RXCharacter, TXCharacter
	      Character	used for representing the percentual share of received
	      and transmitted traffic in list mode outputs. (vnstat only)

       RXHourCharacter,	TXHourCharacter
	      Character	used for representing the percentual share of received
	      and transmitted traffic in hourly	graph output. (vnstat only)

       Sampletime
	      Defines  how  many  seconds  the -tr option will sample traffic.
	      Value range: 2..600 (vnstat only)

       UnitMode
	      Select how units are prefixed. IEC and JEDEC binary prefixes are
	      calculated  with	powers of 1024.	SI decimal prefixes are	calcu-
	      lated  with  powers  of  1000.   0  =  IEC   standard   prefixes
	      (B/KiB/MiB/GiB...),  1  =	 old  style  (JEDEC)  binary  prefixes
	      (B/KB/MB/GB...), 2 = SI decimals prefixes	(B/kB/MB/GB...)	  (vn-
	      stat and vnstati only)

DAEMON RELATED KEYWORDS
       5MinuteHours
	      Data retention duration for the 5	minute resolution entries. The
	      configuration defines for	how many past hours  entries  will  be
	      stored.  Set  to -1 for unlimited	entries	or to 0	to disable the
	      data collection of this resolution.

       64bitInterfaceCounters
	      Select interface counter handling. Set to	1  for	defining  that
	      all  interfaces use 64-bit counters on the kernel	side and 0 for
	      defining 32-bit counter. Set to -1 for using the old style logic
	      used in earlier versions where counter values within 32-bits are
	      assumed to be 32-bit and anything	larger	is  assumed  to	 be  a
	      64-bit  counter.	This  may  produce  false  results if a	64-bit
	      counter is reset within the 32-bits. Set to -2 for  using	 auto-
	      matic detection based on available kernel	datastructures.

       BandwidthDetection
	      Try  to  automatically  detect MaxBandwidth value	for each moni-
	      tored interface. Mostly only ethernet  interfaces	 support  this
	      feature.	 MaxBandwidth or interface specific MaxBW will be used
	      as fallback value	if detection fails.  1 =  enabled,  0  =  dis-
	      abled.

       BandwidthDetectionInterval
	      How  often  in  minutes interface	specific detection of MaxBand-
	      width is done for	detecting possible changes  when  BandwidthDe-
	      tection  is  enabled.  Can  be  disabled	by setting to 0. Value
	      range: 0..30

       BootVariation
	      Time in seconds how much the boot	time reported by system	kernel
	      can variate between updates. Value range:	0..300

       CheckDiskSpace
	      Enable  or  disable the availability check of at least some free
	      disk space before	a database write. 1 = enabled, 0 = disabled.

       CreateDirs
	      Enable or	disable	the creation of	directories when a  configured
	      path doesn't exist. This includes	DatabaseDir , LogFile and Pid-
	      File directories.	The LogFile directory  will  be	 created  only
	      when UseLogging has been set to 1. The PidFile directory will be
	      created only if the daemon is started as a  background  process.
	      The  daemon  process will	try to create the directory using per-
	      missions of the user used	to start the process.

       DaemonGroup
	      Specify the group	to which the daemon process should switch dur-
	      ing startup.  The	group can either be the	name of	the group or a
	      numerical	group id.  Leave empty	to  disable  group  switching.
	      This  option  can	 only  be  used	when the process is started as
	      root.

       DaemonUser
	      Specify the user to which	the daemon process should switch  dur-
	      ing  startup.  The user can either be the	login of the user or a
	      numerical	user id.  Leave	empty to disable user switching.  This
	      option can only be used when the process is started as root.

       DailyDays
	      Data  retention duration for the one day resolution entries. The
	      configuration defines for	how many past  days  entries  will  be
	      stored.  Set  to -1 for unlimited	entries	or to 0	to disable the
	      data collection of this resolution.

       DatabaseSynchronous
	      Change the setting of the	SQLite "synchronous" flag  which  con-
	      trols  how  much	care is	taken to ensure	disk writes have fully
	      completed	when writing data to the  database  before  continuing
	      other  actions.  Higher  values  take extra steps	to ensure data
	      safety at	the cost of slower performance.	A value	of 0 will  re-
	      sult in all handling being left to the filesystem	itself.	Set to
	      -1 to select the default value according to database  mode  con-
	      trolled  by  DatabaseWriteAheadLogging setting. See SQLite docu-
	      mentation	for more details regarding values from 1 to  3.	 Value
	      range: -1..3

       DatabaseWriteAheadLogging
	      Enable  or disable SQLite	Write-Ahead Logging mode for the data-
	      base. See	SQLite documentation for more details  and  note  that
	      support for read-only operations isn't available in older	SQLite
	      versions.	1 = enabled, 0 = disabled.

       HourlyDays
	      Data retention duration for the one hour resolution entries. The
	      configuration  defines  for  how	many past days entries will be
	      stored. Set to -1	for unlimited entries or to 0 to  disable  the
	      data collection of this resolution.

       LogFile
	      Specify  log  file path and name to be used if UseLogging	is set
	      to 1.

       MaxBandwidth
	      Maximum bandwidth	for all	interfaces. If the interface  specific
	      traffic  exceeds	the given value	then the data is assumed to be
	      invalid and rejected.  Set to 0 in order to disable the feature.
	      Value range: 0..50000

       MaxBW  Same as MaxBandwidth but can be used for setting individual lim-
	      its for selected interfaces. The name of the interface is	speci-
	      fied  directly after the MaxBW keyword without spaces. For exam-
	      ple MaxBWeth0 for	eth0 and  MaxBWppp0  for  ppp0.	 Value	range:
	      0..50000

       MonthlyMonths
	      Data  retention  duration	 for the one month resolution entries.
	      The configuration	defines	for how	many past months entries  will
	      be  stored.  Set	to -1 for unlimited entries or to 0 to disable
	      the data collection of this resolution.

       MonthRotate
	      Day of month that	months are expected to change. Usually set  to
	      1	 but can be set	to alternative values for example for tracking
	      monthly billed traffic where the billing period doesn't start on
	      the  first day. For example, if set to 7,	days of	February up to
	      and including the	6th will count for January. Changing this  op-
	      tion  will  not  cause  existing	data to	be recalculated. Value
	      range: 1..28

       MonthRotateAffectsYears
	      Enable or	disable	MonthRotate also affecting yearly data.	Appli-
	      cable  only  when	 MonthRotate has a value greater than one. 1 =
	      enabled, 0 = disabled.

       OfflineSaveInterval
	      How often	in minutes cached interface data is saved to file when
	      all  monitored  interfaces  are offline. Value range: SaveInter-
	      val..60

       PidFile
	      Specify pid file path and	name to	be used. The file  is  created
	      only if the daemon is started as a background process.

       PollInterval
	      How  often in seconds interfaces are checked for status changes.
	      Value range: 2..60

       SaveInterval
	      How often	in minutes cached interface data  is  saved  to	 file.
	      Value range: ( UpdateInterval / 60 )..60

       SaveOnStatusChange
	      Enable or	disable	the additional saving to file of cached	inter-
	      face data	when the availability of an interface  changes,	 i.e.,
	      when an interface	goes offline or	comes online. 1	= enabled, 0 =
	      disabled.

       TimeSyncWait
	      How many minutes to wait during daemon startup for system	 clock
	      to  sync if most recent database update appears to be in the fu-
	      ture. This may be	needed in systems without  a  real-time	 clock
	      (RTC)  which  require  some time after boot to query and set the
	      correct time. 0 =	wait disabled.	Value range: 0..60

       TopDayEntries
	      Data retention duration for the top day entries. The  configura-
	      tion  defines  how  many	of  the	 past  top day entries will be
	      stored. Set to -1	for unlimited entries or to 0 to  disable  the
	      data collection of this resolution.

       TrafficlessEntries
	      Create database entries even when	there is no traffic during the
	      entry's time period. 1 = enabled,	0 = disabled.

       UpdateFileOwner
	      Enable or	disable	the update of  file  ownership	during	daemon
	      process  startup.	 During	daemon startup,	only database, log and
	      pid files	will be	modified if the	user or	group change feature (
	      DaemonUser or DaemonGroup	) is enabled and the files don't match
	      the requested user or group. During  manual  database  creation,
	      this  option  will cause file ownership to be inherited from the
	      database directory if the	directory already exists. This	option
	      only has effect when the process is started as root or via sudo.

       UpdateInterval
	      How often	in seconds the interface data is updated. Value	range:
	      PollInterval..300

       UseLogging
	      Enable or	disable	logging. 0 = disabled, 1 =  logfile  and  2  =
	      syslog.

       YearlyYears
	      Data retention duration for the one year resolution entries. The
	      configuration defines for	how many past years  entries  will  be
	      stored.  Set  to -1 for unlimited	entries	or to 0	to disable the
	      data collection of this resolution.

IMAGE OUTPUT RELATED KEYWORDS
       5MinuteGraphResultCount
	      Number of	5 minute periods to be included	in the 5 minute	 reso-
	      lution  graph.   The value affects the width of the graph. Value
	      range: 288..5MinuteHours*12

       5MinuteGraphHeight
	      Height of	5 minute resolution  graph  in	pixels.	 Value	range:
	      150..2000

       BarColumnShowsRate
	      The  bar column represents traffic rate in list outputs when en-
	      abled. Requires also that	OutputStyle  has  been	configured  to
	      show  the	 traffic  rate	column by using	the value 3.  Enabling
	      this option will automatically cause EstimateStyle to  have  the
	      value 0. Visually	this option affects only the color legend text
	      and the last line	on the list if that line represents  the  cur-
	      rently ongoing time period. 1 = enabled, 0 = disabled.

       CBackground
	      Background color.

       CEdge  Edge color, if visible.

       CHeader
	      Header background	color.

       CHeaderTitle
	      Header title text	color.

       CHeaderDate
	      Header date text color.

       CLine  Line color.

       CLineL Lighter version of line color. Set to '-'	in order to use	a cal-
	      culated value based on CLine.

       CRx    Color for	received data.

       CRxD   Darker version of	received data color. Set to '-'	 in  order  to
	      use a calculated value based on CRx.

       CText  Common text color.

       CTx    Color for	transmitted data.

       CTxD   Darker version of	transmitted data color.	Set to '-' in order to
	      use a calculated value based on CTx.

       EstimateStyle
	      Show a visual representation of the traffic estimation.  0 = not
	      shown, 1 = continuation of existing bar, 2 = separate bar.

       HeaderFormat
	      Formatting of date in header. Uses the same format as date(1).

       HourlyRate
	      Show hours with rate instead of transferred amount. 1 = enabled,
	      0	= disabled.

       ImageScale
	      Scale output to given percent. Value range: 50..500

       LargeFonts
	      Increase the size	of used	fonts. 1 = enabled, 0 =	disabled.

       LineSpacingAdjustment
	      Adjust line spacing in list format outputs. Positive values  in-
	      crease  the space	between	lines while negative values reduce it.
	      Value range: -5..10

       SummaryGraph
	      Select which graph style output is shown	next  to  the  summary
	      data  in the horizontal and vertical summary outputs. 0 =	hours,
	      1	= 5 minutes.

       SummaryRate
	      Show rate	in summary output if available.	1 = enabled, 0 =  dis-
	      abled.

       TransparentBg
	      Set background color as transparent. 1 = enabled,	0 = disabled.

FILES
       /etc/vnstat.conf
	      Config  file  that will be used unless $HOME/.vnstatrc exists or
	      alternative value	is given as command line parameter.

RESTRICTIONS
       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
       vnstat(1), vnstati(1), vnstatd(8), units(7)

version	2.7			   MAY 2021			VNSTAT.CONF(5)

NAME | SYNOPSIS | DESCRIPTION | COMMON KEYWORDS | DAEMON RELATED KEYWORDS | IMAGE OUTPUT RELATED KEYWORDS | FILES | RESTRICTIONS | AUTHOR | SEE ALSO

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

home | help