docs/testing/user/userguide/vCGNAPT/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 vCGNAPT - Readme
   8 ========================================================
   9
  10 Introduction
  11 ==============
  12 This application implements vCGNAPT. The idea of vCGNAPT is to extend the life of
  13 the service providers IPv4 network infrastructure and mitigate IPv4 address
  14 exhaustion by using address and port translation in large scale. It processes the
  15 traffic in both the directions.
  16
  17 It also supports the connectivity between the IPv6 access network to IPv4 data network
  18 using the IPv6 to IPv4 address translation and vice versa.
  19
  20 About DPDK
  21 ----------
  22 The DPDK IP Pipeline Framework provides set of libraries to build a pipeline
  23 application. In this document, CG-NAT application will be explained with its
  24 own building blocks.
  25
  26 This document assumes the reader possess the knowledge of DPDK concepts and IP
  27 Pipeline 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 vCGNAPT
  33 Virtual Network  Function implementation.
  34
  35 Features
  36 ===========
  37 The vCGNAPT VNF currently supports the following functionality:
  38   • Static NAT
  39   • Dynamic NAT
  40   • Static NAPT
  41   • Dynamic NAPT
  42   • ARP (request, response, gratuitous)
  43   • ICMP (terminal echo, echo response, passthrough)
  44   • ICMPv6 and ND (Neighbor Discovery)
  45   • UDP, TCP and ICMP protocol passthrough
  46   • Multithread support
  47   • Multiple physical port support
  48   • Limiting max ports per client
  49   • Limiting max clients per public IP address
  50   • Live Session tracking to NAT flow
  51   • NAT64
  52   • PCP Support
  53   • ALG SIP
  54   • ALG FTP
  55
  56 High Level Design
  57 ====================
  58 The Upstream path defines the traffic from Private to Public and the downstream
  59 path defines the traffic from Public to Private. The vCGNAPT has same set of
  60 components to process Upstream and Downstream traffic.
  61
  62 In vCGNAPT application, each component is constructed as IP Pipeline framework.
  63 It includes Master pipeline component, load balancer pipeline component and vCGNAPT
  64 pipeline component.
  65
  66 A Pipeline framework is collection of input ports, table(s), output ports and
  67 actions (functions). In vCGNAPT pipeline, main sub components are the Inport function
  68 handler, Table and Table function handler. vCGNAPT rules will be configured in the
  69 table which translates egress and ingress traffic according to physical port
  70 information from which side packet is arrived. The actions can be forwarding to the
  71 output port (either egress or ingress) or to drop the packet.
  72
  73 vCGNAPT Graphical Overview
  74 ==========================
  75 The idea of vCGNAPT is to extend the life of the service providers IPv4 network infrastructure
  76 and mitigate IPv4 address exhaustion by using address and port translation in large scale.
  77 It processes the traffic in both the directions.
  78
  79 .. code-block:: console
  80
  81   +------------------+
  82   |                 +-----+
  83   | Private consumer | CPE  |---------------+
  84   |   IPv4 traffic  +-----+                 |
  85   +------------------+                      |
  86                  +------------------+       v        +----------------+
  87                  |                  | +------------+ |                |
  88                  |   Private IPv4   | |  vCGNAPT   | |    Public      |
  89                  |  access network  | |   NAT44    | |  IPv4 traffic  |
  90                  |                  | +------------+ |                |
  91                  +------------------+       |        +----------------+
  92   +------------------+                      |
  93   |                 +-----+                 |
  94   | Private consumer| CPE |-----------------+
  95   |  IPv4 traffic   +-----+
  96   +------------------+
  97       Figure 1: vCGNAPT deployment in Service provider network
  98
  99
 100
 101 Components of vCGNAPT
 102 =====================
 103
 104 In vCGNAPT, each component is constructed as a packet framework. It includes Master pipeline
 105 component, driver, load balancer pipeline component and vCGNAPT worker pipeline component. A
 106 pipeline framework is a collection of input ports, table(s), output ports and actions
 107 (functions).
 108
 109 Receive and transmit driver
 110 ----------------------------
 111 Packets will be received in bulk and provided to load balancer thread. The transmit takes
 112 packets from worker thread in a dedicated ring and sent to the hardware queue.
 113
 114 ARPICMP pipeline
 115 ------------------------
 116 ARPICMP pipeline is responsible for handling all l2l3 arp related packets.
 117
 118 This component does not process any packets and should configure with Core 0,
 119 to save cores for other components which processes traffic. The component
 120 is responsible for:
 121 1. Initializing each component of the Pipeline application in different threads
 122 2. Providing CLI shell for the user
 123 3. Propagating the commands from user to the corresponding components.
 124 4. ARP and ICMP are handled here.
 125
 126 Load Balancer pipeline
 127 ------------------------
 128 Load balancer is part of the Multi-Threaded CGMAPT release which distributes
 129 the flows to Multiple ACL worker threads.
 130
 131 Distributes traffic based on the 2 or 5 tuple (source address, source port,
 132 destination  address, destination port and protocol) applying an XOR logic
 133 distributing the  load to active worker threads, thereby maintaining an
 134 affinity of flows to  worker threads.
 135
 136 Tuple can be modified/configured using configuration file
 137
 138 vCGNAPT - Static
 139 ====================
 140 The vCGNAPT component performs translation of private IP & port to public IP &
 141 port at egress side and public IP & port to private IP & port at Ingress side
 142 based on the NAT rules added to the pipeline Hash table. The NAT rules are
 143 added to the Hash table via user commands. The packets that have a matching
 144 egress key or ingress key in the NAT table will be processed to change IP &
 145 port and will be forwarded to the output port. The packets that do not have a
 146 match will be taken a default action. The default action may result in drop of
 147 the packets.
 148
 149 vCGNAPT - Dynamic
 150 ===================
 151 The vCGNAPT component performs translation of private IP & port to public IP & port
 152 at egress side and public IP & port to private IP & port at Ingress side based on the
 153 NAT rules added to the pipeline Hash table. Dynamic nature of vCGNAPT refers to the
 154 addition of NAT entries in the Hash table dynamically when new packet arrives. The NAT
 155 rules will be added to the Hash table automatically when there is no matching entry in
 156 the table and the packet is circulated through software queue. The packets that have a
 157 matching egress key or ingress key in the NAT table will be processed to change IP &
 158 port and will be forwarded to the output port defined in the entry.
 159
 160 Dynamic vCGNAPT acts as static one too, we can do NAT entries statically. Static NAT
 161 entries port range must not conflict to dynamic NAT port range.
 162
 163 vCGNAPT Static Topology
 164 ------------------------
 165
 166 ::
 167
 168   IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 1) IXIA
 169   operation:
 170   Egress --> The packets sent out from ixia(port 0) will be CGNAPTed to ixia(port 1).
 171   Igress --> The packets sent out from ixia(port 1) will be CGNAPTed to ixia(port 0).
 172
 173 vCGNAPT Dynamic Topology (L4REPLAY)
 174 ------------------------------------
 175
 176 ::
 177
 178   IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 0)L4REPLAY
 179   operation:
 180   Egress --> The packets sent out from ixia will be CGNAPTed to L3FWD/L4REPLAY.
 181   Ingress --> The L4REPLAY upon reception of packets (Private to Public Network),
 182   will immediately replay back the traffic to IXIA interface. (Pub -->Priv).
 183
 184 How to run L4Replay
 185 --------------------
 186 After the installation of samplevnf:
 187
 188 ::
 189
 190  go to <samplevnf/VNFs/L4Replay>
 191  ./buid/L4replay -c  core_mask -n no_of_channels(let it be as 2) -- -p PORT_MASK --config="(port,queue,lcore)"
 192      eg: ./L4replay -c 0xf -n 4 -- -p 0x3 --config="(0,0,1)"
 193
 194 Installation, Compile and Execution
 195 ====================================
 196 Plase refer to <samplevnf>/docs/vCGNAPT/INSTALL.rst for installation, configuration, compilation
 197 and execution.