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 HourlyDecimals
55 Number of decimals to use in hourly graph output. Value range:
56 0..2 (vnstat only)
57 HourlySectionStyle
60 Select what kind of spacer is used for separating the numerical
61 sections of the hourly graph output. 0 = none, 1 = '|', 2 =
62 '][', 3 = '[ ]'. (vnstat only)
63 Interface
66 Default interface used when no other interface is specified on
67 the command line. Leave empty for automatic selection. The auto‐
68 matic selection will prioritize the interface with most traffic
69 for outputs doing database queries. Queries not using the data‐
70 base will first check if the database is available and select
71 the interface with most traffic out those that are currently
72 visible in the system. If no database can be read then the first
73 available interface will be used. (vnstat and vnstati only)
74 InterfaceMatchMethod
77 Method for matching interface given for a query to an interface
78 in the database. Method 0 requires the interface name to be an
79 case sensitive exact match. Method 1 extends the previous method
80 by allowing a case sensitive exact match of the interface alias.
81 Method 2 extends the previous method by allowing a case insensi‐
82 tive exact match of the interface alias. Method 3 extends the
83 previous method by allowing a case insensitive match of the be‐
84 ginning of the interface alias. Methods will be evaluated in the
85 order described above resulting in exact interface matches al‐
86 ways taking precedence. If any interface alias matching method
87 results in multiple matches then the interface with the highest
88 total traffic will be used. (vnstat and vnstati only)
89 List5Mins, ListHours, ListDays, ListMonths, ListYears, ListTop
92 Number of entries to show in list outputs unless overridden from
93 the command line. Set to 0 to show all entries available in the
94 database. (vnstat and vnstati)
95 Locale Locale setting to be used for prints. This replaces the LC_ALL
98 environment variable. Set to "-" or leave empty in order to use
99 the system default value. (vnstat and vnstati only)
100 OutputStyle
103 Modify the content and style of text outputs. 0 = minimal and
104 narrow output for terminal with limited width, 1 = normal output
105 with bar column visible, 2 = same as 1 except rate is visible in
106 summary output, 3 = rate column is visible in all outputs where
107 it is supported. (vnstat and vnstati only)
108 QueryMode
111 Default query mode when no parameters are given. 0 = normal, 1 =
112 days, 2 = months, 3 = top, 5 = short, 6 = years, 7 = hours
113 graph, 8 = xml, 9 = one line, 10 = json, 11 = hours and 12 = 5
114 minute. (vnstat only)
115 RateUnit
118 Select which unit is used when traffic rate is visible. 0 =
119 bytes, 1 = bits. (vnstat and vnstati only)
120 RateUnitMode
123 Select used prefix when traffic rate is shown in bits per sec‐
124 ond. IEC binary prefixes are calculated with powers of 1024. SI
125 decimal prefixes are calculated with powers of 1000. 0 = IEC
126 binary prefixes (Kibit/s...), 1 = SI decimal prefixes
127 (kbit/s...). (vnstat and vnstati only)
128 RXCharacter, TXCharacter
131 Character used for representing the percentual share of received
132 and transmitted traffic in list mode outputs. (vnstat only)
133 RXHourCharacter, TXHourCharacter
136 Character used for representing the percentual share of received
137 and transmitted traffic in hourly graph output. (vnstat only)
138 Sampletime
141 Defines how many seconds the -tr option will sample traffic.
142 Value range: 2..600 (vnstat only)
143 UnitMode
146 Select how units are prefixed. IEC and JEDEC binary prefixes are
147 calculated with powers of 1024. SI decimal prefixes are calcu‐
148 lated with powers of 1000. 0 = IEC standard prefixes
149 (B/KiB/MiB/GiB...), 1 = old style (JEDEC) binary prefixes
150 (B/KB/MB/GB...), 2 = SI decimals prefixes (B/kB/MB/GB...) (vn‐
151 stat and vnstati only)
152
155 5MinuteHours
156 Data retention duration for the 5 minute resolution entries. The
157 configuration defines for how many past hours entries will be
158 stored. Set to -1 for unlimited entries or to 0 to disable the
159 data collection of this resolution.
160 64bitInterfaceCounters
163 Select interface counter handling. Set to 1 for defining that
164 all interfaces use 64-bit counters on the kernel side and 0 for
165 defining 32-bit counter. Set to -1 for using the old style logic
166 used in earlier versions where counter values within 32-bits are
167 assumed to be 32-bit and anything larger is assumed to be a
168 64-bit counter. This may produce false results if a 64-bit
169 counter is reset within the 32-bits. Set to -2 for using auto‐
170 matic detection based on available kernel datastructures.
171 AlwaysAddNewInterfaces
174 Enable or disable automatic creation of new database entries for
175 interfaces not currently in the database even if the database
176 file already exists when the daemon is started. New database en‐
177 tries will also get created for new interfaces seen while the
178 daemon is running. Pseudo interfaces lo, lo0 and sit0 are always
179 excluded from getting added. 1 = enabled, 0 = disabled.
180 BandwidthDetection
183 Try to automatically detect MaxBandwidth value for each moni‐
184 tored interface. Mostly only ethernet interfaces support this
185 feature. MaxBandwidth will be used as fallback value if detec‐
186 tion fails. Any interface specific MaxBW configuration will dis‐
187 able the detection for the specified interface. In Linux, the
188 detection is disabled for tun interfaces due to the Linux kernel
189 always reporting 10 Mbit regardless of the used real interface.
190 1 = enabled, 0 = disabled.
191 BandwidthDetectionInterval
194 How often in minutes interface specific detection of MaxBand‐
195 width is done for detecting possible changes when BandwidthDe‐
196 tection is enabled. Can be disabled by setting to 0. Value
197 range: 0..30
198 BootVariation
201 Time in seconds how much the boot time reported by system kernel
202 can variate between updates. Value range: 0..300
203 CheckDiskSpace
206 Enable or disable the availability check of at least some free
207 disk space before a database write. 1 = enabled, 0 = disabled.
208 CreateDirs
211 Enable or disable the creation of directories when a configured
212 path doesn't exist. This includes DatabaseDir , LogFile and Pid‐
213 File directories. The LogFile directory will be created only
214 when UseLogging has been set to 1. The PidFile directory will be
215 created only if the daemon is started as a background process.
216 The daemon process will try to create the directory using per‐
217 missions of the user used to start the process.
218 DaemonGroup
221 Specify the group to which the daemon process should switch dur‐
222 ing startup. The group can either be the name of the group or a
223 numerical group id. Leave empty to disable group switching.
224 This option can only be used when the process is started as
225 root.
226 DaemonUser
229 Specify the user to which the daemon process should switch dur‐
230 ing startup. The user can either be the login of the user or a
231 numerical user id. Leave empty to disable user switching. This
232 option can only be used when the process is started as root.
233 DailyDays
236 Data retention duration for the one day resolution entries. The
237 configuration defines for how many past days entries will be
238 stored. Set to -1 for unlimited entries or to 0 to disable the
239 data collection of this resolution.
240 DatabaseSynchronous
243 Change the setting of the SQLite "synchronous" flag which con‐
244 trols how much care is taken to ensure disk writes have fully
245 completed when writing data to the database before continuing
246 other actions. Higher values take extra steps to ensure data
247 safety at the cost of slower performance. A value of 0 will re‐
248 sult in all handling being left to the filesystem itself. Set to
249 -1 to select the default value according to database mode con‐
250 trolled by DatabaseWriteAheadLogging setting. See SQLite docu‐
251 mentation for more details regarding values from 1 to 3. Value
252 range: -1..3
253 DatabaseWriteAheadLogging
256 Enable or disable SQLite Write-Ahead Logging mode for the data‐
257 base. See SQLite documentation for more details and note that
258 support for read-only operations isn't available in older SQLite
259 versions. 1 = enabled, 0 = disabled.
260 HourlyDays
263 Data retention duration for the one hour resolution entries. The
264 configuration defines for how many past days entries will be
265 stored. Set to -1 for unlimited entries or to 0 to disable the
266 data collection of this resolution.
267 LogFile
270 Specify log file path and name to be used if UseLogging is set
271 to 1.
272 MaxBandwidth
275 Maximum bandwidth for all interfaces. If the interface specific
276 traffic exceeds the given value then the data is assumed to be
277 invalid and rejected. Set to 0 in order to disable the feature.
278 Value range: 0..50000
279 MaxBW Same as MaxBandwidth but can be used for setting individual lim‐
282 its for selected interfaces. The name of the interface is speci‐
283 fied directly after the MaxBW keyword without spaces. For exam‐
284 ple MaxBWeth0 for eth0 and MaxBWppp0 for ppp0. BandwidthDetec‐
285 tion is disabled on an interface specific level for each MaxBW
286 configuration. Value range: 0..50000
287 MonthlyMonths
290 Data retention duration for the one month resolution entries.
291 The configuration defines for how many past months entries will
292 be stored. Set to -1 for unlimited entries or to 0 to disable
293 the data collection of this resolution.
294 MonthRotate
297 Day of month that months are expected to change. Usually set to
298 1 but can be set to alternative values for example for tracking
299 monthly billed traffic where the billing period doesn't start on
300 the first day. For example, if set to 7, days of February up to
301 and including the 6th will count for January. Changing this op‐
302 tion will not cause existing data to be recalculated. Value
303 range: 1..28
304 MonthRotateAffectsYears
307 Enable or disable MonthRotate also affecting yearly data. Appli‐
308 cable only when MonthRotate has a value greater than one. 1 =
309 enabled, 0 = disabled.
310 OfflineSaveInterval
313 How often in minutes cached interface data is saved to file when
314 all monitored interfaces are offline. Value range: SaveInter‐
315 val..60
316 PidFile
319 Specify pid file path and name to be used. The file is created
320 only if the daemon is started as a background process.
321 PollInterval
324 How often in seconds interfaces are checked for status changes.
325 Value range: 2..60
326 RescanDatabaseOnSave
329 Automatically discover added interfaces from the database and
330 start monitoring. The rescan is done every SaveInterval or Of‐
331 flineSaveInterval minutes depending on the current activity
332 state. 1 = enabled, 0 = disabled.
333 SaveInterval
336 How often in minutes cached interface data is saved to file.
337 Value range: ( UpdateInterval / 60 )..60
338 SaveOnStatusChange
341 Enable or disable the additional saving to file of cached inter‐
342 face data when the availability of an interface changes, i.e.,
343 when an interface goes offline or comes online. 1 = enabled, 0 =
344 disabled.
345 TimeSyncWait
348 How many minutes to wait during daemon startup for system clock
349 to sync if most recent database update appears to be in the fu‐
350 ture. This may be needed in systems without a real-time clock
351 (RTC) which require some time after boot to query and set the
352 correct time. 0 = wait disabled. Value range: 0..60
353 TopDayEntries
356 Data retention duration for the top day entries. The configura‐
357 tion defines how many of the past top day entries will be
358 stored. Set to -1 for unlimited entries or to 0 to disable the
359 data collection of this resolution.
360 TrafficlessEntries
363 Create database entries even when there is no traffic during the
364 entry's time period. 1 = enabled, 0 = disabled.
365 UpdateFileOwner
368 Enable or disable the update of file ownership during daemon
369 process startup. During daemon startup, only database, log and
370 pid files will be modified if the user or group change feature (
371 DaemonUser or DaemonGroup ) is enabled and the files don't match
372 the requested user or group. During manual database creation,
373 this option will cause file ownership to be inherited from the
374 database directory if the directory already exists. This option
375 only has effect when the process is started as root or via sudo.
376 UpdateInterval
379 How often in seconds the interface data is updated. Value range:
380 PollInterval..300
381 UseLogging
384 Enable or disable logging. 0 = disabled, 1 = logfile and 2 =
385 syslog.
386 UseUTC Enable or disable using UTC as timezone in the database for all
389 entries. When enabled, all entries added to the database will
390 use UTC regardless of the configured system timezone. When dis‐
391 abled, the configured system timezone will be used. Changing
392 this setting will not result in already existing data to be mod‐
393 ified. 1 = enabled, 0 = disabled.
394 YearlyYears
397 Data retention duration for the one year resolution entries. The
398 configuration defines for how many past years entries will be
399 stored. Set to -1 for unlimited entries or to 0 to disable the
400 data collection of this resolution.
401
404 5MinuteGraphResultCount
405 Number of 5 minute periods to be included in the 5 minute reso‐
406 lution graph. The value affects the width of the graph. Value
407 range: 288..5MinuteHours*12
408 5MinuteGraphHeight
411 Height of 5 minute resolution graph in pixels. Value range:
412 150..2000
413 BarColumnShowsRate
416 The bar column represents traffic rate in list outputs when en‐
417 abled. Requires also that OutputStyle has been configured to
418 show the traffic rate column by using the value 3. Enabling
419 this option will automatically cause EstimateStyle to have the
420 value 0. Visually this option affects only the color legend text
421 and the last line on the list if that line represents the cur‐
422 rently ongoing time period. 1 = enabled, 0 = disabled.
423 CBackground
426 Background color.
427 CEdge Edge color, if visible.
430 CHeader
433 Header background color.
434 CHeaderTitle
437 Header title text color.
438 CHeaderDate
441 Header date text color.
442 CLine Line color.
445 CLineL Lighter version of line color. Set to '-' in order to use a cal‐
448 culated value based on CLine.
449 CRx Color for received data.
452 CRxD Darker version of received data color. Set to '-' in order to
455 use a calculated value based on CRx.
456 CText Common text color.
459 CTx Color for transmitted data.
462 CTxD Darker version of transmitted data color. Set to '-' in order to
465 use a calculated value based on CTx.
466 EstimateStyle
469 Show a visual representation of the traffic estimation. 0 = not
470 shown, 1 = continuation of existing bar, 2 = separate bar.
471 HeaderFormat
474 Formatting of date in header. Uses the same format as date(1).
475 HourlyGraphMode
478 Select the output mode of the hourly graph. 0 = 24 hour sliding
479 window, 1 = graph begins from midnight.
480 HourlyRate
483 Show hours with rate instead of transferred amount. 1 = enabled,
484 0 = disabled.
485 ImageScale
488 Scale output to given percent. Value range: 50..500
489 LargeFonts
492 Increase the size of used fonts. 1 = enabled, 0 = disabled.
493 LineSpacingAdjustment
496 Adjust line spacing in list format outputs. Positive values in‐
497 crease the space between lines while negative values reduce it.
498 Value range: -5..10
499 SummaryGraph
502 Select which graph style output is shown next to the summary
503 data in the horizontal and vertical summary outputs. 0 = hours,
504 1 = 5 minutes.
505 SummaryRate
508 Show rate in summary output if available. 1 = enabled, 0 = dis‐
509 abled.
510 TransparentBg
513 Set background color as transparent. 1 = enabled, 0 = disabled.
514
517 /etc/vnstat.conf
518 Config file that will be used unless $HOME/.vnstatrc exists or
519 alternative value is given as command line parameter.
520
523 Using long date output formats may cause misalignment in shown columns
524 if the length of the date exceeds the fixed size allocation.
525
528 Teemu Toivola <tst at iki dot fi>
529
532 vnstat(1), vnstati(1), vnstatd(8), units(7)
533version 2.9 JANUARY 2022 VNSTAT.CONF(5)