1VNSTAT.CONF(5) User Manuals VNSTAT.CONF(5)
2
6 vnstat.conf - vnStat configuration file
7
10 /etc/vnstat.conf
11
14 vnstat(1), vnstati(1) and vnstatd(8) all use the same configuration
15 file for configuration related settings. Some of the settings are com‐
16 mon for all three programs. The file consists of keyword-argument
17 pairs, one per line. Empty lines and lines starting with '#' or ';' are
18 interpreted as comments and not processed. Arguments may optionally be
19 enclosed in double quotes (") in order to represent arguments contain‐
20 ing spaces. Arguments can be padded with spaces or tabulator charac‐
21 ters. A hardcoded default value will be used if a keyword can't be
22 found from the configuration file or if the configured value cannot be
23 parsed or is outside supported value range.
24 The configuration file is divided into three sections based on the us‐
26 age of each keyword. The first section contains keywords that are con‐
27 sidered common for all commands, the second section is for daemon re‐
28 lated keywords and the last section is for image output.
29
32 DatabaseDir
33 Specifies the directory where the database is to be stored. A
34 full path must be given and a leading '/' isn't required.
35 DayFormat, MonthFormat, TopFormat
38 Formatting of date in available outputs. Uses the same format as
39 date(1). (vnstat and vnstati only)
40 DefaultDecimals
43 Number of decimals to use in outputs. Value range: 0..2 (vnstat
44 and vnstati only)
45 EstimateBarVisible
48 Show a visual representation of the traffic estimation if Out‐
49 putStyle has been configured with a value of 1 or 2 to make the
50 bar column visible. 1 = enabled, 0 = disabled. (vnstat only,
51 see EstimateStyle for vnstati)
52 EstimateText
55 Replace default "estimated" text on the estimate line with cus‐
56 tom text. Limited to 9 characters. (vnstat and vnstati only)
57 EstimateVisible
60 Show a line with traffic estimation for the selected time period
61 or alert as the last line of the output in output modes support‐
62 ing it. Disabling estimate visibility also disables estimate
63 conditions in --alert. 1 = enabled, 0 = disabled. (vnstat and
64 vnstati only)
65 HourlyDecimals
68 Number of decimals to use in hourly graph output. Value range:
69 0..2 (vnstat only)
70 HourlySectionStyle
73 Select what kind of spacer is used for separating the numerical
74 sections of the hourly graph output. 0 = none, 1 = '|', 2 =
75 '][', 3 = '[ ]'. (vnstat only)
76 Interface
79 Default interface used when no other interface is specified on
80 the command line. Leave empty for automatic selection. The auto‐
81 matic selection will prioritize the interface with most traffic
82 for outputs doing database queries. Queries not using the data‐
83 base will first check if the database is available and select
84 the interface with most traffic out those that are currently
85 visible in the system. If no database can be read then the first
86 available interface will be used. (vnstat and vnstati only)
87 InterfaceMatchMethod
90 Method for matching interface given for a query to an interface
91 in the database.
92 Method 0 requires the interface name to be a case sensitive ex‐
94 act match. Method 1 extends the previous method by allowing a
95 case sensitive exact match of the interface alias. Method 2 ex‐
96 tends the previous method by allowing a case insensitive exact
97 match of the interface alias. Method 3 extends the previous
98 method by allowing a case insensitive match of the beginning of
99 the interface alias.
100 Methods will be evaluated in the order described above resulting
102 in exact interface matches always taking precedence. If any in‐
103 terface alias matching method results in multiple matches then
104 the interface with the highest total traffic will be used. (vn‐
105 stat and vnstati only)
106 List5Mins, ListHours, ListDays, ListMonths, ListYears, ListTop
109 Number of entries to show in list outputs unless overridden from
110 the command line. Set to 0 to show all entries available in the
111 database. (vnstat and vnstati)
112 Locale Locale setting to be used for prints. This replaces the LC_ALL
115 environment variable. Set to "-" or leave empty in order to use
116 the system default value. (vnstat and vnstati only)
117 OutputStyle
120 Modify the content and style of text outputs. 0 = minimal and
121 narrow output for terminal with limited width, 1 = normal output
122 with bar column visible, 2 = same as 1 except rate is visible in
123 summary output, 3 = rate column is visible in all outputs where
124 it is supported. (vnstat and vnstati only)
125 QueryMode
128 Default query mode when no parameters are given. 0 = normal, 1 =
129 days, 2 = months, 3 = top, 5 = short, 6 = years, 7 = hours
130 graph, 8 = xml, 9 = one line, 10 = json, 11 = hours and 12 = 5
131 minute. (vnstat only)
132 RateUnit
135 Select which unit is used when traffic rate is visible. 0 =
136 bytes, 1 = bits. (vnstat and vnstati only)
137 RateUnitMode
140 Select used prefix when traffic rate is shown in bits per sec‐
141 ond. IEC binary prefixes are calculated with powers of 1024. SI
142 decimal prefixes are calculated with powers of 1000. 0 = IEC
143 binary prefixes (Kibit/s...), 1 = SI decimal prefixes
144 (kbit/s...). (vnstat and vnstati only)
145 RXCharacter, TXCharacter
148 Character used for representing the percentual share of received
149 and transmitted traffic in list mode outputs. (vnstat only)
150 RXHourCharacter, TXHourCharacter
153 Character used for representing the percentual share of received
154 and transmitted traffic in hourly graph output. (vnstat only)
155 Sampletime
158 Defines how many seconds the -tr option will sample traffic.
159 Value range: 2..600 (vnstat only)
160 UnitMode
163 Select how units are prefixed. IEC and JEDEC binary prefixes are
164 calculated with powers of 1024. SI decimal prefixes are calcu‐
165 lated with powers of 1000. 0 = IEC standard prefixes
166 (B/KiB/MiB/GiB...), 1 = old style (JEDEC) binary prefixes
167 (B/KB/MB/GB...), 2 = SI decimals prefixes (B/kB/MB/GB...) (vn‐
168 stat and vnstati only)
169
172 5MinuteHours
173 Data retention duration for the 5 minute resolution entries. The
174 configuration defines for how many past hours entries will be
175 stored. Set to -1 for unlimited entries or to 0 to disable the
176 data collection of this resolution.
177 64bitInterfaceCounters
180 Select interface counter handling. Set to 1 for defining that
181 all interfaces use 64-bit counters on the kernel side and 0 for
182 defining 32-bit counter. Set to -1 for using the old style logic
183 used in earlier versions where counter values within 32-bits are
184 assumed to be 32-bit and anything larger is assumed to be a
185 64-bit counter. This may produce false results if a 64-bit
186 counter is reset within the 32-bits. Set to -2 for using auto‐
187 matic detection based on available kernel datastructures.
188 AlwaysAddNewInterfaces
191 Enable or disable automatic creation of new database entries for
192 interfaces not currently in the database even if the database
193 file already exists when the daemon is started. New database en‐
194 tries will also get created for new interfaces seen while the
195 daemon is running. Pseudo interfaces lo, lo0 and sit0 are always
196 excluded from getting added. 1 = enabled, 0 = disabled.
197 BandwidthDetection
200 Try to automatically detect MaxBandwidth value for each moni‐
201 tored interface. Mostly only ethernet interfaces support this
202 feature. MaxBandwidth will be used as fallback value if detec‐
203 tion fails. Any interface specific MaxBW configuration will dis‐
204 able the detection for the specified interface. In Linux, the
205 detection is disabled for tun interfaces due to the Linux kernel
206 always reporting 10 Mbit regardless of the used real interface.
207 1 = enabled, 0 = disabled.
208 BandwidthDetectionInterval
211 How often in minutes interface specific detection of MaxBand‐
212 width is done for detecting possible changes when BandwidthDe‐
213 tection is enabled. Can be disabled by setting to 0. Value
214 range: 0..30
215 BootVariation
218 Time in seconds how much the boot time reported by system kernel
219 can variate between updates. Value range: 0..300
220 CheckDiskSpace
223 Enable or disable the availability check of at least some free
224 disk space before a database write. 1 = enabled, 0 = disabled.
225 CreateDirs
228 Enable or disable the creation of directories when a configured
229 path doesn't exist. This includes DatabaseDir , LogFile and Pid‐
230 File directories. The LogFile directory will be created only
231 when UseLogging has been set to 1. The PidFile directory will be
232 created only if the daemon is started as a background process.
233 The daemon process will try to create the directory using per‐
234 missions of the user used to start the process.
235 DaemonGroup
238 Specify the group to which the daemon process should switch dur‐
239 ing startup. The group can either be the name of the group or a
240 numerical group id. Leave empty to disable group switching.
241 This option can only be used when the process is started as
242 root.
243 DaemonUser
246 Specify the user to which the daemon process should switch dur‐
247 ing startup. The user can either be the login of the user or a
248 numerical user id. Leave empty to disable user switching. This
249 option can only be used when the process is started as root.
250 DailyDays
253 Data retention duration for the one day resolution entries. The
254 configuration defines for how many past days entries will be
255 stored. Set to -1 for unlimited entries or to 0 to disable the
256 data collection of this resolution.
257 DatabaseSynchronous
260 Change the setting of the SQLite "synchronous" flag which con‐
261 trols how much care is taken to ensure disk writes have fully
262 completed when writing data to the database before continuing
263 other actions. Higher values take extra steps to ensure data
264 safety at the cost of slower performance. A value of 0 will re‐
265 sult in all handling being left to the filesystem itself. Set to
266 -1 to select the default value according to database mode con‐
267 trolled by DatabaseWriteAheadLogging setting. See SQLite docu‐
268 mentation for more details regarding values from 1 to 3. Value
269 range: -1..3
270 DatabaseWriteAheadLogging
273 Enable or disable SQLite Write-Ahead Logging mode for the data‐
274 base. See SQLite documentation for more details and note that
275 support for read-only operations isn't available in older SQLite
276 versions. 1 = enabled, 0 = disabled.
277 HourlyDays
280 Data retention duration for the one hour resolution entries. The
281 configuration defines for how many past days entries will be
282 stored. Set to -1 for unlimited entries or to 0 to disable the
283 data collection of this resolution.
284 LogFile
287 Specify log file path and name to be used if UseLogging is set
288 to 1.
289 MaxBandwidth
292 Maximum bandwidth for all interfaces. If the interface specific
293 traffic exceeds the given value then the data is assumed to be
294 invalid and rejected. Set to 0 in order to disable the feature.
295 Value range: 0..50000
296 MaxBW Same as MaxBandwidth but can be used for setting individual lim‐
299 its for selected interfaces. The name of the interface is speci‐
300 fied directly after the MaxBW keyword without spaces. For exam‐
301 ple MaxBWeth0 for eth0 and MaxBWppp0 for ppp0. BandwidthDetec‐
302 tion is disabled on an interface specific level for each MaxBW
303 configuration. Value range: 0..50000
304 MonthlyMonths
307 Data retention duration for the one month resolution entries.
308 The configuration defines for how many past months entries will
309 be stored. Set to -1 for unlimited entries or to 0 to disable
310 the data collection of this resolution.
311 MonthRotate
314 Day of month that months are expected to change. Usually set to
315 1 but can be set to alternative values for example for tracking
316 monthly billed traffic where the billing period doesn't start on
317 the first day. For example, if set to 7, days of February up to
318 and including the 6th will count for January. Changing this op‐
319 tion will not cause existing data to be recalculated. Value
320 range: 1..28
321 MonthRotateAffectsYears
324 Enable or disable MonthRotate also affecting yearly data. Appli‐
325 cable only when MonthRotate has a value greater than one. 1 =
326 enabled, 0 = disabled.
327 OfflineSaveInterval
330 How often in minutes cached interface data is saved to file when
331 all monitored interfaces are offline. Value range: SaveInter‐
332 val..60
333 PidFile
336 Specify pid file path and name to be used. The file is created
337 only if the daemon is started as a background process.
338 PollInterval
341 How often in seconds interfaces are checked for status changes.
342 Value range: 2..60
343 RescanDatabaseOnSave
346 Automatically discover added interfaces from the database and
347 start monitoring. The rescan is done every SaveInterval or Of‐
348 flineSaveInterval minutes depending on the current activity
349 state. 1 = enabled, 0 = disabled.
350 SaveInterval
353 How often in minutes cached interface data is saved to file.
354 Value range: ( UpdateInterval / 60 )..60
355 SaveOnStatusChange
358 Enable or disable the additional saving to file of cached inter‐
359 face data when the availability of an interface changes, i.e.,
360 when an interface goes offline or comes online. 1 = enabled, 0 =
361 disabled.
362 TimeSyncWait
365 How many minutes to wait during daemon startup for system clock
366 to sync if most recent database update appears to be in the fu‐
367 ture. This may be needed in systems without a real-time clock
368 (RTC) which require some time after boot to query and set the
369 correct time. 0 = wait disabled. Value range: 0..60
370 TopDayEntries
373 Data retention duration for the top day entries. The configura‐
374 tion defines how many of the past top day entries will be
375 stored. Set to -1 for unlimited entries or to 0 to disable the
376 data collection of this resolution.
377 TrafficlessEntries
380 Create database entries even when there is no traffic during the
381 entry's time period. 1 = enabled, 0 = disabled.
382 UpdateFileOwner
385 Enable or disable the update of file ownership during daemon
386 process startup. During daemon startup, only database, log and
387 pid files will be modified if the user or group change feature (
388 DaemonUser or DaemonGroup ) is enabled and the files don't match
389 the requested user or group. During manual database creation,
390 this option will cause file ownership to be inherited from the
391 database directory if the directory already exists. This option
392 only has effect when the process is started as root or via sudo.
393 UpdateInterval
396 How often in seconds the interface data is updated. Value range:
397 PollInterval..300
398 UseLogging
401 Enable or disable logging. This option is ignored when the dae‐
402 mon is started with -n, --nodaemon which results in all log out‐
403 put being shown in terminal the daemon process is using. 0 =
404 disabled, 1 = logfile and 2 = syslog.
405 UseUTC Enable or disable using UTC as timezone in the database for all
408 entries. When enabled, all entries added to the database will
409 use UTC regardless of the configured system timezone. When dis‐
410 abled, the configured system timezone will be used. Changing
411 this setting will not result in already existing data to be mod‐
412 ified. 1 = enabled, 0 = disabled.
413 YearlyYears
416 Data retention duration for the one year resolution entries. The
417 configuration defines for how many past years entries will be
418 stored. Set to -1 for unlimited entries or to 0 to disable the
419 data collection of this resolution.
420
423 5MinuteGraphResultCount
424 Number of 5 minute periods to be included in the 5 minute reso‐
425 lution graph. The value affects the width of the graph. Value
426 range: 288..5MinuteHours*12
427 5MinuteGraphHeight
430 Height of 5 minute resolution graph in pixels. Value range:
431 150..2000
432 BarColumnShowsRate
435 The bar column represents traffic rate in list outputs when en‐
436 abled. Requires also that OutputStyle has been configured to
437 show the traffic rate column by using the value 3. Enabling
438 this option will automatically cause EstimateStyle to have the
439 value 0. Visually this option affects only the color legend text
440 and the last line on the list if that line represents the cur‐
441 rently ongoing time period. 1 = enabled, 0 = disabled.
442 CBackground
445 Background color.
446 CEdge Edge color, if visible.
449 CHeader
452 Header background color.
453 CHeaderTitle
456 Header title text color.
457 CHeaderDate
460 Header date text color.
461 CLine Line color.
464 CLineL Lighter version of line color. Set to '-' in order to use a cal‐
467 culated value based on CLine.
468 CRx Color for received data.
471 CRxD Darker version of received data color. Set to '-' in order to
474 use a calculated value based on CRx.
475 CText Common text color.
478 CTx Color for transmitted data.
481 CTxD Darker version of transmitted data color. Set to '-' in order to
484 use a calculated value based on CTx.
485 EstimateStyle
488 Show a visual representation of the traffic estimation. 0 = not
489 shown, 1 = continuation of existing bar, 2 = separate bar.
490 HeaderFormat
493 Formatting of date in header. Uses the same format as date(1).
494 HourlyGraphMode
497 Select the output mode of the hourly graph. 0 = 24 hour sliding
498 window, 1 = graph begins from midnight.
499 HourlyRate
502 Show hours with rate instead of transferred amount. 1 = enabled,
503 0 = disabled.
504 ImageScale
507 Scale output to given percent. Value range: 50..500
508 LargeFonts
511 Increase the size of used fonts. 1 = enabled, 0 = disabled.
512 LineSpacingAdjustment
515 Adjust line spacing in list format outputs. Positive values in‐
516 crease the space between lines while negative values reduce it.
517 Value range: -5..10
518 SummaryGraph
521 Select which graph style output is shown next to the summary
522 data in the horizontal and vertical summary outputs. 0 = hours,
523 1 = 5 minutes.
524 SummaryRate
527 Show rate in summary output if available. 1 = enabled, 0 = dis‐
528 abled.
529 TransparentBg
532 Set background color as transparent. 1 = enabled, 0 = disabled.
533
536 /etc/vnstat.conf
537 Config file that will be used unless $HOME/.vnstatrc exists or
538 alternative value is given as command line parameter.
539
542 Using long date output formats may cause misalignment in shown columns
543 if the length of the date exceeds the fixed size allocation.
544
547 Teemu Toivola <tst at iki dot fi>
548
551 vnstat(1), vnstati(1), vnstatd(8), units(7)
552version 2.10 OCTOBER 2022 VNSTAT.CONF(5)