summaryrefslogtreecommitdiffstats
path: root/docs/usecases/contiv/VPP_CONFIG.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/usecases/contiv/VPP_CONFIG.md')
-rw-r--r--docs/usecases/contiv/VPP_CONFIG.md153
1 files changed, 153 insertions, 0 deletions
diff --git a/docs/usecases/contiv/VPP_CONFIG.md b/docs/usecases/contiv/VPP_CONFIG.md
new file mode 100644
index 00000000000..0d0559372cb
--- /dev/null
+++ b/docs/usecases/contiv/VPP_CONFIG.md
@@ -0,0 +1,153 @@
+## 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 <nitems> attribute.