1VNSTAT(1) User Manuals VNSTAT(1)
2
6 vnstat - a console-based network traffic monitor
7
10 vnstat [-5bDedhlmqstvy?] [--add] [--alert output exit type condition
11 limit unit] [--begin date] [--config file] [--days [limit]] [--dbdir
12 directory] [--dbiflist [mode]] [--debug] [--end date] [--fiveminutes
13 [limit]] [--help] [-hg] [--hours [limit]] [--hoursgraph] [-i interface]
14 [--iface interface] [--iflist [mode]] [--json [mode] [limit]] [--limit
15 limit] [--live [mode]] [--locale locale] [--longhelp] [--months
16 [limit]] [--oneline [mode]] [--query] [--rateunit [mode]] [--remove]
17 [--rename name] [-ru [mode]] [--setalias alias] [--short] [--showcon‐
18 fig] [--style number] [--top [limit]] [-tr [time]] [--traffic [time]]
19 [--version] [--xml [mode] [limit]] [--years [limit]] [interface]
20
23 vnStat is a console-based network traffic monitor. It keeps a log of 5
24 minute interval, hourly, daily, monthly and yearly network traffic for
25 the selected interface(s). However, it isn't a packet sniffer. The
26 traffic information is read from the proc(5) or sys filesystems depend‐
27 ing on availability resulting in light use of system resources regard‐
28 less of network traffic rate. That way vnStat can be used even without
29 root permissions on most systems.
30 Functionality is divided into two commands. The purpose of the vnstat
32 command is to provide an interface for querying the traffic information
33 stored in the database whereas the daemon vnstatd(8) is responsible for
34 data retrieval, caching and storage. Although the daemon process is
35 constantly running as a service, it is actually spending most of its
36 time sleeping between data updates.
37
40 --add Create database entry for interface specified with -i or --iface
41 option. The daemon can be running during this operation and will
42 automatically start monitoring the interface without a restart
43 within SaveInterval minutes if configuration option Rescan‐
44 DatabaseOnSave is enabled. Otherwise the daemon needs to be
45 restarted in order for the added interface to be monitored.
46 --alert output exit type condition limit unit
49 Depending on values of given parameters, show alert, use differ‐
50 ent exit status or a combination of both when configured situa‐
51 tion is met.
52 output parameter takes a number from 0 to 3 and controls when,
55 if at all, the command will result in output. '0' never produces
56 output, '1' always produces output, '2' shows output only when
57 usage estimate exceeds limit and '3' shows output only when
58 limit is exceeded.
59 exit parameter takes a number from 0 to 3 and controls the exit
62 status of the command. '0' always uses exit status 0, '1' always
63 uses exit status 1, '2' uses exit status 1 if usage estimate ex‐
64 ceeds limit but otherwise exit status 0 and '3' uses exit status
65 1 if limit is exceeded but otherwise exit status 0.
66 type parameter defines to which time range type usage the limit
69 is compared against. Available options: 'h', 'hour', 'hourly',
70 'd', 'day', 'daily', 'm', 'month', 'monthly', 'y', 'year',
71 'yearly'.
72 condition parameter defines if limit is compared to received
75 (rx), transmitted (tx), total or estimated usage of these three.
76 Available options: 'rx', 'tx', 'total', 'rx_estimate', 'tx_esti‐
77 mate', 'total_estimate'.
78 limit is a greater than zero integer without decimals which de‐
81 fines the traffic usage limit using the unit defined with the
82 unit parameter. unit accepts the following options: 'B', 'KiB',
83 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'KB', 'MB', 'GB', 'TB', 'PB',
84 'EB'. Usage must exceed limit in order for the alarm to acti‐
85 vate. Exactly the same usage as limit does not raise the alarm.
86 Estimate calculation isn't limited to the estimate options in
89 condition parameter but can also be achieved by using the esti‐
90 mate option in output or exit parameters. Missing or invalid pa‐
91 rameters will result in --alert specific help output being
92 shown.
93 -b, --begin date
96 Begin the list output with a specific date / time defined by
97 date instead of the begin being selected based on the number of
98 entries to be shown. If date isn't available in the database
99 then the closest later date will be used. date supports the
100 following formats: YYYY-MM-DD HH:MM, YYYY-MM-DD and "today".
101 This option can only be used with --json , --xml and list out‐
102 puts.
103 --config file
106 Use file as configuration file instead of using automatic con‐
107 figuration file search functionality.
108 -d, --days [limit]
111 Show traffic statistics on a daily basis for the last days. The
112 length of the list will be limited to 30 entries unless config‐
113 ured otherwise or unless the optional limit parameter is used.
114 All entries stored in the database will be shown if limit is set
115 to 0.
116 --dbdir directory
119 Use directory as database directory instead of using the direc‐
120 tory specified in the configuration file or the hardcoded de‐
121 fault if no configuration file is available.
122 --dbiflist [mode]
125 List interfaces currently in the database. If mode is not de‐
126 fined or is set to 0 then the output will use a one line verbose
127 format. If mode is set to 1 then the output will contain one in‐
128 terface per line. See also --iflist.
129 -D, --debug
132 Show additional debug output.
133 -e, --end date
136 End the list output with a specific date / time defined by date
137 instead of the latest date / time in the database. If date isn't
138 available in the database then the closest earlier date will be
139 used. date supports the following formats: YYYY-MM-DD HH:MM and
140 YYYY-MM-DD. This option can only be used with --json , --xml
141 and list outputs. The top list also requires --begin to be used
142 at the same time with this option.
143 -5, --fiveminutes [limit]
146 Show traffic statistics with a 5 minute resolution for the last
147 hours. The length of the list will be limited to 24 entries un‐
148 less configured otherwise or unless the optional limit parameter
149 is used. All entries stored in the database will be shown if
150 limit is set to 0.
151 -h, --hours [limit]
154 Show traffic statistics on a hourly basis. The length of the
155 list will be limited to 24 entries unless configured otherwise
156 or unless the optional limit parameter is used. All entries
157 store in the database will be shown if the limit is set to 0.
158 -hg, --hoursgraph
161 Show traffic statistics on a hourly basis for the last 24 hours
162 using a bar graph followed by a table representing the numerical
163 data.
164 -i, --iface interface
167 Select one specific interface and apply actions to only it. For
168 database queries, it is possible to merge the information of two
169 or more interfaces using the interface1+interface2+... syntax.
170 All provided interfaces must be unique and must exist in the
171 database when the merge syntax is used. Optionally, depending on
172 the InterfaceMatchMethod configuration setting, interface can be
173 replaced with alias previously set using --setalias. Merge syn‐
174 tax isn't supported when alias is used. The -i, --iface option
175 is optional and interface can be used as parameter on the com‐
176 mand line for selecting the used interface even without the op‐
177 tion being explicitly used.
178 --iflist [mode]
181 List currently available interfaces. If mode is not defined or
182 is set to 0 then the output will use a one line verbose format.
183 If mode is set to 1 then the output will contain one interface
184 per line. See also --dbiflist.
185 --json [mode] [limit]
188 Show database content for selected interface or all interfaces
189 in json format. All traffic values in the output are in bytes.
190 An optional mode parameter can be used for limiting the output
191 to only selected information. Everything is shown by default.
192 Setting mode to 'f' will output only 5 minute resolution en‐
193 tries, 'h' hours, 'd' days, 'm' months, 'y' years and 't' the
194 top days. Alternatively or in combination with mode an optional
195 limit parameter can be used to limit the number of entries in
196 the output. The --json option can be used in combination with
197 -l, --live and -tr options without mode or limit having any ef‐
198 fect to the output. The jsonversion field in the output contains
199 the API version information. It will be changed only when the
200 names or structures of previously existing content gets changed.
201 In comparison, the vnstatversion field exists only as extra in‐
202 formation.
203 --limit limit
206 Set the maximum number of shown entries in list outputs to
207 limit. Usage of --limit overrides the default list entry limit
208 values and the optional limit parameter given directly for a
209 list query. All entries stored in the database will be shown if
210 limit is set to 0. --limit can also be used to control the
211 length of --json and --xml outputs.
212 -l, --live [mode]
215 Display current transfer rate for the selected interface in real
216 time until interrupted. Statistics will be shown after interrup‐
217 tion if the runtime was more than 10 seconds. An optional mode
218 parameter can be used to select between the displaying of pack‐
219 ets per second (mode 0) and transfer counters (mode 1) during
220 execution. --style can also be used to affect the layout of the
221 output. The output will be in json format if used in combination
222 with --json option.
223 --locale locale
226 Use locale instead of using the locale setting specified in the
227 configuration file or the system default if no configuration
228 file is available.
229 --longhelp
232 Show complete options list.
233 -m, --months [limit]
236 Show traffic statistics on a monthly basis for the last months.
237 The length of the list will be limited to 12 entries unless con‐
238 figured otherwise or unless the optional limit parameter is
239 used. All entries stored in the database will be shown if limit
240 is set to 0.
241 --oneline [mode]
244 Show traffic summary for selected interface using one line with
245 a parsable format. The output contains 15 fields with ; used as
246 field delimiter. The 1st field contains the API version informa‐
247 tion of the output that will only be changed in future versions
248 if the field content or structure changes. The following fields
249 in order 2) interface name, 3) timestamp for today, 4) rx for
250 today, 5) tx for today, 6) total for today, 7) average traffic
251 rate for today, 8) timestamp for current month, 9) rx for cur‐
252 rent month, 10) tx for current month, 11) total for current
253 month, 12) average traffic rate for current month, 13) all time
254 total rx, 14) all time total tx, 15) all time total traffic. An
255 optional mode parameter can be used to force all fields to out‐
256 put in bytes without the unit itself shown.
257 -q, --query
260 Force database query mode.
261 --remove
264 Delete the database entry for the interface specified with -i or
265 --iface and stop monitoring it. The daemon can be running during
266 this operation and will automatically detect the change.
267 --rename name
270 Rename the interface specified with -i or --iface in the data‐
271 base with new name name. The new name cannot already exist in
272 the database. This operation doesn't cause any data loss. The
273 daemon should not be running during this operation.
274 -ru, --rateunit [mode]
277 Swap the configured rate unit. If rate has been configured to be
278 shown in bytes then rate will be shown in bits if this option is
279 present. In the same way, if rate has been configured to be
280 shown in bits then rate will be shown in bytes when this option
281 is present. Alternatively, mode with either 0 or 1 can be used
282 as parameter for this option in order to select between bytes
283 (0) and bits (1) regardless of the configuration file setting.
284 --setalias alias
287 Set alias as an alias for the selected interface to be shown in
288 queries. The set alias can be removed by specifying an empty
289 string for alias. The daemon can be running during this opera‐
290 tion.
291 -s, --short
294 Use short output mode. This mode is also used when more than one
295 interface is available in the database and no specific interface
296 is selected.
297 --showconfig
300 Show current configuration using the same format as the configu‐
301 ration file itself uses.
302 --style number
305 Modify the content and style of outputs. Set number to 0 for a
306 narrower output, 1 for enabling bar column, 2 for same as previ‐
307 ous but with average traffic rate visible in summary output and
308 3 for enabling average traffic rate in all outputs where it is
309 supported. 4 disables the use of terminal control characters in
310 -l / --live mode.
311 -t, --top [limit]
314 Show all time top traffic days. The length of the list will be
315 limited to 10 entries unless configured otherwise or unless the
316 optional limit parameter is used. All entries stored in the
317 database will be shown if limit is set to 0. When used with
318 --begin and optionally with --end, the list will be generated
319 using the daily data instead of separate top entries. The
320 availability of daily data defines the boundaries the date spe‐
321 cific query can access.
322 -tr, --traffic [time]
325 Calculate how much traffic goes through the selected interface
326 during the given time seconds. The time will be 5 seconds if a
327 number parameter isn't specified. The output will be in json
328 format if used in combination with --json option. However, in
329 that case, the countdown before results isn't shown.
330 -v, --version
333 Show current version.
334 --xml [mode] [limit]
337 Show database content for selected interface or all interfaces
338 in xml format. All traffic values in the output are in bytes. An
339 optional mode parameter can be used for limiting the output to
340 only selected information. Everything is shown by default. Set‐
341 ting mode to 'f' will output only 5 minute resolution entries,
342 'h' hours, 'd' days, 'm' months, 'y' years and 't' the top days.
343 Alternatively or in combination with mode an optional limit pa‐
344 rameter can be used to limit the number of entries in the out‐
345 put. The xmlversion field in the output contains the API version
346 information. It will be changed only when the names or struc‐
347 tures of previously existing content gets changed. In compari‐
348 son, the vnstatversion field exists only as extra information.
349 -y, --years [limit]
352 Show traffic statistics on a yearly basis for the last years.
353 The list will show all entries by default unless configured oth‐
354 erwise or unless the optional limit parameter is used. All en‐
355 tries stored in the database will also be shown if limit is set
356 to 0.
357 -?, --help
360 Show a command option summary.
361
364 /var/lib/vnstat/
365 Default database directory.
366 /etc/vnstat.conf
369 Config file that will be used unless $HOME/.vnstatrc exists. See
370 vnstat.conf(5) for more information.
371
374 vnstat Display traffic summary for the default interface or multiple
375 interfaces when more than one is monitored.
376 vnstat -i eth0+eth1+eth3
379 Display traffic summary for a merge of interfaces eth0, eth1 and
380 eth3.
381 vnstat -i eth2 --xml
384 Output all information about interface eth2 in xml format.
385 vnstat --json
388 Output all information of all monitored interfaces in json for‐
389 mat.
390 vnstat -i eth0 --setalias local
393 Give interface eth0 the alias "local". That information will be
394 later visible as a label when eth0 is queried.
395 vnstat -i eth2 --remove
398 Delete database entries for interface eth2 and stop monitoring
399 it.
400
403 Updates need to be executed at least as often as it is possible for the
404 interface to generate enough traffic to overflow the kernel interface
405 traffic counter. Otherwise, it is possible that some traffic won't be
406 seen. With 32-bit interface traffic counters, the maximum time between
407 two updates depends on how fast the interface can transfer 4 GiB. Note
408 that there is no guarantee that a 64-bit kernel has 64-bit interface
409 traffic counters for all interfaces. Calculated theoretical times are:
410 10 Mbit: 54 minutes
412 100 Mbit: 5 minutes
413 1000 Mbit: 30 seconds
414 Virtual and aliased interfaces cannot be monitored because the kernel
416 doesn't provide traffic information for that type of interfaces. Such
417 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
418 the actual interface being aliased.
419 Using long date output formats may cause misalignment in shown columns
421 if the length of the date exceeds the fixed size allocation.
422
425 Teemu Toivola <tst at iki dot fi>
426
429 vnstatd(8), vnstati(1), vnstat.conf(5), proc(5), ifconfig(8), units(7)
430version 2.9 JANUARY 2022 VNSTAT(1)