docs/testing/user/userguide/vACL/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 vACL - Installation Guide
   8 ============================
   9
  10 vACL Compilation
  11 ===================
  12
  13 After downloading (or doing a git clone) in a directory (samplevnf)
  14
  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 ---------------------
  25 Environment variables
  26 ---------------------
  27 Apply all the additional patches in 'patches/dpdk_custom_patch/' and build dpdk
  28
  29 ::
  30
  31   export RTE_SDK=<dpdk directory>
  32   export RTE_TARGET=x86_64-native-linuxapp-gcc
  33
  34 This is done by vnf_build.sh script.
  35
  36 Auto Build:
  37 ===========
  38 $ ./tools/vnf_build.sh in samplevnf root folder
  39
  40 Follow the steps in the screen from option [1] --> [9] and select option [8]
  41 to build the vnfs.
  42 It will automatically download selected DPDK version and any required patches
  43 and will setup everything and build vACL VNFs.
  44
  45 Following are the options for setup:
  46
  47 ::
  48
  49         ----------------------------------------------------------
  50          Step 1: Environment setup.
  51         ----------------------------------------------------------
  52         [1] Check OS and network connection
  53         [2] Select DPDK RTE version
  54
  55         ----------------------------------------------------------
  56          Step 2: Download and Install
  57         ----------------------------------------------------------
  58         [3] Agree to download
  59         [4] Download packages
  60         [5] Download DPDK zip
  61         [6] Build and Install DPDK
  62         [7] Setup hugepages
  63
  64         ----------------------------------------------------------
  65          Step 3: Build VNFs
  66         ----------------------------------------------------------
  67         [8] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay)
  68
  69         [9] Exit Script
  70
  71 An vACL executable will be created at the following location
  72 samplevnf/VNFs/vACL/build/vACL
  73
  74
  75 Manual Build:
  76 =============
  77 1. Download DPDK supported version from dpdk.org
  78
  79    - http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip
  80
  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
 103           size for the system. For example, to reserve 8G of hugepage memory
 104           in the form of eight 1G pages, the following options should be passed
 105           to the kernel:
 106           * default_hugepagesz=1G hugepagesz=1G hugepages=8  hugepagesz=2M hugepages=2048
 107         - Add this to Go to /etc/default/grub configuration file.
 108         - Append "default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048"
 109             to the GRUB_CMDLINE_LINUX entry.
 110
 111 3. Setup Environment Variable
 112
 113    - export RTE_SDK=<samplevnf>/dpdk
 114    - export RTE_TARGET=x86_64-native-linuxapp-gcc
 115    - export VNF_CORE=<samplevnf>
 116
 117      or using ./tools/setenv.sh
 118
 119 4. Build vACL VNFs
 120
 121    - cd <samplevnf>/VNFs/vACL
 122    - make clean
 123    - make
 124
 125 5. The vACL executable will be created at the following location
 126
 127    - <samplevnf>/VNFs/vACL/build/vACL
 128
 129 Run
 130 ====
 131
 132 ----------------------
 133 Setup Port to run VNF
 134 ----------------------
 135
 136 ::
 137
 138   For DPDK versions 16.04
 139   1. cd <samplevnf>/dpdk
 140   2. ./tools/dpdk_nic_bind.py --status <--- List the network device
 141   3. ./tools/dpdk_nic_bind.py -b igb_uio <PCI Port 0> <PCI Port 1>
 142   .. _More details: http://dpdk.org/doc/guides-16.04/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 143
 144   For DPDK versions 16.11
 145   1. cd <samplevnf>/dpdk
 146   2. ./tools/dpdk-devbind.py --status <--- List the network device
 147   3. ./tools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
 148   .. _More details: http://dpdk.org/doc/guides-16.11/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 149
 150   For DPDK versions 17.xx
 151   1. cd <samplevnf>/dpdk
 152   2. ./usertools/dpdk-devbind.py --status <--- List the network device
 153   3. ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
 154   .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 155
 156
 157   Make the necessary changes to the config files to run the vACL VNF
 158   eg: ports_mac_list = 00:00:00:30:21:00 00:00:00:30:21:00
 159
 160 -----------------
 161 ACL run commands
 162 -----------------
 163 Update the configuration according to system configuration.
 164
 165 ::
 166
 167   ./build/vACL -p <port mask> -f <config> -s <script> - SW_LoadB
 168
 169   ./build/vACL -p <port mask> -f <config> -s <script> -hwlb <num_WT> - HW_LoadB
 170
 171
 172 Run IPv4
 173 --------
 174
 175 ::
 176
 177  Software LoadB
 178
 179   cd <samplevnf>/VNFs/vACL/
 180
 181   ./build/vACL -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg  -s ./config/ IPv4_swlb_acl.tc
 182
 183
 184  Hardware LoadB
 185
 186   cd <samplevnf>/VNFs/vACL/
 187
 188   ./build/vACL -p 0x3 -f ./config/IPv4_hwlb_acl_1LB_1t.cfg  -s ./config/IPv4_hwlb_acl.tc --hwlb 1
 189
 190 Run IPv6
 191 --------
 192
 193 ::
 194
 195   Software LoadB
 196
 197   cd <samplevnf>/VNFs/vACL/
 198
 199   ./build/vACL -p 0x3 -f ./config/IPv6_swlb_acl_1LB_1t.cfg  -s ./config/IPv6_swlb_acl.tc
 200
 201
 202   Hardware LoadB
 203
 204   cd <samplevnf>/VNFs/vACL/
 205
 206   ./build/vACL -p 0x3 -f ./config/IPv6_hwlb_acl_1LB_1t.cfg  -s ./config/IPv6_hwlb_acl.tc --hwlb 1
 207
 208 vACL execution on BM & SRIOV
 209 --------------------------------
 210 To run the VNF, execute the following
 211
 212 ::
 213
 214   samplevnf/VNFs/vACL# ./build/vACL -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg  -s ./config/ IPv4_swlb_acl.tc
 215
 216   Command Line Params:
 217   -p PORTMASK: Hexadecimal bitmask of ports to configure
 218   -f CONFIG FILE: vACL configuration file
 219   -s SCRIPT FILE: vACL script file
 220
 221 vACL execution on OVS
 222 -------------------------
 223 To run the VNF, execute the following:
 224
 225 ::
 226
 227   samplevnf/VNFs/vACL# ./build/vACL -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg  -s ./config/ IPv4_swlb_acl.tc --disable-hw-csum
 228
 229   Command Line Params:
 230   -p PORTMASK: Hexadecimal bitmask of ports to configure
 231   -f CONFIG FILE: vACL configuration file
 232   -s SCRIPT FILE: vACL script file
 233   --disable-hw-csum :Disable TCP/UDP hw checksum