vnstat.conf(5) User Manuals vnstat.conf(5)
NAME
vnstat.conf - vnStat configuration file
SYNOPSIS
/opt/local/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
/opt/local/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.12 JANUARY 2024 vnstat.conf(5)
vnstat 2.12 - Generated Mon Jan 22 07:53:59 CST 2024