docs: better docs, mv doxygen to sphinx

[vpp.git] / docs / usecases / contiv / VPP_CONFIG.rst

diff --git a/docs/usecases/contiv/VPP_CONFIG.rst b/docs/usecases/contiv/VPP_CONFIG.rst
new file mode 100644 (file)
index 0000000..5dcb6dd
--- /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.
+