Go to main content

man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2017
 
 

flowadm(1M)

Name

flowadm - Administer bandwidth resource control and priority for a connection, protocols, services, containers, and virtual machines.

Synopsis

flowadm
flowadm show-flow [-P] [[-p] -o field[,...]] [{-l link | flow}]
flowadm match-flow [-P] [[-p] -o  field[,...]] [-l link]
           -a attr=value[,...]
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 [-P] [[-c] -o field[,...]] [-l link]
     [-p prop[,...]] [flow]
flowadm help [subcommand-name]

Description

The flowadm command is used to create, modify, remove, and show networking bandwidth, priority 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 can be specified as a combination of all or some of the attributes: transport, local port, remote port, local IP address, and remote IP address. 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, a single connection, or a virtual machine.

There are restrictions on valid flow names. First, flow names cannot be longer than 31 characters. Second, flow names must consist only of alphanumeric (a-z, A-Z, 0-9), underscore ('_'), period ('.') and hyphen ('-'), and must begin with alphabetic characters.

The flowadm command can be used to identify a flow without imposing any bandwidth resource control. This would result in better observability for the flow when used along with flowstat(1M).

Flows can be created, modified, and removed in all of global, non-global and kernel zones. A zone administrator can create a flow only in his zone, global or non-global. However, a flow created in the global zone can migrate to a non-global zone, as described in the following paragraph. An administrator can modify or remove a flow only from within the zone, glo- bal or non-global, in which the flow was created. From the global zone, one can view all flows on a system, within the global and any non-global zones. From a non-global zone, one can view only those flows in that zone.

After an administrator creates a flow in the global zone, the data link associated with that flow can be assigned to a non-global zone. In such a case, the associated flow is also assigned to the same non-global zone. When this non-global zone is halted, the data link and its associated flow return to the global zone.

Different zone names distinguish flows of the same name. For example, one can have three flows named fastpak, if each fastpak is in a different zone. For example, zone1/fastpak, zone2/fastpak , and zone3/fastpak are all valid zone names.

All flow confiugration is part of a Network Confiugration Profile (NCP). Any number of NCPs may be defined on a system, but there will always be one active NCP. Changes made using the flowadm command will be applied to the currently active NCP.

NCPs may be 'fixed' or 'reactive'. There is one fixed NCP, called DefaultFixed. Refer to netcfg(1M) for more information about NCPs.

flowadm is implemented as a set of subcommands with corresponding options. Options are described in the context of each subcommand. If flowadm is invoked with no subcommand, then all of the flows configured on the system will be displayed. See EXAMPLES below for more information.

Sub Commands

The following subcommands are supported:

flowadm show-flow [–P] [[–p] –o field[,...]] [{–l link | flow}]

Show flow configuration information either for all flows, all flows on a link, or for the specified flow. Output is in ranking order, that is, the first flow in the output is searched first for a given packet and so on.

–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 following fields can be displayed:

flow

The name of the flow.

link

The name of the link the flow is on.

proto

The name of the transport layer protocol to be used.

laddr

Local IP address of the flow. If not specified, it will be shown as '--'.

lport

Local port of service for flow.

raddr

Remote IP address of the flow. If not specified, it will be shown as '--'.

rport

Remote port of service for flow.

dir

Flow direction. Values are 'in' for inbound only, 'out' for outbound only, or 'bi' for bidirectional.

dsfld

Differentiated services value for flow and mask used with DSFLD value to state the bits of interest in the differentiated services field of the IP header. This field is not shown in the default flowadm output, but can be displayed with:

flowadm show-flow -o all

or

flowadm show-flow -o flow,dsfld
ipaddr

IP address of the flow. This can be either local or remote depending on how the flow was defined. This field is deprecated and exists only for backward compatibility. Therefore it will not be shown by default, unless specified with –o option. The users are encouraged to use laddr and raddr instead.

pid

Specifies the PID of the process that created this flow. This field is meaningful only for the system generated flows and will show '--' for user generated flows.

A system generated flow has the prefix "<id>.sys.sock" and is a temporary flow that gets created by applications that call setsockopt() with the SO_FLOW_SLA option.

–p, ––parseable

Display using a stable machine-parseable format.

–P, ––persistent

Display persistent flow property information.

–l link, ––link=link | flow

Display information for all flows on the named link or information for the named flow.

flowadm match-flow [–P] [[–p] –o field[,...]] [–l link] –a attr=value[,...]

Finds a flow(s) that is a potential match for the specified list of flow attributes among the existing flows on the system. In case multiple flows are returned, they are shown in the order they are looked up for flow classification of a packet.

