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. If --config is used multi‐
108 ple times, the configuration settings from files later on the
109 command line will override configuration settings loaded from
110 earlier files if the settings defined in the files overlap.
111 -d, --days [limit]
114 Show traffic statistics on a daily basis for the last days. The
115 length of the list will be limited to 30 entries unless config‐
116 ured otherwise or unless the optional limit parameter is used.
117 All entries stored in the database will be shown if limit is set
118 to 0.
119 --dbdir directory
122 Use directory as database directory instead of using the direc‐
123 tory specified in the configuration file or the hardcoded de‐
124 fault if no configuration file is available.
125 --dbiflist [mode]
128 List interfaces currently in the database. If mode is not de‐
129 fined or is set to 0 then the output will use a one line verbose
130 format. If mode is set to 1 then the output will contain one in‐
131 terface per line. See also --iflist.
132 -D, --debug
135 Show additional debug output.
136 -e, --end date
139 End the list output with a specific date / time defined by date
140 instead of the latest date / time in the database. If date isn't
141 available in the database then the closest earlier date will be
142 used. date supports the following formats: YYYY-MM-DD HH:MM and
143 YYYY-MM-DD. This option can only be used with --json , --xml
144 and list outputs. The top list also requires --begin to be used
145 at the same time with this option.
146 -5, --fiveminutes [limit]
149 Show traffic statistics with a 5 minute resolution for the last
150 hours. The length of the list will be limited to 24 entries un‐
151 less configured otherwise or unless the optional limit parameter
152 is used. All entries stored in the database will be shown if
153 limit is set to 0.
154 -h, --hours [limit]
157 Show traffic statistics on a hourly basis. The length of the
158 list will be limited to 24 entries unless configured otherwise
159 or unless the optional limit parameter is used. All entries
160 store in the database will be shown if the limit is set to 0.
161 -hg, --hoursgraph
164 Show traffic statistics on a hourly basis for the last 24 hours
165 using a bar graph followed by a table representing the numerical
166 data.
167 -i, --iface interface
170 Select one specific interface and apply actions to only it. For
171 database queries, it is possible to merge the information of two
172 or more interfaces using the interface1+interface2+... syntax.
173 All provided interfaces must be unique and must exist in the
174 database when the merge syntax is used. Optionally, depending on
175 the InterfaceMatchMethod configuration setting, interface can be
176 replaced with alias previously set using --setalias. Merge syn‐
177 tax isn't supported when alias is used. The -i, --iface option
178 is optional and interface can be used as parameter on the com‐
179 mand line for selecting the used interface even without the op‐
180 tion being explicitly used.
181 --iflist [mode]
184 List currently available interfaces. If mode is not defined or
185 is set to 0 then the output will use a one line verbose format.
186 If mode is set to 1 then the output will contain one interface
187 per line. See also --dbiflist.
188 --json [mode] [limit]
191 Show database content for selected interface or all interfaces
192 in json format. All traffic values in the output are in bytes.
193 An optional mode parameter can be used for limiting the output
194 to only selected information. Everything is shown by default.
195 Setting mode to 's' will output a summary containing the last 2
196 entries of 5 minute, hourly, daily, monthly and yearly resolu‐
197 tion data, 'f' will output only 5 minute resolution entries, 'h'
198 hours, 'd' days, 'm' months, 'y' years and 't' the top days. Al‐
199 ternatively or in combination with mode an optional limit param‐
200 eter can be used to limit the number of entries in the output.
201 The --json option can be used in combination with -l, --live and
202 -tr options without mode or limit having any effect to the out‐
203 put. The jsonversion field in the output contains the API ver‐
204 sion information. It will be changed only when the names or
205 structures of previously existing content gets changed. In com‐
206 parison, the vnstatversion field exists only as extra informa‐
207 tion.
208 --limit limit
211 Set the maximum number of shown entries in list outputs to
212 limit. Usage of --limit overrides the default list entry limit
213 values and the optional limit parameter given directly for a
214 list query. All entries stored in the database will be shown if
215 limit is set to 0. --limit can also be used to control the
216 length of --json and --xml outputs.
217 -l, --live [mode]
220 Display current transfer rate for the selected interface in real
221 time until interrupted. Statistics will be shown after interrup‐
222 tion if the runtime was more than 10 seconds. An optional mode
223 parameter can be used to select between the displaying of pack‐
224 ets per second (mode 0) and transfer counters (mode 1) during
225 execution. --style can also be used to affect the layout of the
226 output. The output will be in json format if used in combination
227 with --json option.
228 --locale locale
231 Use locale instead of using the locale setting specified in the
232 configuration file or the system default if no configuration
233 file is available.
234 --longhelp
237 Show complete options list.
238 -m, --months [limit]
241 Show traffic statistics on a monthly basis for the last months.
242 The length of the list will be limited to 12 entries unless con‐
243 figured otherwise or unless the optional limit parameter is
244 used. All entries stored in the database will be shown if limit
245 is set to 0.
246 --oneline [mode]
249 Show traffic summary for selected interface using one line with
250 a parsable format. The output contains 15 fields with ; used as
251 field delimiter. The 1st field contains the API version informa‐
252 tion of the output that will only be changed in future versions
253 if the field content or structure changes. The following fields
254 in order 2) interface name, 3) timestamp for today, 4) rx for
255 today, 5) tx for today, 6) total for today, 7) average traffic
256 rate for today, 8) timestamp for current month, 9) rx for cur‐
257 rent month, 10) tx for current month, 11) total for current
258 month, 12) average traffic rate for current month, 13) all time
259 total rx, 14) all time total tx, 15) all time total traffic. An
260 optional mode parameter can be used to force all fields to out‐
261 put in bytes without the unit itself shown.
262 -q, --query
265 Force database query mode.
266 --remove
269 Delete the database entry for the interface specified with -i or
270 --iface and stop monitoring it. The daemon can be running during
271 this operation and will automatically detect the change.
272 --rename name
275 Rename the interface specified with -i or --iface in the data‐
276 base with new name name. The new name cannot already exist in
277 the database. This operation doesn't cause any data loss. The
278 daemon should not be running during this operation.
279 -ru, --rateunit [mode]
282 Swap the configured rate unit. If rate has been configured to be
283 shown in bytes then rate will be shown in bits if this option is
284 present. In the same way, if rate has been configured to be
285 shown in bits then rate will be shown in bytes when this option
286 is present. Alternatively, mode with either 0 or 1 can be used
287 as parameter for this option in order to select between bytes
288 (0) and bits (1) regardless of the configuration file setting.
289 --setalias alias
292 Set alias as an alias for the selected interface to be shown in
293 queries. The set alias can be removed by specifying an empty
294 string for alias. The daemon can be running during this opera‐
295 tion.
296 -s, --short
299 Use short output mode. This mode is also used when more than one
300 interface is available in the database and no specific interface
301 is selected.
302 --showconfig
305 Show current configuration using the same format as the configu‐
306 ration file itself uses.
307 --style number
310 Modify the content and style of outputs. Set number to 0 for a
311 narrower output, 1 for enabling bar column, 2 for same as previ‐
312 ous but with average traffic rate visible in summary output and
313 3 for enabling average traffic rate in all outputs where it is
314 supported. 4 disables the use of terminal control characters in
315 -l, --live and -tr, --traffic modes.
316 -t, --top [limit]
319 Show all time top traffic days. The length of the list will be
320 limited to 10 entries unless configured otherwise or unless the
321 optional limit parameter is used. All entries stored in the
322 database will be shown if limit is set to 0. When used with
323 --begin and optionally with --end, the list will be generated
324 using the daily data instead of separate top entries. The
325 availability of daily data defines the boundaries the date spe‐
326 cific query can access.
327 -tr, --traffic [time]
330 Calculate how much traffic goes through the selected interface
331 during the given time seconds. The time will be 5 seconds if a
332 number parameter isn't specified. The output will be in json
333 format if used in combination with --json option. However, in
334 that case, the countdown before results isn't shown. --style
335 can also be used to affect the layout of the output.
336 -v, --version
339 Show current version.
340 --xml [mode] [limit]
343 Show database content for selected interface or all interfaces
344 in xml format. All traffic values in the output are in bytes. An
345 optional mode parameter can be used for limiting the output to
346 only selected information. Everything is shown by default. Set‐
347 ting mode to 's' will output a summary containing the last 2 en‐
348 tries of 5 minute, hourly, daily, monthly and yearly resolution
349 data, 'f' will output only 5 minute resolution entries, 'h'
350 hours, 'd' days, 'm' months, 'y' years and 't' the top days. Al‐
351 ternatively or in combination with mode an optional limit param‐
352 eter can be used to limit the number of entries in the output.
353 The xmlversion field in the output contains the API version in‐
354 formation. It will be changed only when the names or structures
355 of previously existing content gets changed. In comparison, the
356 vnstatversion field exists only as extra information.
357 -y, --years [limit]
360 Show traffic statistics on a yearly basis for the last years.
361 The list will show all entries by default unless configured oth‐
362 erwise or unless the optional limit parameter is used. All en‐
363 tries stored in the database will also be shown if limit is set
364 to 0.
365 -?, --help
368 Show a command option summary.
369
372 /var/lib/vnstat/
373 Default database directory.
374 /etc/vnstat.conf
377 Config file that will be used unless $HOME/.vnstatrc exists. See
378 vnstat.conf(5) for more information.
379
382 vnstat Display traffic summary for the default interface or multiple
383 interfaces when more than one is monitored.
384 vnstat -i eth0+eth1+eth3
387 Display traffic summary for a merge of interfaces eth0, eth1 and
388 eth3.
389 vnstat -i eth2 --xml
392 Output all information about interface eth2 in xml format.
393 vnstat --json
396 Output all information of all monitored interfaces in json for‐
397 mat.
398 vnstat -i eth0 --setalias local
401 Give interface eth0 the alias "local". That information will be
402 later visible as a label when eth0 is queried.
403 vnstat -i eth2 --remove
406 Delete database entries for interface eth2 and stop monitoring
407 it.
408
411 Updates need to be executed at least as often as it is possible for the
412 interface to generate enough traffic to overflow the kernel interface
413 traffic counter. Otherwise, it is possible that some traffic won't be
414 seen. With 32-bit interface traffic counters, the maximum time between
415 two updates depends on how fast the interface can transfer 4 GiB. Note
416 that there is no guarantee that a 64-bit kernel has 64-bit interface
417 traffic counters for all interfaces. Calculated theoretical times are:
418 10 Mbit: 54 minutes
420 100 Mbit: 5 minutes
421 1000 Mbit: 30 seconds
422 Virtual and aliased interfaces cannot be monitored because the kernel
424 doesn't provide traffic information for that type of interfaces. Such
425 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
426 the actual interface being aliased.
427 Using long date output formats may cause misalignment in shown columns
429 if the length of the date exceeds the fixed size allocation.
430
433 Teemu Toivola <tst at iki dot fi>
434
437 vnstatd(8), vnstati(1), vnstat.conf(5), proc(5), ifconfig(8), units(7)
438version 2.10 OCTOBER 2022 VNSTAT(1)