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 add-flow [-t] [-R root-dir] -l link -a attr=value[,...]
11 [-p prop=value[,...]] flow
12 flowadm remove-flow [-t] [-R root-dir] {-l link | flow}
13 flowadm show-flow [-p] [-l link] [-o field[,...]] [flow]
14
15
16 flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow
17 flowadm reset-flowprop [-t] [-R root-dir] [-p prop[,...]] flow
18 flowadm show-flowprop [-cP] [-l link] [-o field[,...]]
19 [-p prop[,...]] [flow]
20
21
22 DESCRIPTION
23 The flowadm command is used to create, modify, remove, and show
24 networking bandwidth and associated resources for a type of traffic on
25 a particular link.
26
27
28 The flowadm command allows users to manage networking bandwidth
29 resources for a transport, service, or a subnet. The service is
30 specified as a combination of transport and local port. The subnet is
31 specified by its IP address and subnet mask. The command can be used on
32 any type of data link, including physical links, virtual NICs, and link
33 aggregations.
34
35
36 A flow is defined as a set of attributes based on Layer 3 and Layer 4
37 headers, which can be used to identify a protocol, service, or a
38 virtual machine. When a flow is identified based on flow attributes,
39 separate kernel resources including layer 2, 3, and 4 queues, their
40 processing threads, and other resources are uniquely created for it,
41 such that other traffic has minimal or zero impact on it.
42
43
44 Inbound and outbound packet are matched to flows in a very fast and
45 scalable way, so that limits can be enforced with minimal performance
46 impact.
47
48
49 The flowadm command can be used to define a flow without imposing any
50 bandwidth resource control. This would result in the traffic type
51 getting its own resources and queues so that it is isolated from rest
52 of the networking traffic for more observable and deterministic
53 behavior.
54
55
56 flowadm is implemented as a set of subcommands with corresponding
57 options. Options are described in the context of each subcommand.
58
59 SUBCOMMANDS
60 The following subcommands are supported:
61
62 flowadm add-flow [-t] [-R root-dir] -l link -a attr=value[,...] [-p
63 prop=value[,...]] flow
64
65 Adds a flow to the system. The flow is identified by its flow
66 attributes and properties.
67
68 As part of identifying a particular flow, its bandwidth resource
69 can be limited and its relative priority to other traffic can be
70 specified. If no bandwidth limit or priority is specified, the
71 traffic still gets its unique layer 2, 3, and 4 queues and
72 processing threads, including NIC hardware resources (when
73 supported), so that the selected traffic can be separated from
74 others and can flow with minimal impact from other traffic.
75
76 -t, --temporary
77
78 The changes are temporary and will not persist across reboots.
79 Persistence is the default.
80
81
82 -R root-dir, --root-dir=root-dir
83
84 Specifies an alternate root directory where flowadm should
85 apply persistent creation.
86
87
88 -l link, --link=link
89
90 Specify the link to which the flow will be added.
91
92
93 -a attr=value[,...], --attr=value
94
95 A mandatory comma-separated list of attributes to be set to the
96 specified values.
97
98
99 -p prop=value[,...], --prop=value[,...]
100
101 An optional comma-separated list of properties to be set to the
102 specified values. Flow properties are documented in the "Flow
103 Properties" section, below.
104
105
106
107 flowadm remove-flow [-t] [-R root-dir] -l {link | flow}
108
109 Remove an existing flow identified by its link or name.
110
111 -t, --temporary
112
113 The changes are temporary and will not persist across reboots.
114 Persistence is the default.
115
116
117 -R root-dir, --root-dir=root-dir
118
119 Specifies an alternate root directory where flowadm should
120 apply persistent removal.
121
122
123 -l link | flow, --link=link | flow
124
125 If a link is specified, remove all flows from that link. If a
126 single flow is specified, remove only that flow.
127
128
129
130 flowadm show-flow [-pP] [-s [-i interval]] [-o field[,...]] [-l link]
131 [flow]
132
133 Show flow configuration information, either for all flows, all
134 flows on a link, or for the specified flow.
135
136 -o field[,...]
137
138 A case-insensitive, comma-separated list of output fields to
139 display. The field name must be one of the fields listed below,
140 or a special value all, to display all fields. For each flow
141 found, the following fields can be displayed:
142
143 flow
144
145 The name of the flow.
146
147
148 link
149
150 The name of the link the flow is on.
151
152
153 ipaddr
154
155 IP address of the flow. This can be either local or remote
156 depending on how the flow was defined.
157
158
159 proto
160
161 The name of the layer for protocol to be used.
162
163
164 lport
165
166 Local port of service for flow.
167
168
169 rport
170
171 Remote port of service for flow.
172
173
174 dsfld
175
176 Differentiated services value for flow and mask used with
177 DSFIELD value to state the bits of interest in the
178 differentiated services field of the IP header.
179
180
181
182 -p, --parsable
183
184 Display using a stable machine-parsable format.
185
186
187 -P, --persistent
188
189 Display persistent flow property information.
190
191
192 -l link, --link=link | flow
193
194 Display information for all flows on the named link or
195 information for the named flow.
196
197
198
199 flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow
200
201 Set values of one or more properties on the flow specified by name.
202 The complete list of properties can be retrieved using the show-
203 flowprop subcommand.
204
205 -t, --temporary
206
207 The changes are temporary and will not persist across reboots.
208 Persistence is the default.
209
210
211 -R root-dir, --root-dir=root-dir
212
213 Specifies an alternate root directory where flowadm should
214 apply persistent setting of properties.
215
216
217 -p prop=value[,...], --prop=value[,...]
218
219 A comma-separated list of properties to be set to the specified
220 values.
221
222
223
224 flowadm reset-flowprop [-t] [-R root-dir] -p [prop=value[,...]] flow
225
226 Resets one or more properties to their default values on the
227 specified flow. If no properties are specified, all properties are
228 reset. See the show-flowprop subcommand for a description of
229 properties, which includes their default values.
230
231 -t, --temporary
232
233 Specifies that the resets are temporary. Temporary resets last
234 until the next reboot.
235
236
237 -R root-dir, --root-dir=root-dir
238
239 Specifies an alternate root directory where flowadm should
240 apply persistent setting of properties.
241
242
243 -p prop=value[,...], --prop=value[,...]
244
245 A comma-separated list of properties to be reset.
246
247
248
249 flowadm show-flowprop [-cP] [-l link] [-p prop[,...]] [flow]
250
251 Show the current or persistent values of one or more properties,
252 either for all flows, flows on a specified link, or for the
253 specified flow.
254
255 By default, current values are shown. If no properties are
256 specified, all available flow properties are displayed. For each
257 property, the following fields are displayed:
258
259 FLOW
260
261 The name of the flow.
262
263
264 PROPERTY
265
266 The name of the property.
267
268
269 VALUE
270
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
280 The default value of the property. If the property has no
281 default value, -- (double hyphen), is shown.
282
283
284 POSSIBLE
285
286 A comma-separated list of the values the property can have. If
287 the values span a numeric range, the minimum and maximum values
288 might be shown as shorthand. If the possible values are unknown
289 or unbounded, -- (double hyphen), is shown.
290
291 Flow properties are documented in the "Flow Properties" section,
292 below.
293
294 -c
295
296 Display using a stable machine-parsable format.
297
298
299 -P, --persistent
300
301 Display persistent flow property information.
302
303
304 -p prop[,...], --prop=prop[,...]
305
306 A comma-separated list of properties to show.
307
308
309
310 Flow Attributes
311 The flow operand that identify a flow in a flowadm command is a comma-
312 separated list of one or more keyword, value pairs from the list below.
313
314 local_ip[/prefix_len]
315
316 Identifies a network flow by the local IP address. value must be a
317 IPv4 address in dotted-decimal notation or an IPv6 address in
318 colon-separated notation. prefix_len is optional.
319
320 If prefix_len is specified, it describes the netmask for a subnet
321 address, following the same notation convention of ifconfig(1M) and
322 route(1M) addresses. If unspecified, the given IP address will be
323 considered as a host address for which the default prefix length
324 for a IPv4 address is /32 and for IPv6 is /128.
325
326
327 remote_ip[/prefix_len]
328
329 Identifies a network flow by the remote IP address. The syntax is
330 the same as the local_ip attribute.
331
332
333 transport={tcp|udp|sctp|icmp|icmpv6}
334
335 Identifies a layer 4 protocol to be used. It is typically used in
336 combination with local_port to identify the service that needs
337 special attention.
338
339
340 local_port
341
342 Identifies a service specified by the local port.
343
344
345 remote_port
346
347 Identifies a service specified by the remote port.
348
349
350 dsfield[:dsfield_mask]
351
352 Identifies the 8-bit differentiated services field (as defined in
353 RFC 2474).
354
355 The optional dsfield_mask is used to state the bits of interest in
356 the differentiated services field when comparing with the dsfield
357 value. A 0 in a bit position indicates that the bit value needs to
358 be ignored and a 1 indicates otherwise. The mask can range from
359 0x01 to 0xff. If dsfield_mask is not specified, the default mask
360 0xff is used. Both the dsfield value and mask must be in
361 hexadecimal.
362
363
364
365 The following six types of combinations of attributes are supported:
366
367 local_ip[/prefixlen]=address
368 remote_ip[/prefixlen]=address
369 transport={tcp|udp|sctp|icmp|icmpv6}
370 transport={tcp|udp|sctp},local_port=port
371 transport={tcp|udp|sctp},remote_port=port
372 dsfield=val[:dsfield_mask]
373
374
375
376
377 On a given link, the types of combinations above are mutually
378 exclusive. An attempt to create flows of different types on a given
379 link will fail.
380
381 Restrictions
382 There are individual flow restrictions and flow restrictions per zone.
383
384 Individual Flow Restrictions
385 Restrictions on individual flows do not require knowledge of other
386 flows that have been added to the link.
387
388
389 An attribute can be listed only once for each flow. For example, the
390 following command is not valid:
391
392 # flowadm add-flow -l vnic1 -a local_port=80,local_port=8080 httpflow
393
394
395
396
397 transport and local_port:
398
399
400 TCP, UDP, or SCTP flows can be specified with a local port. An ICMP or
401 ICMPv6 flow that specifies a port is not allowed. The following
402 commands are valid:
403
404 # flowadm add-flow -l e1000g0 -a transport=udp udpflow
405 # flowadm add-flow -l e1000g0 -a transport=tcp,local_port=80 \
406 udp80flow
407
408
409
410
411 The following commands are not valid:
412
413 # flowadm add-flow -l e1000g0 -a local_port=25 flow25
414 # flowadm add-flow -l e1000g0 -a transport=icmpv6,local_port=16 \
415 flow16
416
417
418
419 Flow Restrictions Per Zone
420 Within a zone, no two flows can have the same name. After adding a flow
421 with the link specified, the link will not be required for display,
422 modification, or deletion of the flow.
423
424 Flow Properties
425 The following flow properties are supported. Note that the ability to
426 set a given property to a given value depends on the driver and
427 hardware.
428
429 maxbw
430
431 Sets the full duplex bandwidth for the flow. The bandwidth is
432 specified as an integer with one of the scale suffixes(K, M, or G
433 for Kbps, Mbps, and Gbps). If no units are specified, the input
434 value will be read as Mbps. The default is no bandwidth limit.
435
436
437 priority
438
439 Sets the relative priority for the flow. The value can be given as
440 one of the tokens high, medium, or low. The default is medium.
441
442
443 EXAMPLES
444 Example 1 Creating a Policy Around a Mission-Critical Port
445
446
447 The command below creates a policy around inbound HTTPS traffic on an
448 HTTPS server so that HTTPS obtains dedicated NIC hardware and kernel
449 TCP/IP resources. The name specified, https-1, can be used later to
450 modify or delete the policy.
451
452
453 # flowadm add-flow -l bge0 -a transport=TCP,local_port=443 https-1
454 # flowadm show-flow -l bge0
455 FLOW LINK IPADDR PROTO LPORT RPORT DSFLD
456 https1 bge0 -- tcp 443 -- --
457
458
459
460 Example 2 Modifying an Existing Policy to Add Bandwidth Resource
461 Control
462
463
464 The following command modifies the https-1 policy from the preceding
465 example. The command adds bandwidth control and give the policy a high
466 priority.
467
468
469 # flowadm set-flowprop -p maxbw=500M,priority=high https-1
470 # flowadm show-flow https-1
471 FLOW LINK IPADDR PROTO LPORT RPORT DSFLD
472 https-1 bge0 -- tcp 443 -- --
473
474 # flowadm show-flowprop https-1
475 FLOW PROPERTY VALUE DEFAULT POSSIBLE
476 https-1 maxbw 500 -- --
477 https-1 priority high -- low,medium,high
478
479
480
481 Example 3 Limiting the UDP Bandwidth Usage
482
483
484 The following command creates a policy for UDP protocol so that it
485 cannot consume more than 100Mbps of available bandwidth. The flow is
486 named limit-udp-1.
487
488
489 # flowadm add-flow -l bge0 -a transport=UDP -p maxbw=100M, \
490 priority=low limit-udp-1
491
492
493
494 Example 4 Setting Policy, Making Use of dsfield Attribute
495
496
497 The following command sets a policy for EF PHB (DSCP value of 101110
498 from RFC 2598) with a bandwidth of 500 Mbps and a high priority. The
499 dsfield value for this flow will be 0x2e (101110) with the dsfield_mask
500 being 0xfc (because we want to ignore the 2 least significant bits).
501
502
503 # flowadm add-flow -l bge0 -a dsfield=0x2e:0xfc \
504 -p maxbw=500M,priority=high efphb-flow
505
506
507
508 EXIT STATUS
509 0
510
511 All actions were performed successfully.
512
513
514 >0
515
516 An error occurred.
517
518
519 ATTRIBUTES
520 See attributes(5) for descriptions of the following attributes:
521
522
523
524
525 +--------------------+-----------------+
526 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
527 +--------------------+-----------------+
528 |Interface Stability | Committed |
529 +--------------------+-----------------+
530
531 SEE ALSO
532 dladm(1M), flowstat(1M), ifconfig(1M), route(1M), attributes(5)
533
534
535 NOTES
536 The display of statistics by the show-flow subcommand, and the show-
537 usage subcommand, have been removed. This functionality can now be
538 accessed using the flowstat(1M) utility.
539
540
541
542 February 26, 2020 FLOWADM(1M)