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 [limit]] [--dbdir [directory]] [--debug] [--end date]
12 [--fiveminutes [limit]] [--help] [-hg] [--hours [limit]] [--hoursgraph]
13 [-i interface] [--iface interface] [--iflist] [--json [mode] [limit]]
14 [--limit limit] [--live [mode]] [--locale locale] [--longhelp]
15 [--months [limit]] [--oneline [mode]] [--query] [--rateunit [mode]]
16 [--remove] [--rename name] [-ru [mode]] [--setalias alias] [--short]
17 [--showconfig] [--style number] [--top [limit]] [-tr [time]] [--traffic
18 [time]] [--version] [--xml [mode] [limit]] [--years [limit]]
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(8) 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. The daemon can be running during this operation but will
41 not automatically detect the addition without a restart.
42 -b, --begin date
45 Begin the list output with a specific date / time defined by
46 date instead of the begin being selected based on the number of
47 entries to be shown. If date isn't available in the database
48 then the closest later date will be used. date supports the
49 following formats: YYYY-MM-DD HH:MM and YYYY-MM-DD. This option
50 can only be used with --json , --xml and list outputs.
51 --config file
54 Use file as configuration file instead of using automatic con‐
55 figuration file search functionality.
56 -d, --days [limit]
59 Show traffic statistics on a daily basis for the last days. The
60 length of the list will be limited to 30 entries unless config‐
61 ured otherwise or unless the optional limit parameter is used.
62 All entries stored in the database will be shown if limit is set
63 to 0.
64 --dbdir directory
67 Use directory as database directory instead of using the direc‐
68 tory specified in the configuration file or the hardcoded
69 default if no configuration file is available.
70 -D, --debug
73 Show additional debug output.
74 -e, --end date
77 End the list output with a specific date / time defined by date
78 instead of the latest date / time in the database. If date isn't
79 available in the database then the closest earlier date will be
80 used. date supports the following formats: YYYY-MM-DD HH:MM and
81 YYYY-MM-DD. This option can only be used with --json , --xml
82 and list outputs. The top list also requires --begin to be used
83 at the same time with this option.
84 -5, --fiveminutes [limit]
87 Show traffic statistics with a 5 minute resolution for the last
88 hours. The length of the list will be limited to 24 entries
89 unless configured otherwise or unless the optional limit parame‐
90 ter is used. All entries stored in the database will be shown if
91 limit is set to 0.
92 -h, --hours [limit]
95 Show traffic statistics on a hourly basis. The length of the
96 list will be limited to 24 entries unless configured otherwise
97 or unless the optional limit parameter is used. All entries
98 store in the database will be shown if the limit is set to 0.
99 -hg, --hoursgraph
102 Show traffic statistics on a hourly basis for the last 24 hours
103 using a bar graph followed by a table representing the numerical
104 data.
105 -i, --iface interface
108 Select one specific interface and apply actions to only it. For
109 queries, it is possible to merge the information of two or more
110 interfaces using the interface1+interface2+... syntax. All pro‐
111 vided interfaces must be unique and must exist in the database
112 when the merge syntax is used.
113 --iflist
116 Show list of currently available interfaces.
117 --json [mode] [limit]
120 Show database content for selected interface or all interfaces
121 in json format. All traffic values in the output are in bytes.
122 An optional mode parameter can be used for limiting the output
123 to only selected information. Everything is shown by default.
124 Setting mode to 'f' will output only 5 minute resolution
125 entries, 'h' hours, 'd' days, 'm' months, 'y' years and 't' the
126 top days. Alternatively or in combination with mode an optional
127 limit parameter can be used to limit the number of entries in
128 the output. The --json option can be used in combination with
129 -l, --live and -tr options without mode or limit having any
130 effect to the output. The jsonversion field in the output con‐
131 tains the API version information. It will be changed only when
132 the names or structures of previously existing content gets
133 changed. In comparison, the vnstatversion field exists only as
134 extra information.
135 --limit limit
138 Set the maximum number of shown entries in list outputs to
139 limit. Usage of --limit overrides the default list entry limit
140 values and the optional limit parameter given directly for a
141 list query. All entries stored in the database will be shown if
142 limit is set to 0. --limit can also be used to control the
143 length of --json and --xml outputs.
144 -l, --live [mode]
147 Display current transfer rate for the selected interface in real
148 time until interrupted. Statistics will be shown after interrup‐
149 tion if the runtime was more than 10 seconds. An optional mode
150 parameter can be used to select between the displaying of pack‐
151 ets per second (mode 0) and transfer counters (mode 1) during
152 execution. --style can also be used to affect the layout of the
153 output. The output will be in json format if used in combination
154 with --json option.
155 --locale locale
158 Use locale instead of using the locale setting specified in the
159 configuration file or the system default if no configuration
160 file is available.
161 --longhelp
164 Show complete options list.
165 -m, --months [limit]
168 Show traffic statistics on a monthly basis for the last months.
169 The length of the list will be limited to 12 entries unless con‐
170 figured otherwise or unless the optional limit parameter is
171 used. All entries stored in the database will be shown if limit
172 is set to 0.
173 --oneline [mode]
176 Show traffic summary for selected interface using one line with
177 a parsable format. The output contains 15 fields with ; used as
178 field delimiter. The 1st field contains the API version informa‐
179 tion of the output that will only be changed in future versions
180 if the field content or structure changes. The following fields
181 in order 2) interface name, 3) timestamp for today, 4) rx for
182 today, 5) tx for today, 6) total for today, 7) average traffic
183 rate for today, 8) timestamp for current month, 9) rx for cur‐
184 rent month, 10) tx for current month, 11) total for current
185 month, 12) average traffic rate for current month, 13) all time
186 total rx, 14) all time total tx, 15) all time total traffic. An
187 optional mode parameter can be used to force all fields to out‐
188 put in bytes without the unit itself shown.
189 -q, --query
192 Force database query mode.
193 --remove
196 Delete the database entry for the interface specified with -i or
197 --iface and stop monitoring it. The daemon can be running during
198 this operation and will automatically detect the change.
199 --rename name
202 Rename the interface specified with -i or --iface in the data‐
203 base with new name name. The new name cannot already exist in
204 the database. This operation doesn't cause any data loss. The
205 daemon should not be running during this operation.
206 -ru, --rateunit [mode]
209 Swap the configured rate unit. If rate has been configured to be
210 shown in bytes then rate will be shown in bits if this option is
211 present. In the same way, if rate has been configured to be
212 shown in bits then rate will be shown in bytes when this option
213 is present. Alternatively, mode with either 0 or 1 can be used
214 as parameter for this option in order to select between bytes
215 (0) and bits (1) regardless of the configuration file setting.
216 --setalias alias
219 Set alias as an alias for the selected interface to be shown in
220 queries. The set alias can be removed by specifying an empty
221 string for alias. The daemon can be running during this opera‐
222 tion.
223 -s, --short
226 Use short output mode. This mode is also used when more than one
227 interface is available in the database and no specific interface
228 is selected.
229 --showconfig
232 Show current configuration using the same format as the configu‐
233 ration file itself uses.
234 --style number
237 Modify the content and style of outputs. Set number to 0 for a
238 narrower output, 1 for enabling bar column, 2 for same as previ‐
239 ous but with average traffic rate visible in summary output and
240 3 for enabling average traffic rate in all outputs where it is
241 supported. 4 disables the use of terminal control characters in
242 -l / --live mode.
243 -t, --top [limit]
246 Show all time top traffic days. The length of the list will be
247 limited to 10 entries unless configured otherwise or unless the
248 optional limit parameter is used. All entries stored in the
249 database will be shown if limit is set to 0. When used with
250 --begin and optionally with --end, the list will be generated
251 using the daily data instead of separate top entries. The
252 availability of daily data defines the boundaries the date spe‐
253 cific query can access.
254 -tr, --traffic [time]
257 Calculate how much traffic goes through the selected interface
258 during the given time seconds. The time will be 5 seconds if a
259 number parameter isn't specified. The output will be in json
260 format if used in combination with --json option. However, in
261 that case, the countdown before results isn't shown.
262 -v, --version
265 Show current version.
266 --xml [mode] [limit]
269 Show database content for selected interface or all interfaces
270 in xml format. All traffic values in the output are in bytes. An
271 optional mode parameter can be used for limiting the output to
272 only selected information. Everything is shown by default. Set‐
273 ting mode to 'f' will output only 5 minute resolution entries,
274 'h' hours, 'd' days, 'm' months, 'y' years and 't' the top days.
275 Alternatively or in combination with mode an optional limit
276 parameter can be used to limit the number of entries in the out‐
277 put. The xmlversion field in the output contains the API version
278 information. It will be changed only when the names or struc‐
279 tures of previously existing content gets changed. In compari‐
280 son, the vnstatversion field exists only as extra information.
281 -y, --years [limit]
284 Show traffic statistics on a yearly basis for the last years.
285 The list will show all entries by default unless configured oth‐
286 erwise or unless the optional limit parameter is used. All
287 entries stored in the database will also be shown if limit is
288 set to 0.
289 -?, --help
292 Show a command option summary.
293
296 /var/lib/vnstat/
297 Default database directory.
298 /etc/vnstat.conf
301 Config file that will be used unless $HOME/.vnstatrc exists. See
302 vnstat.conf(5) for more information.
303
306 vnstat Display traffic summary for the default interface or multiple
307 interfaces when more than one is monitored.
308 vnstat -i eth0+eth1+eth3
311 Display traffic summary for a merge of interfaces eth0, eth1 and
312 eth3.
313 vnstat -i eth2 --xml
316 Output all information about interface eth2 in xml format.
317 vnstat --json
320 Output all information of all monitored interfaces in json for‐
321 mat.
322 vnstat -i eth0 --setalias local
325 Give interface eth0 the alias "local". That information will be
326 later visible as a label when eth0 is queried.
327 vnstat -i eth2 --remove
330 Delete database entries for interface eth2 and stop monitoring
331 it.
332
335 Updates need to be executed at least as often as it is possible for the
336 interface to generate enough traffic to overflow the kernel interface
337 traffic counter. Otherwise, it is possible that some traffic won't be
338 seen. With 32-bit kernels, the maximum time between two updates depends
339 on how fast the interface can transfer 4 GiB. Calculated theoretical
340 times are:
341 10 Mbit: 54 minutes
343 100 Mbit: 5 minutes
344 1000 Mbit: 30 seconds
345 However, for 1000 Mbit interfaces updating once every minute is usually
347 a usable solution if a shorter update interval can't be used.
348 Virtual and aliased interfaces cannot be monitored because the kernel
350 doesn't provide traffic information for that type of interfaces. Such
351 interfaces are usually named eth0:0, eth0:1, eth0:2 etc. where eth0 is
352 the actual interface being aliased.
353 Using long date output formats may cause misalignment in shown columns
355 if the length of the date exceeds the fixed size allocation.
356
359 Teemu Toivola <tst at iki dot fi>
360
363 vnstatd(8), vnstati(1), vnstat.conf(5), proc(5), ifconfig(8), units(7)
364version 2.6 JANUARY 2020 VNSTAT(1)