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