3 **Data Plane Development Kit** (DPDK) is a set of drivers and libraries for fast
8 The *dpdkstat plugin* has the following requirements:
13 You can also build with GCC 4.8 (e.g. Ubuntu 14.04) if you specify the SSSE3
14 instruction set manually:
16 make -j CFLAGS+='-mssse3'
20 * Setup the build environment:
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:
25 add-apt-repository ppa:ubuntu-toolchain-r/test
27 apt-get install gcc-4.9
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:
32 make -j CFLAGS+='-mssse3'
36 git clone git://dpdk.org/dpdk
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.
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.
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:
51 mount -t hugetlbfs nodev /mnt/huge
52 echo 64 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
54 * To configure the DPDK build for the combined shared library modify
55 `config/common_base` in your DPDK as follows
58 # Compile to share library
60 -CONFIG_RTE_BUILD_SHARED_LIB=n
61 +CONFIG_RTE_BUILD_SHARED_LIB=y
63 * Prepare the configuration for the appropriate target as specified at:
64 http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html.
68 make config T=x86_64-native-linuxapp-gcc
74 * Install DPDK to `/usr`
76 sudo make install prefix=/usr
78 **Note 1:** You must run make install as the configuration of collectd with
79 DPDK expects DPDK to be installed somewhere.
81 **Note 2:** If you don't specify a prefix then DPDK will be installed in
84 **Note 3:** If you are not root then use sudo to make install DPDK to the
87 * Check that the DPDK library has been installed in `/usr/lib` or `/lib`:
89 ls /usr/lib | grep dpdk
91 * Bind the interfaces to use with dpdkstat to DPDK:
93 DPDK devices can be setup with either the VFIO (for DPDK 1.7+) or UIO
96 **Note:** UIO requires inserting an out of tree driver `igb_uio.ko` that is
105 * Insert `igb_uio.ko`:
107 sudo insmod $DPDK_BUILD/kmod/igb_uio.ko
109 * Bind network device to `igb_uio`:
111 sudo $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio eth1
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:
121 * Set the correct permissions for the VFIO device:
123 sudo /usr/bin/chmod a+x /dev/vfio
124 sudo /usr/bin/chmod 0666 /dev/vfio/*
126 * Bind the network device to `vfio-pci`:
128 sudo $DPDK_DIR/tools/dpdk_nic_bind.py --bind=vfio-pci eth1
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
134 * Run `ldconfig` to update the shared library cache.
138 To build static DPDK library for use with collectd:
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:
145 # Compile to share library
147 CONFIG_RTE_BUILD_SHARED_LIB=n
149 * Prepare the configuration for the appropriate target as specified at:
150 http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html.
154 make config T=x86_64-native-linuxapp-gcc
156 * Build the target using `-fPIC`:
158 make EXTRA_CFLAGS=-fPIC -j
160 * Install DPDK to `/usr`:
162 sudo make install prefix=/usr
164 ## Build collectd with DPDK
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.
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
178 echo 0 > /proc/sys/kernel/randomize_va_space
180 * To fully enable ASLR:
182 echo 2 > /proc/sys/kernel/randomize_va_space
184 See also: http://dpdk.org/doc/guides/prog_guide/multi_proc_support.html
186 * Generate the build script as specified below. (i.e. run `build.sh`).
187 * Configure collectd with the DPDK shared library:
189 ./configure --with-libdpdk=/usr
191 ### Build with the static DPDK library
193 To configure collectd with the DPDK static library:
195 * Run *configure* with the following CFLAGS:
197 ./configure --with-libdpdk=/usr CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive"
199 * Make sure that dpdk and dpdkstat are enabled in the *configure* output.
205 libdpdk . . . . . . . . yes
209 dpdkstat . . . . . . .yes
213 make -j && make -j install.
215 **Note:** As mentioned above, if you are building on Ubuntu 14.04 with
216 GCC <= 4.8.X, you need to use:
218 make -j CFLAGS+='-mssse3' && make -j install
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.
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