vFW/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 vFW - Installation Guide
   8 ============================
   9
  10
  11 vFW 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 vFW 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 vFW executable will be created at the following location
  68 samplevnf/VNFs/vFW/build/vFW
  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 vFW VNFs
 101    - cd <samplevnf>/VNFs/vFW
 102    - make clean
 103    - make
 104 5. The vFW executable will be created at the following location
 105    - <samplevnf>/VNFs/vFW/build/vFW
 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 vFW VNF
 119   eg: ports_mac_list = 00:00:00:30:21:01 00:00:00:30:21:00
 120
 121 Firewall
 122 --------------
 123 Update the configuration according to system configuration.
 124
 125 ::
 126   ./vFW -p <port mask> -f <config> -s <script> - SW_LoadB
 127   ./vFW -p <port mask> -f <config> -s <script> -hwlb <num_WT> - HW_LoadB
 128
 129
 130 Run IPv4
 131 ----------
 132 ::
 133   Software LoadB
 134   --------------
 135   cd <samplevnf>/VNFs/vFW/
 136   ./build/vFW -p 0x3 -f ./config/VFW_SWLB_IPV4_SinglePortPair_4Thread.cfg  -s ./config/VFW_SWLB_IPV4_SinglePortPair_script.tc
 137
 138
 139   Hardware LoadB
 140   --------------
 141   cd <samplevnf>/VNFs/vFW/
 142   ./build/vFW -p 0x3 -f ./config/VFW_HWLB_IPV4_SinglePortPair_4Thread.cfg  -s ./config/VFW_HWLB_IPV4_SinglePortPair_script.cfg --hwlb 4
 143
 144 Run IPv6
 145 ---------
 146 ::
 147   Software LoadB
 148   --------------
 149   cd <samplevnf>/VNFs/vFW
 150   ./build/vFW -p 0x3 -f ./config/VFW_SWLB_IPV6_SinglePortPair_4Thread.cfg  -s ./config/VFW_SWLB_IPV6_SinglePortPair_script.tc
 151
 152
 153   Hardware LoadB
 154   --------------
 155   cd <samplevnf>/VNFs/vFW/
 156   ./build/vFW -p 0x3 -f ./config/VFW_HWLB_IPV6_SinglePortPair_4Thread.cfg  -s ./config/VFW_HWLB_IPV6_SinglePortPair_script.tc --hwlb 4
 157
 158 vFW execution on BM & SRIOV:
 159 --------------------------------
 160 ::
 161   To run the VNF, execute the following:
 162   samplevnf/VNFs/vFW# ./build/vFW -p 0x3 -f ./config/VFW_SWLB_IPV4_SinglePortPair_4Thread.cfg  -s ./config/VFW_SWLB_IPV4_SinglePortPair_script.tc
 163   Command Line Params:
 164   -p PORTMASK: Hexadecimal bitmask of ports to configure
 165   -f CONFIG FILE: vFW configuration file
 166   -s SCRIPT FILE: vFW script file
 167
 168 vFW execution on OVS:
 169 -------------------------
 170 ::
 171   To run the VNF, execute the following:
 172   samplevnf/VNFs/vFW# ./build/vFW -p 0x3 -f ./config/VFW_SWLB_IPV4_SinglePortPair_4Thread.cfg  -s ./config/VFW_SWLB_IPV4_SinglePortPair_script.tc --disable-hw-csum
 173   Command Line Params:
 174   -p PORTMASK: Hexadecimal bitmask of ports to configure
 175   -f CONFIG FILE: vFW configuration file
 176   -s SCRIPT FILE: vFW script file
 177 --disable-hw-csum :Disable TCP/UDP hw checksum