1VNSTAT(1) User Manuals VNSTAT(1)
2
6 vnstat - a console-based network traffic monitor
7
10 vnstat [-5bDedhlmqrstvwy?] [--add] [--begin date] [--config file]
11 [--days [count]] [--dbdir [directory]] [--debug] [--end date]
12 [--fiveminutes [count]] [--help] [-hg] [--hours [count]] [--hoursgraph]
13 [-i interface] [--iface interface] [--iflist] [--json [mode] [limit]]
14 [--live [mode]] [--locale locale] [--longhelp] [--months [count]]
15 [--oneline [mode]] [--query] [--rateunit [mode]] [--remove] [-ru
16 [mode]] [--setalias alias] [--short] [--showconfig] [--style number]
17 [--top [count]] [-tr [time]] [--traffic [time]] [--version] [--xml
18 [mode] [limit]] [--years [count]]
19
22 vnStat is a console-based network traffic monitor. It keeps a log of 5
23 minute interval, hourly, daily, monthly and yearly network traffic for
24 the selected interface(s). However, it isn't a packet sniffer. The
25 traffic information is read from the proc(5) or sys filesystems depend‐
26 ing on availability resulting in light use of system resources regard‐
27 less of network traffic rate. That way vnStat can be used even without
28 root permissions on most systems.
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 the database whereas the daemon vnstatd(1) is
33 responsible for data retrieval, caching and storage. Although the dae‐
34 mon process is constantly running as a service, it is actually spending
35 most of its time sleeping between data updates.
36
39 --add Create database entry for interface specified with -i or --iface
40 option.
41 -b, --begin date
44 Begin the list output with a specific date / time defined by
45 date instead of the begin being selected based on the number of
46 entries to be shown. If date isn't available in the database
47 then the closest later date will be used. date supports the
48 following formats: YYYY-MM-DD HH:MM and YYYY-MM-DD. This option
49 can only be used with --json , --xml and list outputs.
50 --config file
53 Use file as configuration file instead of using automatic con‐
54 figuration file search functionality.
55 -d, --days [count]
58 Show traffic statistics on a daily basis for the last days. The
59 length of the list will default to 30 entries unless configured
60 otherwise or unless the optional count parameter is used. All
61 entries stored in the database will be shown if count is set to
62 0.
63 --dbdir directory
66 Use directory as database directory instead of using the direc‐
67 tory specified in the configuration file or the hardcoded
68 default if no configuration file is available.
69 -D, --debug
72 Show additional debug output.
73 -e, --end date
76 End the list output with a specific date / time defined by date
77 instead of the latest date / time in the database. If date isn't
78 available in the database then the closest earlier date will be
79 used. date supports the following formats: YYYY-MM-DD HH:MM and
80 YYYY-MM-DD. This option can only be used with --json , --xml
81 and list outputs. The top list also requires --begin to be used
82 at the same time with this option.
83 -5, --fiveminutes [count]
86 Show traffic statistics with a 5 minute resolution for the last
87 hours. The length of the list will default to 24 entries unless
88 configured otherwise or unless the optional count parameter is
89 used. All entries stored in the database will be shown if count
90 is set to 0.
91 -h, --hours [count]
94 Show traffic statistics on a hourly basis. The length of the
95 list will default to 24 entries unless configured otherwise or
96 unless the optional count parameter is used. All entries store
97 in the database will be shown if the count is set to 0.
98 -hg, --hoursgraph
101 Show traffic statistics on a hourly basis for the last 24 hours
102 using a bar graph followed by a table representing the numerical
103 data.
104 -i, --iface interface
107 Select one specific interface and apply actions to only it. For
108 queries, it is possible to merge the information of two or more
109 interfaces using the interface1+interface2+... syntax. All pro‐
110 vided interfaces must be unique and must exist in the database
111 when the merge syntax is used.
112 --iflist
115 Show list of currently available interfaces.
116 --json [mode] [limit]
119 Show database content for selected interface or all interfaces
120 in json format. All traffic values in the output are in bytes.
121 An optional mode parameter can be used for limiting the output
122 to only selected information. Everything is shown by default.
123 Setting mode to 'f' will output only 5 minute resolution
124 entries, 'h' hours, 'd' days, 'm' months, 'y' years and 't' the
125 top days. An optional limit parameter can be used to limit the
126 number results to a given number of most recent entries. The
127 --json option can be used in combination with -l, --live and -tr
128 options without mode having any effect to the output. The json‐
129 version field in the output contains the API version informa‐
130 tion. It will be changed only when the names or structures of
131 previously existing content gets changed. In comparison, the
132 vnstatversion field exists mainly as extra information.
133 -l, --live [mode]
136 Display current transfer rate for the selected interface in real
137 time until interrupted. Statistics will be shown after interrup‐
138 tion if the runtime was more than 10 seconds. An optional mode
139 parameter can be used to select between the displaying of pack‐
140 ets per second (mode 0) and transfer counters (mode 1) during
141 execution. --style can also be used to affect the layout of the
142 output. The output will be in json format if used in combination
143 with --json option.
144 --locale locale
147 Use locale instead of using the locale setting specified in the
148 configuration file or the system default if no configuration
149 file is available.
150 --longhelp
153 Show complete options list.
154 -m, --months [count]
157 Show traffic statistics on a monthly basis for the last months.
158 The length of the list will default to 12 entries unless config‐
159 ured otherwise or unless the optional count parameter is used.
160 All entries stored in the database will be shown if count is set
161 to 0.
162 --oneline [mode]
165 Show traffic summary for selected interface using one line with
166 a parsable format. The output contains 15 fields with ; used as
167 field delimiter. The 1st field contains the API version informa‐
168 tion of the output that will only be changed in future versions
169 if the field content or structure changes. The following fields
170 in order 2) interface name, 3) timestamp for today, 4) rx for
171 today, 5) tx for today, 6) total for today, 7) average traffic
172 rate for today, 8) timestamp for current month, 9) rx for cur‐
173 rent month, 10) tx for current month, 11) total for current
174 month, 12) average traffic rate for current month, 13) all time
175 total rx, 14) all time total tx, 15) all time total traffic. An
176 optional mode parameter can be used to force all fields to out‐
177 put in bytes without the unit itself shown.
178 -q, --query
181 Force database query mode.
182 --remove
185 Delete the database entry for the interface specified with -i or
186 --iface and stop monitoring it.
187 -ru, --rateunit [mode]
190 Swap the configured rate unit. If rate has been configured to be
191 shown in bytes then rate will be shown in bits if this option is
192 present. In the same way, if rate has been configured to be
193 shown in bits then rate will be shown in bytes when this option
194 is present. Alternatively, mode with either 0 or 1 can be used
195 as parameter for this option in order to select between bytes
196 (0) and bits (1) regardless of the configuration file setting.
197 --setalias alias
200 Set the selected interface alias as an alias that will be dis‐
201 played in queries.
202 -s, --short
205 Use short output mode. This mode is also used when more than one
206 interface is available in the database and no specific interface
207 is selected.
208 --showconfig
211 Show current configuration using the same format as the configu‐
212 ration file itself uses.
213 --style number
216 Modify the content and style of outputs. Set number to 0 for a
217 narrower output, 1 for enabling bar column, 2 for same as previ‐
218 ous but with average traffic rate visible in summary output and
219 3 for enabling average traffic rate in all outputs where it is
220 supported. 4 disables the use of terminal control characters in
221 -l / --live mode.
222 -t, --top [count]
225 Show all time top traffic days. The length of the list will
226 default to 10 entries unless configured otherwise or unless the
227 optional count parameter is used. All entries stored in the
228 database will be shown if count is set to 0. When used with
229 --begin and optionally with --end, the list will be generated
230 using the daily data instead of separate top entries. The
231 availability of daily data defines the boundaries the date spe‐
232 cific query can access.
233 -tr, --traffic [time]
236 Calculate how much traffic goes through the selected interface
237 during the given time seconds. The time will be 5 seconds if a
238 number parameter isn't specified. The output will be in json
239 format if used in combination with --json option. However, in
240 that case, the countdown before results isn't shown.
241 -v, --version
244 Show current version.
245 --xml [mode] [limit]
248 Show database content for selected interface or all interfaces
249 in xml format. All traffic values in the output are in bytes. An
250 optional mode parameter can be used for limiting the output to
251 only selected information. Everything is shown by default. Set‐
252 ting mode to 'f' will output only 5 minute resolution entries,
253 'h' hours, 'd' days, 'm' months, 'y' years and 't' the top days.
254 An optional limit parameter can be used to limit the number
255 results to a given number of most recent entries. The xmlversion
256 field in the output contains the API version information. It
257 will be changed only when the names or structures of previously
258 existing content gets changed. In comparison, the vnstatversion
259 field exists mainly as extra information.
260 -y, --years [count]
263 Show traffic statistics on a yearly basis for the last years.
264 The list will show all entries by default unless configured oth‐
265 erwise or unless the optional count parameter is used. All
266 entries stored in the database will also be shown if count is
267 set to 0.
268 -?, --help
271 Show a command option summary.
272
275 /var/lib/vnstat/
276 Default database directory.
277 /etc/vnstat.conf
280 Config file that will be used unless $HOME/.vnstatrc exists. See
281 vnstat.conf(5) for more information.
282
285 vnstat Display traffic summary for the default interface or multiple
286 interfaces when more than one is monitored.
287 vnstat -i eth0+eth1+eth3
290 Display traffic summary for a merge of interfaces eth0, eth1 and
291 eth3.
292 vnstat -i eth2 --xml
295 Output all information about interface eth2 in xml format.
296 vnstat --json
299 Output all information of all monitored interfaces in json for‐
300 mat.
301 vnstat -i eth0 --setalias local
304 Give interface eth0 the alias "local". That information will be
305 later visible as a label when eth0 is queried.
306 vnstat -i eth2 --remove
309 Delete database entries for interface eth2 and stop monitoring
310 it.
311
314 Updates need to be executed at least as often as it is possible for the
315 interface to generate enough traffic to overflow the kernel interface
316 traffic counter. Otherwise, it is possible that some traffic won't be
317 seen. With 32-bit kernels, the maximum time between two updates depends
318 on how fast the interface can transfer 4 GiB. Calculated theoretical
319 times are:
320 10 Mbit: 54 minutes
322 100 Mbit: 5 minutes
323 1000 Mbit: 30 seconds
324 However, for 1000 Mbit interfaces updating once every minute is usually
326 a usable solution if a shorter update interval can't be used.
327 Virtual and aliased interfaces cannot be monitored because the kernel
329 doesn't provide traffic information for that type of interfaces. Such
330 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
331 the actual interface being aliased.
332 Using long date output formats may cause misalignment in shown columns
334 if the length of the date exceeds the fixed size allocation.
335
338 Teemu Toivola <tst at iki dot fi>
339
342 vnstatd(1), vnstati(1), vnstat.conf(5), proc(5), ifconfig(8), units(7)
343version 2.3 JULY 2019 VNSTAT(1)