1VNSTAT.CONF(5)                   User Manuals                   VNSTAT.CONF(5)
2
3
4

NAME

6       vnstat.conf - vnStat configuration file
7
8

SYNOPSIS

10       /etc/vnstat.conf
11
12

DESCRIPTION

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
25       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
30

COMMON KEYWORDS

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
36
37       DayFormat, MonthFormat, TopFormat
38              Formatting of date in available outputs. Uses the same format as
39              date(1).  (vnstat and vnstati only)
40
41
42       DefaultDecimals
43              Number  of decimals to use in outputs. Value range: 0..2 (vnstat
44              and vnstati only)
45
46
47       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
53
54       HourlyDecimals
55              Number  of  decimals to use in hourly graph output. Value range:
56              0..2 (vnstat only)
57
58
59       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
64
65       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
75
76       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
90
91       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
96
97       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
101
102       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
109
110       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
116
117       RateUnit
118              Select  which  unit  is  used  when traffic rate is visible. 0 =
119              bytes, 1 = bits.  (vnstat and vnstati only)
120
121
122       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
129
130       RXCharacter, TXCharacter
131              Character used for representing the percentual share of received
132              and transmitted traffic in list mode outputs. (vnstat only)
133
134
135       RXHourCharacter, TXHourCharacter
136              Character used for representing the percentual share of received
137              and transmitted traffic in hourly graph output. (vnstat only)
138
139
140       Sampletime
141              Defines how many seconds the -tr  option  will  sample  traffic.
142              Value range: 2..600 (vnstat only)
143
144
145       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
153
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
161
162       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
172
173       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
181
182       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
192
193       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
199
200       BootVariation
201              Time in seconds how much the boot time reported by system kernel
202              can variate between updates. Value range: 0..300
203
204
205       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
209
210       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
219
220       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
227
228       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
234
235       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
241
242       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
254
255       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
261
262       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
268
269       LogFile
270              Specify log file path and name to be used if UseLogging  is  set
271              to 1.
272
273
274       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
280
281       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
288
289       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
295
296       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
305
306       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
311
312       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
317
318       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
322
323       PollInterval
324              How  often in seconds interfaces are checked for status changes.
325              Value range: 2..60
326
327
328       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
334
335       SaveInterval
336              How  often  in  minutes  cached interface data is saved to file.
337              Value range: ( UpdateInterval / 60 )..60
338
339
340       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
346
347       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
354
355       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
361
362       TrafficlessEntries
363              Create database entries even when there is no traffic during the
364              entry's time period. 1 = enabled, 0 = disabled.
365
366
367       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
377
378       UpdateInterval
379              How often in seconds the interface data is updated. Value range:
380              PollInterval..300
381
382
383       UseLogging
384              Enable  or  disable  logging.  0 = disabled, 1 = logfile and 2 =
385              syslog.
386
387
388       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
395
396       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
402
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
409
410       5MinuteGraphHeight
411              Height of 5 minute resolution  graph  in  pixels.  Value  range:
412              150..2000
413
414
415       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
424
425       CBackground
426              Background color.
427
428
429       CEdge  Edge color, if visible.
430
431
432       CHeader
433              Header background color.
434
435
436       CHeaderTitle
437              Header title text color.
438
439
440       CHeaderDate
441              Header date text color.
442
443
444       CLine  Line color.
445
446
447       CLineL Lighter version of line color. Set to '-' in order to use a cal‐
448              culated value based on CLine.
449
450
451       CRx    Color for received data.
452
453
454       CRxD   Darker version of received data color. Set to '-'  in  order  to
455              use a calculated value based on CRx.
456
457
458       CText  Common text color.
459
460
461       CTx    Color for transmitted data.
462
463
464       CTxD   Darker version of transmitted data color. Set to '-' in order to
465              use a calculated value based on CTx.
466
467
468       EstimateStyle
469              Show a visual representation of the traffic estimation.  0 = not
470              shown, 1 = continuation of existing bar, 2 = separate bar.
471
472
473       HeaderFormat
474              Formatting of date in header. Uses the same format as date(1).
475
476
477       HourlyGraphMode
478              Select  the output mode of the hourly graph. 0 = 24 hour sliding
479              window, 1 = graph begins from midnight.
480
481
482       HourlyRate
483              Show hours with rate instead of transferred amount. 1 = enabled,
484              0 = disabled.
485
486
487       ImageScale
488              Scale output to given percent. Value range: 50..500
489
490
491       LargeFonts
492              Increase the size of used fonts. 1 = enabled, 0 = disabled.
493
494
495       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
500
501       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
506
507       SummaryRate
508              Show  rate in summary output if available. 1 = enabled, 0 = dis‐
509              abled.
510
511
512       TransparentBg
513              Set background color as transparent. 1 = enabled, 0 = disabled.
514
515

FILES

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
521

RESTRICTIONS

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
526

AUTHOR

528       Teemu Toivola <tst at iki dot fi>
529
530

SEE ALSO

532       vnstat(1), vnstati(1), vnstatd(8), units(7)
533
534
535
536version 2.9                      JANUARY 2022                   VNSTAT.CONF(5)
Impressum