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