#pragma ident	"@(#)flowadm.1m.txt	1.12	08/02/14 SMI"


System Administration Commands			      flowadm(1M)



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-name

|    flowadm remove-flow [-t] [-R root-dir] {-l link | flow-name}

|    flowadm modify-flow [-t] [-R root-dir] -a attr=value[,...] flow-name

|    flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow-name

+    flowadm reset-flowprop [-t] [-R root-dir] [-p prop,...] flow-name
+
+    flowadm show-flowprop [-cP] [-l link] [-p prop,...] [flow-name]
+
|    flowadm show-flow [-pP] [-s [-i interval]] [-l link] [flow-name]

|    flowadm show-usage [-v|-t] [-f <filename>] [-p <plotfile>] 
|        [-s <time>] [-e  <time>] [-l <link>] [flow-name>]

     flowadm -?

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.

CONCEPTS

     The flowadm command allows users to manage networking bandwidth
     resource for a transport, service, or a virtual machine. The
     service is specified as a combination of transport and port
     while a virtual machine is specified by its MAC address or an
     IP address. The command can also be used on Virtual NICs
     which are created for a virtual machine or Solaris Containers
     to allow the Virtual machine or Container administrator to
     further sub divide the bandwidth allocated to it when the VNIC
     was created.

     A flow is defined as a set of attributes based on Layer 2, 3 and
     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, etc are uniquely created for it
     such that other traffic has minimal or zero impact on it. The 
     processing of the packets for a given flow can be restricted to
     a given CPU or processor set such that all the resources 
     necessary for processing the packets of the flow are dedicated to 
     it. The in bound packets for the identified transport, service or
     virtual machine are separated by the NIC hardware (when possible)
     which utilizes separate FIFOs and DMA channels so that bandwidth
     limits or guarantees can be enforced with near zero 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 hardware and software resources
     and queues so that its isolated from rest of the networking
     traffic for more deterministic behavior.


SUBCOMMANDS


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

	 Adds a flow to the system 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, guarantee 
         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.

	 Properties can be specified only for flows added to a physical
	 NIC. If the underlying link has a bandwidth set, then the limit
	 on a flow, if specified, must not exceed the link's bandwidth.
	 If the underlying link is bound to a processor set, then the
	 processor set for a flow, if specified, should fall within the
	 the underlying link's processor set.

         -t, --temporary

             The changes are temporary and will not persist across reboots.


         -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 attr=value,...
 
             A comma-separated list of attributes to be set  to  the
             specified values.


         -p prop=value,..., --prop 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-name}

	 Remove an existing flow identified by its link and flow-name. 

         -t, --temporary

             The changes are temporary and will not persist across reboots.


         -R root-dir, --root-dir=root-dir

             Specifies an alternate root  directory  where  flowadm should 
             apply persistent removal.


|        -l <link>, --link=<link> | flow-name

|            If a link is specified, remove all flows from that link.  If
|            a flow-name is specified, remove only that flow.



|    flowadm modify-flow [-t] [-R root-dir] -a attr=value[,...] flow-name

         Modify the one or more attributes on an existing flow specified
         by name.  The complete list of attributes can be retrieved using
         show-flow.


         -t, --temporary

             The changes are temporary and will not persist across reboots.


         -R root-dir, --root-dir=root-dir

             Specifies an alternate root  directory  where  flowadm should 
             apply persistent modification.


         -a attr=value,..., --attr attr=value,...
 
             A comma-separated list of attributes to be modified  to  the
             specified values.


|    flowadm set-flowprop [-t] [-R root-dir] -p prop=value[,...] flow-name

	 Set values of one or more properties on the flow specifed by 
         name.  The complete list of properties can be retrieved using 
         show-flow

         -t, --temporary

             The changes are temporary and will not persist across reboots.


         -R root-dir, --root-dir=root-dir

             Specifies an alternate root  directory  where  flowadm should 
             apply persistent creation.

         -p prop=value,..., --prop prop=value,...
 
             A comma-separated list of properties to be set  to  the
             specified values.


+    flowadm reset-flowprop [-t] [-R root-dir] -p prop, ... flow-name
+
+        Resets one or more properties to  their  values  on  the
+        flow  specified by name. If no properties are specified,
+        all properties are reset.
+
+        -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 creation.
+
+        -p prop, ..., --prop=prop, ...
+
+            A comma-separated list of properties to reset.
+
+
+    flowadm show-flowprop [-cP] [-p prop, ...] [flow-name]
+
+        Show the current or persistent values  of  one  or  more
+        properties,  either for all flows or for the specified flow name. 
+        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 "--", if it is not
+                    set, and "?", if the value is unknown.  Per-
+                    sistent 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,  "--"  is
+                    shown.
+
+        POSSIBLE    A comma-separated list  of  the  values  the
+                    property  may  have.  If  the  values span a
+                    numeric range, min - max  may  be  shown  as
+                    shorthand.   If   the  possible  values  are
+                    unknown or unbounded, "--" is shown.
+
+        Flow properties are documented in the FLOW PROPERTIES section.
+
+        -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-flow [-pP] [-s [-i interval]] [-l link | flow-name]


         Show flow configuration information (the  default)  or
         statistics,  either for all flows, all flows on a link
         or for the specified flow-name.

         -p, --parseable
 
             Display using a stable machine-parseable format.


