te
Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
flowadm - administer bandwidth resource control and priority for protocols, services, containers, and virtual machines

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 | {-p plotfile -F format}] [-s time]
 [-e time] -f filename [flow]

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 protocol, service, or a virtual machine. When a flow is identified 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.

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.

The following subcommands are supported:

flowadm show-flow [-pP] [-s [-i interval]] [-o field[,...]] [-l link] [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=value[,...]] flow

flowadm show-flowprop [-cP] [-l link] [-p prop[,...]] [flow]

flowadm show-usage [-a] [-d | {-p plotfile -F format}] [-s time] [-e time] [flow]

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]

remote_ip[/prefix_len]

transport={tcp|udp|sctp|icmp|icmpv6}

local_port

dsfield[:dsfield_mask]

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 combinations will fail.

There are individual flow restrictions and flow restrictions per zone.

Restrictions on individual flows do not require knowledge of other flows that have been added to the link.

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 \e
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 \e
flow16

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.

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

priority

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 specified, 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, \e
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 summary 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 \e
-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

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:

# flowadm show-usage -s 02/19/2008,10:39:06 -e 02/19/2008,10:40:06 \e
-f /var/log/net.log flowtcp
FLOW TIME IPACKETS RBYTES OPACKETS OBYTES BANDWIDTH
flowtcp 10:39:06 1 1546 4 6539 3.23 Kbps
flowtcp 10:39:26 2 3586 5 9922 5.40 Kbps
flowtcp 10:39:46 1 240 1 216 182.40 bps
flowtcp 10:40:06 0 0 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 \e
-p /home/plot/myplot -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

0

>0

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed

acctadm(1M), dladm(1M), ifconfig(1M), prstat(1M), route(1M), attributes(5), dlpi(7P)