docs/testing/user/userguide/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 vCGNAPT - 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 -------------
  18
  19 - DPDK supported versions ($DPDK_RTE_VER = 16.04, 16.11, 17.02 or 17.05) Downloaded and installed via vnf_build.sh or manually from [here] (http://fast.dpdk.org/rel/)
  20 - libpcap-dev
  21 - libzmq
  22 - libcurl
  23
  24 Environment variables
  25 ---------------------
  26
  27 Apply all the additional patches in 'patches/dpdk_custom_patch/' and build dpdk
  28 required only for DPDK version 16.04.
  29
  30 ::
  31
  32   export RTE_SDK=<dpdk directory>
  33   export RTE_TARGET=x86_64-native-linuxapp-gcc
  34
  35 This is done by vnf_build.sh script.
  36
  37 Auto Build:
  38 ===========
  39 $ ./tools/vnf_build.sh in samplevnf root folder
  40
  41 Follow the steps in the screen from option [1] --> [9] and select option [8]
  42 to build the vnfs.
  43 It will automatically download selected DPDK version and any required patches
  44 and will setup everything and build vCGNAPT VNFs.
  45
  46 Following are the options for setup:
  47
  48 ::
  49
  50         ----------------------------------------------------------
  51          Step 1: Environment setup.
  52         ----------------------------------------------------------
  53         [1] Check OS and network connection
  54         [2] Select DPDK RTE version
  55
  56         ----------------------------------------------------------
  57          Step 2: Download and Install
  58         ----------------------------------------------------------
  59         [3] Agree to download
  60         [4] Download packages
  61         [5] Download DPDK zip
  62         [6] Build and Install DPDK
  63         [7] Setup hugepages
  64
  65         ----------------------------------------------------------
  66          Step 3: Build VNFs
  67         ----------------------------------------------------------
  68         [8] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay)
  69
  70         [9] Exit Script
  71
  72 An vCGNAPT executable will be created at the following location
  73 samplevnf/VNFs/vCGNAPT/build/vCGNAPT
  74
  75
  76 Manual Build:
  77 =============
  78 1. Download DPDK supported version from dpdk.org
  79
  80    - http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip
  81 2. unzip  dpdk-$DPDK_RTE_VER.zip and apply dpdk patches only in case of 16.04
  82    (Not required for other DPDK versions)
  83
  84    - cd dpdk
  85
  86          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-link-management.patch
  87          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-Rx-hang-when-disable-LLDP.patch
  88          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-link-status-change-interrupt.patch
  89          - patch -p1 < VNF_CORE/patches/dpdk_custom_patch/i40e-fix-VF-bonded-device-link-down.patch
  90          - patch -p1 < $VNF_CORE/patches/dpdk_custom_patch/disable-acl-debug-logs.patch
  91          - patch -p1 < $VNF_CORE/patches/dpdk_custom_patch/set-log-level-to-info.patch
  92
  93    - build dpdk
  94
  95         - make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc
  96         - cd x86_64-native-linuxapp-gcc
  97         - make
  98
  99    - Setup huge pages
 100
 101         - For 1G/2M hugepage sizes, for example 1G pages, the size must be specified
 102           explicitly and can also be optionally set as the default hugepage size for
 103           the system. For example, to reserve 8G of hugepage memory in the form of
 104           eight 1G pages, the following options should be passed to the kernel:
 105           * default_hugepagesz=1G hugepagesz=1G hugepages=8  hugepagesz=2M hugepages=2048
 106         - Add this to Go to /etc/default/grub configuration file.
 107         - Append "default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048"
 108             to the GRUB_CMDLINE_LINUX entry.
 109
 110 3. Setup Environment Variable
 111
 112    - export RTE_SDK=<samplevnf>/dpdk
 113    - export RTE_TARGET=x86_64-native-linuxapp-gcc
 114    - export VNF_CORE=<samplevnf>
 115      or using ./tools/setenv.sh
 116
 117 4. Build vCGNAPT VNFs
 118
 119    - cd <samplevnf>/VNFs/vCGNAPT
 120    - make clean
 121    - make
 122
 123 5. An vCGNAPT executable will be created at the following location
 124
 125    - <samplevnf>/VNFs/vCGNAPT/build/vCGNAPT
 126
 127 Run
 128 ====
 129
 130 Setup Port to run VNF
 131 ----------------------
 132
 133 ::
 134
 135   For DPDK versions 16.04
 136   1. cd <samplevnf>/dpdk
 137   2. ./tools/dpdk_nic_bind.py --status <--- List the network device
 138   3. ./tools/dpdk_nic_bind.py -b igb_uio <PCI Port 0> <PCI Port 1>
 139   .. _More details: http://dpdk.org/doc/guides-16.04/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 140
 141   For DPDK versions 16.11
 142   1. cd <samplevnf>/dpdk
 143   2. ./tools/dpdk-devbind.py --status <--- List the network device
 144   3. ./tools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
 145   .. _More details: http://dpdk.org/doc/guides-16.11/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 146
 147   For DPDK versions 17.xx
 148   1. cd <samplevnf>/dpdk
 149   2. ./usertools/dpdk-devbind.py --status <--- List the network device
 150   3. ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
 151   .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 152
 153   Make the necessary changes to the config files to run the vCGNAPT VNF
 154   eg: ports_mac_list = 00:00:00:30:21:F0 00:00:00:30:21:F1
 155
 156 Dynamic CGNAPT
 157 --------------
 158 Update the configuration according to system configuration.
 159
 160 ::
 161
 162   ./vCGNAPT -p <port mask> -f <config> -s <script> - SW_LoadB
 163   ./vCGNAPT -p <port mask> -f <config> -s <script> -hwlb <num_WT> - HW_LoadB
 164
 165 Static CGNAPT
 166 -------------
 167 Update the script file and add Static NAT Entry
 168
 169 ::
 170
 171   e.g,
 172   ;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>
 173   ;p 3 entry addm 152.16.100.20 1234 152.16.40.10 1 0 500 65535 1234 65535
 174
 175 Run IPv4
 176 ----------
 177
 178 ::
 179
 180   Software LoadB:
 181
 182   cd <samplevnf>/VNFs/vCGNAPT/build
 183   ./vCGNAPT -p 0x3 -f ./config/arp_txrx-2P-1T.cfg  -s ./config/arp_txrx_ScriptFile_2P.cfg
 184
 185
 186   Hardware LoadB:
 187
 188   cd <samplevnf>/VNFs/vCGNAPT/build
 189   ./vCGNAPT -p 0x3 -f ./config/arp_hwlb-2P-1T.cfg  -s ./config/arp_hwlb_scriptfile_2P.cfg --hwlb 1
 190
 191 Run IPv6
 192 ---------
 193
 194 ::
 195
 196   Software LoadB:
 197
 198   cd <samplevnf>/VNFs/vCGNAPT/build
 199   ./vCGNAPT -p 0x3 -f ./config/arp_txrx-2P-1T-ipv6.cfg  -s ./config/arp_txrx_ScriptFile_2P.cfg
 200
 201
 202   Hardware LoadB:
 203
 204   cd <samplevnf>/VNFs/vCGNAPT/build
 205   ./vCGNAPT -p 0x3 -f ./config/arp_hwlb-2P-1T-ipv6.cfg  -s ./config/arp_hwlb_scriptfile_2P.cfg --hwlb 1
 206
 207 vCGNAPT execution on BM & SRIOV
 208 --------------------------------
 209
 210 ::
 211
 212   To run the VNF, execute the following:
 213   samplevnf/VNFs/vCGNAPT# ./build/vCGNAPT -p 0x3 -f ./config/arp_txrx-2P-1T.cfg -s ./config/arp_txrx_ScriptFile_2P.cfg
 214   Command Line Params:
 215   -p PORTMASK: Hexadecimal bitmask of ports to configure
 216   -f CONFIG FILE: vCGNAPT configuration file
 217   -s SCRIPT FILE: vCGNAPT script file
 218
 219 vCGNAPT execution on OVS
 220 -------------------------
 221 To run the VNF, execute the following:
 222
 223 ::
 224
 225   samplevnf/VNFs/vCGNAPT# ./build/vCGNAPT -p 0x3 ./config/arp_txrx-2P-1T.cfg -s ./config/arp_txrx_ScriptFile_2P.cfg --disable-hw-csum
 226   Command Line Params:
 227   -p PORTMASK: Hexadecimal bitmask of ports to configure
 228   -f CONFIG FILE: vCGNAPT configuration file
 229   -s SCRIPT FILE: vCGNAPT script file
 230   --disable-hw-csum :Disable TCP/UDP hw checksum