+        -P, --persistent
+
+           Display persistent flow property information.
+ 
+ 
         -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  will  only
             be displayed once.


|        -l link, --link=link | flow-name

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


     flowadm show-usage [-v|-t] [-f <filename>] [-p <plotfile>] 
|        [-s <time>] [-e <time>] [-l <link> | <flow-name> ]
 
      
         Show the historical network flow usage from a stored extended
         accounting file.  Configuration and enabling of net 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.
  
         -v, --verbose
 
         Display all network flow usage records sorted by link.
 
         -t, --time
 
         Display all network flow usage records in chronological order.

         -f <filename>, --file=<filename>
 
         Read extended accounting records of network flow usage from the
         <filename>.  By default, /var/log/net.log will be read.
 
         -p <plotfile>, --plot=<filename>
 
         Write network flow usage data in a form suitable for input to
         gnuplot.
 
|        -s <time>, --start=<time> -e <time>, --stop=<time>
 
         Start and stop times for data display.  Time is in the
         format YYYY.MM.DD.hh:mm:ss.

         -l <link-name>, --link=<link-name>

         If specified, only print the network flow usage from the named
         link.  Otherwise, display network usage from all links.

         <flow-name>
 
         If specified, only print the network flow usage from the named
         flow.  Otherwise, display network usage from all flows.
 
	  
  FLOW ATTRIBUTES

     The flow attribute that identify a flow is a comma separated list
     of one or more keyword,value pair from below

     sap      Identifies a flow by the SAP  <value>. The <value>
	      may be specified in decimal, hexadecimal (preceded by
	      the 0x or 0X prefix) or octal (preceded by the prefix 0).

|    ip_version={4|6}
|            Version of IP protocol. 

|     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 specified, it describes the netmask for a subnet address, 
	      following the same notation convention of ifconfig(1M) and
	      route(1M) addresses.
	      If unspecified, given IP address will be considered as
	      host address for which default prefix length for a
	      IPv4 address is /32 and for IPv6 it is /128.
		
|     remote_ip[/prefix_len]
|	      Identifies a network flow by the remote IP address.
|	      <value> must be a IPv4 address in dotted-decimal notation
|	      or an IPv6 address in colon-separated notation.
	      If specified, it describes the netmask for a subnet address, 
	      following the same notation convention of ifconfig(1M) and
	      route(1M) addresses.
	      If unspecified, given IP address will be considered as
	      host address for which default prefix length for a
	      IPv4 address is /32 and for IPv6 it is /128.

|    transport={tcp|udp|icmpv6|sctp|<transport number>}
	     Identifies a layer 4 protocol to be used. Is typically used
	     in combination with local_port to identify the service which 
 	     needs special attention.

     local_port
	     Identifies a service specified by the local port.

     remote_port
	     Identifies a service identified by the remote port

