summaryrefslogtreecommitdiffstats
path: root/docs/usecases/contiv/VPP_CONFIG.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/usecases/contiv/VPP_CONFIG.rst')
-rw-r--r--docs/usecases/contiv/VPP_CONFIG.rst183
1 files changed, 183 insertions, 0 deletions
diff --git a/docs/usecases/contiv/VPP_CONFIG.rst b/docs/usecases/contiv/VPP_CONFIG.rst
new file mode 100644
index 00000000000..5dcb6dd5f66
--- /dev/null
+++ b/docs/usecases/contiv/VPP_CONFIG.rst
@@ -0,0 +1,183 @@
+Creating VPP Startup Configuration
+==================================
+
+This document describes how to create the VPP startup configuration file
+located at ``/etc/vpp/contiv-vswitch.conf``.
+
+Hardware Interface Configuration
+--------------------------------
+
+Single-NIC Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You need to configure hardware interfaces for use by VPP. First, find
+out the PCI address of the host’s network interface. On Debian-based
+distributions, you can use ``lshw``:
+
+::
+
+ sudo lshw -class network -businfo
+ Bus info Device Class Description
+ ========================================================
+ pci@0000:03:00.0 ens160 network VMXNET3 Ethernet Controller
+
+In our case, it would be the ``ens3`` interface with the PCI address
+``0000:00:03.0``
+
+Now, add or modify the VPP startup config file
+(``/etc/vpp/contiv-vswitch.conf``) to contain the proper PCI address:
+
+::
+
+ unix {
+ nodaemon
+ cli-listen /run/vpp/cli.sock
+ cli-no-pager
+ coredump-size unlimited
+ full-coredump
+ poll-sleep-usec 100
+ }
+ nat {
+ endpoint-dependent
+ }
+ dpdk {
+ dev 0000:00:03.0
+ }
+ api-trace {
+ on
+ nitems 500
+ }
+
+Multi-NIC Configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Similar to the single-NIC configuration, use command *lshw* to find the
+PCI addresses of all the NICs in the system, for example:
+
+::
+
+ $ sudo lshw -class network -businfo
+ Bus info Device Class Description
+ ====================================================
+ pci@0000:00:03.0 ens3 network Virtio network device
+ pci@0000:00:04.0 ens4 network Virtio network device
+
+In the example above, ``ens3`` would be the primary interface and
+``ens4`` would be the interface that would be used by VPP. The PCI
+address of the ``ens4`` interface would be ``0000:00:04.0``.
+
+Make sure the selected interface is *shut down*, otherwise VPP will not
+grab it:
+
+::
+
+ sudo ip link set ens4 down
+
+Now, add or modify the VPP startup config file in
+``/etc/vpp/contiv-vswitch.conf`` to contain the proper PCI address:
+
+::
+
+ unix {
+ nodaemon
+ cli-listen /run/vpp/cli.sock
+ cli-no-pager
+ coredump-size unlimited
+ full-coredump
+ poll-sleep-usec 100
+ }
+ nat {
+ endpoint-dependent
+ }
+ dpdk {
+ dev 0000:00:04.0
+ }
+ api-trace {
+ on
+ nitems 500
+ }
+
+If assigning multiple NICs to VPP you will need to include each NIC’s
+PCI address in the dpdk stanza in ``/etc/vpp/contiv-vswitch.conf``.
+
+Assigning all NICs to VPP
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On a multi-NIC node, it is also possible to assign all NICs from the
+kernel for use by VPP. First, you need to install the STN daemon, as
+described [here][1], since you will want the NICs to revert to the
+kernel if VPP crashes.
+
+You also need to configure the NICs in the VPP startup config file in
+``/etc/vpp/contiv-vswitch.conf``. For example, to use both the primary
+and secondary NIC, in a two-NIC node, your VPP startup config file would
+look something like this:
+
+::
+
+ unix {
+ nodaemon
+ cli-listen /run/vpp/cli.sock
+ cli-no-pager
+ coredump-size unlimited
+ full-coredump
+ poll-sleep-usec 100
+ }
+ nat {
+ endpoint-dependent
+ }
+ dpdk {
+ dev 0000:00:03.0
+ dev 0000:00:04.0
+ }
+ api-trace {
+ on
+ nitems 500
+ }
+
+Installing ``lshw`` on CentOS/RedHat/Fedora
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note: On CentOS/RedHat/Fedora distributions, ``lshw`` may not be
+available by default, install it by
+
+::
+
+ sudo yum -y install lshw
+
+Power-saving Mode
+-----------------
+
+In regular operation, VPP takes 100% of one CPU core at all times (poll
+loop). If high performance and low latency is not required you can
+“slow-down” the poll-loop and drastically reduce CPU utilization by
+adding the following stanza to the ``unix`` section of the VPP startup
+config file:
+
+::
+
+ unix {
+ ...
+ poll-sleep-usec 100
+ ...
+ }
+
+The power-saving mode is especially useful in VM-based development
+environments running on laptops or less powerful servers.
+
+VPP API Trace
+-------------
+
+To troubleshoot VPP configuration issues in production environments, it
+is strongly recommended to configure VPP API trace. This is done by
+adding the following stanza to the VPP startup config file:
+
+::
+
+ api-trace {
+ on
+ nitems 500
+ }
+
+You can set the size of the trace buffer with the attribute.
+