1flowadm(1M) System Administration Commands flowadm(1M)
2
6 flowadm - administer bandwidth resource control and priority for proto‐
7 cols, services, containers, and virtual machines
8
10 flowadm show-flow [-pP] [-S] [-s [-i interval]] [-l link]
11 [-o field[,...]] [flow]
12 flowadm add-flow [-t] [-R root-dir] -l link -a attr=value[,...]
15 -p prop=value[,...] flow
16 flowadm remove-flow [-t] [-R root-dir] {-l link | flow}
17 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 flowadm show-usage [-a] [-d | {-p plotfile -F format}] [-s time]
26 [-e time] -f filename [flow]
27
30 The flowadm command is used to create, modify, remove, and show net‐
31 working bandwidth and associated resources for a type of traffic on a
32 particular link.
33 The flowadm command allows users to manage networking bandwidth
36 resources for a transport, service, or a subnet. The service is speci‐
37 fied as a combination of transport and local port. The subnet is speci‐
38 fied by its IP address and subnet mask. The command can be used on any
39 type of data link, including physical links, virtual NICs, and link
40 aggregations.
41 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 vir‐
45 tual machine. When a flow is identified based on flow attributes, sepa‐
46 rate kernel resources including layer 2, 3, and 4 queues, their pro‐
47 cessing threads, and other resources are uniquely created for it, such
48 that other traffic has minimal or zero impact on it.
49 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 The flowadm command can be used to identify a flow without imposing any
57 bandwidth resource control. This would result in the traffic type get‐
58 ting its own resources and queues so that it is isolated from rest of
59 the networking traffic for more observable and deterministic behavior.
60 flowadm is implemented as a set of subcommands with corresponding
63 options. Options are described in the context of each subcommand.
64
66 The following subcommands are supported:
67 flowadm show-flow [-pP] [-s [-i interval]] [-o field[,...]] [-l link]
69 [flow]
70 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 -o field[,...]
76 A case-insensitive, comma-separated list of output fields to
78 display. The field name must be one of the fields listed below,
79 or a special value all, to display all fields. For each flow
80 found, the following fields can be displayed:
81 flow
83 The name of the flow.
85 link
88 The name of the link the flow is on.
90 ipaddr
93 IP address of the flow. This can be either local or remote
95 depending on how the flow was defined.
96 transport
99 The name of the layer for protocol to be used.
101 port
104 Local port of service for flow.
106 dsfield
109 Differentiated services value for flow and mask used with
111 DSFIELD value to state the bits of interest in the differ‐
112 entiated services field of the IP header.
113 -p, --parseable
117 Display using a stable machine-parseable format.
119 -P, --persistent
122 Display persistent flow property information.
124 -S, --continuous
127 Continuously display network utilization by flow in a manner
129 similar to the way that prstat(1M) displays CPU utilization by
130 process.
131 -s, --statistics
134 Displays flow statistics.
136 -i interval, --interval=interval
139 Used with the -s option to specify an interval, in seconds, at
141 which statistics should be displayed. If this option is not
142 specified, statistics are displayed once.
143 -l link, --link=link | flow
146 Display information for all flows on the named link or informa‐
148 tion for the named flow.
149 flowadm add-flow [-t] [-R root-dir] -l link -a attr=value[,...] -p
153 prop=value[,...] flow
154 Adds a flow to the system. The flow is identified by its flow
156 attributes and properties.
157 As part of identifying a particular flow, its bandwidth resource
159 can be limited and its relative priority to other traffic can be
160 specified. If no bandwidth limit or priority is specified, the
161 traffic still gets its unique layer 2, 3, and 4 queues and process‐
162 ing threads, including NIC hardware resources (when supported), so
163 that the selected traffic can be separated from others and can flow
164 with minimal impact from other traffic.
165 -t, --temporary
167 The changes are temporary and will not persist across reboots.
169 Persistence is the default.
170 -R root-dir, --root-dir=root-dir
173 Specifies an alternate root directory where flowadm should
175 apply persistent creation.
176 -l link, --link=link
179 Specify the link to which the flow will be added.
181 -a attr=value[,...], --attr=value
184 A comma-separated list of attributes to be set to the specified
186 values.
187 -p prop=value[,...], --prop=value[,...]
190 A comma-separated list of properties to be set to the specified
192 values.
193 flowadm remove-flow [-t] [-R root-dir] -l {link | flow}
197 Remove an existing flow identified by its link or name.
199 -t, --temporary
201 The changes are temporary and will not persist across reboots.
203 Persistence is the default.
204 -R root-dir, --root-dir=root-dir
207 Specifies an alternate root directory where flowadm should
209 apply persistent removal.
210 -l link | flow, --link=link | flow
213 If a link is specified, remove all flows from that link. If a
215 single flow is specified, remove only that flow.
216 flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow
220 Set values of one or more properties on the flow specified by name.
222 The complete list of properties can be retrieved using the show-
223 flow subcommand.
224 -t, --temporary
226 The changes are temporary and will not persist across reboots.
228 Persistence is the default.
229 -R root-dir, --root-dir=root-dir
232 Specifies an alternate root directory where flowadm should
234 apply persistent setting of properties.
235 -p prop=value[,...], --prop=value[,...]
238 A comma-separated list of properties to be set to the specified
240 values.
241 flowadm reset-flowprop [-t] [-R root-dir] -p [prop=value[,...]] flow
245 Resets one or more properties to their default values on the speci‐
247 fied flow. If no properties are specified, all properties are
248 reset. See the show-flowprop subcommand for a description of prop‐
249 erties, which includes their default values.
250 -t, --temporary
252 Specifies that the resets are temporary. Temporary resets last
254 until the next reboot.
255 -R root-dir, --root-dir=root-dir
258 Specifies an alternate root directory where flowadm should
260 apply persistent setting of properties.
261 -p prop=value[,...], --prop=value[,...]
264 A comma-separated list of properties to be reset.
266 flowadm show-flowprop [-cP] [-l link] [-p prop[,...]] [flow]
270 Show the current or persistent values of one or more properties,
272 either for all flows, flows on a specified link, or for the speci‐
273 fied flow.
274 By default, current values are shown. If no properties are speci‐
276 fied, all available flow properties are displayed. For each prop‐
277 erty, the following fields are displayed:
278 FLOW
280 The name of the flow.
282 PROPERTY
285 The name of the property.
287 VALUE
290 The current (or persistent) property value. The value is shown
292 as -- (double hyphen), if it is not set, and ? (question mark),
293 if the value is unknown. Persistent values that are not set or
294 have been reset will be shown as -- and will use the system
295 DEFAULT value (if any).
296 DEFAULT
299 The default value of the property. If the property has no
301 default value, -- (double hyphen), is shown.
302 POSSIBLE
305 A comma-separated list of the values the property can have. If
307 the values span a numeric range, the minimum and maximum values
308 might be shown as shorthand. If the possible values are unknown
309 or unbounded, -- (double hyphen), is shown.
310 Flow properties are documented in the "Flow Properties" section,
312 below.
313 -c, --parseable
315 Display using a stable machine-parseable format.
317 -P, --persistent
320 Display persistent flow property information.
322 -p prop[,...], --prop=prop[,...]
325 A comma-separated list of properties to show.
327 flowadm show-usage [-a] [-d | {-p plotfile -F format}] [-s time] [-e
331 time] [flow]
332 Show the historical network flow usage from a stored extended
334 accounting file. Configuration and enabling of network accounting
335 through acctadm(1M) is required. The default output will be the
336 summary of flow usage for the entire period of time in which
337 extended accounting was enabled.
338 -a
340 Display all historical network usage for the specified period
342 of time during which extended accounting is enabled. This
343 includes the usage information for the flows that have already
344 been deleted.
345 -d
348 Display the dates for which there is logging information. The
350 date is in the format DD/MM/YYYY.
351 -F format
354 Specifies the format of plotfile that is specified by the -p
356 option. As of this release, gnuplot is the only supported for‐
357 mat.
358 -p plotfile
361 When specified with -s or -e (or both), outputs flow usage data
363 to a file of the format specified by the -F option, which is
364 required.
365 -s time, -e time
368 Start and stop times for data display. Time is in the format
370 YYYY.MM.DD,hh:mm:ss.
371 -f filename
374 Read extended accounting records of network flow usage from
376 filename.
377 flow
380 If specified, display the network flow usage only from the
382 named flow. Otherwise, display network usage from all flows.
383 Flow Attributes
387 The flow operand that identify a flow in a flowadm command is a comma-
388 separated list of one or more keyword, value pairs from the list below.
389 local_ip[/prefix_len]
391 Identifies a network flow by the local IP address. value must be a
393 IPv4 address in dotted-decimal notation or an IPv6 address in
394 colon-separated notation. prefix_len is optional.
395 If prefix_len is specified, it describes the netmask for a subnet
397 address, following the same notation convention of ifconfig(1M) and
398 route(1M) addresses. If unspecified, the given IP address will be
399 considered as a host address for which the default prefix length
400 for a IPv4 address is /32 and for IPv6 is /128.
401 remote_ip[/prefix_len]
404 Identifies a network flow by the remote IP address. The syntax is
406 the same as local_ip attributes
407 transport={tcp|udp|sctp|icmp|icmpv6}
410 Identifies a layer 4 protocol to be used. It is typically used in
412 combination with local_port to identify the service that needs spe‐
413 cial attention.
414 local_port
417 Identifies a service specified by the local port.
419 dsfield[:dsfield_mask]
422 Identifies the 8-bit differentiated services field (as defined in
424 RFC 2474).
425 The optional dsfield_mask is used to state the bits of interest in
427 the differentiated services field when comparing with the dsfield
428 value. A 0 in a bit position indicates that the bit value needs to
429 be ignored and a 1 indicates otherwise. The mask can range from
430 0x01 to 0xff. If dsfield_mask is not specified, the default mask
431 0xff is used. Both the dsfield value and mask must be in hexadeci‐
432 mal.
433 The following five types of combinations of attributes are supported:
437 local_ip[/prefixlen]=address
439 remote_ip[/prefixlen]=address
440 transport={tcp|udp|sctp|icmp|icmpv6}
441 transport={tcp|udp|sctp},local_port=port
442 dsfield=val[:dsfield_mask]
443 On a given link, the combinations above are mutually exclusive. An
448 attempt to create flows of different combinations will fail.
449 Restrictions
451 There are individual flow restrictions and flow restrictions per zone.
452 Individual Flow Restrictions
454 Restrictions on individual flows do not require knowledge of other
455 flows that have been added to the link.
456 An attribute can be listed only once for each flow. For example, the
459 following command is not valid:
460 # flowadm add-flow -l vnic1 -a local_port=80,local_port=8080 httpflow
462 transport and local_port:
467 TCP, UDP, or SCTP flows can be specified with a local port. An ICMP or
470 ICMPv6 flow that specifies a port is not allowed. The following com‐
471 mands are valid:
472 # flowadm add-flow -l e1000g0 -a transport=udp udpflow
474 # flowadm add-flow -l e1000g0 -a transport=tcp,local_port=80 \
475 udp80flow
476 The following commands are not valid:
481 # flowadm add-flow -l e1000g0 -a local_port=25 flow25
483 # flowadm add-flow -l e1000g0 -a transport=icmpv6,local_port=16 \
484 flow16
485 Flow Restrictions Per Zone
489 Within a zone, no two flows can have the same name. After adding a flow
490 with the link specified, the link will not be required for display,
491 modification, or deletion of the flow.
492 Flow Properties
494 The following flow properties are supported. Note that the ability to
495 set a given property to a given value depends on the driver and hard‐
496 ware.
497 maxbw
499 Sets the full duplex bandwidth for the flow. The bandwidth is spec‐
501 ified as an integer with one of the scale suffixes(K, M, or G for
502 Kbps, Mbps, and Gbps). If no units are specified, the input value
503 will be read as Mbps. The default is no bandwidth limit.
504 priority
507 Sets the relative priority for the flow. The value can be given as
509 one of the tokens high, medium, or low. The default is medium.
510
513 Example 1 Creating a Policy Around a Mission-Critical Port
514 The command below creates a policy around inbound HTTPS traffic on an
517 HTTPS server so that HTTPS obtains dedicated NIC hardware and kernel
518 TCP/IP resources. The name specified, https-1, can be used later to
519 modify or delete the policy.
520 # flowadm add-flow -l bge0 -a transport=TCP,local_port=443 https-1
523 # flowadm show-flow -l bge0
524 FLOW LINK IP ADDR PROTO PORT DSFLD
525 https1 bge0 -- tcp 443 --
526 Example 2 Modifying an Existing Policy to Add Bandwidth Resource Con‐
530 trol
531 The following command modifies the https-1 policy from the preceding
534 example. The command adds bandwidth control and give the policy a high
535 priority.
536 # flowadm set-flowprop -p maxbw=500M,priority=high https-1
539 # flowadm show-flow https-1
540 FLOW LINK IP ADDR PROTO PORT DSFLD
541 https1 bge0 -- tcp 443 --
542 # flowadm show-flowprop https-1
544 FLOW PROPERTY VALUE DEFAULT POSSIBLE
545 https-1 maxbw 500 -- --
546 https-1 priority HIGH -- LOW,NORMAL,HIGH
547 Example 3 Limiting the UDP Bandwidth Usage
551 The following command creates a policy for UDP protocol so that it can‐
554 not consume more than 100Mbps of available bandwidth. The flow is named
555 limit-udp-1.
556 # flowadm add-flow -l bge0 -a transport=UDP -p maxbw=100M, \
559 priority=low limit-udp-1
560 Example 4 Showing Flow Usage
564 Flow usage statistics can be stored using the extended accounting
567 facility, acctadm(1M).
568 # acctadm -e extended -f /var/log/net.log net
571 # acctadm net
573 Network accounting: active
574 Network accounting file: /var/log/net.log
575 Tracked Network resources: extended
576 Untracked Network resources: none
577 The historical data that was saved can be retrieved in summary form
582 using the show-usage subcommand of flowadm.
583 Example 5 Setting Policy, Making Use of dsfield Attribute
586 The following command sets a policy for EF PHB (DSCP value of 101110
589 from RFC 2598) with a bandwidth of 500 Mbps and a high priority. The
590 dsfield value for this flow will be 0x2e (101110) with the dsfield_mask
591 being 0xfc (because we want to ignore the 2 least significant bits).
592 # flowadm add-flow -l bge0 -a dsfield=0x2e:0xfc \
595 -p maxbw=500M,priority=high efphb-flow
596 Display summary information:
601 # flowadm show-usage -f /var/log/net.log
604 FLOW DURATION IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH
605 flowtcp 100 1031 546908 0 0 43.76 Kbps
606 flowudp 0 0 0 0 0 0.00 Mbps
607 Display dates for which logging information is available:
612 # flowadm show-usage -d -f /var/log/net.log
615 02/19/2008
616 Display logging information for flowtcp starting at 02/19/2008,
621 10:38:46 and ending at 02/19/2008, 10:40:06:
622 # flowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \
625 -f /var/log/net.log flowtcp
626 FLOW TIME IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH
627 flowtcp 10:39:06 1 1546 4 6539 3.23 Kbps
628 flowtcp 10:39:26 2 3586 5 9922 5.40 Kbps
629 flowtcp 10:39:46 1 240 1 216 182.40 bps
630 flowtcp 10:40:06 0 0 0 0 0.00 bps
631 Output the same information as above as a plotfile:
636 # flowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \
639 -p /home/plot/myplot -F gnuplot -f /var/log/net.log flowtcp
640 # Time tcp-flow
641 10:39:06 3.23
642 10:39:26 5.40
643 10:39:46 0.18
644 10:40:06 0.00
645
649 0
650 All actions were performed successfully.
652 >0
655 An error occurred.
657
660 See attributes(5) for descriptions of the following attributes:
661 ┌─────────────────────────────┬─────────────────────────────┐
666 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
667 ├─────────────────────────────┼─────────────────────────────┤
668 │Availability │SUNWcnetr │
669 ├─────────────────────────────┼─────────────────────────────┤
670 │Interface Stability │Committed │
671 └─────────────────────────────┴─────────────────────────────┘
672
674 acctadm(1M), dladm(1M), ifconfig(1M), prstat(1M), route(1M),
675 attributes(5), dlpi(7P)
676SunOS 5.11 14 Feb 2009 flowadm(1M)