docs/vACL/README.rst

   1 .. This work is licensed under a creative commons attribution 4.0 international
   2 .. license.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) opnfv, national center of scientific research "demokritos" and others.
   5
   6 ========================================================
   7 Virtual ACL - vACL
   8 ========================================================
   9
  10 1. Introduction
  11 ==============
  12 This application implements Access Control List (ACL). ACL is typically
  13 used for rule based policy enforcement. It restricts access to a destination
  14 IP address/port based on various header fields, such as source IP address/port,
  15 destination IP address/port and protocol. It is built on top of DPDK and
  16 uses the packet framework infrastructure.
  17
  18
  19 About DPDK
  20 ----------
  21 The DPDK IP Pipeline Framework provides a set of libraries to build a pipeline
  22 application. In this document, vACL will be explained in detail with its own
  23 building blocks.
  24
  25 This document assumes the reader possesses the knowledge of DPDK concepts and
  26 packet framework. For more details, read DPDK Getting Started Guide, DPDK
  27 Programmers Guide, DPDK Sample Applications Guide.
  28
  29 2.  Scope
  30 ==========
  31 This application provides a standalone DPDK based high performance vACL Virtual
  32 Network Function implementation.
  33
  34 3. Features
  35 ===========
  36 The vACL VNF currently supports the following functionality:
  37   • CLI based Run-time rule configuration.(Add, Delete, List,  Display,  Clear, Modify)
  38   • Ipv4 and ipv6 standard 5 tuple packet Selector support.
  39   • Multithread support
  40   • Multiple physical port support
  41   • Hardware and Software Load Balancing
  42   • L2L3 stack support for ARP/ICMP handling
  43   • ARP (request, response, gratuitous)
  44   • ICMP (terminal echo, echo response, passthrough)
  45   • ICMPv6 and ND (Neighbor Discovery)
  46
  47 4. High Level Design
  48 ====================
  49 The ACL Filter performs bulk filtering of incoming packets based on rules in current ruleset,
  50 discarding any packets not permitted by the rules. The mechanisms needed for building the
  51 rule database and performing lookups are provided by the DPDK API.
  52 http://dpdk.org/doc/api/rte__acl_8h.html
  53
  54 The Input FIFO contains all the incoming packets for ACL filtering. Packets will be dequeued
  55 from the FIFO in bulk for processing by the ACL. Packets will be enqueued to the output FIFO.
  56 The Input and Output FIFOs will be implemented using DPDK Ring Buffers.
  57
  58 The DPDK ACL example: http://dpdk.org/doc/guides/sample_app_ug/l3_forward_access_ctrl.html
  59 #figure-ipv4-acl-rule contains a suitable syntax and parser for ACL rules.
  60
  61 ===================
  62 5. Components of vACL
  63 ===================
  64 In vACL, each component is constructed using packet framework pipelines.
  65 It includes Rx and Tx Driver, Master pipeline, load balancer pipeline and
  66 vACL worker pipeline components. A Pipeline framework is a collection of input
  67 ports, table(s),output ports and actions (functions).
  68
  69 Receive and Transmit Driver
  70 ******************************
  71 Packets will be received in bulk and provided to LoadBalancer(LB) thread.
  72 Transimit takes packets from worker threads in a dedicated ring and sent to
  73 hardware queue.
  74
  75 Master Pipeline
  76 ******************************
  77 The Master component is part of all the IP Pipeline applications. This component
  78 does not process any packets and should configure with Core 0, to allow
  79 other cores for processing of the traffic. This component is responsible for
  80  1. Initializing each component of the Pipeline application in different threads
  81  2. Providing CLI shell for the user control/debug
  82  3. Propagating the commands from user to the corresponding components
  83
  84 ARPICMP Pipeline
  85 ******************************
  86 This pipeline processes the APRICMP packets.
  87
  88 TXRX Pipelines
  89 ******************************
  90 The TXTX and RXRX pipelines are pass through pipelines to forward both ingress
  91 and egress traffic to Loadbalancer. This is required when the Software
  92 Loadbalancer is used.
  93
  94 Load Balancer Pipeline
  95 ******************************
  96 The vACL support both hardware and software balancing for load blalcning of
  97 traffic across multiple VNF threads. The Hardware load balncing require support
  98 from hardware like Flow Director for steering of packets to application through
  99 hardware queues.
 100
 101 The Software Load balancer is also supported if hardware loadbalancing can't be
 102 used for any reason. The TXRX along with LOADB pipeline provides support for
 103 software load balancing by distributing the flows to Multiple vACL worker
 104 threads.
 105 Loadbalancer (HW or SW) distributes traffic based on the 5 tuple (src addr, src
 106 port, dest addr, dest port and protocol) applying an XOR logic distributing to
 107 active worker threads, thereby maintaining an affinity of flows to worker
 108 threads.
 109
 110 vACL Pipeline
 111 ******************************
 112 The vACL performs the rule-based packet filtering.
 113
 114 vACL Topology:
 115 ------------------------
 116 ::
 117   IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 1) IXIA
 118   operation:
 119     Egress --> The packets sent out from ixia(port 0) will be sent through ACL to ixia(port 1).
 120     Igress --> The packets sent out from ixia(port 1) will be sent through ACL to ixia(port 0).
 121
 122 vACL Topology (L4REPLAY):
 123 ------------------------------------
 124 ::
 125   IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 0)L4REPLAY
 126   operation:
 127     Egress --> The packets sent out from ixia will pass through vACL to L3FWD/L4REPLAY.
 128     Ingress --> The L4REPLAY upon reception of packets (Private to Public Network),
 129                 will immediately replay back the traffic to IXIA interface. (Pub -->Priv).
 130
 131 How to run L4Replay:
 132 --------------------
 133 ::
 134   1. After the installation of samplevnf:
 135      go to <samplevnf/VNFs/L4Replay>
 136   2. ./buid/L4replay -c  core_mask -n no_of_channels(let it be as 2) -- -p PORT_MASK --config="(port,queue,lcore)"
 137      eg: ./L4replay -c 0xf -n 4 -- -p 0x3 --config="(0,0,1)"
 138
 139 6. Installation, Compile and Execution
 140 -----------------------------------------------------------------
 141 Plase refer to <samplevnf>/docs/vACL/INSTALL.rst for installation, configuration, compilation
 142 and execution.