Ordered ACL output actions and tunnel improvements

docs/configuration.rst

@@ -910,6 +910,9 @@ and actions. Matches are key/values based on the `ryu RESTFul API.
 <https://ryu.readthedocs.io/en/latest/app/ofctl_rest.html#reference-description-of-match-and-actions>`_
 Actions is a dictionary of actions to apply upon match.
 
+.. note:: When setting allow to true, the packet will be submitted to the
+    next table AFTER having the output actions applied to it.
+
 .. list-table:: : acls: <acl name>: - rule: actions: {}
     :widths: 30 15 15 40
     :header-rows: 1
@@ -940,12 +943,21 @@ Actions is a dictionary of actions to apply upon match.
       - None
       - Copy the packet, before any modifications, to the specified port (NOTE: ACL mirroring is done in input direction only)
     * - output
-      - dictionary
+      - dictionary or list
       - None
-      - Used to output a packet directly. Details below.
+      - Used to apply more specific output actions for an ACL
 
 The output action contains a dictionary with the following elements:
 
+.. note:: When using the dictionary format, Faucet will
+    build the actions in the following order: pop_vlans, vlan_vids, swap_vid,
+    vlan_vids, set_fields, port, ports and then failover.
+  The ACL dictionary format also restricts using port & ports, vlan_vid & vlan_vids
+    at the same time.
+
+.. note:: When using the list format, the output actions will be applied in the
+    user defined order.
+
 .. list-table:: : acls: <acl name>: - rule: actions: output: {}
     :widths: 30 15 15 40
     :header-rows: 1
@@ -986,6 +998,10 @@ The output action contains a dictionary with the following elements:
       - dictionary
       - None
       - Output with a failover port (see below).
+    * - Tunnel
+      - dictionary
+      - None
+      - Generic port output to any port in the stack
 
 Failover is an experimental option, but can be configured as follows:
 
@@ -1006,6 +1022,40 @@ Failover is an experimental option, but can be configured as follows:
       - None
       - The list of ports the packet can be output through.
 
+A tunnel ACL will encapsulate a packet before sending it through the stack topology
+
+.. note:: Currently tunnel ACLs only support VLAN encapsulation.
+
+.. note:: When using the list output format,
+  the tunnel output action will push the tunnel VID onto the packet.
+  Any actions after the tunnel will be applied to the packet with the
+    tunnel VID.
+
+.. list-table:: : acls: <acl name>: - rule: actions: output: tunnel: {}
+    :widths: 30 15 15 40
+    :header-rows: 1
+
+    * - Attribute
+      - Type
+      - Default
+      - Description
+    * - type
+      - str
+      - 'vlan'
+      - The encapsulation type for the packet. Default is to encapsulate using QinQ.
+    * - tunnel_id
+      - int/str
+      - Lowest unused VID
+      - The ID for the encapsulation type
+    * - dp
+      - int/str
+      - None
+      - The name or dp_id of the dp where the output port belongs
+    * - port
+      - int/str
+      - None
+      - The name or port number of the interface on the remote DP to output the packet
+
 .. _gauge-configuration:
 
 Gauge configuration

docs/tutorials/acls.rst

@@ -266,14 +266,14 @@ There is also the 'output' action which can be used to achieve the same thing.
             actions:
                 allow: False
                 output:
-                    port: 4
+                    - port: 4
         - rule:
             dl_type: 0x86dd
             ip_proto: 58
             actions:
                 allow: False
                 output:
-                    port: 4
+                    - port: 4
 
 
 The output action also allows us to change the packet by setting fields
@@ -302,7 +302,7 @@ Let's create a new ACL for host2's port that will change the MAC source address.
                 actions:
                     allow: True
                     output:
-                        set_fields:
+                        - set_fields:
                             - eth_src: "00:00:00:00:00:02"
     ...
 
@@ -356,16 +356,16 @@ To do this we will use both the 'port' & 'vlan_vid' output fields.
             actions:
                 allow: False
                 output:
-                    vlan_vid: 3
-                    port: 4
+                    - vlan_vid: 3
+                    - port: 4
         - rule:
             dl_type: 0x86dd
             ip_proto: 58
             actions:
                 allow: False
                 output:
-                    vlan_vid: 3
-                    port: 4
+                    - vlan_vid: 3
+                    - port: 4
 
 
 Again reload Faucet, start a tcpdump on host4, and ping from host1 to host3.