docs/BUILD.dpdkstat.md

   1 # The dpdkstat plugin
   2
   3 **Data Plane Development Kit** (DPDK) is a set of drivers and libraries for fast
   4 packet processing.
   5
   6 ## Summary
   7
   8 The *dpdkstat plugin* has the following requirements:
   9
  10  * DPDK 16.04 or later
  11  * GCC 4.9 or later
  12
  13 You can also build with GCC 4.8 (e.g. Ubuntu 14.04) if you specify the SSSE3
  14 instruction set manually:
  15
  16     make -j CFLAGS+='-mssse3'
  17
  18 ## Building DPDK
  19
  20  *  Setup the build environment:
  21
  22     Ensure that you have GCC 4.9 or later. Ubuntu 14.04, for example, has GCC
  23     4.8 by default and requires an upgrade:
  24
  25         add-apt-repository ppa:ubuntu-toolchain-r/test
  26         apt-get update
  27         apt-get install gcc-4.9
  28
  29     If you know that the platform that you wish to run collectd on supports the
  30     SSSE3 instruction set, GCC 4.8 also works if you enable SSSE3 manually:
  31
  32         make -j CFLAGS+='-mssse3'
  33
  34  *  Clone DPDK:
  35
  36         git clone git://dpdk.org/dpdk
  37
  38  *  Checkout the [DPDK system
  39     requirements](http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html) and make
  40     sure you have the required tools and hugepage setup as specified there.
  41
  42     **Note:** It's recommended to use the 1GB hugepage setup for best
  43     performance, please follow the instruction for "Reserving Hugepages for DPDK
  44     Use" in the link above.
  45
  46     However if you plan on configuring 2MB hugepages on the fly please ensure to
  47     add appropriate commands to reserve hugepages in a system startup script if
  48     collectd is booted at system startup time. These commands include:
  49
  50         mkdir -p /mnt/huge
  51         mount -t hugetlbfs nodev /mnt/huge
  52         echo 64 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
  53
  54  *  To configure the DPDK build for the combined shared library modify
  55     `config/common_base` in your DPDK as follows
  56
  57         #
  58         # Compile to share library
  59         #
  60         -CONFIG_RTE_BUILD_SHARED_LIB=n
  61         +CONFIG_RTE_BUILD_SHARED_LIB=y
  62
  63  *  Prepare the configuration for the appropriate target as specified at:
  64     http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html.
  65
  66     For example:
  67
  68         make config T=x86_64-native-linuxapp-gcc
  69
  70  *  Build the target:
  71
  72         make
  73
  74  *  Install DPDK to `/usr`
  75
  76         sudo make install prefix=/usr
  77
  78     **Note 1:** You must run make install as the configuration of collectd with
  79     DPDK expects DPDK to be installed somewhere.
  80
  81     **Note 2:** If you don't specify a prefix then DPDK will be installed in
  82     `/usr/local/`.
  83
  84     **Note 3:** If you are not root then use sudo to make install DPDK to the
  85     appropriate location.
  86
  87  *  Check that the DPDK library has been installed in `/usr/lib` or `/lib`:
  88
  89         ls /usr/lib | grep dpdk
  90
  91  *  Bind the interfaces to use with dpdkstat to DPDK:
  92
  93     DPDK devices can be setup with either the VFIO (for DPDK 1.7+) or UIO
  94     modules.
  95
  96     **Note:** UIO requires inserting an out of tree driver `igb_uio.ko` that is
  97     available in DPDK.
  98
  99     **UIO Setup:**
 100
 101      *  Insert `uio.ko`:
 102
 103             sudo modprobe uio
 104
 105      *  Insert `igb_uio.ko`:
 106
 107             sudo insmod $DPDK_BUILD/kmod/igb_uio.ko
 108
 109      *  Bind network device to `igb_uio`:
 110
 111             sudo $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio eth1
 112
 113     **VFIO Setup:**
 114
 115      *  VFIO needs to be supported in the kernel and the BIOS. More information
 116         can be found at: http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html.
 117      *  Insert the `vfio-pci.ko` module:
 118
 119             modprobe vfio-pci
 120
 121      *  Set the correct permissions for the VFIO device:
 122
 123             sudo /usr/bin/chmod a+x /dev/vfio
 124             sudo /usr/bin/chmod 0666 /dev/vfio/*
 125
 126      *  Bind the network device to `vfio-pci`:
 127
 128             sudo $DPDK_DIR/tools/dpdk_nic_bind.py --bind=vfio-pci eth1
 129
 130         **Note:** Please ensure to add appropriate commands to bind the network
 131         interfaces to DPDK in a system startup script if collectd is booted at
 132         system startup time.
 133
 134      *  Run `ldconfig` to update the shared library cache.
 135
 136 ### Static library
 137
 138 To build static DPDK library for use with collectd:
 139
 140  *  To configure DPDK to build the combined static library `libdpdk.a` ensure
 141     that `CONFIG_RTE_BUILD_SHARED_LIB` is set to “n” in `config/common_base` in
 142     your DPDK as follows:
 143
 144         #
 145         # Compile to share library
 146         #
 147         CONFIG_RTE_BUILD_SHARED_LIB=n
 148
 149  *  Prepare the configuration for the appropriate target as specified at:
 150     http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html.
 151
 152     For example:
 153
 154         make config T=x86_64-native-linuxapp-gcc
 155
 156  *  Build the target using `-fPIC`:
 157
 158         make EXTRA_CFLAGS=-fPIC -j
 159
 160  *  Install DPDK to `/usr`:
 161
 162         sudo make install prefix=/usr
 163
 164 ## Build collectd with DPDK
 165
 166 **Note:** DPDK 16.04 is the minimum version and currently supported version of
 167 DPDK required for the dpdkstat plugin. This is to allow the plugin to take
 168 advantage of functions added to detect if the DPDK primary process is alive.
 169
 170
 171 **Note:** The *Address-Space Layout Randomization* (ASLR) security feature in
 172 Linux should be disabled, in order for the same hugepage memory mappings to be
 173 present in all DPDK multi-process applications. Note that this has security
 174 implications.
 175
 176  *  To disable ASLR:
 177
 178         echo 0 > /proc/sys/kernel/randomize_va_space
 179
 180  *  To fully enable ASLR:
 181
 182         echo 2 > /proc/sys/kernel/randomize_va_space
 183
 184 See also: http://dpdk.org/doc/guides/prog_guide/multi_proc_support.html
 185
 186  *  Generate the build script as specified below. (i.e. run `build.sh`).
 187  *  Configure collectd with the DPDK shared library:
 188
 189         ./configure --with-libdpdk=/usr
 190
 191 ### Build with the static DPDK library
 192
 193 To configure collectd with the DPDK static library:
 194
 195  *  Run *configure* with the following CFLAGS:
 196
 197         ./configure --with-libdpdk=/usr CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive"
 198
 199  *  Make sure that dpdk and dpdkstat are enabled in the *configure* output.
 200
 201     Expected output:
 202
 203         Libraries:
 204         ...
 205         libdpdk  . . . . . . . . yes
 206
 207         Modules:
 208         ...
 209         dpdkstat . . . . . . .yes
 210
 211  *  Build collectd:
 212
 213         make -j && make -j install.
 214
 215     **Note:** As mentioned above, if you are building on Ubuntu 14.04 with
 216     GCC <= 4.8.X, you need to use:
 217
 218         make -j CFLAGS+='-mssse3' && make -j install
 219
 220 ## Caveats
 221
 222  *  The same PCI device configuration should be passed to the primary process as
 223     the secondary process uses the same port indexes as the primary.
 224  *  A blacklist / whitelist of NICs isn't supported yet.
 225
 226 ## License
 227
 228 The *dpdkstat plugin* is copyright (c) 2016 *Intel Corporation* and licensed
 229 under the *MIT license*. Full licensing terms can be found in the file
 230 `COPYING`.