docs/vCGNAPT/INSTALL.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 CGNAPT - Installation Guide
   8 ============================
   9
  10
  11 vCGNAPT Compilation
  12 ===================
  13
  14 After downloading (or doing a git clone) in a directory (samplevnf)
  15
  16 ###### Dependencies
  17 * DPDK 16.04: Downloaded and installed via vnf_build.sh or manually from [here](http://fast.dpdk.org/rel/dpdk-16.04.tar.xz)
  18 Both the options are available as part of vnf_build.sh below.
  19 * libpcap-dev
  20 * libzmq
  21 * libcurl
  22
  23 ###### Environment variables
  24
  25 Apply all the additional patches in 'patches/dpdk_custom_patch/' and build dpdk
  26
  27 ::
  28   export RTE_SDK=<dpdk 16.04 directory>
  29   export RTE_TARGET=x86_64-native-linuxapp-gcc
  30
  31 This is done by vnf_build.sh script.
  32
  33 Auto Build:
  34 ==========
  35 $ ./tools/vnf_build.sh in samplevnf root folder
  36
  37 Follow the steps in the screen from option [1] --> [8] and select option [7]
  38 to build the vnfs.
  39 It will automatically download DPDK 16.04 and any required patches and will setup
  40 everything and build vCGNAPT VNFs.
  41
  42 Following are the options for setup:
  43
  44 ::
  45
  46   ----------------------------------------------------------
  47    Step 1: Environment setup.
  48   ----------------------------------------------------------
  49   [1] Check OS and network connection
  50
  51   ----------------------------------------------------------
  52    Step 2: Download and Install
  53   ----------------------------------------------------------
  54   [2] Agree to download
  55   [3] Download packages
  56   [4] Download DPDK zip (optional, use it when option 4 fails)
  57   [5] Install DPDK
  58   [6] Setup hugepages
  59
  60   ----------------------------------------------------------
  61    Step 3: Build VNF
  62   ----------------------------------------------------------
  63   [7] Build VNF
  64
  65   [8] Exit Script
  66
  67 An vCGNAPT executable will be created at the following location
  68 samplevnf/VNFs/vCGNAPT/build/vCGNAPT
  69
  70
  71 Manual Build:
  72 ============
  73 1. Download DPDK 16.04 from dpdk.org
  74    - http://dpdk.org/browse/dpdk/snapshot/dpdk-16.04.zip
  75 2. unzip  dpdk-16.04 and apply dpdk patch
  76    - cd dpdk-16.04
  77          - patch -p0 < VNF_CORE/patches/dpdk_custom_patch/rte_pipeline.patch
  78          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-link-management.patch
  79          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-Rx-hang-when-disable-LLDP.patch
  80          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-link-status-change-interrupt.patch
  81          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-VF-bonded-device-link-down.patch
  82    - build dpdk
  83         - make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc
  84         - cd x86_64-native-linuxapp-gcc
  85         - make
  86    - Setup huge pages
  87         - For 1G/2M hugepage sizes, for example 1G pages, the size must be specified
  88           explicitly and can also be optionally set as the default hugepage size for
  89           the system. For example, to reserve 8G of hugepage memory in the form of
  90           eight 1G pages, the following options should be passed to the kernel:
  91                 * default_hugepagesz=1G hugepagesz=1G hugepages=8  hugepagesz=2M hugepages=2048
  92         - Add this to Go to /etc/default/grub configuration file.
  93           - Append "default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048"
  94             to the GRUB_CMDLINE_LINUX entry.
  95 3. Setup Environment Variable
  96    - export RTE_SDK=<samplevnf>/dpdk-16.04
  97    - export RTE_TARGET=x86_64-native-linuxapp-gcc
  98    - export VNF_CORE=<samplevnf>
  99      or using ./toot/setenv.sh
 100 4. Build vCGNAPT VNFs
 101    - cd <samplevnf>/VNFs/vCGNAPT
 102    - make clean
 103    - make
 104 5. An vCGNAPT executable will be created at the following location
 105    - <samplevnf>/VNFs/vCGNAPT/build/vCGNAPT
 106
 107 Run
 108 ====
 109
 110 Setup Port to run VNF:
 111 ----------------------
 112 ::
 113   1. cd <samplevnf>/dpdk-16.04
 114   3. ./tool/dpdk_nic_bind.py --status <--- List the network device
 115   2. ./tool/dpdk_nic_bind.py -b igb_uio <PCI Port 0> <PCI Port 1>
 116   .. _More details: http://dpdk.org/doc/guides-16.04/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 117
 118   Make the necessary changes to the config files to run the vCGNAPT VNF
 119   eg: ports_mac_list = 00:00:00:30:21:F0 00:00:00:30:21:F1
 120
 121 Dynamic CGNAPT
 122 --------------
 123 Update the configuration according to system configuration.
 124
 125 ::
 126   ./vCGNAPT -p <port mask> -f <config> -s <script> - SW_LoadB
 127   ./vCGNAPT -p <port mask> -f <config> -s <script> -hwlb <num_WT> - HW_LoadB
 128
 129 Static CGNAPT
 130 -------------
 131 Update the script file and add Static NAT Entry
 132
 133 ::
 134   e.g,
 135   ;p <pipeline id> entry addm <prv_ipv4/6> prvport> <pub_ip> <pub_port> <phy_port> <ttl> <no_of_entries> <end_prv_port> <end_pub_port>
 136   ;p 3 entry addm 152.16.100.20 1234 152.16.40.10 1 0 500 65535 1234 65535
 137
 138 Run IPv4
 139 ----------
 140 ::
 141   Software LoadB
 142   --------------
 143   cd <samplevnf>/VNFs/vCGNAPT/build
 144   ./vCGNAPT -p 0x3 -f ./config/arp_txrx-2P-1T.cfg  -s ./config/arp_txrx_ScriptFile_2P.cfg
 145
 146
 147   Hardware LoadB
 148   --------------
 149   cd <samplevnf>/VNFs/vCGNAPT/build
 150   ./vCGNAPT -p 0x3 -f ./config/arp_hwlb-2P-1T.cfg  -s ./config/arp_hwlb_scriptfile_2P.cfg --hwlb 1
 151
 152 Run IPv6
 153 ---------
 154 ::
 155   Software LoadB
 156   --------------
 157   cd <samplevnf>/VNFs/vCGNAPT/build
 158   ./vCGNAPT -p 0x3 -f ./config/arp_txrx-2P-1T-ipv6.cfg  -s ./config/arp_txrx_ScriptFile_2P.cfg
 159
 160
 161   Hardware LoadB
 162   --------------
 163   cd <samplevnf>/VNFs/vCGNAPT/build
 164   ./vCGNAPT -p 0x3 -f ./config/arp_hwlb-2P-1T-ipv6.cfg  -s ./config/arp_hwlb_scriptfile_2P.cfg --hwlb 1
 165
 166 vCGNAPT execution on BM & SRIOV:
 167 --------------------------------
 168 ::
 169   To run the VNF, execute the following:
 170   samplevnf/VNFs/vCGNAPT# ./build/vCGNAPT -p 0x3 -f ./config/arp_txrx-2P-1T.cfg -s ./config/arp_txrx_ScriptFile_2P.cfg
 171   Command Line Params:
 172   -p PORTMASK: Hexadecimal bitmask of ports to configure
 173   -f CONFIG FILE: vCGNAPT configuration file
 174   -s SCRIPT FILE: vCGNAPT script file
 175
 176 vCGNAPT execution on OVS:
 177 -------------------------
 178 ::
 179   To run the VNF, execute the following:
 180   samplevnf/VNFs/vCGNAPT# ./build/vCGNAPT -p 0x3 ./config/arp_txrx-2P-1T.cfg -s ./config/arp_txrx_ScriptFile_2P.cfg --disable-hw-csum
 181   Command Line Params:
 182   -p PORTMASK: Hexadecimal bitmask of ports to configure
 183   -f CONFIG FILE: vCGNAPT configuration file
 184   -s SCRIPT FILE: vCGNAPT script file
 185   --disable-hw-csum :Disable TCP/UDP hw checksum