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