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