Tribblix: manual page: flowadm.8

FLOWADM(8) Maintenance Commands and Procedures FLOWADM(8)

NAME

flowadm - administer bandwidth resource control and priority for
protocols, services, containers, and virtual machines

SYNOPSIS

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 show-flow [-p] [-l link] [-o field[,...]] [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]

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

SUBCOMMANDS

The following subcommands are supported:

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
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, including 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 mandatory comma-separated list of attributes to be set to
the specified values.

-p prop=value[,...], --prop=value[,...]

An optional comma-separated list of properties to be set to
the specified values. Flow properties are documented in the
"Flow Properties" section, below.

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

Show flow configuration information, 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 following 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.

proto

The name of the layer for protocol to be used.

lport

Local port of service for flow.

rport

Remote port of service for flow.

dsfld

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, --parsable

Display using a stable machine-parsable 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 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-flowprop 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=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.

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

Display using a stable machine-parsable format.

-P, --persistent

Display persistent flow property information.

-p prop[,...], --prop=prop[,...]

A comma-separated list of properties to show.

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=value[/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(8)
and route(8) 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=value[/prefix_len]

Identifies a network flow by the remote IP address. The syntax is
the same as the local_ip attribute.

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

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

local_port=port

Identifies a service specified by the local port.

remote_port=port

Identifies a service specified by the remote port.

dsfield=value[: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.

The following six types of combinations of attributes are supported:

local_ip=address[/prefixlen]
remote_ip=address[/prefixlen]
transport={tcp|udp|sctp|icmp|icmpv6}
transport={tcp|udp|sctp},local_port=port
transport={tcp|udp|sctp},remote_port=port
dsfield=val[:dsfield_mask]

On a given link, the types of combinations above are mutually
exclusive. An attempt to create flows of different types on a given
link 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.

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 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 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 IPADDR PROTO LPORT RPORT 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 IPADDR PROTO LPORT RPORT DSFLD
https-1 bge0 -- tcp 443 -- --

# flowadm show-flowprop https-1
FLOW PROPERTY VALUE DEFAULT POSSIBLE
https-1 maxbw 500 -- --
https-1 priority high -- low,medium,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, \
priority=low limit-udp-1

Example 4: 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

EXIT STATUS

0

All actions were performed successfully.

>0

An error occurred.

ATTRIBUTES

NOTES

The display of statistics by the show-flow subcommand, and the show-
usage subcommand, have been removed. This functionality can now be
accessed using the flowstat(8) utility.

February 5, 2022 FLOWADM(8)