–p, –-parseable

Display using a stable machine-parseable format.

–P, –-persistent

Display persistent flow property information.

–o field[,...]

See –o field para for show-flow subcommand above.

–l link, –-link=link

Limit the match to flows on the specified link. If no link is specified, flows on all the links are used.

–a attr=value[,...], –-attr=value

A comma-separated list of attributes that is used as the key for the lookup for a matching flow(s).

flowadm add-flow [–t] [–R root-dir] –l link –a attr=value[,...] –p prop=value[,...] flow

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, and priority can be limited.

–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.

–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 specified 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 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[,...]

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.

PERM

The permission of the property. 'r-' for read-only property and 'rw' for the property that can be both read and written.

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.

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 shorthand. 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 help [subcommand-name]

Displays all the supported flowadm subcommands or usage for the given subcommand. If you display help for a specific subcommand, the command syntax is displayed, along with an example. Using flowadm help without any argument displays all the subcommands.

Flow Attributes

The flow operand that identifies 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

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

Identifies a layer 4 protocol to be used. It is typically used in combination with local_port or remote_port to identify the local or remote service that needs special attention.

local_port

Identifies a service specified by the local port.

remote_port

Identifies a service specified by the remote port.

direction={in|out|bi}

Identifies the flow direction as inbound only, or outbound only or bidirectional. A flow is treated as bidirectional if this attributes is not specified.

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 comparing 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.

All combinations of attributes are allowed. This removes the limitation in earlier releases, where only some combinations were allowed.

Flows with different combinations of attributes can be created on a link. This removes the limitation in earlier releases, where all the flows on a given link must have the same combination of flow attributes.

Note that when flows with different combinations of attributes are created, they can be either mutually exclusive or they can be overlapping (non exclusive).

In the latter case, the flows are ranked using the number of attributes specified when creating the flow. Flows with the same number of attributes are ranked based on a system default policy. flowadm show-flow output lists the set of flows on a given link in the ranking order, that is, the first flow in the output is searched first for a given packet and so on.

Restrictions

There are individual flow restrictions and flow restrictions per zone.

Individual Flow Restrictions

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 or transport and remote_port:

TCP, UDP, or SCTP flows can be specified with a local port or with a remote 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 command is not valid:

# flowadm add-flow -l e1000g0 -a transport=icmpv6,remote_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 priority of the flow. Priority values can take one of 'high', 'medium' and 'low'. The default value of priority is 'medium'.

Setting the token to 'high' on a flow has the effect that packets classified to that flow are processed ahead of packets from normal flows on the same link. Also, the flow is offloaded to the NIC if the NIC has the flow offload capability. A high priority flow may offer a better latency depending on the availability of system resources.

dscp

Sets the specified DSCP value on all outgoing IP packets for the flow. The valid values are 0 to 63. The value must be specified in decimal. For IPV4, set the six DSCP bits in the DSCP field and for IPv6 set the 6 DSCP bits in the traffic class field. The two ECN bits are untouched. This conforms to RFC 2474.

Note that any IP_TOS value set by an application using setsockopt (3C) is overwritten if the 'dscp' property is set on the flow and the packet is classified to that flow.

hwflow

Read-only property that shows whether the flow is offloaded to the underlying NIC. 'on' means the flow is offloaded and 'off' denotes otherwise.

rank

Specify the rank for a flow. Valid values for a 'rank' are 1 to 65535.

There is no requirement to set the rank property on all the flows. A flow with the rank property specified is always ahead in lookup order than a flow with no rank specified.

A flow with a low rank value is ahead in lookup order than a flow with a high rank value. It is legal to have two flows with the same rank. In this case, any tie is broken by following the default system policy.

Examples

Example 1 Displaying Flow Configuration

The following command invokes flowadm with no arguments, thereby displaying all flows in the system.

# flowadm
	FLOW        LINK     PROTO LADDR             LPORT RADDR             RPORT DIR  
       tcpflow     net0     tcp   --                --    --                --    bi
       udpflow     net0     udp   --                --    --                --    bi
Example 2 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 net0 -a transport=TCP,local_port=443 https-1
	# flowadm show-flow -l net0
	FLOW        LINK     PROTO LADDR             LPORT RADDR             RPORT DSFLD
	https-1     net0     tcp   --                443   --                --    bi
Example 3 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.


