flowadm man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

FLOWADM(1M)							   FLOWADM(1M)

NAME
       flowadm - administer bandwidth resource control and priority for proto‐
       cols, services, containers, and virtual machines

SYNOPSIS
       flowadm show-flow [-pP] [-S] [-s [-i interval]] [-l link]
	    [-o field[,...]] [-z zonename] [flow]

       flowadm add-flow [-t] [-R root-dir] [-z zonename] -l link
	    -a attr=value[,...] -p prop=value[,...] flow
       flowadm remove-flow [-t] [-R root-dir] [-z zonename] {-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  net‐
       working	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 speci‐
       fied as a combination of transport and local port. The subnet is speci‐
       fied  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  vir‐
       tual machine. When a flow is identified based on flow attributes, sepa‐
       rate kernel resources including layer 2, 3, and 4  queues,  their  pro‐
       cessing	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 get‐
       ting 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]
       [-z zonename] [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 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.

	       transport

		   The name of the layer for protocol to be used.

	       port

		   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  differ‐
		   entiated 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 informa‐
	       tion for the named flow.

	   -z zonename

	       Operate on a link that has  been	 delegated  to	the  specified
	       zone.

       flowadm add-flow [-t] [-R root-dir] [-z zonename] -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 process‐
	   ing	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.

	   -z zonename

	       Operate	on  a  link  that  has been delegated to the specified
	       zone.

	   -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] [-z zonename] -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.

	   -z zonename

	       Operate on a link that has  been	 delegated  to	the  specified
	       zone.

	   -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 speci‐
	   fied flow. If no  properties	 are  specified,  all  properties  are
	   reset.  See the show-flowprop subcommand for a description of prop‐
	   erties, 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 speci‐
	   fied flow.

	   By default, current values are shown. If no properties  are	speci‐
	   fied,  all  available flow properties are displayed. For each prop‐
	   erty, 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, --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  specified	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 information. The
	       date is in the format DD/MM/YYYY.

	   -F format

	       Specifies the format of plotfile that is specified  by  the  -p
	       option.	As of this release, gnuplot is the only supported for‐
	       mat.

	   -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
	       YYYY.MM.DD,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.

       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 to identify the service that needs spe‐
	   cial 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 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 hexadeci‐
	   mal.

       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.

   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  com‐
       mands 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	 hard‐
       ware.

       maxbw

	   Sets the full duplex bandwidth for the flow. The bandwidth is spec‐
	   ified 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	   IP ADDR		  PROTO	 PORT	 DSFLD
	 https1	      bge0	   --			  tcp	 443	 --

       Example 2 Modifying an Existing Policy to Add Bandwidth	Resource  Con‐
       trol

       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 can‐
       not 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	 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 \
	 -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 \
	 -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.

       >0

	   An error occurred.

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Committed	      │
       └────────────────────┴─────────────────┘

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

				 Feb 14, 2009			   FLOWADM(1M)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net