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 '#´ are inter‐
18 preted 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
26 usage of each keyword. The first section contains keywords that are
27 considered common for all commands, the second section is for daemon
28 related 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 HourlyDecimals
48 Number of decimals to use in hourly graph output. Value range:
49 0..2 (vnstat only)
50 HourlySectionStyle
53 Select what kind of spacer is used for separating the numerical
54 sections of the hourly graph output. 0 = none, 1 = '|', 2 =
55 '][', 3 = '[ ]'. (vnstat only)
56 Interface
59 Default interface used when no other interface is specified on
60 the command line. Leave empty for automatic selection. The auto‐
61 matic selection will prioritize the interface with most traffic
62 for outputs doing database queries. Queries not using the data‐
63 base will first check if the database is available and select
64 the interface with most traffic out those that are currently
65 visible in the system. If no database can be read then the first
66 available interface will be used. (vnstat and vnstati only)
67 List5Mins, ListHours, ListDays, ListMonths, ListYears, ListTop
70 Number of entries to show in list outputs unless overridden from
71 the command line. Set to 0 to show all entries available in the
72 database. (vnstat and vnstati)
73 Locale Locale setting to be used for prints. This replaces the LC_ALL
76 environment variable. Set to "-" or leave empty in order to use
77 the system default value. (vnstat and vnstati only)
78 OutputStyle
81 Modify the content and style of text outputs. 0 = minimal and
82 narrow output for terminal with limited width, 1 = normal output
83 with bar column visible, 2 = same as 1 except rate is visible in
84 summary output, 3 = rate column is visible in all outputs where
85 it is supported. (vnstat and vnstati only)
86 QueryMode
89 Default query mode when no parameters are given. 0 = normal, 1 =
90 days, 2 = months, 3 = top, 5 = short, 6 = years, 7 = hours
91 graph, 8 = xml, 9 = one line, 10 = json, 11 = hours and 12 = 5
92 minute. (vnstat only)
93 RateUnit
96 Select which unit is used when traffic rate is visible. 0 =
97 bytes, 1 = bits. (vnstat and vnstati only)
98 RateUnitMode
101 Select used prefix when traffic rate is shown in bits per sec‐
102 ond. IEC binary prefixes are calculated with powers of 1024. SI
103 decimal prefixes are calculated with powers of 1000. 0 = IEC
104 binary prefixes (Kibit/s...), 1 = SI decimal prefixes
105 (kbit/s...). (vnstat and vnstati only)
106 RXCharacter, TXCharacter
109 Character used for representing the percentual share of received
110 and transmitted traffic in list mode outputs. (vnstat only)
111 RXHourCharacter, TXHourCharacter
114 Character used for representing the percentual share of received
115 and transmitted traffic in hourly graph output. (vnstat only)
116 Sampletime
119 Defines how many seconds the -tr option will sample traffic.
120 Value range: 2..600 (vnstat only)
121 UnitMode
124 Select how units are prefixed. IEC and JEDEC binary prefixes are
125 calculated with powers of 1024. SI decimal prefixes are calcu‐
126 lated with powers of 1000. 0 = IEC standard prefixes
127 (B/KiB/MiB/GiB...), 1 = old style (JEDEC) binary prefixes
128 (B/KB/MB/GB...), 2 = SI decimals prefixes (B/kB/MB/GB...)
129 (vnstat and vnstati only)
130
133 5MinuteHours
134 Data retention duration for the 5 minute resolution entries. The
135 configuration defines for how many past hours entries will be
136 stored. Set to -1 for unlimited entries or to 0 to disable the
137 data collection of this resolution.
138 64bitInterfaceCounters
141 Select interface counter handling. Set to 1 for defining that
142 all interfaces use 64-bit counters on the kernel side and 0 for
143 defining 32-bit counter Set to -1 for using the old style logic
144 used in earlier versions where counter values within 32-bits are
145 assumed to be 32-bit and anything larger is assumed to be a
146 64-bit counter. This may produce false results if a 64-bit
147 counter is reset within the 32-bits. Set to -2 for using auto‐
148 matic detection based on available kernel datastructures.
149 BandwidthDetection
152 Try to automatically detect MaxBandwidth value for each moni‐
153 tored interface. Mostly only ethernet interfaces support this
154 feature. MaxBandwidth or interface specific MaxBW will be used
155 as fallback value if detection fails. 1 = enabled, 0 = dis‐
156 abled.
157 BandwidthDetectionInterval
160 How often in minutes interface specific detection of MaxBand‐
161 width is done for detecting possible changes when BandwidthDe‐
162 tection is enabled. Can be disabled by setting to 0. Value
163 range: 0..30
164 BootVariation
167 Time in seconds how much the boot time reported by system kernel
168 can variate between updates. Value range: 0..300
169 CheckDiskSpace
172 Enable or disable the availability check of at least some free
173 disk space before a database write. 1 = enabled, 0 = disabled.
174 CreateDirs
177 Enable or disable the creation of directories when a configured
178 path doesn't exist. This includes DatabaseDir , LogFile and Pid‐
179 File directories. The LogFile directory will be created only
180 when UseLogging has been set to 1. The PidFile directory will be
181 created only if the daemon is started as a background process.
182 The daemon process will try to create the directory using per‐
183 missions of the user used to start the process.
184 DaemonGroup
187 Specify the group to which the daemon process should switch dur‐
188 ing startup. The group can either be the name of the group or a
189 numerical group id. Leave empty to disable group switching.
190 This option can only be used when the process is started as
191 root.
192 DaemonUser
195 Specify the user to which the daemon process should switch dur‐
196 ing startup. The user can either be the login of the user or a
197 numerical user id. Leave empty to disable user switching. This
198 option can only be used when the process is started as root.
199 DailyDays
202 Data retention duration for the one day resolution entries. The
203 configuration defines for how many past days entries will be
204 stored. Set to -1 for unlimited entries or to 0 to disable the
205 data collection of this resolution.
206 DatabaseSynchronous
209 Change the setting of the SQLite "synchronous" flag which con‐
210 trols how much care is taken to ensure disk writes have fully
211 completed when writing data to the database before continuing
212 other actions. Higher values take extra steps to ensure data
213 safety at the cost of slower performance. A value of 0 will
214 result in all handling being left to the filesystem itself. Set
215 to -1 to select the default value according to database mode
216 controlled by DatabaseWriteAheadLogging setting. See SQLite doc‐
217 umentation for more details regarding values from 1 to 3. Value
218 range: -1..3
219 DatabaseWriteAheadLogging
222 Enable or disable SQLite Write-Ahead Logging mode for the data‐
223 base. See SQLite documentation for more details and note that
224 support for read-only operations isn't available in older SQLite
225 versions. 1 = enabled, 0 = disabled.
226 HourlyDays
229 Data retention duration for the one hour resolution entries. The
230 configuration defines for how many past days entries will be
231 stored. Set to -1 for unlimited entries or to 0 to disable the
232 data collection of this resolution.
233 LogFile
236 Specify log file path and name to be used if UseLogging is set
237 to 1.
238 MaxBandwidth
241 Maximum bandwidth for all interfaces. If the interface specific
242 traffic exceeds the given value then the data is assumed to be
243 invalid and rejected. Set to 0 in order to disable the feature.
244 Value range: 0..50000
245 MaxBW Same as MaxBandwidth but can be used for setting individual lim‐
248 its for selected interfaces. The name of the interface is speci‐
249 fied directly after the MaxBW keyword without spaces. For exam‐
250 ple MaxBWeth0 for eth0 and MaxBWppp0 for ppp0. Value range:
251 0..50000
252 MonthlyMonths
255 Data retention duration for the one month resolution entries.
256 The configuration defines for how many past months entries will
257 be stored. Set to -1 for unlimited entries or to 0 to disable
258 the data collection of this resolution.
259 MonthRotate
262 Day of month that months are expected to change. Usually set to
263 1 but can be set to alternative values for example for tracking
264 monthly billed traffic where the billing period doesn't start on
265 the first day. For example, if set to 7, days of February up to
266 and including the 6th will count for January. Changing this
267 option will not cause existing data to be recalculated. Value
268 range: 1..28
269 MonthRotateAffectsYears
272 Enable or disable MonthRotate also affecting yearly data. Appli‐
273 cable only when MonthRotate has a value greater than one. 1 =
274 enabled, 0 = disabled.
275 OfflineSaveInterval
278 How often in minutes cached interface data is saved to file when
279 all monitored interfaces are offline. Value range: SaveInter‐
280 val..60
281 PidFile
284 Specify pid file path and name to be used.
285 PollInterval
288 How often in seconds interfaces are checked for status changes.
289 Value range: 2..60
290 SaveInterval
293 How often in minutes cached interface data is saved to file.
294 Value range: ( UpdateInterval / 60 )..60
295 SaveOnStatusChange
298 Enable or disable the additional saving to file of cached inter‐
299 face data when the availability of an interface changes, i.e.,
300 when an interface goes offline or comes online. 1 = enabled, 0 =
301 disabled.
302 TimeSyncWait
305 How many minutes to wait during daemon startup for system clock
306 to sync if most recent database update appears to be in the
307 future. This may be needed in systems without a real-time clock
308 (RTC) which require some time after boot to query and set the
309 correct time. 0 = wait disabled. Value range: 0..60
310 TopDayEntries
313 Data retention duration for the top day entries. The configura‐
314 tion defines how many of the past top day entries will be
315 stored. Set to -1 for unlimited entries or to 0 to disable the
316 data collection of this resolution.
317 TrafficlessEntries
320 Create database entries even when there is no traffic during the
321 entry's time period. 1 = enabled, 0 = disabled.
322 UpdateFileOwner
325 Enable or disable the update of file ownership during daemon
326 process startup. During daemon startup, only database, log and
327 pid files will be modified if the user or group change feature (
328 DaemonUser or DaemonGroup ) is enabled and the files don't match
329 the requested user or group. During manual database creation,
330 this option will cause file ownership to be inherited from the
331 database directory if the directory already exists. This option
332 only has effect when the process is started as root or via sudo.
333 UpdateInterval
336 How often in seconds the interface data is updated. Value range:
337 PollInterval..300
338 UseLogging
341 Enable or disable logging. 0 = disabled, 1 = logfile and 2 =
342 syslog.
343 YearlyYears
346 Data retention duration for the one year resolution entries. The
347 configuration defines for how many past years entries will be
348 stored. Set to -1 for unlimited entries or to 0 to disable the
349 data collection of this resolution.
350
353 CBackground
354 Background color.
355 CEdge Edge color, if visible.
358 CHeader
361 Header background color.
362 CHeaderTitle
365 Header title text color.
366 CHeaderDate
369 Header date text color.
370 CLine Line color.
373 CLineL Lighter version of line color. Set to '-' in order to use a cal‐
376 culated value based on CLine.
377 CRx Color for received data.
380 CRxD Darker version of received data color. Set to '-' in order to
383 use a calculated value based on CRx.
384 CText Common text color.
387 CTx Color for transmitted data.
390 CTxD Darker version of transmitted data color. Set to '-' in order to
393 use a calculated value based on CTx.
394 HeaderFormat
397 Formatting of date in header. Uses the same format as date(1).
398 HourlyRate
401 Show hours with rate instead of transferred amount. 1 = enabled,
402 0 = disabled.
403 SummaryRate
406 Show rate in summary output if available. 1 = enabled, 0 = dis‐
407 abled.
408 TransparentBg
411 Set background color as transparent. 1 = enabled, 0 = disabled.
412
415 /etc/vnstat.conf
416 Config file that will be used unless $HOME/.vnstatrc exists or
417 alternative value is given as command line parameter.
418
421 Using long date output formats may cause misalignment in shown columns
422 if the length of the date exceeds the fixed size allocation.
423
426 Teemu Toivola <tst at iki dot fi>
427
430 vnstat(1), vnstati(1), vnstatd(8), units(7)
431version 2.6 JANUARY 2020 VNSTAT.CONF(5)