Ubuntu Manpage: vnstat.conf - vnStat configuration file

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  common  for  all  three  programs.  The  file
       consists  of keyword-argument pairs, one per line. Empty lines and lines starting with '#´
       are interpreted as comments and not processed.  Arguments may optionally  be  enclosed  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 usage of each  keyword.
       The  first  section  contains  keywords  that  are considered common for all commands, the
       second section is for daemon related 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)

       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 automatic selection  will  prioritize  the
              interface  with most traffic for outputs doing database queries.  Queries not using
              the database 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  second.   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 calculated 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...)  (vnstat 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 automatic detection based on available kernel
datastructures.

BandwidthDetection
Try to automatically detect MaxBandwidth value for each monitored 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 =
disabled.

BandwidthDetectionInterval
How often in minutes interface specific detection of MaxBandwidth is done for
detecting possible changes when BandwidthDetection 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 PidFile 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 permissions of the user used to
start the process.

DaemonGroup
Specify the group to which the daemon process should switch during 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 during 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 controls 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 result in all handling
being left to the filesystem itself. Set to -1 to select the default value
according to database mode controlled by DatabaseWriteAheadLogging setting. See
SQLite documentation for more details regarding values from 1 to 3. Value range:
-1..3

DatabaseWriteAheadLogging
Enable or disable SQLite Write-Ahead Logging mode for the database. 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 limits for selected
interfaces. The name of the interface is specified directly after the MaxBW keyword
without spaces. For example 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 option
will not cause existing data to be recalculated. Value range: 1..28

MonthRotateAffectsYears
Enable or disable MonthRotate also affecting yearly data. Applicable 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: SaveInterval..60

PidFile
Specify pid file path and name to be used.

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 interface 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 future. 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 configuration 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

       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 calculated 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.

       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.

       SummaryRate
              Show rate in summary output if available. 1 = enabled, 0 = disabled.

       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>