Print this page
4508 flowadm not working as documented, or documentation incorrect
4538 flowadm man page does not list lport and rport as output fields for show-flow
7210 flowadm does not have show-usage command described in the manual page

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