VNSTAT.CONF(5)

📦
version 2.14 · 5 versions
, in arch rolling

🎀 VNSTAT.CONF(5) — the config file bestie 🎀

okay so this is VNSTAT.CONF(5), aka the vnstat.conf manual page, and it’s literally the shared config file for vnstat(1), vnstati(1) and vnstatd(8). Same file, three programs, main character energy only. 💅

✨ NAME ✨

vnstat.conf — the vnStat configuration file, periodt. 🫶

✨ SYNOPSIS ✨

Configuration file locations are platform- and environment-dependent. See FILES below.

✨ DESCRIPTION ✨

vibe check: 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 (COMMON KEYWORDS) contains keywords that are considered common for all commands, the second section (DAEMON RELATED KEYWORDS) is for daemon related keywords and the last section (IMAGE OUTPUT RELATED KEYWORDS) is for image output.

💖 COMMON KEYWORDS 💖

These are the shared ones, bestie. iykyk. 🌈

  • DatabaseDir — specifies the directory where the database is to be stored. A full path must be given and a leading '/' isn’t required. (yes, that’s the rule, don’t ask me, I just work here 💀)
  • 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, 12 = 5 minute and 13 = 95th percentile. (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 bestie, this section is for you. No cap, these settings are lowkey important. 🦋

  • 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 — how long we keep the one-day resolution entries, bestie 🎀. This config says how many past days entries will be stored. Set to -1 for unlimited entries, or 0 to disable data collection for this resolution. Choose wisely 💅
  • DatabaseSynchronous — this one changes the SQLite "synchronous" flag, which controls how much care is taken to make sure 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 the 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 the log file path and name to be used if UseLogging is set to 1 🎀
  • MaxBandwidth — maximum bandwidth for all interfaces. If traffic since the previous update would exceed the maximum possible transfer for the configured rate, then the delta for that interval is discarded and counters are synchronized instead. Set to 0 in order to disable the feature. Value range: 0..400000 🔥
  • MaxBW — same as MaxBandwidth, but you can use it 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..400000 💅
  • 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 it 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 ✨
  • MonthRotateVisible — control visibility of a note documenting on which day of the month monthly data begins. The note is shown in text and image outputs that include monthly data. 0 = never, 1 = when MonthRotate is not 1, 2 = always. (vnstat and vnstati only) 👀
  • OfflineSaveInterval — how often in minutes cached interface data is saved to file when all monitored interfaces are offline. Value range: SaveInterval..60 💤
  • PidFile — specify the 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. The value in minutes multiplied by 60 must be at least UpdateInterval seconds. Value range: 1..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 the system clock to sync if the 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 the 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 🌈

okay bestie, this is the image-output corner of the config and it is lowkey iconic — every keyword, every range, every tiny visual detail is right here 💅✨

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 the 5 minute resolution graph in pixels. Value range: 150..2000

BarColumnShowsRate

The bar column represents traffic rate in list outputs when enabled. It also requires 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 after rendering the image. Doesn't improve output quality, only changes the size of the image. Value range: 50..500

CommonWidth

Use a common image width for summary, list, hourly graph and 5 minute graph image outputs based on the active font metrics. Useful when vertical alignment of multiple images is needed. 1 = enabled, 0 = disabled.

FontFile

Path to a TrueType font (.ttf) file to be used for image text rendering. Leave empty to use the libGD built-in bitmap fonts. When set, libGD must have been built with FreeType support and the font file must be readable; otherwise vnstati exits with error. Both monospace and proportional fonts are supported.

FontSize

Point size used for the body text when FontFile is set. Title, header, axis label and timestamp size scaling is controlled with FontScaleHeader, FontScaleTitle, FontScaleAxis and FontScaleTimestamp. Has no effect when FontFile is empty. Value range: 6..72

FontScaleHeader

Header text size as a percentage of FontSize when FontFile is set. Value range: 50..300

FontScaleTitle

Title text size as a percentage of FontSize when FontFile is set. Value range: 50..300

FontScaleAxis

Axis label text size as a percentage of FontSize when FontFile is set. Value range: 50..300

FontScaleTimestamp

Header and alternative date text size as a percentage of FontSize when FontFile is set. Value range: 50..300

LargeFonts

Increase the size of used fonts. When a FontFile is configured, this multiplies FontSize by 1.5 instead of switching built-in font faces. 1 = enabled, 0 = disabled

LineSpacingAdjustment

Adjust line spacing in list format outputs. Positive values increase the space between lines while negative values reduce it. Supports both built-in and TrueType fonts. 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 📁

No configuration file is required. Built-in defaults are used if no file is found during automatic search.

  • --config — command-line option path; when given, it overrides automatic search.
  • $XDG_CONFIG_HOME/vnstat/vnstat.conf — used only when the XDG_CONFIG_HOME environment variable is set to a non-empty value and --config has not been used. An empty value is treated as unset.
  • $HOME/.config/vnstat/vnstat.conf — used when the HOME environment variable is set and no earlier location was found.
  • $HOME/.vnstatrc — used when the HOME environment variable is set and no earlier location was found.
  • /etc/vnstat.conf — used when no earlier location was found.
  • /usr/local/etc/vnstat.conf — used when no earlier location was found.

🚨 RESTRICTIONS 🚨

Using long date output formats may cause misalignment or clipping 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)

mwah 💋 — that's the whole VNSTAT.CONF(5) page, version 2.14, dated OCTOBER 2026. now go make your graphs iconic 🎀

📦 where this page comes from