docs/vFW/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 vFW - Readme
   8 ========================================================
   9
  10 Introduction
  11 ===============
  12 The virtual firewall (vFW) is an application implements Firewall. vFW is used
  13 as a barrier between secure internal and an un-secure external network. The
  14 firewall performs Dynamic Packet Filtering. This involves keeping track of the
  15 state of Layer 4 (Transport)traffic,by examining both incoming and outgoing
  16 packets over time. Packets which don't fall within expected parameters given
  17 the state of the connection are discarded. The Dynamic Packet Filtering will
  18 be performed by Connection Tracking component, similar to that supported in
  19 linux. The firewall also supports Access Controlled List(ACL) for rule based
  20 policy enforcement. Firewall is built on top of DPDK and uses the packet library.
  21
  22 ----------
  23 About DPDK
  24 ----------
  25 The DPDK IP Pipeline Framework provides a set of libraries to build a pipeline
  26 application. In this document, vFW will be explained in detail with its own
  27 building blocks.
  28
  29 This document assumes the reader possesses the knowledge of DPDK concepts and
  30 packet framework. For more details, read DPDK Getting Started Guide, DPDK
  31 Programmers Guide, DPDK Sample Applications Guide.
  32
  33 Scope
  34 ==========
  35 This application provides a standalone DPDK based high performance vFW Virtual
  36 Network Function implementation.
  37
  38 Features
  39 ===========
  40 The vFW VNF currently supports the following functionality:
  41   • Basic packet filtering (malformed packets, IP fragments)
  42   • Connection tracking for TCP and UDP
  43   • Access Control List for rule based policy enforcement
  44   • SYN-flood protection via Synproxy* for TCP
  45   • UDP, TCP and ICMP protocol pass-through
  46   • CLI based enable/disable connection tracking, synproxy, basic packet
  47     filtering
  48   • Multithread support
  49   • Multiple physical port support
  50   • Hardware and Software Load Balancing
  51   • L2L3 stack support for ARP/ICMP handling
  52   • ARP (request, response, gratuitous)
  53   • ICMP (terminal echo, echo response, passthrough)
  54   • ICMPv6 and ND (Neighbor Discovery)
  55
  56 High Level Design
  57 ====================
  58 The Firewall performs basic filtering for malformed packets and dynamic packet
  59 filtering incoming packets using the connection tracker library.
  60 The connection data will be stored using a DPDK hash table. There will be one
  61 entry in the hash table for each connection. The hash key will be based on source
  62 address/port,destination address/port, and protocol of a packet. The hash key
  63 will be processed to allow a single entry to be used, regardless of which
  64 direction the packet is flowing (thus changing the source and destination).
  65 The ACL is implemented as libray stattically linked to vFW, which is used for
  66 used for rule based packet filtering.
  67
  68 TCP connections and UDP pseudo connections will be tracked separately even if
  69 theaddresses and ports are identical. Including the protocol in the hash key
  70 will ensure this.
  71
  72 The Input FIFO contains all the incoming packets for vFW filtering.  The vFW
  73 Filter has no dependency on which component has written to the Input FIFO.
  74 Packets will be dequeued from the FIFO in bulk for processing by the vFW.
  75 Packets will be enqueued to the output FIFO.
  76 The software or hardware loadbalancing can be used for traffic distribution
  77 across multiple worker threads. The hardware loadbalancing require ethernet
  78 flow director support from hardware (eg. Fortville x710 NIC card).
  79 The Input and Output FIFOs will be implemented using DPDK Ring Buffers.
  80
  81 Components of vFW
  82 ====================
  83
  84 In vFW, each component is constructed using packet framework pipelines.
  85 It includes Rx and Tx Driver, Master pipeline, load balancer pipeline and
  86 vfw worker pipeline components. A Pipeline framework is a collection of input
  87 ports, table(s),output ports and actions (functions).
  88
  89 ---------------------------
  90 Receive and Transmit Driver
  91 ---------------------------
  92 Packets will be received in bulk and provided to LoadBalancer(LB) thread.
  93 Transimit takes packets from worker threads in a dedicated ring and sent to
  94 hardware queue.
  95
  96 ---------------------------
  97 Master Pipeline
  98 ---------------------------
  99 The Master component is part of all the IP Pipeline applications. This component
 100 does not process any packets and should configure with Core 0, to allow
 101 other cores for processing of the traffic. This component is responsible for
 102 1. Initializing each component of the Pipeline application in different threads
 103 2. Providing CLI shell for the user control/debug
 104 3. Propagating the commands from user to the corresponding components
 105
 106 ------------------
 107 ARPICMP Pipeline
 108 ------------------
 109 This pipeline processes the APRICMP packets.
 110
 111 ---------------
 112 TXRX Pipelines
 113 ---------------
 114 The TXTX and RXRX pipelines are pass through pipelines to forward both ingress
 115 and egress traffic to Loadbalancer. This is required when the Software
 116 Loadbalancer is used.
 117
 118 ----------------------
 119 Load Balancer Pipeline
 120 ----------------------
 121 The vFW support both hardware and software balancing for load balancing of
 122 traffic across multiple VNF threads. The Hardware load balancing require support
 123 from hardware like Flow Director for steering of packets to application through
 124 hardware queues.
 125
 126 The Software Load balancer is also supported if hardware load balancing can't be
 127 used for any reason. The TXRX along with LOADB pipeline provides support for
 128 software load balancing by distributing the flows to Multiple vFW worker
 129 threads.
 130 Loadbalancer (HW or SW) distributes traffic based on the 5 tuple (src addr, src
 131 port, dest addr, dest port and protocol) applying an XOR logic distributing to
 132 active worker threads, thereby maintaining an affinity of flows to worker
 133 threads.
 134
 135 ---------------
 136 vFW Pipeline
 137 ---------------
 138 The vFW performs the basic packet filtering and will drop the invalid and
 139 malformed packets.The Dynamic packet filtering done using the connection tracker
 140 library. The packets are processed in bulk and Hash table is used to maintain
 141 the connection details.
 142 Every TCP/UDP packets are passed through connection tracker library for valid
 143 connection. The ACL library integrated to firewall provide rule based filtering.
 144
 145 ------------------------
 146 vFW Topology
 147 ------------------------
 148
 149 ::
 150
 151   IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 1) IXIA
 152   operation:
 153   Egress --> The packets sent out from ixia(port 0) will be Firewalled to ixia(port 1).
 154   Igress --> The packets sent out from ixia(port 1) will be Firewalled to ixia(port 0).
 155
 156 ------------------------------------
 157 vFW Topology (L4REPLAY)
 158 ------------------------------------
 159
 160 ::
 161
 162   IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 0)L4REPLAY
 163   operation:
 164   Egress --> The packets sent out from ixia will pass through vFW to L3FWD/L4REPLAY.
 165   Ingress --> The L4REPLAY upon reception of packets (Private to Public Network),
 166   will immediately replay back the traffic to IXIA interface. (Pub -->Priv).
 167
 168 --------------------
 169 How to run L4Replay
 170 --------------------
 171 After the installation of samplevnf
 172
 173 ::
 174
 175  go to <samplevnf/VNFs/L4Replay>
 176  ./buid/L4replay -c  core_mask -n no_of_channels(let it be as 2) -- -p PORT_MASK --config="(port,queue,lcore)"
 177      eg: ./L4replay -c 0xf -n 4 -- -p 0x3 --config="(0,0,1)"
 178
 179 Installation, Compile and Execution
 180 ====================================
 181 Plase refer to <samplevnf>/docs/vFW/INSTALL.rst for installation, configuration,
 182 compilation and execution.