# flowadm set-flowprop -p maxbw=500M https-1
	#  flowadm show-flow https-1
	FLOW        LINK     PROTO LADDR             LPORT RADDR             RPORT DSFLD
	https-1     net0     tcp   --                443   --                --    bi

# flowadm show-flowprop https-1
	FLOW         PROPERTY        PERM VALUE          DEFAULT        POSSIBLE
	https-1      maxbw           rw     500          --             -- 
	https-1      priority        rw   medium         medium         low,medium,high 
	https-1      hwflow          r-   off            --             on,off 

Example 4 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 net0 -a transport=UDP -p maxbw=100M \
       limit-udp-1
Example 5 Setting Policy to a Flow Defined by Local Address/Port

The following command creates a policy for a TCP flow whose local ip port is 192.168.200.102:443. That is, we want to give special treatment to HTTPS packets such that it is delivered with high priority and maximum bandwidth of 800 Mbps.

# flowadm add-flow -l net0 -a transport=tcp,\
       local_ip=192.168.200.102,local_port=443 \
       -p priority=high,maxbw=800M my-https

# flowadm show-flow
	FLOW        LINK     PROTO LADDR             LPORT RADDR             RPORT DSFLD
	my-https    net0     tcp   192.168.200.102   443   --                --    bi

# flowadm show-flowprop
	FLOW         PROPERTY        PERM VALUE          DEFAULT        POSSIBLE
	my-https     maxbw           rw     800          --             -- 
	my-https     priority        rw   high           medium         low,medium,high 
	my-https     hwflow          r-   off            --             on,off
Example 6 Setting Policy to a Flow Defined by Local/Remote Address/Port

The following command creates a policy for a TCP flow whose local ip port is 192.168.200.102:443 and remote ip port is 192.168.200.104:12785. That is, we want to give special treatment to HTTPS packets that are communicating with specific remote ip port. Any packets that belong to this flow will be delivered with high priority. At the same time this flow cannot consume more that 800 Mbps of available bandwidth.

# flowadm add-flow -l net0 -a transport=tcp,\
       local_ip=192.168.200.102,local_port=443,\
       remote_ip=192.168.200.104,remote_port=12785 \
       -p priority=high,maxbw=800M my-flow

# flowadm show-flow
	FLOW        LINK     PROTO LADDR             LPORT RADDR             RPORT DSFLD
	my-flow     net0     tcp   192.168.200.102   443   192.168.200.104   12785 bi

# flowadm show-flowprop
	FLOW         PROPERTY        PERM VALUE          DEFAULT        POSSIBLE
	my-flow      maxbw           rw     800          --             -- 
	my-flow      priority        rw   high           medium         low,medium,high 
	my-flow      hwflow          r-   off            --             on,off 
Example 7 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. 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 net0 -a dsfield=0x2e:0xfc
-p maxbw=500M efphb-flow
Example 8 Viewing Flows in Multiple Zones

The following command shows two flows of the same name. The first flow is in the global zone, the second is in the zone zone1. The command is invoked from the global zone, enabling you to view all flows on the system

# flowadm 
	FLOW        LINK     PROTO LADDR             LPORT RADDR             RPORT DSFLD
	tcpflow     net0     tcp   --                --    --                --    bi
	zone1/tcpflow zone1/net0 tcp   --                --    --                --    bi
Example 9 Getting the Processes That Created a System Flow

The following command shows how to get the pid and the process name, given a system flow.


# flowadm
	FLOW        LINK     PROTO LADDR             LPORT RADDR             RPORT DSFLD
	1.sys.sock  net5     tcp   10.1.5.100        51204 10.1.5.101        22    bi

# ps `flowadm show-flow -p -o pid 5.sys.sock`
      PID TT       S  TIME COMMAND
     1581 pts/1    T  0:00 ssh 10.1.5.101

The following command shows how to find any flows created by a pid.

# flowadm show-flow  -p -o pid,flow | grep 1581
      1581:1.sys.sock
Example 10 Setting Bandwidth Limit on an Outbound Only Flow

The following command shows how to create an outbound only flow and set some bandwidth limit on it.

# flowadm add-flow -l net4 -a remote_ip=10.1.5.101,direction=out backup
# flowadm set-flowprop -p maxbw=500M backup

Exit Status

0

All actions were performed successfully.

>0

An error occurred.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/network
Interface Stability
Committed

See Also

acctadm(1M), dladm(1M), flowstat(1M), ifconfig(1M), prstat(1M), route(1M), attributes(5), ifconfig(1M)

Notes

The show-usage subcommand, present in previous releases of flowadm, has been replaced by the flowstat(1M) –h command.