1VNSTAT(1) User Manuals VNSTAT(1)
2
6 vnstat - a console-based network traffic monitor
7
10 vnstat [ -Ddhlmqrstuvw? ] [ --cleartop ] [ --config file ] [ --create
11 ] [ --days ] [ --delete ] [ --dbdir directory ] [ --debug ] [ --disable
12 ] [ --enable ] [ --exportdb ] [ --help ] [ --hours ] [ --importdb file
13 ] [ -i interface ] [ --iface interface ] [ --iflist ] [ --json mode ] [
14 --live mode ] [ --locale locale ] [ --longhelp ] [ --months ] [ --nick
15 nickname ] [ --oneline mode ] [ --query ] [ --rateunit ] [ --rebuildto‐
16 tal ] [ --reset ] [ -ru ] [ --savemerged ] [ --short ] [ --showconfig ]
17 [ --style number ] [ --sync ] [ --testkernel ] [ --top10 ] [ -tr time ]
18 [ --traffic time ] [ --update ] [ --version ] [ --weeks ] [ --xml mode
19 ]
20
23 vnStat is a console-based network traffic monitor. It keeps a log of
24 hourly, daily and monthly network traffic for the selected inter‐
25 face(s). However, it isn't a packet sniffer. The traffic information is
26 read from the proc(5) or sys filesystems depending on availability.
27 That way vnStat can be used even without root permissions on most sys‐
28 tems.
29 The implementation is divided into two commands. The purpose of the
31 vnstat command is to provide an interface for querying the traffic
32 information stored in network interface specific databases where as the
33 daemon vnstatd(1) is responsible for data retrieval and storage.
34 Although the daemon process is constantly running as a service, it is
35 actually spending most of the time sleeping between data updates.
36
39 --cleartop
40 Remove all top 10 entries.
41 --config file
44 Use file as configuration file instead of using normal configu‐
45 ration file search functionality.
46 --create
49 Create database for interface specified with -i or --iface
50 option.
51 -d, --days
54 Show traffic statistics on a daily basis for the last 30 days.
55 --dbdir directory
58 Use directory as database directory instead of using the direc‐
59 tory specified in the configuration file or the hardcoded
60 default if no configuration file is available.
61 -D, --debug
64 Show additional debug output.
65 --delete
68 Delete the database for the interface specified with -i or
69 --iface and stop monitoring it.
70 --enable, --disable
73 Enable or disable updates for selected interface. Useful for
74 interfaces that aren't always available, like ppp0. If the
75 interface goes down it should be disabled in order to avoid
76 errors. Add something like vnstat -r --disable -i ppp0 to the
77 script that's executed when the interface goes down and vnstat
78 --enable -i ppp0 to the up script. These two options aren't
79 needed when the daemon is used.
80 --exportdb
83 Instead of showing the database with a formatted output, this
84 output will dump the whole database in a plain text based archi‐
85 tecture independent format. The output can be imported back
86 using the --importdb option and can be used for moving a data‐
87 base from one host to another. See the --importdb documentation
88 below for an example. Using the output for scripting is possible
89 but the outputs of --xml and --json are likely to be more suit‐
90 able. The dump uses ; as field delimiter.
91 active;1 activity status
93 interface;eth0 name for the interface
94 nick;inet nick (if given)
95 created;1023895272 creation date in Unix time
96 updated;1065467100 when the database was updated
97 totalrx;569605 all time total received MiB
98 totaltx;2023708 all time total transmitted MiB
99 currx;621673719 latest rx value in /proc
100 curtx;981730184 latest tx value in /proc
101 totalrxk;644 total rx KiB counter
102 totaltxk;494 total tx KiB counter
103 btime;1059414541 system boot time in Unix time
104 Then follows 30 lines like the following
106 d;0;1078696800;559;7433;68;557;1
108 where d = days, 0 = day number in database (0 is today),
110 1077314401 date in Unix time, 559 = rx MiB, 7433 = tx MiB, 68 =
111 rx KiB, 557 = tx KiB and 1 tells that vnStat has filled this
112 value and it is in use.
113 m;0;1078092000;48649;139704;527;252;1 (x12)
115 t;0;1078351200;5979;47155;362;525;1 (x10)
116 h;0;1078699800;118265;516545 (x24)
117 m = months, t = top 10 and h = hours, all other fields are in
119 the same order as in days except hours that doesn't have a sepa‐
120 rate KiB value. For hours the forth and fifth fields have values
121 in KiB.
122 -h, --hours
125 Show traffic statistics on a hourly basis for the last 24 hours.
126 --importdb file
129 Import a database from file which was previously exported using
130 the --exportdb option. This can be used to transfer a database
131 between different architectures and hosts, as the database is
132 architecture dependent and not compatible between different
133 architectures. First dump the database on one host, e.g. with
134 vnstat -i ppp0 --exportdb >ppp0db.txt and then import the text
135 file on a different host using vnstat -i ppp0 --importdb
136 ppp0db.txt
137 -i, --iface interface
140 Select one specific interface and apply actions to only it. For
141 queries, it is possible to merge the information of two or more
142 interfaces using the interface1+interface2+... syntax.
143 --iflist
146 Show list of currently available interfaces.
147 --json mode
150 Show database content for selected interface or all interfaces
151 in json format. All traffic values in the output are in KiB. An
152 optional mode parameter can be used for limiting the output to
153 only selected information. Everything is shown by default. Set‐
154 ting mode to 'h' will output only hours, 'd' days, 'm' months
155 and 't' the top 10. This option can also be used in combination
156 with -l, --live and -tr options without mode having any effect
157 to the output.
158 -l, --live mode
161 Display current transfer rate for the selected interface in real
162 time until interrupted. Statistics will be shown after interrup‐
163 tion if the runtime was more than 10 seconds. An optional mode
164 parameter can be used to select between the displaying of pack‐
165 ets per second (mode 0) and transfer counters (mode 1) during
166 execution. --style can also be used to affect the layout of the
167 output. The output will be in json format if used in combination
168 with --json option.
169 --locale locale
172 Use locale instead of using the locale setting specified in the
173 configuration file or the system default if no configuration
174 file is available.
175 --longhelp
178 Show complete options list.
179 -m, --months
182 Show traffic statistics on a monthly basis for the last 12
183 months.
184 --nick nickname
187 Set the selected interfaces nickname as an alias the will be
188 displayed in queries. Usage of -u is required to save the change
189 and the daemon may not be running during the set operation.
190 --oneline
193 Show traffic summary for selected interface using one line with
194 a parseable format. The output contains 15 fields with ; used as
195 field delimiter. The 1st field contains the version information
196 of the output that will be changed in future versions of vnStat
197 if the field structure changes. The following fields in order 2)
198 interface name, 3) timestamp for today, 4) rx for today, 5) tx
199 for today, 6) total for today, 7) average traffic rate for
200 today, 8) timestamp for current month, 9) rx for current month,
201 10) tx for current month, 11) total for current month, 12) aver‐
202 age traffic rate for today, 13) all time total rx, 14) all time
203 total tx, 15) all time total traffic. An optional mode parame‐
204 ter can be used to force all fields to output in bytes without
205 the unit itself shown.
206 -q, --query
209 Force database query mode.
210 -r, --reset
213 Reset the internal counters in the database for the selected
214 interface. Use this if the interface goes down and back up, oth‐
215 erwise that interface will get some extra traffic to its data‐
216 base. Not needed when the daemon is used.
217 --rebuildtotal
220 Reset the total traffic counters and recount those using
221 recorded months.
222 -ru, --rateunit
225 Swap the configured rate unit. If rate has been configured to be
226 shown in bytes then rate will be shown in bits if this option is
227 present. In the same way, if rate has been configured to be
228 shown in bits then rate will be shown in bytes when this option
229 is present. Alternatively 0 or 1 can be given as parameter for
230 this option in order to select between bytes (0) and bits (1)
231 regardless of the configuration file setting.
232 --savemerged
235 Write the end result of a database merge to the file mergeddb
236 that can then be used as a new database if renamed. Top 10 traf‐
237 fic days isn't included in the merge and will start empty in the
238 new database. The merge interface syntax is documented in -i,
239 --iface option.
240 -s, --short
243 Use short output mode. This mode is also used if more than one
244 database is available.
245 --style number
248 Modify the content and style of outputs. Set number to 0 for a
249 more narrow output, 1 for enabling bar column, 2 for same as
250 previous but with average traffic rate visible in summary and
251 weekly outputs and 3 for enabling average traffic rate in all
252 outputs where it is supported. 4 disables the use of terminal
253 control characters in -l / --live mode.
254 --sync Synchronize internal counters in the database with interface
257 counters for the selected interface. Use this if the system is
258 rebooted but interface counters aren't reset. Such can occur
259 when suspend to ram/disk is used. Not needed when the daemon is
260 used.
261 --testkernel
264 Test if the kernel boot time information always stays the same
265 like it should or if it's shifting.
266 -t, --top10
269 Show all time top 10 traffic days.
270 -tr time
273 Calculate how much traffic goes through the selected interface
274 during the given time seconds. The time will be 5 seconds if a
275 number parameter isn't specified. The output will be in json
276 format if used in combination with --json option. However, in
277 that case, the countdown before results isn't shown.
278 -u, --update
281 Update all enabled databases or only the one specified with -i
282 parameter. Not supported when the daemon is running.
283 -v, --version
286 Show current version.
287 -w, --weeks
290 Show traffic for 7 days, current and previous week.
291 --xml mode
294 Show database content for selected interface or all interfaces
295 in xml format. All traffic values in the output are in KiB. An
296 optional mode parameter can be used for limiting the output to
297 only selected information. Everything is shown by default. Set‐
298 ting mode to 'h' will output only hours, 'd' days, 'm' months
299 and 't' the top 10.
300 -?, --help
303 Show a command option summary.
304
307 /var/lib/vnstat/
308 This directory contains all databases the program uses. Files
309 are named according to the monitored interfaces. A backup copy
310 of each database is kept in a file starting with a . (dot char‐
311 acter) and otherwise named according to the original file.
312 /etc/vnstat.conf
315 Config file that will be used unless $HOME/.vnstatrc exists. See
316 vnstat.conf(5) for more information.
317
320 vnstat Display traffic summary for the default interface or multiple
321 interfaces when more than one is monitored.
322 vnstat -i eth0+eth1+eth3
325 Display traffic summary for a merge of interfaces eth0, eth1 and
326 eth3.
327 vnstat -i eth2 --xml
330 Output all information about interface eth2 in xml format.
331 vnstat --json
334 Output all information of all monitored interfaces in json for‐
335 mat.
336 vnstat -u -i eth0
339 Force a database update for interface eth0 or create the data‐
340 base if it doesn't exist. This is usually the first command used
341 after a fresh install if the daemon isn't used.
342 vnstat -u -i eth0 --nick local
345 Give interface eth0 the nickname "local". That information will
346 be later later visible as a label when eth0 is queried. The
347 database will also be updated when this command is executed or
348 created if the database doesn't exist.
349 vnstat -i eth2 --delete
352 Delete database of interface eth2 and stop monitoring it.
353
356 Updates needs to be executed at least as often as it is possible for
357 the interface to generate enough traffic to overflow the kernel inter‐
358 face traffic counter. Otherwise, it is possible that some traffic won't
359 be seen. This isn't an issue for 64-bit kernels but at least one update
360 every hour is always required in order to provide proper input. With
361 32-bit kernels, the maximum time between two updates depends on how
362 fast the interface can transfer 4 GiB. Calculated theoretical times
363 are:
364 10 Mbit: 54 minutes
366 100 Mbit: 5 minutes
367 1000 Mbit: 30 seconds
368 However, for 1000 Mbit interfaces updating once every minute is usually
370 a usable solution if faster updates can't be used.
371 Estimated traffic values are likely to be somewhat inaccurate if daily
373 traffic is low because only the MiB counter is used to calculate the
374 estimate.
375 Virtual and aliased interfaces cannot be monitored because the kernel
377 doesn't provide traffic information for that type of interfaces. Such
378 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
379 the actual interface being aliased.
380 Using long date output formats may cause misalignment in shown columns
382 if the length of the date exceeds the fixed size allocation.
383
386 Teemu Toivola <tst at iki dot fi>
387
390 vnstatd(1), vnstati(1), vnstat.conf(5), proc(5), ifconfig(8), units(7)
391version 1.18 MARCH 2018 VNSTAT(1)