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 '#' or ';' 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)

       EstimateBarVisible
              Show  a  visual representation of the traffic estimation if OutputStyle 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)

       EstimateText
              Replace  default "estimated" text on the estimate line with custom text.  Limited to 9 characters.
              (vnstat and vnstati only)

       EstimateVisible
              Show a line with traffic estimation for the selected time period or alert as the last line of  the
              output  in  output  modes  supporting  it.  Disabling  estimate  visibility also disables estimate
              conditions in --alert.  1 = enabled, 0 = disabled. (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)

       InterfaceMatchMethod
              Method for matching interface given for a query to an interface in the database.

              Method 0 requires the interface name to be a case sensitive exact  match.  Method  1  extends  the
              previous  method by allowing a case sensitive exact match of the interface alias. Method 2 extends
              the previous method by allowing a case insensitive exact match of the interface  alias.  Method  3
              extends the previous method by allowing a case insensitive match of the beginning of the interface
              alias.

              Methods will be evaluated in the order described above resulting in exact interface matches always
              taking  precedence.  If  any  interface alias matching method results in multiple matches then the
              interface with the highest total traffic will be used. (vnstat and vnstati only)

       InterfaceOrder
              Interface order in outputs with multiple interfaces. 0 = alphabetical by name, 1 = alphabetical by
              alias. If 1 is selected and multiple interfaces don't have aliases then the interface name will be
              used for defining the order.  (vnstat 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)

       LiveSpinner
              Show  spinning  animation  at the beginning of -l / --live output line. 1 = enabled, 0 = disabled.
              (vnstat only)

       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 = summary, 1 = days, 2 = months, 3 = top, 4 =
              single summary, 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.

AlwaysAddNewInterfaces
Enable or disable automatic creation of new database entries for interfaces not currently in the
database even if the database file already exists when the daemon is started. New database entries
will also get created for new interfaces seen while the daemon is running. Pseudo interfaces lo,
lo0 and sit0 are always excluded from getting added. 1 = enabled, 0 = disabled.

BandwidthDetection
Try to automatically detect MaxBandwidth value for each monitored interface. Mostly only ethernet
interfaces support this feature. MaxBandwidth will be used as fallback value if detection fails.
Any interface specific MaxBW configuration will disable the detection for the specified interface.
In Linux, the detection is disabled for tun interfaces due to the Linux kernel always reporting 10
Mbit regardless of the used real interface. 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. BandwidthDetection is disabled on an interface
specific level for each MaxBW configuration. 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. 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

RescanDatabaseOnSave
Automatically discover added interfaces from the database and start monitoring. The rescan is
done every SaveInterval or OfflineSaveInterval minutes depending on the current activity state. 1
= enabled, 0 = disabled.

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. This option is ignored when the daemon is started with -n, --nodaemon
which results in all log output being shown in terminal the daemon process is using. 0 =
disabled, 1 = logfile and 2 = syslog.

UseUTC Enable or disable using UTC as timezone in the database for all entries. When enabled, all entries
added to the database will use UTC regardless of the configured system timezone. When disabled,
the configured system timezone will be used. Changing this setting will not result in already
existing data to be modified. 1 = enabled, 0 = disabled.

VacuumOnHUPSignal
Enable or disable the execution of SQLite VACUUM command after the daemon has received a HUP
signal. When enabled, the database file is rebuilt and repacked into a minimal amount of disk
space. The difference in size can be notable especially if data retention durations have been
reduced or previously monitored interfaces removed from the database. 1 = enabled, 0 = disabled.

VacuumOnStartup
Enable or disable the execution of SQLite VACUUM command during daemon startup. When enabled, the
database file is rebuilt and repacked into a minimal amount of disk space. The difference in size
can be notable especially if data retention durations have been reduced or previously monitored
interfaces removed from the database. 1 = enabled, 0 = disabled.

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 resolution graph. The value affects the
width of the graph. Value range: 288..2000

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

BarColumnShowsRate
The bar column represents traffic rate in list outputs when enabled. 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
currently 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 calculated value based on CLine.

CPercentileLine
95th percentile line color. Used only in 95th percentile graph.

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.

CTotal Color for total data, sum of received and transmitted data. Used only in 95th percentile graph.

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

HourlyGraphMode
Select the output mode of the hourly graph. 0 = 24 hour sliding window, 1 = graph begins from
midnight.

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 increase 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 = 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>