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