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 {-p plotfile -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: 14 Feb 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-COMANDS
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: 14 Feb 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
Continuously display network utilization by flow in
a manner similar to the way that prstat(1M) displays
CPU utilization by process.
-s, --statistics
Displays flow statistics.
-i interval, --interval=interval
Used with the -s option to specify an interval, in
seconds, at which statistics should be displayed. If
this option is not specified, statistics are
displayed once.
-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: 14 Feb 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: 14 Feb 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: 14 Feb 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: 14 Feb 2009 6
System Administration Commands flowadm(1M)
POSIBLE
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 {-p plotfile -F format}] [-s
time] [-e time] [flow]
Show the historical network flow usage from a stored
extended accounting file. Configuration and enabling of
network accounting through acctadm(1M) is required. The
default output will be the summary of flow usage for the
entire period of time in which extended accounting was
enabled.
-a
Display all historical network usage for the speci-
fied period of time during which extended accounting
is enabled. This includes the usage information for
the flows that have already been deleted.
-d
Display the dates for which there is logging infor-
mation. The date is in the format D/M/Y.
SunOS 5.11 Last change: 14 Feb 2009 7
System Administration Commands flowadm(1M)
-F format
Specifies the format of plotfile that is specified
by the -p option. As of this release, gnuplot is the
only supported format.
-p plotfile
When specified with -s or -e (or both), outputs flow
usage data to a file of the format specified by the
-F option, which is required.
-s time, -e time
Start and stop times for data display. Time is in
the format Y.M.D,hh:mm:ss.
-f filename
Read extended accounting records of network flow
usage from filename.
flow
If specified, display the network flow usage only
from the named flow. Otherwise, display network
usage from all flows.
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.
localip[/prefixlen]
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. prefixlen is
optional.
If prefixlen 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.
SunOS 5.11 Last change: 14 Feb 2009 8
System Administration Commands flowadm(1M)
remoteip[/prefixlen]
Identifies a network flow by the remote IP address. The
syntax is the same as localip attributes
transport={tcpudpsctpicmpicmpv6}
Identifies a layer 4 protocol to be used. It is typi-
cally used in combination with localport to identify
the service that needs special attention.
localport
Identifies a service specified by the local port.
dsfield[:dsfieldmask]
Identifies the 8-bit differentiated services field (as
defined in RFC 2474).
The optional dsfieldmask 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 dsfieldmask 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:
localip[/prefixlen]=address
remoteip[/prefixlen]=address
transport={tcpudpsctpicmpicmpv6}
transport={tcpudpsctp},localport=port
dsfield=val[:dsfieldmask]
On a given link, the combinations above are mutually
exclusive. An attempt to create flows of different combina-
tions will fail.
Restrictions
SunOS 5.11 Last change: 14 Feb 2009 9
System Administration Commands flowadm(1M)
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.
An attribute can be listed only once for each flow. For
example, the following command is not valid:
# flowadm add-flow -l vnic1 -a localport=80,localport=8080 httpflow
transport and localport:
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,localport=80 \
udp80flow
The following commands are not valid:
# flowadm add-flow -l e1000g0 -a localport=25 flow25
# flowadm add-flow -l e1000g0 -a transport=icmpv6,localport=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
SunOS 5.11 Last change: 14 Feb 2009 10
System Administration Commands flowadm(1M)
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
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 HTPS
traffic on an HTPS server so that HTPS 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,localport=443 https-1
# flowadm show-flow -l bge0
FLOW LINK IP ADR 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 ADR PROTO PORT DSFLD
https1 bge0 -- tcp 443 --
# flowadm show-flowprop https-1
FLOW PROPERTY VALUE DEFAULT POSIBLE
https-1 maxbw 500 -- --
https-1 priority HIGH -- LOW,NORMAL,HIGH
SunOS 5.11 Last change: 14 Feb 2009 11
System Administration Commands flowadm(1M)
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, \
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 dsfieldmask 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
SunOS 5.11 Last change: 14 Feb 2009 12
System Administration Commands flowadm(1M)
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 \
-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 \
-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
EXIT STATUS
0
All actions were performed successfully.
SunOS 5.11 Last change: 14 Feb 2009 13
System Administration Commands flowadm(1M)
>0
An error occurred.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcnetr
Interface Stability Committed
SEE ALSO
acctadm(1M), dladm(1M), ifconfig(1M), prstat(1M), route(1M),
attributes(5), dlpi(7P)
SunOS 5.11 Last change: 14 Feb 2009 14
|
