1VNSTATI(1) User Manuals VNSTATI(1)
2
6 vnstati - image output support for vnStat
7
10 vnstati [-5bcdDehiLmosStvy?] [-5g [limit] [height]] [--altdate] [--be‐
11 gin date] [--cache time] [--config file] [--days [limit]] [--dbdir di‐
12 rectory] [--debug] [--end date] [--fivegraph [limit] [height]]
13 [--fiveminutes [limit]] [--headertext text] [--help] [-hg [mode]]
14 [--hours [limit]] [--hoursgraph [mode]] [-hs [graph]] [--hsummary
15 [graph]] [-i interface] [--iface interface] [--large] [--limit limit]
16 [--locale locale] [--months [limit]] [-ne] [-nh] [-nl] [--noedge]
17 [--noheader] [--nolegend] [--output file] [-ru [mode]] [--rateunit
18 [mode]] [--scale percent] [--small] [--style number] [--summary] [--top
19 [limit]] [--transparent [enabled]] [--version] [-vs [graph]] [--vsum‐
20 mary [graph]] [--months [limit]] [interface]
21
24 The purpose of vnstati is to provide image output support for statis‐
25 tics collected using vnstat(1). The available image file formats de‐
26 pend on what is supported by the used GD library. All basic outputs of
27 vnStat are supported excluding live traffic features. The image can be
28 outputted either to a file or to standard output, with the later being
29 limited to png image format.
30
33 --altdate
34 Use alternative date and time text location. The date and time
35 text will be moved from the upper right header section to the
36 lower left corner. This option will have no effect if -nh, --no‐
37 header has been selected.
38 -b, --begin date
41 Begin the list output with a specific date / time defined by
42 date instead of the begin being selected based on the number of
43 entries to be shown. If date isn't available in the database
44 then the closest later date will be used. date supports the
45 following formats: YYYY-MM-DD HH:MM, YYYY-MM-DD and "today".
46 This option can only be used with list outputs.
47 -c, --cache time
50 Update output file only if at least time minutes have passed
51 since the previous file update. This option is ignored if stdout
52 is used as output.
53 --config file
56 Use file as configuration file instead of using automatic con‐
57 figuration file search functionality. If --config is used mul‐
58 tiple times, the configuration settings from files later on the
59 command line will override configuration settings loaded from
60 earlier files if the settings defined in the files overlap.
61 -d, --days [limit]
64 Output traffic statistics on a daily basis for the last days.
65 The length of the list will be limited to 30 entries unless con‐
66 figured otherwise or unless the optional limit parameter is
67 used. All entries stored in the database will be shown if limit
68 is set to 0.
69 --dbdir directory
72 Use directory as database directory instead of using the direc‐
73 tory specified in the configuration file or the hardcoded de‐
74 fault if no configuration file is available.
75 -D, --debug
78 Show additional debug output.
79 -e, --end date
82 End the list output with a specific date / time defined by date
83 instead of the latest date / time in the database. If date isn't
84 available in the database then the closest earlier date will be
85 used. date supports the following formats: YYYY-MM-DD HH:MM and
86 YYYY-MM-DD. This option can only be used with list outputs. The
87 top list also requires --begin to be used at the same time with
88 this option.
89 -5g, --fivegraph [limit] [height]
92 Output traffic statistics with a 5 minute resolution for the
93 last 48 hours using a bar graph. The width of the graph can be
94 modified using the optional limit parameter which represents the
95 number of 5 minute entries with 12 entries for each hour. The
96 smallest supported value is 288 (last 24 hours). Additionally,
97 the height of the graph can be modified using the optional
98 height parameter. The smallest supported height is 150 pixels.
99 -5, --fiveminutes [limit]
102 Output traffic statistics with a 5 minute resolution for the
103 last hours. The length of the list will be limited to 24 en‐
104 tries unless configured otherwise or unless the optional limit
105 parameter is used. All entries stored in the database will be
106 shown if limit is set to 0.
107 --headertext text
110 Show text in image header section instead of automatically gen‐
111 erated interface identification. text is limited to 64 charac‐
112 ters and may not get completely shown if longer than the width
113 of the image. Use with --altdate if maximal space is needed.
114 This option will have no effect if -nh, --noheader has been se‐
115 lected.
116 -h, --hours [limit]
119 Output traffic statistics on a hourly basis. The length of the
120 list will be limited to 24 entries unless configured otherwise
121 or unless the optional limit parameter is used. All entries
122 store in the database will be shown if the limit is set to 0.
123 -hg, --hoursgraph [mode]
126 Output traffic statistics on a hourly basis for the last 24
127 hours using a bar graph. The optional mode parameter can be
128 used to override the configuration file setting. Available
129 modes: 0 = 24 hour sliding window, 1 = graph begins from mid‐
130 night.
131 -hs, --hsummary [graph]
134 Output traffic summary with the graph selected using the Summa‐
135 ryGraph setting in the configuration file next to it using a
136 horizontal layout. The optional graph parameter can be used to
137 override the configuration file setting. Available graphs: 0 =
138 hours, 1 = 5 minutes.
139 -i, --iface interface
142 Use interface instead of default or configured interface. It is
143 also possible to merge the information of two or more interfaces
144 using the interface1+interface2+... syntax. All provided inter‐
145 faces must be unique and must exist in the database when the
146 merge syntax is used. Optionally, depending on the Interface‐
147 MatchMethod configuration setting, interface can be replaced
148 with alias previously set using vnstat --setalias. Merge syntax
149 isn't supported when alias is used. The -i, --iface option is
150 optional and interface can be used as parameter on the command
151 line for selecting the used interface even without the option
152 being explicitly used.
153 -L, --large
157 Use large fonts in output.
158 --limit limit
161 Set the maximum number of shown entries in list outputs to
162 limit. Usage of --limit overrides the default list entry limit
163 values and the optional limit parameter given directly for a
164 list query. All entries stored in the database will be shown if
165 limit is set to 0.
166 --locale locale
169 Use locale instead of using the locale setting specified in the
170 configuration file or the system default if no configuration
171 file is available.
172 -m, --months [limit]
175 Output traffic statistics on a monthly basis for the last
176 months. The length of the list will be limited to 12 entries un‐
177 less configured otherwise or unless the optional limit parameter
178 is used. All entries stored in the database will be shown if
179 limit is set to 0.
180 -ne, --noedge
183 Remove darker edges from around the image.
184 -nh, --noheader
187 Remove header containing title and update time. Time of the pre‐
188 vious update will still be visible in the lower right corner us‐
189 ing a less visible color.
190 -nl, --nolegend
193 Remove legend containing rx and tx color mapping information
194 from the image.
195 -o, --output file
198 Write image to file and exit. The used image format is selected
199 by the given file extension of file. For example, "image.png"
200 results in the file getting written using the png image format
201 due to the ".png" extension having been used. Usage of png image
202 format usually results in the smallest file size without loss of
203 detail or introduction of compression artifacts. Alternatively,
204 output can be directed to stdout by giving "-" as file in which
205 case png image format is used.
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 --scale percent
219 Scale output to given percent resulting in the image being ei‐
220 ther smaller or larger than the default size.
221 -S, --small
224 Use small fonts in output.
225 --style number
228 Modify the content and style of outputs. Setting number to 3
229 will show average traffic rate in all outputs where it is sup‐
230 ported. Other values will show bar graphics instead.
231 -s, --summary
234 Output traffic statistics summary.
235 -t, --top [limit]
238 Output all time top traffic days. The length of the list will be
239 limited to 10 entries unless configured otherwise or unless the
240 optional limit parameter is used. All entries stored in the
241 database will be shown if limit is set to 0. When used with
242 --begin and optionally with --end, the list will be generated
243 using the daily data instead of separate top entries. The
244 availability of daily data defines the boundaries the date spe‐
245 cific query can access.
246 --transparent [enabled]
249 Toggle background color transparency depending of the Transpar‐
250 entBg setting in the configuration file. Alternatively, 0 or 1
251 can be given as parameter enabled for this option in order to
252 either disable (0) or enable (1) transparency regardless of the
253 configuration file setting.
254 -v, --version
257 Show current version.
258 -vs, --vsummary [graph]
261 Output traffic summary with the graph selected using the Summa‐
262 ryGraph setting in the configuration file below it using a ver‐
263 tical layout. The optional graph parameter can be used to over‐
264 ride the configuration file setting. Available graphs: 0 =
265 hours, 1 = 5 minutes.
266 -y, --years [limit]
269 Output traffic statistics on a yearly basis for the last years.
270 The list will show all entries by default unless configured oth‐
271 erwise or unless the optional limit parameter is used. All en‐
272 tries stored in the database will also be shown if limit is set
273 to 0.
274 -?, --help
277 Show a command option summary.
278
281 /var/lib/vnstat/
282 Default database directory.
283 /etc/vnstat.conf
286 Config file that will be used unless $HOME/.vnstatrc exists. See
287 vnstat.conf(5) for more information.
288
291 vnstati -s -i eth0 -o /tmp/vnstat.png
292 Output traffic summary for interface eth0 to file /tmp/vn‐
293 stat.png.
294 vnstati -vs -i eth0+eth1+eth2 -o /tmp/vnstat.png
297 Output traffic summary with hourly data under the normal summary
298 for a merge of interfaces eth0, eth1 and eth2 to file /tmp/vn‐
299 stat.png.
300 vnstati -h -c 15 -o /tmp/vnstat_h.png
303 Output hourly traffic statistics for default interface to file
304 /tmp/vnstat_h.png if the file has not been updated within the
305 last 15 minutes.
306 vnstati -d -ne -nh -o -
309 Output daily traffic statistics without displaying the header
310 section and edges for default interface to standard output (std‐
311 out).
312 vnstati -m --config /home/me/vnstat.cfg -i -o -
315 Output monthly traffic statistics for default interface speci‐
316 fied in configuration file /home/me/vnstat.cfg to standard out‐
317 put (stdout).
318
321 Depending on the built-in fonts provided by the GD library, not all
322 characters may end up shown correctly when a UTF-8 locale is used.
323 Using long date output formats may cause misalignment in shown columns
325 if the length of the date exceeds the fixed size allocation.
326 Scaling an image when background transparency is enabled may not result
328 in transparency being retained.
329
332 Teemu Toivola <tst at iki dot fi>
333
336 vnstat(1), vnstatd(8), vnstat.conf(5), units(7)
337version 2.10 OCTOBER 2022 VNSTATI(1)