VNSTAT.CONF

Section: User Manuals (5)
Updated: OCTOBER 2018
Index Return to Main Contents
 

NAME

vnstat.conf - vnStat configuration file

 

SYNOPSIS

/etc/vnstat.conf

 

DESCRIPTION

vnstat(1), vnstati(1) and vnstatd(1) 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. (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.

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 user to which the daemon process will switch during startup. The user can either be the name of the group or a numerical group id. Leave empty to disable the group switch. This option can only be used when the process is started as root.

DaemonUser
Specify the user to which the daemon process will switch during startup. The user can either be the login of the user or a numerical user id. Leave empty to disable the user switch. 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.

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>

 

SEE ALSO

vnstat(1), vnstati(1), vnstatd(1), units(7)


 

Index

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

This document was created by man2html, using the manual pages.
Time: 17:18:20 GMT, October 21, 2018