1 '\" te
2 .\"
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .\"
12 .\"
13 .\" Copyright 2015 William Dowling <wmdowling@gmail.com>
14 .\"
15 .TH FLOWSTAT 1M "Nov 12, 2015"
16 .SH NAME
17 flowstat \- display bandwidth statistics for a single flow, or all flows,
18 on a link created by \fBflowadm\fR(1M)
19 .SH SYNOPSIS
20 .LP
21 .nf
22 \fBflowstat [\fB-r\fR | \fB-t\fR] [\fB-i\fR \fIinterval\fR]] [\fB-l\fR \fIlink\fR] [\fIflow\fR]
23 .fi
24
25 .LP
26 .nf
27 \fBflowstat [\fB-p\fR | \fB-u\fR \fIR|K|M|G|T|P\fR] [\fB-o\fR \fIfield[,...]\fR] [\fB-l\fR \fIlink\fR] [\fIflow\fR]
28 .fi
29
30 .LP
31 .nf
32 \fBflowstat [\fB-A\fR] [\fB-l\fR \fIlink\fR] [\fIflow\fR]
33 .fi
34
35 .LP
36 .nf
37 \fBflowstat [\fB-S\fR] [\fB-i\fR \fIinterval\fR] [\fB-l\fR \fIlink\fR] [\fIflow\fR]
38 .fi
39
40 .LP
41 .nf
42 \fBflowstat -h\fR [\fB-a\fR] [\fB-d\fR] [\fB-F\fR \fIformat\fR] [\fB-s\fR \fI<DD/MM/YYYY,HH:MM:SS>\fR]
43 [\fB-e\fR \fI<DD/MM/YYYY,HH:MM:SS>\fR] [\fB-f\fR \fI<logfile>\fR] [\fIflow\fR]
44 .fi
45
46 .SH DESCRIPTION
47 .sp
48 .LP
49 The \fBflowstat\fR command displays bandwidth statistics on flows created using
50 \fBflowadm\fR(1M). This information includes packets received and transmitted,
51 bytes received and transmitted, and errors received and transmitted.
52 .sp
53
54 .SS "Options"
55 .LP
56 Each \fBflowstat\fR subcommand has its own set of options. However, many of the
57 subcommands have the following as a common option:
58 .sp
59 .ne 2
60 .na
61 [\fB\fB-l\fR \fIlink\fR] [\fIflow\fR\fR]
62 .sp
63 .ad
64 .sp .6
65 .RS 4n
66 \fIlink\fR refers to a physical or virtual interface while \fIflow\fR refers to a network
67 bandwidth resource created using \fBflowadm\fR(1M). If a link is specified without a flow, the data returned
68 will be for all flows active on the link. If a flow is specified without a link, the
69 data will be returned if the flow is found active on any link. \fIflow\fR names
70 must be unique across all active links.
71 .RE
72
73 .SH SUB-COMMANDS
74 .sp
75 .LP
76 The flowstat command may be invoked in the following ways:
77 .sp
78 .ne 2
79 .na
80 \fB\fBflowstat\fR [\fB-?\fR]
81 .ad
82 .sp .6
83 .RS 4n
84 Display a usage message.
85 .RE
86
87 .sp
88 .ne 2
89 .na
90 \fB\fBflowstat\fR [\fB-r\fR | \fB-t\fR] [\fB-i\fR \fIinterval\fR] [\fB-l\fR \fIlink\fR] [\fIflow\fR]
91 .ad
92 .sp .6
93 .RS 4n
94 Display received or transmitted packets on a specified link or flow with an optional
95 interval. If no flow is specified, statistics for all flows will be displayed. Output
96 is sorted in descending order of flow utilization.
97
98 .sp
99 .ne 2
100 .na
101 \fB\fB-r\fR
102 .ad
103 .sp .6
104 .RS 4n
105 Display receive-side packet statistics which includes the amount of packets received,
106 bytes received, and errors encountered.
107 .RE
108
109 .sp
110 .ne 2
111 .na
112 \fB\fB-t\fR
113 .ad
114 .sp .6
115 .RS 4n
116 Display transmit-side packet statistics which includes the amount of packets transmitted,
117 bytes transmitted, and errors encountered.
118 .RE
119
120 .sp
121 .ne 2
122 .na
123 \fB\fB-i \fIinterval\fR
124 .ad
125 .sp .6
126 .RS 4n
127 Specify an interval in seconds to refresh statistics. The default interval is one second.
128 .RE
129
130 .RE
131
132 .sp
133 .ne 2
134 .na
135 \fB\fBflowstat\fR [\fB-p\fR | \fB-u\fR \fIR|K|M|G|T|P\fR] [\fB-o\fR \fIfield[,...]\fR] [\fB-l\fR
136 \fIlink\fR] [\fIflow\fR]\fR
137 .ad
138 .sp .6
139 .RS 4n
140 Display some or all of the flow statistics in a particular format. Note that if \fB-p\fR is specified
141 then \fB-o\fR is required.
142 .sp
143 .ne 2
144 .na
145 \fB\fB-p\fR\fR
146 .ad
147 .sp .6
148 .RS 4n
149 The output is displayed in a machine-parseable format.
150 .RE
151
152 .sp
153 .ne 2
154 .na
155 \fB\fB-u\fR \fIR|K|M|G|T|P\fR
156 .ad
157 .sp .6
158 .RS 4n
159 Display the statistics in a chosen unit. One of (R)aw Numbers, (K)ilobits,
160 (M)egabits, (G)igabits, (T)erabits or (P)etabits.
161 .RE
162
163 .sp
164 .ne 2
165 .na
166 \fB\fB-o\fR \fIfield[,...]\fR
167 .ad
168 .sp .6
169 .RS 4n
170 Display a list of output fields which must be comma separated. Valid fields
171 are listed below.
172 .RE
173
174 .sp .6
175 .RS 4n
176 List of supported RX fields:
177 .RS 4n
178 .in +6
179 .nf
180 .IP \fBflow\fR
181 \The name of the flow that is currently active on
182 a link.
183 .IP \fBrbytes\fR
184 \The total number of bytes received on a flow or
185 a link if a flow is not specified.
186 .IP \fBipkts\fR
187 \The total number of packets received on a flow
188 or a link if a flow is not specified.
189 .IP \fBierrs\fR
190 \The total number of errors seen on the a link
191 or flow while receiving data.
192 .fi
193 .in -6
194 .ad
195 .RE
196
197 .sp .6
198 List of supported TX fields:
199 .RS 4n
200 .in +6
201 .nf
202 .IP \fBflow\fR
203 \The name of the flow that is currently active on
204 a link.
205 .IP \fBobytes\fR
206 \The total number of bytes transmitted on a flow
207 or a link if a flow is not specified.
208 .IP \fBopkts\fR
209 \The total number of packets transmitted on a
210 flow or a link if a flow is not specified.
211 .IP \fBoerrs\fR
212 \The total number of errors seen on a link or
213 flow while transmitting data.
214 .fi
215 .in -6
216 .ad
217 .RE
218 .RE
219
220 .RE
221
222 .sp
223 .ne 2
224 .na
225 \fB\fBflowstat\fR \fB-A\fR [\fB-l\fR \fIlink\fR] [\fIflow\fR\fR]
226 .ad
227 .sp .6
228 .RS 4n
229 Display all statistics for a single flow, or all flows if none is specified.
230 .RE
231
232 .sp
233 .ne 2
234 .RS 4n
235 \fB\fB-A\fR
236 .ad
237 .sp .6
238 .RS 4n
239 Display all statistical information for the flow specified or all flows.
240 .RE
241
242 .RE
243
244 .sp
245 .ne 2
246 .na
247 \fB\fBflowstat\fR \fB-S\fR [\fB-i\fR \fIinterval\fR] [\fB-l\fR \fIlink\fR]
248 [\fIflow\fR\fR]
249 .ad
250 .sp .6
251 .RS 4n
252 Display a continuously updated real-time view of statistics from the link or flow.
253 .sp
254 .ne 2
255 .na
256 \fB\fB-S\fR
257 .ad
258 .sp .6
259 .RS 4n
260 Display updated statistics in a dynamic real-time view of an active link or flow.
261 .RE
262
263 .sp
264 .ne 2
265 .na
266 \fB\fB-i\fR \fIinterval\fR
267 .ad
268 .sp .6
269 .RS 4n
270 Specify an interval in seconds to refresh statistics. The default interval is one
271 second.
272 .RE
273
274 .RE
275
276 .sp
277 .ne 2
278 .na
279 \fB\fBflowstat\fR \fB-h\fR [\fB-a\fR] [\fB-d\fR] [\fB-F\fR \fIformat\fR]
280 [\fB-s\fR \fI<DD/MM/YYYY,HH:MM:SS>\fR]
281 [\fB-e\fR \fI<DD/MM/YYYY,HH:MM:SS>\fR] [\fB-f\fR \fIlogfile\fR] [\fIflow\fR]
282 .ad
283 .sp .6
284 .RS 4n
285 Display historical statistical information for a single flow, or all flows if
286 none is specified.
287 .sp
288 .ne 2
289 .na
290 \fB\fB-h\fR\fR
291 .ad
292 .sp .6
293 .RS 4n
294 Use historical information generated from extended accounting. This option
295 must be used with the \fB-f\fR option to specify the logfile where the historical
296 data is written to. See \fBacctadm\fR(1M) for information on enabling extended
297 accounting.
298 .RE
299
300 .sp
301 .ne 2
302 .na
303 \fB\fB-a\fR\fR
304 .ad
305 .sp .6
306 .RS 4n
307 Displays all historical network usage. The only works once extended
308 accounting is enabled. It includes usage information for the flows that
309 have already been deleted.
310 .RE
311
312 .sp
313 .ne 2
314 .na
315 \fB\fB-d\fR\fR
316 .ad
317 .sp .6
318 .RS 4n
319 Display dates where logging information exists in the format MM/DD/YYYY.
320 .RE
321
322 .sp
323 .ne 2
324 .na
325 \fB\fB-F\fR \fIformat\fR\fR
326 .ad
327 .sp .6
328 .RS 4n
329 Displays the network flow usage in a format specified. The only format
330 currently supported is gnuplot.
331 .RE
332
333 .sp
334 .ne 2
335 .na
336 \fB-s\fR \fIstarttime\fR
337 .ad
338 .sp .6
339 .RS 4n
340 Define the start-time for which to display flow data which is of the format \fIYYYY\fR.\fIMM\fR.\fIDD\fR,\fIhh\fR:\fImm\fR:\fIss\fR.
341 This option must be used with \fB-e\fR.
342 .RE
343
344 .sp
345 .ne 2
346 .na
347 \fB-e\fR \fIendtime\fR\fR
348 .ad
349 .sp .6
350 .RS 4n
351 Define the end-time for which to display flow data which is of the format \fIYYYY\fR.\fIMM\fR.\fIDD\fR,\fIhh\fR:\fImm\fR:\fIss\fR.
352 This option must be used with \fB-s\fR.
353 .RE
354
355 .sp
356 .ne 2
357 .na
358 \fB\fB-f\fR \fIlogfile\fR\fR
359 .ad
360 .sp .6
361 .RS 4n
362 The \fIlogfile\fR contains flow data captured from enabling extended accounting
363 using \fBacctadm\fR(1M).
364 .RE
365
366 .RE
367
368 .SH EXAMPLES
369 .LP
370 \fBExample 1 \fRDisplay received packets on a particular flow
371 .sp
372 .LP
373 The command below displays received packet data for the flow \fBssh-1\fR
374 on the link \fBe1000g0\fR over an interval of 2 seconds.
375
376 .sp
377 .in +2
378 .nf
379 # \fBflowstat -r -i 2 -l e1000g0 ssh-1\fR
380 FLOW IPKTS RBYTES IERRS
381 ssh-1 382 32.10K 0
382 ssh-1 3 202 0
383 .fi
384 .in -2
385 .sp
386
387 .LP
388 \fBExample 2 \fRDisplay all statistics for a particular flow.
389 .sp
390 .LP
391 The following command displays all statistics available for the flow \fBssh-1\fR
392 on the link \fBe1000g0\fR.
393
394 .sp
395 .in +2
396 .nf
397 # \fBflowstat -A -l e1000g0 ssh-1\fR
398 ssh-1
399 ipackets 766
400 rbytes 64474
401 opackets 464
402 obytes 56516
403 .fi
404 .in -2
405 .sp
406
407 .LP
408 \fBExample 3 \fRDisplay historical flow statistics.
409 .sp
410 .LP
411 The following command displays flow statistics captured when using the
412 extended accounting facility \fBacctadm\fR(1M).
413
414 .sp
415 .in +2
416 .nf
417 # \fBflowstat -h -a -s 11/06/2015,16:02:51 -e 11/06/2015,16:04:31 \e
418 -f /var/adm/acct/flowlog.log \fR
419 FLOW START END RBYTES OBYTES BANDWIDTH
420 ssh-1 16:02:51 16:03:11 0 0 0 Mbps
421 ssh-1 16:03:11 16:03:31 0 0 0 Mbps
422 ssh-1 16:03:31 16:03:51 756 876 0 Mbps
423 ssh-1 16:03:51 16:04:11 0 0 0 Mbps
424 ssh-1 16:04:11 16:04:31 5564 3228 0.003 Mbps
425
426 .fi
427 .in -2
428 .sp
429
430 .LP
431 .SH EXIT STATUS
432 .sp
433 .ne 2
434 .na
435 \fB\fB0\fR\fR
436 .ad
437 .sp .6
438 .RS 4n
439 All actions were performed successfully.
440 .RE
441
442 .sp
443 .ne 2
444 .na
445 \fB\fB>0\fR\fR
446 .ad
447 .sp .6
448 .RS 4n
449 An error occurred.
450 .RE
451
452 .SH STABILITY
453 .sp
454 .LP
455 .sp
456 The invocation is committed. The output of the command is
457 Not-an-Interface; however, the machine-parseable output of the command
458 is committed.
459
460 .SH SEE ALSO
461 .sp
462 .LP
463 \fBacctadm\fR(1M), \fBdladm\fR(1M), \fBflowadm\fR(1M), \fBifconfig\fR(1M), \fBprstat\fR(1M),
464 \fBroute\fR(1M), \fBattributes\fR(5), \fBdlpi\fR(7P)