1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright (c) 2011, Joyent, Inc. All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH FLOWADM 1M "Feb 14, 2009"
8 .SH NAME
9 flowadm \- administer bandwidth resource control and priority for protocols,
10 services, containers, and virtual machines
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fBflowadm show-flow\fR [\fB-pP\fR] [\fB-S\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] [\fB-l\fR \fIlink\fR]
15 [\fB-o\fR \fIfield\fR[,...]] [\fB-z\fR \fIzonename\fR] [\fIflow\fR]
16 .fi
17
18 .LP
19 .nf
20 \fBflowadm add-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-l\fR \fIlink\fR
21 \fB-a\fR \fIattr\fR=\fIvalue\fR[,...] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIflow\fR
22 \fBflowadm remove-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] {\fB-l\fR \fIlink\fR | \fIflow\fR}
23 .fi
24
25 .LP
26 .nf
27 \fBflowadm set-flowprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIflow\fR
28 \fBflowadm reset-flowprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-p\fR \fIprop\fR[,...]] \fIflow\fR
29 \fBflowadm show-flowprop\fR [\fB-cP\fR] [\fB-l\fR \fIlink\fR] [\fB-o\fR \fIfield\fR[,...]]
30 [\fB-p\fR \fIprop\fR[,...]] [\fIflow\fR]
31 .fi
32
33 .LP
34 .nf
35 \fBflowadm show-usage\fR [\fB-a\fR] [\fB-d\fR | {\fB-p\fR \fIplotfile\fR \fB-F\fR \fIformat\fR}] [\fB-s\fR \fItime\fR]
36 [\fB-e\fR \fItime\fR] \fB-f\fR \fIfilename\fR [\fIflow\fR]
37 .fi
38
39 .SH DESCRIPTION
40 .sp
41 .LP
42 The \fBflowadm\fR command is used to create, modify, remove, and show
43 networking bandwidth and associated resources for a type of traffic on a
44 particular link.
45 .sp
46 .LP
47 The \fBflowadm\fR command allows users to manage networking bandwidth resources
48 for a transport, service, or a subnet. The service is specified as a
49 combination of transport and local port. The subnet is specified by its IP
50 address and subnet mask. The command can be used on any type of data link,
51 including physical links, virtual NICs, and link aggregations.
52 .sp
53 .LP
54 A flow is defined as a set of attributes based on Layer 3 and Layer 4 headers,
55 which can be used to identify a protocol, service, or a virtual machine. When a
56 flow is identified based on flow attributes, separate kernel resources
57 including layer 2, 3, and 4 queues, their processing threads, and other
58 resources are uniquely created for it, such that other traffic has minimal or
59 zero impact on it.
60 .sp
61 .LP
62 Inbound and outbound packet are matched to flows in a very fast and scalable
63 way, so that limits can be enforced with minimal performance impact.
64 .sp
65 .LP
66 The \fBflowadm\fR command can be used to identify a flow without imposing any
67 bandwidth resource control. This would result in the traffic type getting its
68 own resources and queues so that it is isolated from rest of the networking
69 traffic for more observable and deterministic behavior.
70 .sp
71 .LP
72 \fBflowadm\fR is implemented as a set of subcommands with corresponding
73 options. Options are described in the context of each subcommand.
74 .SH SUB-COMMANDS
75 .sp
76 .LP
77 The following subcommands are supported:
78 .sp
79 .ne 2
80 .na
81 \fB\fBflowadm show-flow\fR [\fB-pP\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] [\fB-o\fR \fIfield\fR[,...]] [\fB-l\fR \fIlink\fR] [\fB-z\fR \fIzonename\fR] [\fIflow\fR]\fR
82 .ad
83 .sp .6
84 .RS 4n
85 Show flow configuration information (the default) or statistics, either for all
86 flows, all flows on a link, or for the specified \fIflow\fR.
87 .sp
88 .ne 2
89 .na
90 \fB\fB-o\fR \fIfield\fR[,...]\fR
91 .ad
92 .sp .6
93 .RS 4n
94 A case-insensitive, comma-separated list of output fields to display. The field
95 name must be one of the fields listed below, or a special value \fBall\fR, to
96 display all fields. For each flow found, the following fields can be displayed:
97 .sp
98 .ne 2
99 .na
100 \fB\fBflow\fR\fR
101 .ad
102 .sp .6
103 .RS 4n
104 The name of the flow.
105 .RE
106
107 .sp
108 .ne 2
109 .na
110 \fB\fBlink\fR\fR
111 .ad
112 .sp .6
113 .RS 4n
114 The name of the link the flow is on.
115 .RE
116
117 .sp
118 .ne 2
119 .na
120 \fB\fBipaddr\fR\fR
121 .ad
122 .sp .6
123 .RS 4n
124 IP address of the flow. This can be either local or remote depending on how the
125 flow was defined.
126 .RE
127
128 .sp
129 .ne 2
130 .na
131 \fB\fBtransport\fR\fR
132 .ad
133 .sp .6
134 .RS 4n
135 The name of the layer for protocol to be used.
136 .RE
137
138 .sp
139 .ne 2
140 .na
141 \fB\fBport\fR\fR
142 .ad
143 .sp .6
144 .RS 4n
145 Local port of service for flow.
146 .RE
147
148 .sp
149 .ne 2
150 .na
151 \fB\fBdsfield\fR\fR
152 .ad
153 .sp .6
154 .RS 4n
155 Differentiated services value for flow and mask used with \fBDSFIELD\fR value
156 to state the bits of interest in the differentiated services field of the IP
157 header.
158 .RE
159
160 .RE
161
162 .sp
163 .ne 2
164 .na
165 \fB\fB-p\fR, \fB--parseable\fR\fR
166 .ad
167 .sp .6
168 .RS 4n
169 Display using a stable machine-parseable format.
170 .RE
171
172 .sp
173 .ne 2
174 .na
175 \fB\fB-P\fR, \fB--persistent\fR\fR
176 .ad
177 .sp .6
178 .RS 4n
179 Display persistent flow property information.
180 .RE
181
182 .sp
183 .ne 2
184 .na
185 \fB\fB-S\fR, \fB--continuous\fR\fR
186 .ad
187 .sp .6
188 .RS 4n
189 Continuously display network utilization by flow in a manner similar to the way
190 that \fBprstat\fR(1M) displays CPU utilization by process.
191 .RE
192
193 .sp
194 .ne 2
195 .na
196 \fB\fB-s\fR, \fB--statistics\fR\fR
197 .ad
198 .sp .6
199 .RS 4n
200 Displays flow statistics.
201 .RE
202
203 .sp
204 .ne 2
205 .na
206 \fB\fB-i\fR \fIinterval\fR, \fB--interval\fR=\fIinterval\fR\fR
207 .ad
208 .sp .6
209 .RS 4n
210 Used with the \fB-s\fR option to specify an interval, in seconds, at which
211 statistics should be displayed. If this option is not specified, statistics are
212 displayed once.
213 .RE
214
215 .sp
216 .ne 2
217 .na
218 \fB\fB-l\fR \fIlink\fR, \fB--link\fR=\fIlink\fR | \fIflow\fR\fR
219 .ad
220 .sp .6
221 .RS 4n
222 Display information for all flows on the named link or information for the
223 named flow.
224 .RE
225
226 .sp
227 .ne 2
228 .na
229 \fB\fB-z\fR \fIzonename\fR
230 .ad
231 .sp .6
232 .RS 4n
233 Operate on a link that has been delegated to the specified zone.
234 .RE
235
236 .RE
237
238 .sp
239 .ne 2
240 .na
241 \fB\fBflowadm add-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-l\fR \fIlink\fR \fB-a\fR \fIattr\fR=\fIvalue\fR[,...] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIflow\fR\fR
242 .ad
243 .sp .6
244 .RS 4n
245 Adds a flow to the system. The flow is identified by its flow attributes and
246 properties.
247 .sp
248 As part of identifying a particular flow, its bandwidth resource can be limited
249 and its relative priority to other traffic can be specified. If no bandwidth
250 limit or priority is specified, the traffic still gets its unique layer 2, 3,
251 and 4 queues and processing threads, including NIC hardware resources (when
252 supported), so that the selected traffic can be separated from others and can
253 flow with minimal impact from other traffic.
254 .sp
255 .ne 2
256 .na
257 \fB\fB-t\fR, \fB--temporary\fR\fR
258 .ad
259 .sp .6
260 .RS 4n
261 The changes are temporary and will not persist across reboots. Persistence is
262 the default.
263 .RE
264
265 .sp
266 .ne 2
267 .na
268 \fB\fB-R\fR \fIroot-dir\fR, \fB--root-dir\fR=\fIroot-dir\fR\fR
269 .ad
270 .sp .6
271 .RS 4n
272 Specifies an alternate root directory where \fBflowadm\fR should apply
273 persistent creation.
274 .RE
275
276 .sp
277 .ne 2
278 .na
279 \fB\fB-z\fR \fIzonename\fR
280 .ad
281 .sp .6
282 .RS 4n
283 Operate on a link that has been delegated to the specified zone.
284 .RE
285
286 .sp
287 .ne 2
288 .na
289 \fB\fB-l\fR \fIlink\fR, \fB--link\fR=\fIlink\fR\fR
290 .ad
291 .sp .6
292 .RS 4n
293 Specify the link to which the flow will be added.
294 .RE
295
296 .sp
297 .ne 2
298 .na
299 \fB\fB-a\fR \fIattr\fR=\fIvalue\fR[,...], \fB--attr\fR=\fIvalue\fR\fR
300 .ad
301 .sp .6
302 .RS 4n
303 A comma-separated list of attributes to be set to the specified values.
304 .RE
305
306 .sp
307 .ne 2
308 .na
309 \fB\fB-p\fR \fIprop\fR=\fIvalue\fR[,...], \fB--prop\fR=\fIvalue\fR[,...]\fR
310 .ad
311 .sp .6
312 .RS 4n
313 A comma-separated list of properties to be set to the specified values.
314 .RE
315
316 .RE
317
318 .sp
319 .ne 2
320 .na
321 \fB\fBflowadm remove-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-l\fR {\fIlink\fR | \fIflow\fR}\fR
322 .ad
323 .sp .6
324 .RS 4n
325 Remove an existing flow identified by its link or name.
326 .sp
327 .ne 2
328 .na
329 \fB\fB-t\fR, \fB--temporary\fR\fR
330 .ad
331 .sp .6
332 .RS 4n
333 The changes are temporary and will not persist across reboots. Persistence is
334 the default.
335 .RE
336
337 .sp
338 .ne 2
339 .na
340 \fB\fB-R\fR \fIroot-dir\fR, \fB--root-dir\fR=\fIroot-dir\fR\fR
341 .ad
342 .sp .6
343 .RS 4n
344 Specifies an alternate root directory where \fBflowadm\fR should apply
345 persistent removal.
346 .RE
347
348 .sp
349 .ne 2
350 .na
351 \fB\fB-z\fR \fIzonename\fR
352 .ad
353 .sp .6
354 .RS 4n
355 Operate on a link that has been delegated to the specified zone.
356 .RE
357
358 .sp
359 .ne 2
360 .na
361 \fB\fB-l\fR \fIlink\fR | \fIflow\fR, \fB--link\fR=\fIlink\fR | \fIflow\fR\fR
362 .ad
363 .sp .6
364 .RS 4n
365 If a link is specified, remove all flows from that link. If a single flow is
366 specified, remove only that flow.
367 .RE
368
369 .RE
370
371 .sp
372 .ne 2
373 .na
374 \fB\fBflowadm set-flowprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-p\fR
375 \fIprop\fR=\fIvalue\fR[,...] \fIflow\fR\fR
376 .ad
377 .sp .6
378 .RS 4n
379 Set values of one or more properties on the flow specified by name. The
380 complete list of properties can be retrieved using the \fBshow-flow\fR
381 subcommand.
382 .sp
383 .ne 2
384 .na
385 \fB\fB-t\fR, \fB--temporary\fR\fR
386 .ad
387 .sp .6
388 .RS 4n
389 The changes are temporary and will not persist across reboots. Persistence is
390 the default.
391 .RE
392
393 .sp
394 .ne 2
395 .na
396 \fB\fB-R\fR \fIroot-dir\fR, \fB--root-dir\fR=\fIroot-dir\fR\fR
397 .ad
398 .sp .6
399 .RS 4n
400 Specifies an alternate root directory where \fBflowadm\fR should apply
401 persistent setting of properties.
402 .RE
403
404 .sp
405 .ne 2
406 .na
407 \fB\fB-p\fR \fIprop\fR=\fIvalue\fR[,...], \fB--prop\fR=\fIvalue\fR[,...]\fR
408 .ad
409 .sp .6
410 .RS 4n
411 A comma-separated list of properties to be set to the specified values.
412 .RE
413
414 .RE
415
416 .sp
417 .ne 2
418 .na
419 \fB\fBflowadm reset-flowprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-p\fR
420 [\fIprop\fR=\fIvalue\fR[,...]] \fIflow\fR\fR
421 .ad
422 .sp .6
423 .RS 4n
424 Resets one or more properties to their default values on the specified flow. If
425 no properties are specified, all properties are reset. See the
426 \fBshow-flowprop\fR subcommand for a description of properties, which includes
427 their default values.
428 .sp
429 .ne 2
430 .na
431 \fB\fB-t\fR, \fB--temporary\fR\fR
432 .ad
433 .sp .6
434 .RS 4n
435 Specifies that the resets are temporary. Temporary resets last until the next
436 reboot.
437 .RE
438
439 .sp
440 .ne 2
441 .na
442 \fB\fB-R\fR \fIroot-dir\fR, \fB--root-dir\fR=\fIroot-dir\fR\fR
443 .ad
444 .sp .6
445 .RS 4n
446 Specifies an alternate root directory where \fBflowadm\fR should apply
447 persistent setting of properties.
448 .RE
449
450 .sp
451 .ne 2
452 .na
453 \fB\fB-p\fR \fIprop\fR=\fIvalue\fR[,...], \fB--prop\fR=\fIvalue\fR[,...]\fR
454 .ad
455 .sp .6
456 .RS 4n
457 A comma-separated list of properties to be reset.
458 .RE
459
460 .RE
461
462 .sp
463 .ne 2
464 .na
465 \fB\fBflowadm show-flowprop\fR [\fB-cP\fR] [\fB-l\fR \fIlink\fR] [\fB-p\fR
466 \fIprop\fR[,...]] [\fIflow\fR]\fR
467 .ad
468 .sp .6
469 .RS 4n
470 Show the current or persistent values of one or more properties, either for all
471 flows, flows on a specified link, or for the specified flow.
472 .sp
473 By default, current values are shown. If no properties are specified, all
474 available flow properties are displayed. For each property, the following
475 fields are displayed:
476 .sp
477 .ne 2
478 .na
479 \fB\fBFLOW\fR\fR
480 .ad
481 .sp .6
482 .RS 4n
483 The name of the flow.
484 .RE
485
486 .sp
487 .ne 2
488 .na
489 \fB\fBPROPERTY\fR\fR
490 .ad
491 .sp .6
492 .RS 4n
493 The name of the property.
494 .RE
495
496 .sp
497 .ne 2
498 .na
499 \fB\fBVALUE\fR\fR
500 .ad
501 .sp .6
502 .RS 4n
503 The current (or persistent) property value. The value is shown as \fB--\fR
504 (double hyphen), if it is not set, and \fB?\fR (question mark), if the value is
505 unknown. Persistent values that are not set or have been reset will be shown as
506 \fB--\fR and will use the system \fBDEFAULT\fR value (if any).
507 .RE
508
509 .sp
510 .ne 2
511 .na
512 \fB\fBDEFAULT\fR\fR
513 .ad
514 .sp .6
515 .RS 4n
516 The default value of the property. If the property has no default value,
517 \fB--\fR (double hyphen), is shown.
518 .RE
519
520 .sp
521 .ne 2
522 .na
523 \fB\fBPOSSIBLE\fR\fR
524 .ad
525 .sp .6
526 .RS 4n
527 A comma-separated list of the values the property can have. If the values span
528 a numeric range, the minimum and maximum values might be shown as shorthand. If
529 the possible values are unknown or unbounded, \fB--\fR (double hyphen), is
530 shown.
531 .RE
532
533 Flow properties are documented in the "Flow Properties" section, below.
534 .sp
535 .ne 2
536 .na
537 \fB\fB-c\fR, \fB--parseable\fR\fR
538 .ad
539 .sp .6
540 .RS 4n
541 Display using a stable machine-parseable format.
542 .RE
543
544 .sp
545 .ne 2
546 .na
547 \fB\fB-P\fR, \fB--persistent\fR\fR
548 .ad
549 .sp .6
550 .RS 4n
551 Display persistent flow property information.
552 .RE
553
554 .sp
555 .ne 2
556 .na
557 \fB\fB-p\fR \fIprop\fR[,...], \fB--prop\fR=\fIprop\fR[,...]\fR
558 .ad
559 .sp .6
560 .RS 4n
561 A comma-separated list of properties to show.
562 .RE
563
564 .RE
565
566 .sp
567 .ne 2
568 .na
569 \fB\fBflowadm show-usage\fR [\fB-a\fR] [\fB-d\fR | {\fB-p\fR \fIplotfile\fR
570 \fB-F\fR \fIformat\fR}] [\fB-s\fR \fItime\fR] [\fB-e\fR \fItime\fR]
571 [\fIflow\fR]\fR
572 .ad
573 .sp .6
574 .RS 4n
575 Show the historical network flow usage from a stored extended accounting file.
576 Configuration and enabling of network accounting through \fBacctadm\fR(1M) is
577 required. The default output will be the summary of flow usage for the entire
578 period of time in which extended accounting was enabled.
579 .sp
580 .ne 2
581 .na
582 \fB\fB-a\fR\fR
583 .ad
584 .sp .6
585 .RS 4n
586 Display all historical network usage for the specified period of time during
587 which extended accounting is enabled. This includes the usage information for
588 the flows that have already been deleted.
589 .RE
590
591 .sp
592 .ne 2
593 .na
594 \fB\fB-d\fR\fR
595 .ad
596 .sp .6
597 .RS 4n
598 Display the dates for which there is logging information. The date is in the
599 format \fIDD\fR/\fIMM\fR/\fIYYYY\fR.
600 .RE
601
602 .sp
603 .ne 2
604 .na
605 \fB\fB-F\fR \fIformat\fR\fR
606 .ad
607 .sp .6
608 .RS 4n
609 Specifies the format of \fIplotfile\fR that is specified by the \fB-p\fR
610 option. As of this release, \fBgnuplot\fR is the only supported format.
611 .RE
612
613 .sp
614 .ne 2
615 .na
616 \fB\fB-p\fR \fIplotfile\fR\fR
617 .ad
618 .sp .6
619 .RS 4n
620 When specified with \fB-s\fR or \fB-e\fR (or both), outputs flow usage data to
621 a file of the format specified by the \fB-F\fR option, which is required.
622 .RE
623
624 .sp
625 .ne 2
626 .na
627 \fB\fB-s\fR \fItime\fR, \fB-e\fR \fItime\fR\fR
628 .ad
629 .sp .6
630 .RS 4n
631 Start and stop times for data display. Time is in the format
632 \fIYYYY\fR.\fIMM\fR.\fIDD\fR,\fIhh\fR:\fImm\fR:\fIss\fR.
633 .RE
634
635 .sp
636 .ne 2
637 .na
638 \fB\fB-f\fR \fIfilename\fR\fR
639 .ad
640 .sp .6
641 .RS 4n
642 Read extended accounting records of network flow usage from \fIfilename\fR.
643 .RE
644
645 .sp
646 .ne 2
647 .na
648 \fB\fIflow\fR\fR
649 .ad
650 .sp .6
651 .RS 4n
652 If specified, display the network flow usage only from the named flow.
653 Otherwise, display network usage from all flows.
654 .RE
655
656 .RE
657
658 .SS "Flow Attributes"
659 .sp
660 .LP
661 The flow operand that identify a flow in a \fBflowadm\fR command is a
662 comma-separated list of one or more keyword, value pairs from the list below.
663 .sp
664 .ne 2
665 .na
666 \fB\fBlocal_ip\fR[\fB/\fR\fIprefix_len\fR]\fR
667 .ad
668 .sp .6
669 .RS 4n
670 Identifies a network flow by the local IP address. \fIvalue\fR must be a IPv4
671 address in dotted-decimal notation or an IPv6 address in colon-separated
672 notation. \fIprefix_len\fR is optional.
673 .sp
674 If \fIprefix_len\fR is specified, it describes the netmask for a subnet
675 address, following the same notation convention of \fBifconfig\fR(1M) and
676 \fBroute\fR(1M) addresses. If unspecified, the given IP address will be
677 considered as a host address for which the default prefix length for a IPv4
678 address is \fB/32\fR and for IPv6 is \fB/128\fR.
679 .RE
680
681 .sp
682 .ne 2
683 .na
684 \fB\fBremote_ip\fR[\fB/\fR\fIprefix_len\fR]\fR
685 .ad
686 .sp .6
687 .RS 4n
688 Identifies a network flow by the remote IP address. The syntax is the same as
689 \fBlocal_ip\fR attributes
690 .RE
691
692 .sp
693 .ne 2
694 .na
695 \fB\fBtransport\fR={\fBtcp\fR|\fBudp\fR|\fBsctp\fR|\fBicmp\fR|\fBicmpv6\fR}\fR
696 .ad
697 .sp .6
698 .RS 4n
699 Identifies a layer 4 protocol to be used. It is typically used in combination
700 with local_port to identify the service that needs special attention.
701 .RE
702
703 .sp
704 .ne 2
705 .na
706 \fB\fBlocal_port\fR\fR
707 .ad
708 .sp .6
709 .RS 4n
710 Identifies a service specified by the local port.
711 .RE
712
713 .sp
714 .ne 2
715 .na
716 \fB\fBdsfield\fR[\fB:\fR\fIdsfield_mask\fR]\fR
717 .ad
718 .sp .6
719 .RS 4n
720 Identifies the 8-bit differentiated services field (as defined in RFC 2474).
721 .sp
722 The optional \fIdsfield_mask\fR is used to state the bits of interest in the
723 differentiated services field when comparing with the \fBdsfield\fR value. A
724 \fB0\fR in a bit position indicates that the bit value needs to be ignored and
725 a \fB1\fR indicates otherwise. The mask can range from \fB0x01\fR to
726 \fB0xff\fR. If \fIdsfield_mask\fR is not specified, the default mask \fB0xff\fR
727 is used. Both the \fBdsfield\fR value and mask must be in hexadecimal.
728 .RE
729
730 .sp
731 .LP
732 The following five types of combinations of attributes are supported:
733 .sp
734 .in +2
735 .nf
736 local_ip[/\fIprefixlen\fR]=\fIaddress\fR
737 remote_ip[/\fIprefixlen\fR]=\fIaddress\fR
738 transport={tcp|udp|sctp|icmp|icmpv6}
739 transport={tcp|udp|sctp},local_port=\fIport\fR
740 dsfield=\fIval\fR[:\fIdsfield_mask\fR]
741 .fi
742 .in -2
743 .sp
744
745 .sp
746 .LP
747 On a given link, the combinations above are mutually exclusive. An attempt to
748 create flows of different combinations will fail.
749 .SS "Restrictions"
750 .sp
751 .LP
752 There are individual flow restrictions and flow restrictions per zone.
753 .SS "Individual Flow Restrictions"
754 .sp
755 .LP
756 Restrictions on individual flows do not require knowledge of other flows that
757 have been added to the link.
758 .sp
759 .LP
760 An attribute can be listed only once for each flow. For example, the following
761 command is not valid:
762 .sp
763 .in +2
764 .nf
765 # \fBflowadm add-flow -l vnic1 -a local_port=80,local_port=8080 httpflow\fR
766 .fi
767 .in -2
768 .sp
769
770 .sp
771 .LP
772 \fBtransport\fR and \fBlocal_port\fR:
773 .sp
774 .LP
775 TCP, UDP, or SCTP flows can be specified with a local port. An ICMP or ICMPv6
776 flow that specifies a port is not allowed. The following commands are valid:
777 .sp
778 .in +2
779 .nf
780 # \fBflowadm add-flow -l e1000g0 -a transport=udp udpflow\fR
781 # \fBflowadm add-flow -l e1000g0 -a transport=tcp,local_port=80 \e
782 udp80flow\fR
783 .fi
784 .in -2
785 .sp
786
787 .sp
788 .LP
789 The following commands are not valid:
790 .sp
791 .in +2
792 .nf
793 # \fBflowadm add-flow -l e1000g0 -a local_port=25 flow25\fR
794 # \fBflowadm add-flow -l e1000g0 -a transport=icmpv6,local_port=16 \e
795 flow16\fR
796 .fi
797 .in -2
798 .sp
799
800 .SS "Flow Restrictions Per Zone"
801 .sp
802 .LP
803 Within a zone, no two flows can have the same name. After adding a flow with
804 the link specified, the link will not be required for display, modification, or
805 deletion of the flow.
806 .SS "Flow Properties"
807 .sp
808 .LP
809 The following flow properties are supported. Note that the ability to set a
810 given property to a given value depends on the driver and hardware.
811 .sp
812 .ne 2
813 .na
814 \fB\fBmaxbw\fR\fR
815 .ad
816 .sp .6
817 .RS 4n
818 Sets the full duplex bandwidth for the flow. The bandwidth is specified as an
819 integer with one of the scale suffixes(\fBK\fR, \fBM\fR, or \fBG\fR for Kbps,
820 Mbps, and Gbps). If no units are specified, the input value will be read as
821 Mbps. The default is no bandwidth limit.
822 .RE
823
824 .sp
825 .ne 2
826 .na
827 \fB\fBpriority\fR\fR
828 .ad
829 .sp .6
830 .RS 4n
831 Sets the relative priority for the flow. The value can be given as one of the
832 tokens \fBhigh\fR, \fBmedium\fR, or \fBlow\fR. The default is \fBmedium\fR.
833 .RE
834
835 .SH EXAMPLES
836 .LP
837 \fBExample 1 \fRCreating a Policy Around a Mission-Critical Port
838 .sp
839 .LP
840 The command below creates a policy around inbound HTTPS traffic on an HTTPS
841 server so that HTTPS obtains dedicated NIC hardware and kernel TCP/IP
842 resources. The name specified, \fBhttps-1\fR, can be used later to modify or
843 delete the policy.
844
845 .sp
846 .in +2
847 .nf
848 # \fBflowadm add-flow -l bge0 -a transport=TCP,local_port=443 https-1\fR
849 # \fBflowadm show-flow -l bge0\fR
850 FLOW LINK IP ADDR PROTO PORT DSFLD
851 https1 bge0 -- tcp 443 --
852 .fi
853 .in -2
854 .sp
855
856 .LP
857 \fBExample 2 \fRModifying an Existing Policy to Add Bandwidth Resource Control
858 .sp
859 .LP
860 The following command modifies the \fBhttps-1\fR policy from the preceding
861 example. The command adds bandwidth control and give the policy a high
862 priority.
863
864 .sp
865 .in +2
866 .nf
867 # \fBflowadm set-flowprop -p maxbw=500M,priority=high https-1\fR
868 # \fBflowadm show-flow https-1\fR
869 FLOW LINK IP ADDR PROTO PORT DSFLD
870 https1 bge0 -- tcp 443 --
871
872 # \fBflowadm show-flowprop https-1\fR
873 FLOW PROPERTY VALUE DEFAULT POSSIBLE
874 https-1 maxbw 500 -- --
875 https-1 priority HIGH -- LOW,NORMAL,HIGH
876 .fi
877 .in -2
878 .sp
879
880 .LP
881 \fBExample 3 \fRLimiting the UDP Bandwidth Usage
882 .sp
883 .LP
884 The following command creates a policy for UDP protocol so that it cannot
885 consume more than 100Mbps of available bandwidth. The flow is named
886 \fBlimit-udp-1\fR.
887
888 .sp
889 .in +2
890 .nf
891 # \fBflowadm add-flow -l bge0 -a transport=UDP -p maxbw=100M, \e
892 priority=low limit-udp-1\fR
893 .fi
894 .in -2
895 .sp
896
897 .LP
898 \fBExample 4 \fRShowing Flow Usage
899 .sp
900 .LP
901 Flow usage statistics can be stored using the extended accounting facility,
902 \fBacctadm\fR(1M).
903
904 .sp
905 .in +2
906 .nf
907 # \fBacctadm -e extended -f /var/log/net.log net\fR
908
909 # \fBacctadm net\fR
910 Network accounting: active
911 Network accounting file: /var/log/net.log
912 Tracked Network resources: extended
913 Untracked Network resources: none
914 .fi
915 .in -2
916 .sp
917
918 .sp
919 .LP
920 The historical data that was saved can be retrieved in summary form using the
921 \fBshow-usage\fR subcommand of \fBflowadm\fR.
922
923 .LP
924 \fBExample 5 \fRSetting Policy, Making Use of \fBdsfield\fR Attribute
925 .sp
926 .LP
927 The following command sets a policy for EF PHB (DSCP value of 101110 from RFC
928 2598) with a bandwidth of 500 Mbps and a high priority. The \fBdsfield\fR value
929 for this flow will be \fB0x2e\fR (101110) with the \fBdsfield_mask\fR being
930 \fB0xfc\fR (because we want to ignore the 2 least significant bits).
931
932 .sp
933 .in +2
934 .nf
935 # \fBflowadm add-flow -l bge0 -a dsfield=0x2e:0xfc \e
936 -p maxbw=500M,priority=high efphb-flow\fR
937 .fi
938 .in -2
939 .sp
940
941 .sp
942 .LP
943 Display summary information:
944
945 .sp
946 .in +2
947 .nf
948 # \fBflowadm show-usage -f /var/log/net.log\fR
949 FLOW DURATION IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH
950 flowtcp 100 1031 546908 0 0 43.76 Kbps
951 flowudp 0 0 0 0 0 0.00 Mbps
952 .fi
953 .in -2
954 .sp
955
956 .sp
957 .LP
958 Display dates for which logging information is available:
959
960 .sp
961 .in +2
962 .nf
963 # \fBflowadm show-usage -d -f /var/log/net.log\fR
964 02/19/2008
965 .fi
966 .in -2
967 .sp
968
969 .sp
970 .LP
971 Display logging information for \fBflowtcp\fR starting at 02/19/2008, 10:38:46
972 and ending at 02/19/2008, 10:40:06:
973
974 .sp
975 .in +2
976 .nf
977 # \fBflowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \e
978 -f /var/log/net.log flowtcp\fR
979 FLOW TIME IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH
980 flowtcp 10:39:06 1 1546 4 6539 3.23 Kbps
981 flowtcp 10:39:26 2 3586 5 9922 5.40 Kbps
982 flowtcp 10:39:46 1 240 1 216 182.40 bps
983 flowtcp 10:40:06 0 0 0 0 0.00 bps
984 .fi
985 .in -2
986 .sp
987
988 .sp
989 .LP
990 Output the same information as above as a plotfile:
991
992 .sp
993 .in +2
994 .nf
995 # \fBflowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \e
996 -p /home/plot/myplot -F gnuplot -f /var/log/net.log flowtcp\fR
997 # \fBTime tcp-flow\fR
998 10:39:06 3.23
999 10:39:26 5.40
1000 10:39:46 0.18
1001 10:40:06 0.00
1002 .fi
1003 .in -2
1004 .sp
1005
1006 .SH EXIT STATUS
1007 .sp
1008 .ne 2
1009 .na
1010 \fB\fB0\fR\fR
1011 .ad
1012 .sp .6
1013 .RS 4n
1014 All actions were performed successfully.
1015 .RE
1016
1017 .sp
1018 .ne 2
1019 .na
1020 \fB\fB>0\fR\fR
1021 .ad
1022 .sp .6
1023 .RS 4n
1024 An error occurred.
1025 .RE
1026
1027 .SH ATTRIBUTES
1028 .sp
1029 .LP
1030 See \fBattributes\fR(5) for descriptions of the following attributes:
1031 .sp
1032
1033 .sp
1034 .TS
1035 box;
1036 c | c
1037 l | l .
1038 ATTRIBUTE TYPE ATTRIBUTE VALUE
1039 _
1040 Interface Stability Committed
1041 .TE
1042
1043 .SH SEE ALSO
1044 .sp
1045 .LP
1046 \fBacctadm\fR(1M), \fBdladm\fR(1M), \fBifconfig\fR(1M), \fBprstat\fR(1M),
1047 \fBroute\fR(1M), \fBattributes\fR(5), \fBdlpi\fR(7P)