System Administration Commands flowadm(1M) NAME flowadm - administer bandwidth resource control and priority for protocols, services, containers, and virtual machines SYNOPSIS flowadm show-flow [-pP] [-S] [-s [-i interval]] [-l link] [-o field[,...]] [flow] flowadm add-flow [-t] [-R root-dir] -l link -a attr=value[,...] -p prop=value[,...] flow flowadm remove-flow [-t] [-R root-dir] {-l link | flow} flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow flowadm reset-flowprop [-t] [-R root-dir] [-p prop[,...]] flow flowadm show-flowprop [-cP] [-l link] [-o field[,...]] [-p prop[,...]] [flow] flowadm show-usage [-a] [-d | -F format] [-s time] [-e time] -f filename [flow] DESCRIPTION The flowadm command is used to create, modify, remove, and show networking bandwidth and associated resources for a type of traffic on a particular link. The flowadm command allows users to manage networking bandwidth resources for a transport, service, or a subnet. The service is specified as a combination of transport and local port. The subnet is specified by its IP address and subnet mask. The command can be used on any type of data link, including physical links, virtual NICs, and link aggregations. A flow is defined as a set of attributes based on Layer 3 and Layer 4 headers, which can be used to identify a proto- col, service, or a virtual machine. When a flow is identi- fied based on flow attributes, separate kernel resources including layer 2, 3, and 4 queues, their processing threads, and other resources are uniquely created for it, such that other traffic has minimal or zero impact on it. Inbound and outbound packet are matched to flows in a very fast and scalable way, so that limits can be enforced with minimal performance impact. SunOS 5.11 Last change: 16 Jan 2009 1 System Administration Commands flowadm(1M) The flowadm command can be used to identify a flow without imposing any bandwidth resource control. This would result in the traffic type getting its own resources and queues so that it is isolated from rest of the networking traffic for more observable and deterministic behavior. flowadm is implemented as a set of subcommands with corresponding options. Options are described in the context of each subcommand. SUB-COMMANDS The following subcommands are supported: flowadm show-flow [-pP] [-s [-i interval]] [-o field[,...]] [-l link] [flow] Show flow configuration information (the default) or statistics, either for all flows, all flows on a link, or for the specified flow. -o field[,...] A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or a special value all, to display all fields. For each flow found, the follow- ing fields can be displayed: flow The name of the flow. link The name of the link the flow is on. ipaddr IP address of the flow. This can be either local or remote depending on how the flow was defined. transport The name of the layer for protocol to be used. port SunOS 5.11 Last change: 16 Jan 2009 2 System Administration Commands flowadm(1M) Local port of service for flow. dsfield Differentiated services value for flow and mask used with DSFIELD value to state the bits of interest in the differentiated services field of the IP header. -p, --parseable Display using a stable machine-parseable format. -P, --persistent Display persistent flow property information. -S, --continuous This option is made obsolete by flowstat(1M) -w. -s, --statistics This option is made obsolete by flowstat(1M). -i interval, --interval=interval This option is made obsolete by flowstat(1M). -l link, --link=link | flow Display information for all flows on the named link or information for the named flow. flowadm add-flow [-t] [-R root-dir] -l link -a attr=value[,...] -p prop=value[,...] flow SunOS 5.11 Last change: 16 Jan 2009 3 System Administration Commands flowadm(1M) Adds a flow to the system. The flow is identified by its flow attributes and properties. As part of identifying a particular flow, its bandwidth resource can be limited and its relative priority to other traffic can be specified. If no bandwidth limit or priority is specified, the traffic still gets its unique layer 2, 3, and 4 queues and processing threads, includ- ing NIC hardware resources (when supported), so that the selected traffic can be separated from others and can flow with minimal impact from other traffic. -t, --temporary The changes are temporary and will not persist across reboots. Persistence is the default. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where flowadm should apply persistent creation. -l link, --link=link Specify the link to which the flow will be added. -a attr=value[,...], --attr=value A comma-separated list of attributes to be set to the specified values. -p prop=value[,...], --prop=value[,...] A comma-separated list of properties to be set to the specified values. flowadm remove-flow [-t] [-R root-dir] -l {link | flow} Remove an existing flow identified by its link or name. -t, --temporary The changes are temporary and will not persist across reboots. Persistence is the default. SunOS 5.11 Last change: 16 Jan 2009 4 System Administration Commands flowadm(1M) -R root-dir, --root-dir=root-dir Specifies an alternate root directory where flowadm should apply persistent removal. -l link | flow, --link=link | flow If a link is specified, remove all flows from that link. If a single flow is specified, remove only that flow. flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow Set values of one or more properties on the flow speci- fied by name. The complete list of properties can be retrieved using the show-flow subcommand. -t, --temporary The changes are temporary and will not persist across reboots. Persistence is the default. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where flowadm should apply persistent setting of properties. -p prop=value[,...], --prop=value[,...] A comma-separated list of properties to be set to the specified values. flowadm reset-flowprop [-t] [-R root-dir] -p [prop=value[,...]] flow Resets one or more properties to their default values on the specified flow. If no properties are specified, all properties are reset. See the show-flowprop subcommand for a description of properties, which includes their default values. -t, --temporary Specifies that the resets are temporary. Temporary SunOS 5.11 Last change: 16 Jan 2009 5 System Administration Commands flowadm(1M) resets last until the next reboot. -R root-dir, --root-dir=root-dir Specifies an alternate root directory where flowadm should apply persistent setting of properties. -p prop=value[,...], --prop=value[,...] A comma-separated list of properties to be reset. flowadm show-flowprop [-cP] [-l link] [-p prop[,...]] [flow] Show the current or persistent values of one or more properties, either for all flows, flows on a specified link, or for the specified flow. By default, current values are shown. If no properties are specified, all available flow properties are displayed. For each property, the following fields are displayed: FLOW The name of the flow. PROPERTY The name of the property. VALUE The current (or persistent) property value. The value is shown as -- (double hyphen), if it is not set, and ? (question mark), if the value is unknown. Persistent values that are not set or have been reset will be shown as -- and will use the system DEFAULT value (if any). DEFAULT The default value of the property. If the property has no default value, -- (double hyphen), is shown. SunOS 5.11 Last change: 16 Jan 2009 6 System Administration Commands flowadm(1M) POSSIBLE A comma-separated list of the values the property can have. If the values span a numeric range, the minimum and maximum values might be shown as short- hand. If the possible values are unknown or unbounded, -- (double hyphen), is shown. Flow properties are documented in the "Flow Properties" section, below. -c, --parseable Display using a stable machine-parseable format. -P, --persistent Display persistent flow property information. -p prop[,...], --prop=prop[,...] A comma-separated list of properties to show. flowadm show-usage [-a] [-d | -F format] [-s time] [-e time] -f filename [flow] This subcommand is made obsolete by flowstat(1M) -h. SunOS 5.11 Last change: 16 Jan 2009 7 System Administration Commands flowadm(1M) Flow Attributes The flow operand that identify a flow in a flowadm command is a comma-separated list of one or more keyword, value pairs from the list below. local_ip[/prefix_len] Identifies a network flow by the local IP address. value must be a IPv4 address in dotted-decimal notation or an IPv6 address in colon-separated notation. prefix_len is optional. If prefix_len is specified, it describes the netmask for a subnet address, following the same notation convention of ifconfig(1M) and route(1M) addresses. If unspecified, the given IP address will be considered as a host address for which the default prefix length for a IPv4 address is /32 and for IPv6 is /128. remote_ip[/prefix_len] Identifies a network flow by the remote IP address. The syntax is the same as local_ip attributes SunOS 5.11 Last change: 16 Jan 2009 8 System Administration Commands flowadm(1M) transport={tcp|udp|sctp|icmp|icmpv6} Identifies a layer 4 protocol to be used. It is typi- cally used in combination with local_port to identify the service that needs special attention. local_port Identifies a service specified by the local port. dsfield[:dsfield_mask] Identifies the 8-bit differentiated services field (as defined in RFC 2474). The optional dsfield_mask is used to state the bits of interest in the differentiated services field when com- paring with the dsfield value. A 0 in a bit position indicates that the bit value needs to be ignored and a 1 indicates otherwise. The mask can range from 0x01 to 0xff. If dsfield_mask is not specified, the default mask 0xff is used. Both the dsfield value and mask must be in hexadecimal. The following five types of combinations of attributes are supported: local_ip[/prefixlen]=address remote_ip[/prefixlen]=address transport={tcp|udp|sctp|icmp|icmpv6} transport={tcp|udp|sctp},local_port=port dsfield=val[:dsfield_mask] On a given link, the combinations above are mutually exclusive. An attempt to create flows of different combina- tions will fail. Restrictions There are individual flow restrictions and flow restrictions per zone. Individual Flow Restrictions Restrictions on individual flows do not require knowledge of other flows that have been added to the link. SunOS 5.11 Last change: 16 Jan 2009 9 System Administration Commands flowadm(1M) An attribute can be listed only once for each flow. For example, the following command is not valid: # flowadm add-flow -l vnic1 -a local_port=80,local_port=8080 httpflow transport and local_port: TCP, UDP, or SCTP flows can be specified with a local port. An ICMP or ICMPv6 flow that specifies a port is not allowed. The following commands are valid: # flowadm add-flow -l e1000g0 -a transport=udp udpflow # flowadm add-flow -l e1000g0 -a transport=tcp,local_port=80 \ udp80flow The following commands are not valid: # flowadm add-flow -l e1000g0 -a local_port=25 flow25 # flowadm add-flow -l e1000g0 -a transport=icmpv6,local_port=16 \ flow16 Flow Restrictions Per Zone Within a zone, no two flows can have the same name. After adding a flow with the link specified, the link will not be required for display, modification, or deletion of the flow. Flow Properties The following flow properties are supported. Note that the ability to set a given property to a given value depends on the driver and hardware. maxbw Sets the full duplex bandwidth for the flow. The bandwidth is specified as an integer with one of the scale suffixes(K, M, or G for Kbps, Mbps, and Gbps). If no units are specified, the input value will be read as Mbps. The default is no bandwidth limit. priority Sets the relative priority for the flow. The value can SunOS 5.11 Last change: 16 Jan 2009 10 System Administration Commands flowadm(1M) be given as one of the tokens high, medium, or low. The default is medium. EXAMPLES Example 1 Creating a Policy Around a Mission-Critical Port The command below creates a policy around inbound HTTPS traffic on an HTTPS server so that HTTPS obtains dedicated NIC hardware and kernel TCP/IP resources. The name speci- fied, https-1, can be used later to modify or delete the policy. # flowadm add-flow -l bge0 -a transport=TCP,local_port=443 https-1 # flowadm show-flow -l bge0 FLOW LINK IP ADDR PROTO PORT DSFLD https1 bge0 -- tcp 443 -- Example 2 Modifying an Existing Policy to Add Bandwidth Resource Control The following command modifies the https-1 policy from the preceding example. The command adds bandwidth control and give the policy a high priority. # flowadm set-flowprop -p maxbw=500M,priority=high https-1 # flowadm show-flow https-1 FLOW LINK IP ADDR PROTO PORT DSFLD https1 bge0 -- tcp 443 -- # flowadm show-flowprop https-1 FLOW PROPERTY VALUE DEFAULT POSSIBLE https-1 maxbw 500 -- -- https-1 priority HIGH -- LOW,NORMAL,HIGH Example 3 Limiting the UDP Bandwidth Usage The following command creates a policy for UDP protocol so that it cannot consume more than 100Mbps of available bandwidth. The flow is named limit-udp-1. # flowadm add-flow -l bge0 -a transport=UDP -p maxbw=100M, \ SunOS 5.11 Last change: 16 Jan 2009 11 System Administration Commands flowadm(1M) priority=low limit-udp-1 Example 4 Showing Flow Usage Flow usage statistics can be stored using the extended accounting facility, acctadm(1M). # acctadm -e extended -f /var/log/net.log net # acctadm net Network accounting: active Network accounting file: /var/log/net.log Tracked Network resources: extended Untracked Network resources: none The historical data that was saved can be retrieved in sum- mary form using the show-usage subcommand of flowadm. Example 5 Setting Policy, Making Use of dsfield Attribute The following command sets a policy for EF PHB (DSCP value of 101110 from RFC 2598) with a bandwidth of 500 Mbps and a high priority. The dsfield value for this flow will be 0x2e (101110) with the dsfield_mask being 0xfc (because we want to ignore the 2 least significant bits). # flowadm add-flow -l bge0 -a dsfield=0x2e:0xfc \ -p maxbw=500M,priority=high efphb-flow Display summary information: # flowadm show-usage -f /var/log/net.log FLOW DURATION IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH flowtcp 100 1031 546908 0 0 43.76 Kbps flowudp 0 0 0 0 0 0.00 Mbps SunOS 5.11 Last change: 16 Jan 2009 12 System Administration Commands flowadm(1M) Display dates for which logging information is available: # flowadm show-usage -d -f /var/log/net.log 02/19/2008 Display logging information for flowtcp starting at 02/19/2008, 10:38:46 and ending at 02/19/2008, 10:40:06: FLOW DURATION IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH tcpflow1 20 16 2066 13 2606 0.001 Mbps # flowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \ -f /var/log/net.log flowtcp FLOW START END RBYTES OBYTES BANDWIDTH flowtcp 10:39:06 10:39:26 1546 6539 3.23 Kbps flowtcp 10:39:26 10:39:46 3586 9922 5.40 Kbps flowtcp 10:39:46 10:40:06 240 216 182.40 bps flowtcp 10:40:06 10:40:26 0 0 0.00 bps Output the same information as above as a plotfile: # flowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \ -F gnuplot -f /var/log/net.log flowtcp # Time tcp-flow 10:39:06 3.23 10:39:26 5.40 10:39:46 0.18 10:40:06 0.00 EXIT STATUS 0 All actions were performed successfully. >0 An error occurred. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: SunOS 5.11 Last change: 16 Jan 2009 13 System Administration Commands flowadm(1M) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcnetr | |_____________________________|_____________________________| | Interface Stability | Committed* | |_____________________________|_____________________________| * flowadm show-flow's -s and -i are committed obselete. SEE ALSO acctadm(1M), dladm(1M), flowstat(1M), ifconfig(1M), prstat(1M), route(1M), attributes(5), dlpi(7P) SunOS 5.11 Last change: 16 Jan 2009 14