1 FLOWADM(1M) Maintenance Commands FLOWADM(1M)
2
3
4
5 NAME
6 flowadm - administer bandwidth resource control and priority for
7 protocols, services, containers, and virtual machines
8
9 SYNOPSIS
10 flowadm show-flow [-pP] [-S] [-s [-i interval]] [-l link]
11 [-o field[,...]] [-z zonename] [flow]
12
13
14 flowadm add-flow [-t] [-R root-dir] [-z zonename] -l link
15 -a attr=value[,...] -p prop=value[,...] flow
16 flowadm remove-flow [-t] [-R root-dir] [-z zonename] {-l link | flow}
17
18
19 flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow
20 flowadm reset-flowprop [-t] [-R root-dir] [-p prop[,...]] flow
21 flowadm show-flowprop [-cP] [-l link] [-o field[,...]]
22 [-p prop[,...]] [flow]
23
24
25 flowadm show-usage [-a] [-d | {-p plotfile -F format}] [-s time]
26 [-e time] -f filename [flow]
27
28
29 DESCRIPTION
30 The flowadm command is used to create, modify, remove, and show
31 networking bandwidth and associated resources for a type of traffic on
32 a particular link.
33
34
35 The flowadm command allows users to manage networking bandwidth
36 resources for a transport, service, or a subnet. The service is
37 specified as a combination of transport and local port. The subnet is
38 specified by its IP address and subnet mask. The command can be used on
39 any type of data link, including physical links, virtual NICs, and link
40 aggregations.
41
42
43 A flow is defined as a set of attributes based on Layer 3 and Layer 4
44 headers, which can be used to identify a protocol, service, or a
45 virtual machine. When a flow is identified based on flow attributes,
46 separate kernel resources including layer 2, 3, and 4 queues, their
47 processing threads, and other resources are uniquely created for it,
48 such that other traffic has minimal or zero impact on it.
49
50
51 Inbound and outbound packet are matched to flows in a very fast and
52 scalable way, so that limits can be enforced with minimal performance
53 impact.
54
55
56 The flowadm command can be used to identify a flow without imposing any
57 bandwidth resource control. This would result in the traffic type
58 getting its own resources and queues so that it is isolated from rest
59 of the networking traffic for more observable and deterministic
60 behavior.
61
62
63 flowadm is implemented as a set of subcommands with corresponding
64 options. Options are described in the context of each subcommand.
65
66 SUB-COMMANDS
67 The following subcommands are supported:
68
69 flowadm show-flow [-pP] [-s [-i interval]] [-o field[,...]] [-l link] [-z
70 zonename] [flow]
71 Show flow configuration information (the default) or statistics,
72 either for all flows, all flows on a link, or for the specified
73 flow.
74
75 -o field[,...]
76 A case-insensitive, comma-separated list of output fields to
77 display. The field name must be one of the fields listed below,
78 or a special value all, to display all fields. For each flow
79 found, the following fields can be displayed:
80
81 flow
82 The name of the flow.
83
84
85 link
86 The name of the link the flow is on.
87
88
89 ipaddr
90 IP address of the flow. This can be either local or remote
91 depending on how the flow was defined.
92
93
94 transport
95 The name of the layer for protocol to be used.
96
97
98 port
99 Local port of service for flow.
100
101
102 dsfield
103 Differentiated services value for flow and mask used with
104 DSFIELD value to state the bits of interest in the
105 differentiated services field of the IP header.
106
107
108
109 -p, --parseable
110 Display using a stable machine-parseable format.
111
112
113 -P, --persistent
114 Display persistent flow property information.
115
116
117 -S, --continuous
118 Continuously display network utilization by flow in a manner
119 similar to the way that prstat(1M) displays CPU utilization by
120 process.
121
122
123 -s, --statistics
124 Displays flow statistics.
125
126
127 -i interval, --interval=interval
128 Used with the -s option to specify an interval, in seconds, at
129 which statistics should be displayed. If this option is not
130 specified, statistics are displayed once.
131
132
133 -l link, --link=link | flow
134 Display information for all flows on the named link or
135 information for the named flow.
136
137
138 -z zonename
139 Operate on a link that has been delegated to the specified
140 zone.
141
142
143
144 flowadm add-flow [-t] [-R root-dir] [-z zonename] -l link -a attr=value[,...]
145 -p prop=value[,...] flow
146 Adds a flow to the system. The flow is identified by its flow
147 attributes and properties.
148
149 As part of identifying a particular flow, its bandwidth resource
150 can be limited and its relative priority to other traffic can be
151 specified. If no bandwidth limit or priority is specified, the
152 traffic still gets its unique layer 2, 3, and 4 queues and
153 processing threads, including NIC hardware resources (when
154 supported), so that the selected traffic can be separated from
155 others and can flow with minimal impact from other traffic.
156
157 -t, --temporary
158 The changes are temporary and will not persist across reboots.
159 Persistence is the default.
160
161
162 -R root-dir, --root-dir=root-dir
163 Specifies an alternate root directory where flowadm should
164 apply persistent creation.
165
166
167 -z zonename
168 Operate on a link that has been delegated to the specified
169 zone.
170
171
172 -l link, --link=link
173 Specify the link to which the flow will be added.
174
175
176 -a attr=value[,...], --attr=value
177 A comma-separated list of attributes to be set to the specified
178 values.
179
180
181 -p prop=value[,...], --prop=value[,...]
182 A comma-separated list of properties to be set to the specified
183 values.
184
185
186
187 flowadm remove-flow [-t] [-R root-dir] [-z zonename] -l {link | flow}
188 Remove an existing flow identified by its link or name.
189
190 -t, --temporary
191 The changes are temporary and will not persist across reboots.
192 Persistence is the default.
193
194
195 -R root-dir, --root-dir=root-dir
196 Specifies an alternate root directory where flowadm should
197 apply persistent removal.
198
199
200 -z zonename
201 Operate on a link that has been delegated to the specified
202 zone.
203
204
205 -l link | flow, --link=link | flow
206 If a link is specified, remove all flows from that link. If a
207 single flow is specified, remove only that flow.
208
209
210
211 flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow
212 Set values of one or more properties on the flow specified by name.
213 The complete list of properties can be retrieved using the show-flow
214 subcommand.
215
216 -t, --temporary
217 The changes are temporary and will not persist across reboots.
218 Persistence is the default.
219
220
221 -R root-dir, --root-dir=root-dir
222 Specifies an alternate root directory where flowadm should
223 apply persistent setting of properties.
224
225
226 -p prop=value[,...], --prop=value[,...]
227 A comma-separated list of properties to be set to the specified
228 values.
229
230
231
232 flowadm reset-flowprop [-t] [-R root-dir] -p [prop=value[,...]] flow
233 Resets one or more properties to their default values on the
234 specified flow. If no properties are specified, all properties are
235 reset. See the show-flowprop subcommand for a description of
236 properties, which includes their default values.
237
238 -t, --temporary
239 Specifies that the resets are temporary. Temporary resets last
240 until the next reboot.
241
242
243 -R root-dir, --root-dir=root-dir
244 Specifies an alternate root directory where flowadm should
245 apply persistent setting of properties.
246
247
248 -p prop=value[,...], --prop=value[,...]
249 A comma-separated list of properties to be reset.
250
251
252
253 flowadm show-flowprop [-cP] [-l link] [-p prop[,...]] [flow]
254 Show the current or persistent values of one or more properties,
255 either for all flows, flows on a specified link, or for the
256 specified flow.
257
258 By default, current values are shown. If no properties are
259 specified, all available flow properties are displayed. For each
260 property, the following fields are displayed:
261
262 FLOW
263 The name of the flow.
264
265
266 PROPERTY
267 The name of the property.
268
269
270 VALUE
271 The current (or persistent) property value. The value is shown
272 as -- (double hyphen), if it is not set, and ? (question mark),
273 if the value is unknown. Persistent values that are not set or
274 have been reset will be shown as -- and will use the system
275 DEFAULT value (if any).
276
277
278 DEFAULT
279 The default value of the property. If the property has no
280 default value, -- (double hyphen), is shown.
281
282
283 POSSIBLE
284 A comma-separated list of the values the property can have. If
285 the values span a numeric range, the minimum and maximum values
286 might be shown as shorthand. If the possible values are unknown
287 or unbounded, -- (double hyphen), is shown.
288
289 Flow properties are documented in the "Flow Properties" section,
290 below.
291
292 -c, --parseable
293 Display using a stable machine-parseable format.
294
295
296 -P, --persistent
297 Display persistent flow property information.
298
299
300 -p prop[,...], --prop=prop[,...]
301 A comma-separated list of properties to show.
302
303
304
305 flowadm show-usage [-a] [-d | {-p plotfile -F format}] [-s time] [-e time]
306 [flow]
307 Show the historical network flow usage from a stored extended
308 accounting file. Configuration and enabling of network accounting
309 through acctadm(1M) is required. The default output will be the
310 summary of flow usage for the entire period of time in which
311 extended accounting was enabled.
312
313 -a
314 Display all historical network usage for the specified period
315 of time during which extended accounting is enabled. This
316 includes the usage information for the flows that have already
317 been deleted.
318
319
320 -d
321 Display the dates for which there is logging information. The
322 date is in the format DD/MM/YYYY.
323
324
325 -F format
326 Specifies the format of plotfile that is specified by the -p
327 option. As of this release, gnuplot is the only supported
328 format.
329
330
331 -p plotfile
332 When specified with -s or -e (or both), outputs flow usage data
333 to a file of the format specified by the -F option, which is
334 required.
335
336
337 -s time, -e time
338 Start and stop times for data display. Time is in the format
339 YYYY.MM.DD,hh:mm:ss.
340
341
342 -f filename
343 Read extended accounting records of network flow usage from
344 filename.
345
346
347 flow
348 If specified, display the network flow usage only from the
349 named flow. Otherwise, display network usage from all flows.
350
351
352
353 Flow Attributes
354 The flow operand that identify a flow in a flowadm command is a comma-
355 separated list of one or more keyword, value pairs from the list below.
356
357 local_ip[/prefix_len]
358 Identifies a network flow by the local IP address. value must be a
359 IPv4 address in dotted-decimal notation or an IPv6 address in colon-
360 separated notation. prefix_len is optional.
361
362 If prefix_len is specified, it describes the netmask for a subnet
363 address, following the same notation convention of ifconfig(1M) and
364 route(1M) addresses. If unspecified, the given IP address will be
365 considered as a host address for which the default prefix length
366 for a IPv4 address is /32 and for IPv6 is /128.
367
368
369 remote_ip[/prefix_len]
370 Identifies a network flow by the remote IP address. The syntax is
371 the same as local_ip attributes
372
373
374 transport={tcp|udp|sctp|icmp|icmpv6}
375 Identifies a layer 4 protocol to be used. It is typically used in
376 combination with local_port to identify the service that needs
377 special attention.
378
379
380 local_port
381 Identifies a service specified by the local port.
382
383
384 dsfield[:dsfield_mask]
385 Identifies the 8-bit differentiated services field (as defined in
386 RFC 2474).
387
388 The optional dsfield_mask is used to state the bits of interest in
389 the differentiated services field when comparing with the dsfield
390 value. A 0 in a bit position indicates that the bit value needs to
391 be ignored and a 1 indicates otherwise. The mask can range from
392 0x01 to 0xff. If dsfield_mask is not specified, the default mask
393 0xff is used. Both the dsfield value and mask must be in
394 hexadecimal.
395
396
397
398 The following five types of combinations of attributes are supported:
399
400 local_ip[/prefixlen]=address
401 remote_ip[/prefixlen]=address
402 transport={tcp|udp|sctp|icmp|icmpv6}
403 transport={tcp|udp|sctp},local_port=port
404 dsfield=val[:dsfield_mask]
405
406
407
408
409 On a given link, the combinations above are mutually exclusive. An
410 attempt to create flows of different combinations will fail.
411
412 Restrictions
413 There are individual flow restrictions and flow restrictions per zone.
414
415 Individual Flow Restrictions
416 Restrictions on individual flows do not require knowledge of other
417 flows that have been added to the link.
418
419
420 An attribute can be listed only once for each flow. For example, the
421 following command is not valid:
422
423 # flowadm add-flow -l vnic1 -a local_port=80,local_port=8080 httpflow
424
425
426
427
428 transport and local_port:
429
430
431 TCP, UDP, or SCTP flows can be specified with a local port. An ICMP or
432 ICMPv6 flow that specifies a port is not allowed. The following
433 commands are valid:
434
435 # flowadm add-flow -l e1000g0 -a transport=udp udpflow
436 # flowadm add-flow -l e1000g0 -a transport=tcp,local_port=80 \
437 udp80flow
438
439
440
441
442 The following commands are not valid:
443
444 # flowadm add-flow -l e1000g0 -a local_port=25 flow25
445 # flowadm add-flow -l e1000g0 -a transport=icmpv6,local_port=16 \
446 flow16
447
448
449
450 Flow Restrictions Per Zone
451 Within a zone, no two flows can have the same name. After adding a flow
452 with the link specified, the link will not be required for display,
453 modification, or deletion of the flow.
454
455 Flow Properties
456 The following flow properties are supported. Note that the ability to
457 set a given property to a given value depends on the driver and
458 hardware.
459
460 maxbw
461 Sets the full duplex bandwidth for the flow. The bandwidth is
462 specified as an integer with one of the scale suffixes(K, M, or G
463 for Kbps, Mbps, and Gbps). If no units are specified, the input
464 value will be read as Mbps. The default is no bandwidth limit.
465
466
467 priority
468 Sets the relative priority for the flow. The value can be given as
469 one of the tokens high, medium, or low. The default is medium.
470
471
472 EXAMPLES
473 Example 1 Creating a Policy Around a Mission-Critical Port
474
475
476 The command below creates a policy around inbound HTTPS traffic on an
477 HTTPS server so that HTTPS obtains dedicated NIC hardware and kernel
478 TCP/IP resources. The name specified, https-1, can be used later to
479 modify or delete the policy.
480
481
482 # flowadm add-flow -l bge0 -a transport=TCP,local_port=443 https-1
483 # flowadm show-flow -l bge0
484 FLOW LINK IP ADDR PROTO PORT DSFLD
485 https1 bge0 -- tcp 443 --
486
487
488
489 Example 2 Modifying an Existing Policy to Add Bandwidth Resource
490 Control
491
492
493 The following command modifies the https-1 policy from the preceding
494 example. The command adds bandwidth control and give the policy a high
495 priority.
496
497
498 # flowadm set-flowprop -p maxbw=500M,priority=high https-1
499 # flowadm show-flow https-1
500 FLOW LINK IP ADDR PROTO PORT DSFLD
501 https1 bge0 -- tcp 443 --
502
503 # flowadm show-flowprop https-1
504 FLOW PROPERTY VALUE DEFAULT POSSIBLE
505 https-1 maxbw 500 -- --
506 https-1 priority HIGH -- LOW,NORMAL,HIGH
507
508
509
510 Example 3 Limiting the UDP Bandwidth Usage
511
512
513 The following command creates a policy for UDP protocol so that it
514 cannot consume more than 100Mbps of available bandwidth. The flow is
515 named limit-udp-1.
516
517
518 # flowadm add-flow -l bge0 -a transport=UDP -p maxbw=100M, \
519 priority=low limit-udp-1
520
521
522
523 Example 4 Showing Flow Usage
524
525
526 Flow usage statistics can be stored using the extended accounting
527 facility, acctadm(1M).
528
529
530 # acctadm -e extended -f /var/log/net.log net
531
532 # acctadm net
533 Network accounting: active
534 Network accounting file: /var/log/net.log
535 Tracked Network resources: extended
536 Untracked Network resources: none
537
538
539
540
541 The historical data that was saved can be retrieved in summary form
542 using the show-usage subcommand of flowadm.
543
544
545 Example 5 Setting Policy, Making Use of dsfield Attribute
546
547
548 The following command sets a policy for EF PHB (DSCP value of 101110
549 from RFC 2598) with a bandwidth of 500 Mbps and a high priority. The
550 dsfield value for this flow will be 0x2e (101110) with the dsfield_mask
551 being 0xfc (because we want to ignore the 2 least significant bits).
552
553
554 # flowadm add-flow -l bge0 -a dsfield=0x2e:0xfc \
555 -p maxbw=500M,priority=high efphb-flow
556
557
558
559
560 Display summary information:
561
562
563 # flowadm show-usage -f /var/log/net.log
564 FLOW DURATION IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH
565 flowtcp 100 1031 546908 0 0 43.76 Kbps
566 flowudp 0 0 0 0 0 0.00 Mbps
567
568
569
570
571 Display dates for which logging information is available:
572
573
574 # flowadm show-usage -d -f /var/log/net.log
575 02/19/2008
576
577
578
579
580 Display logging information for flowtcp starting at 02/19/2008,
581 10:38:46 and ending at 02/19/2008, 10:40:06:
582
583
584 # flowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \
585 -f /var/log/net.log flowtcp
586 FLOW TIME IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH
587 flowtcp 10:39:06 1 1546 4 6539 3.23 Kbps
588 flowtcp 10:39:26 2 3586 5 9922 5.40 Kbps
589 flowtcp 10:39:46 1 240 1 216 182.40 bps
590 flowtcp 10:40:06 0 0 0 0 0.00 bps
591
592
593
594
595 Output the same information as above as a plotfile:
596
597
598 # flowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \
599 -p /home/plot/myplot -F gnuplot -f /var/log/net.log flowtcp
600 # Time tcp-flow
601 10:39:06 3.23
602 10:39:26 5.40
603 10:39:46 0.18
604 10:40:06 0.00
605
606
607
608 EXIT STATUS
609 0
610 All actions were performed successfully.
611
612
613 >0
614 An error occurred.
615
616
617 ATTRIBUTES
618 See attributes(5) for descriptions of the following attributes:
619
620
621
622
623 +--------------------+-----------------+
624 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
625 +--------------------+-----------------+
626 |Interface Stability | Committed |
627 +--------------------+-----------------+
628
629 SEE ALSO
630 acctadm(1M), dladm(1M), ifconfig(1M), prstat(1M), route(1M),
631 attributes(5), dlpi(7P)
632
633
634
635 February 14, 2009 FLOWADM(1M)