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