1VNSTAT(1) User Manuals VNSTAT(1)
2
6 vnStat - a console-based network traffic monitor
7
10 vnstat [ -Ddhlmqrstuvw? ] [ --cleartop ] [ --config file ] [ --days ]
11 [ --delete ] [ --dbdir directory ] [ --debug ] [ --disable ] [ --dumpdb
12 ] [ --enable ] [ --help ] [ --hours ] [ -i interface ] [ --iface inter‐
13 face ] [ --iflist ] [ --live mode ] [ --locale locale ] [ --longhelp ]
14 [ --months ] [ --nick nickname ] [ --oneline ] [ --query ] [ --rateunit
15 ] [ --rebuildtotal ] [ --reset ] [ -ru ] [ --savemerged ] [ --short ] [
16 --showconfig ] [ --style number ] [ --sync ] [ --testkernel ] [ --top10
17 ] [ -tr time ] [ --traffic time ] [ --update ] [ --version ] [ --weeks
18 ] [ --xml ]
19
22 vnStat is a console-based network traffic monitor. It keeps a log of
23 hourly, daily and monthly network traffic for the selected inter‐
24 face(s). However, it isn't a packet sniffer. The traffic information is
25 analyzed from the proc(5) and sys filesystems depending on availabil‐
26 ity. That way vnStat can be used even without root permissions on most
27 systems.
28
31 --cleartop
32 Remove all top10 entries.
33 --config file
36 Use file as config file instead of using normal config file
37 search function.
38 -d, --days
41 Show traffic for days.
42 --dbdir directory
45 Use directory as database directory instead of using the direc‐
46 tory specified in the configuration file or the hardcoded
47 default if no configuration file is available.
48 -D, --debug
51 Show additional debug output.
52 --delete
55 Delete the database for the selected interface and stop monitor‐
56 ing it.
57 --dumpdb
60 Instead of showing the database with a formated output, this
61 output will dump the whole database in a format that should be
62 easy to parse with most script languages. Use this for example
63 with PHP, Perl or Python to make a custom webpage. The dump
64 uses ; as field delimeter.
65 active;1 activity status
68 interface;eth0 name for the interface
69 nick;inet nick (if given)
70 created;1023895272 creation date in Unix time
71 updated;1065467100 when the database was updated
72 totalrx;569605 all time total received MiB
73 totaltx;2023708 all time total transmitted MiB
74 currx;621673719 latest rx value in /proc
75 curtx;981730184 latest tx value in /proc
76 totalrxk;644 total rx KiB counter
77 totaltxk;494 total tx KiB counter
78 btime;1059414541 system boot time in Unix time
79 Then follows 30 lines like the following
81 d;0;1078696800;559;7433;68;557;1
83 where d = days, 0 = day number in database (0 is today),
85 1077314401 date in Unix time, 559 = rx MiB, 7433 = tx MiB, 68 =
86 rx KiB, 557 = tx KiB and 1 tells that vnStat has filled this
87 value and it is in use.
88 m;0;1078092000;48649;139704;527;252;1 (x12)
90 t;0;1078351200;5979;47155;362;525;1 (x10)
91 h;0;1078699800;118265;516545 (x24)
92 m = months, t = top10 and h = hours, all other fields are in the
94 same order as in days except hours that doesn't have a separate
95 KiB value. For hours the forth and fifth fields have values in
96 KiB.
97 --enable, --disable
100 Enable or disable updates for selected interface. Useful for
101 interfaces that aren't always available, like ppp0. If the
102 interface goes down it should be disabled in order to avoid
103 errors. Add something like vnstat -r --disable -i ppp0 to the
104 script that's executed when the interface goes down and vnstat
105 --enable -i ppp0 to the up script. These two options aren't
106 needed when the daemon is used.
107 -h, --hours
110 Show traffic for the last 24 hours.
111 -i, --iface interface
114 Select one specific interface and apply actions to only it.
115 --iflist
118 Show list of currently available interfaces.
119 -l, --live mode
122 Display current transfer rate for the selected interface in real
123 time until interrupted. Statistics will be shown after interrup‐
124 tion if the runtime was more than 10 seconds. An optional mode
125 parameter can be used to select between the displaying of pack‐
126 ets per second (mode 0) and transfer counters (mode 1) during
127 execution. --style can also be used to affect the layout of the
128 output.
129 --locale locale
132 Use locale instead of using the locale setting specified in the
133 configuration file or the system default if no configuration
134 file is available.
135 --longhelp
138 Show complete options list.
139 -m, --months
142 Show traffic for months.
143 --nick nickname
146 Set the selected interfaces nickname as an alias the will be
147 displayed in queries. Usage of -u is required to save the
148 change.
149 --oneline
152 Show traffic summary for selected interface using one line with
153 a parseable format. The output contains 15 fields with ; used as
154 field delimeter. The 1st field contains the version information
155 of the output that will be changed in future versions of vnStat
156 if the field structure changes. The following fields in order 2)
157 interface name, 3) timestamp for today, 4) rx for today, 5) tx
158 for today, 6) total for today, 7) average traffic rate for
159 today, 8) timestamp for current month, 9) rx for current month,
160 10) tx for current month, 11) total for current month, 12) aver‐
161 age traffic rate for today, 13) all time total rx, 14) all time
162 total tx, 15) all time total traffic.
163 -q, --query
166 Force database query mode.
167 -r, --reset
170 Reset the internal counters in the database for the selected
171 interface. Use this if the interface goes down and back up, oth‐
172 erwise that interface will get some extra traffic to its data‐
173 base.
174 --rebuildtotal
177 Reset the total traffic counters and recount those using
178 recorded months.
179 -ru, --rateunit
182 Swap the configured rate unit. If rate has been configured to be
183 shown in bytes then rate will be shown in bits if this option is
184 present. In the same way, if rate has been configured to be
185 shown in bits then rate will be shown in bytes when this option
186 is present. Alternatively 0 or 1 can be given as parameter for
187 this option in order to select between bytes (0) and bits (1)
188 regardless of the configuration file setting.
189 --savemerged
192 Write the end result of a database merge to the file mergeddb
193 that can then be used as a new database if renamed. Top10 traf‐
194 fic days isn't included in the merge and will start empty in the
195 new database.
196 -s, --short
199 Use short output mode. This mode is also used if more than one
200 database is available.
201 --style number
204 Modify the content and style of outputs. Set number to 0 for a
205 more narrow output, 1 for enabling bar column, 2 for same as
206 previous but with average traffic rate visible in summary and
207 weekly outputs and 3 for enabling average traffic rate in all
208 outputs where it is supported. 4 disables the use of terminal
209 control characters in -l / --live mode.
210 --sync Synchronize internal counters in the database with interface
213 counters for the selected interface. Use this if the system is
214 rebooted but interface counters aren't reseted. Such can occur
215 when suspend to ram/disk is used.
216 --testkernel
219 Test if the kernel boot time information always stays the same
220 like it should or if it's shifting.
221 -t, --top10
224 Show all time top10 traffic days.
225 -tr time
228 Calculate how much traffic goes through the selected interface
229 during the given time seconds. The time will be 5 seconds if a
230 number parameter isn't included.
231 -u, --update
234 Update all enabled databases or only the one specified with -i
235 parameter.
236 -v, --version
239 Show current version.
240 -w, --weeks
243 Show traffic for 7 days, current and previous week.
244 --xml Show database content for selected interface or all interfaces
247 in xml format. All traffic values in the output are in KiB.
248 -?, --help
251 Show a command summary.
252
255 /var/lib/vnstat/
256 This directory contains all databases the program uses. Files
257 are named according to the monitored interfaces.
258 /etc/vnstat.conf
261 Config file that will be used unless $HOME/.vnstatrc exists. See
262 vnstat.conf(5) for more information.
263
266 vnstat Display traffic summary for the default interface.
267 vnstat -i eth0+eth1+eth3
270 Display traffic summary for a merge of interfaces eth0, eth1 and
271 eth3.
272 vnstat -i eth2 --xml
275 Output all information about interface eth2 in xml format.
276 vnstat -u -i eth0
279 Force a database update for interface eth0 or create the data‐
280 base if it doesn't exist. This is usually the first command used
281 after a fresh install.
282 vnstat -u -i eth0 --nick local
285 Give interface eth0 the nickname "local". That information will
286 be later later visible as a label when eth0 is queried. The
287 database will also be updated when this command is executed or
288 created if the database doesn't exist.
289 vnstat -i eth2 --delete
292 Delete database of interface eth2 and stop monitoring it.
293
296 Updates needs to be executed at least as often as it is possible for
297 the interface to generate enough traffic to wrap the kernel interface
298 traffic counter. Otherwise it is possible that some traffic won't be
299 seen. This isn't an issue for 64 bit kernels but at least one update
300 every hour is always required in order to provide proper input. With
301 32 bit kernels the maximum time between two updates depends on how fast
302 the interface can transfer 4 GiB. Calculated theoretical times are:
303 10 Mbit: 54 minutes
305 100 Mbit: 5 minutes
306 1000 Mbit: 30 seconds
307 However, for 1000 Mbit interfaces updating once every minute is usually
309 still a working option.
310 Estimated traffic values are likely to be somewhat inaccurate if daily
312 traffic is low because only the MiB counter is used to calculate the
313 estimate.
314 Virtual and aliased interfaces cannot be monitored because the kernel
317 doesn't provide traffic information for that type of interfaces. Such
318 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
319 the actual interface being aliased.
320
323 Teemu Toivola <tst at iki dot fi>
324
327 vnstatd(1), vnstati(1), vnstat.conf(5), proc(5), ifconfig(8), units(7)
328version 1.11 JUNE 2011 VNSTAT(1)