+RESTRICTIONS
+     Individual flow restrictions
+
+         Restrictions on individual flows do not require knowledge of other
+         flows that have been added to the link.
+
+         ip_version, local_ip and remote_ip
+	       Flows which specify both local_ip and remote_ip but have
+	       addresses from different versions are not allowed.
+
+	       Flows which specify an ip_version which conflicts with the
+	       ip_version of local_ip or remote_ip are not allowed.
+
+	       Valid:
+	       #flowadm add-flow -l vnic1 -a ip_version=6 v6flow
+	       #flowadm add-flow -l vnic1 -a ip_version=4,local_ip=10.10.10.1 
+                                 v4flow
+
+	       Not Valid:
+	       #flowadm add-flow -l vnic1 -a local_ip=10.10.10.1,
+                                remote_ip=::1:2:3 flow1
+	       #flowadm add-flow -l vnic1 -a ip_version=6,local_ip=10.100.100.1
+                                flow1
+	
+          transport, local_port and remote_port
+	       TCP, UDP and SCTP flows can be specified with a local or 
+	       remote port.  An ICMPv6 flow which specifies a port will 
+	       not be allowed.
+
+	       If a local or remote port is specifed, the transport must
+	       be either TCP, UDP or SCTP.
+
+	       Valid:
+	       #flowadm add-flow -l e1000g0 -a transport=udp udpflow
+	       #flowadm add-flow -l e1000g0 -a transport=tcp,local_port=80
+                                udp80flow
+
+	       Not valid:
+	       #flowadm add-flow -l e1000g0 -a local_port=25 flow25
+	       #flowadm add-flow -l e1000g0 -a transport=icmpv6,port=16 flow16
+  
+     Flow restrictions per link
+
+         Disjoint flows
+
+	  Two flows are considered disjoint if they specify a different
+         value for the same attribute.  Disjoint flows are allowed.
+
+	      #flowadm add-flow -l bge0 -a transport=tcp flow1
+	      #flowadm add-flow -l bge0 -a transport=udp flow2
+
+         Enclosed flows
+
+         
+         A flow is considered to be enclosed by another flow if all of the 
+         flow's packets to the other flow.  The properties of the flow which 
+         is more specific will be applied.  In the example, all packets 
+         that match flow2 will also match flow1.  As flow2 is more 
+         specific, its resource constraint (maxbw=200) will be used.
+
+	      #flowadm add-flow -l bge0 -a transport=tcp -p maxbw=300 tcpflow
+	      #flowadm add-flow -l bge0 -p transport=tcp,local_port=80 
+                               -p maxbw=200 tcp80flow 
+      
+         Intersecting flows
+
+	  Two flows are intersecting if a packet can belong to both
+	  flows, but other packets can belong only one of the flows.
+	  The creation of a flow which intersects an existing flow 
+         will not be allowed.
+
+	      #flowadm add-flow -l nxge0 -a transport=tcp -p maxbw=100 tcpflow
+	      #flowadm add-flow -l nxge0 -a local_ip=10.100.100.80  
+                               -p maxbw=200 localipflow
+
+     Flow restrictions per zone
+
+         Flow names
+
+	        Within a zone, no 2 flows may have the same name.  Conversely,
+               after adding the flow with the link specified, the link will
+               not be required for display, modifcation or deletion of the 
+               flow.
+
+         Links with exclusive IP stacks
+          
+               The global zone is prevented from creating flows on top of
+               a data-link which is assigned to a non-global zone.

 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).
	     Bandwidth can be configured only for a flow that
	     is on a physical NIC.

 
     priority
             Sets the relative priority for the  flow. The value may
             be given as one of the tokens  rt(real time), high, normal,
             or low.

     cpus    Bind the processing of packets for a given flow to
             a processor or a set of processors. The value can be
             a comma separated list of one or more processor id.
             If the list consists of more than one processor,
             the processing will spread out to all the processors
             although connection to processor affinity and packet
             ordering for packets of any individual connection will
             be maintained.
 
             The processor or set of processors are not exclusively
             reserved  for the network device. Only the kernel
             threads and interrupt  associated with processing of
             the device are bound to the processor or the set of
             processor specified. In case, it is desired that
             processors be dedicated to the device, psrset(1M) can
             be used to create a processor_set and then
             specifiying the processors from  the processor_set to
             bind the device to.
 
             If the flow was already bound to processor or set
             of processors  due to a previous operation, the binding
             will be removed and the  new set of processors will be
             used instead.

	     Processor (or sets) can be specified only for a flow that
	     is on a physical NIC.

EXAMPLES

	Example 1: Create a policy around mission critical port 443 traffic
	which is https service.

	To create a policy around inbound https traffic on a https server
	so that https gets it dedicated NIC hardware and kernel TCP/IP
	resources. The flow-name specified is https-1 which is used to
	later modify of delete the policy.

	# flowadm add-flow -l bge0 -a transport=TCP local_port=443 https-1

	Example 2: Modify an existing policy to add bandwidth resource control

	To modify https-1 policy to add bandwidth control, give it a 
	high priority and bind the processing of the flow to CPU# 9
	
|	# flowadm set-flowprop -p maxbw=90%,priority=high,cpus=9
	 https-1

	Example 3: Limit the bandwidth usage of UDP protocol

	To create a policy for UDP protocol so that it can not consume more
	than 10% of available bandwidth. The flow-name is called limit-udp-1.

|	# flowadm add-flow -l bge0 -a transport=UDP -p maxbw=10% priority=low 
             limit-udp-1
	
	

EXIT STATUS
     The following exit	values are returned:
     0	      All actions were performed successfully.

     >0	      An error occurred.



ATTRIBUTES
     See attributes(5) for descriptions	of the	following  attri-
     butes:
     ____________________________________________________________
    |	    ATTRIBUTE TYPE	  |	  ATTRIBUTE VALUE	|
    |_____________________________|_____________________________|
    |_____________________________|_____________________________|
    | Interface	Stability	  | Evolving			|
    |_____________________________|_____________________________|

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

NOTES
     The configuration of all policies will persist across reboot.