docs/usecases/contiv/VPP_CONFIG.rst

   1 Creating VPP Startup Configuration
   2 ==================================
   3
   4 This document describes how to create the VPP startup configuration file
   5 located at ``/etc/vpp/contiv-vswitch.conf``.
   6
   7 Hardware Interface Configuration
   8 --------------------------------
   9
  10 Single-NIC Configuration
  11 ~~~~~~~~~~~~~~~~~~~~~~~~
  12
  13 You need to configure hardware interfaces for use by VPP. First, find
  14 out the PCI address of the host’s network interface. On Debian-based
  15 distributions, you can use ``lshw``:
  16
  17 ::
  18
  19    sudo lshw -class network -businfo
  20    Bus info          Device      Class          Description
  21    ========================================================
  22    pci@0000:03:00.0  ens160      network        VMXNET3 Ethernet Controller
  23
  24 In our case, it would be the ``ens3`` interface with the PCI address
  25 ``0000:00:03.0``
  26
  27 Now, add or modify the VPP startup config file
  28 (``/etc/vpp/contiv-vswitch.conf``) to contain the proper PCI address:
  29
  30 ::
  31
  32    unix {
  33        nodaemon
  34        cli-listen /run/vpp/cli.sock
  35        cli-no-pager
  36        coredump-size unlimited
  37        full-coredump
  38        poll-sleep-usec 100
  39    }
  40    nat {
  41        endpoint-dependent
  42    }
  43    dpdk {
  44        dev 0000:00:03.0
  45    }
  46    api-trace {
  47       on
  48       nitems 500
  49    }
  50
  51 Multi-NIC Configuration
  52 ~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 Similar to the single-NIC configuration, use command *lshw* to find the
  55 PCI addresses of all the NICs in the system, for example:
  56
  57 ::
  58
  59    $ sudo lshw -class network -businfo
  60    Bus info          Device      Class      Description
  61    ====================================================
  62    pci@0000:00:03.0  ens3        network    Virtio network device
  63    pci@0000:00:04.0  ens4        network    Virtio network device
  64
  65 In the example above, ``ens3`` would be the primary interface and
  66 ``ens4`` would be the interface that would be used by VPP. The PCI
  67 address of the ``ens4`` interface would be ``0000:00:04.0``.
  68
  69 Make sure the selected interface is *shut down*, otherwise VPP will not
  70 grab it:
  71
  72 ::
  73
  74    sudo ip link set ens4 down
  75
  76 Now, add or modify the VPP startup config file in
  77 ``/etc/vpp/contiv-vswitch.conf`` to contain the proper PCI address:
  78
  79 ::
  80
  81    unix {
  82        nodaemon
  83        cli-listen /run/vpp/cli.sock
  84        cli-no-pager
  85        coredump-size unlimited
  86        full-coredump
  87        poll-sleep-usec 100
  88    }
  89    nat {
  90        endpoint-dependent
  91    }
  92    dpdk {
  93        dev 0000:00:04.0
  94    }
  95    api-trace {
  96       on
  97       nitems 500
  98    }
  99
 100 If assigning multiple NICs to VPP you will need to include each NIC’s
 101 PCI address in the dpdk stanza in ``/etc/vpp/contiv-vswitch.conf``.
 102
 103 Assigning all NICs to VPP
 104 ^^^^^^^^^^^^^^^^^^^^^^^^^
 105
 106 On a multi-NIC node, it is also possible to assign all NICs from the
 107 kernel for use by VPP. First, you need to install the STN daemon, as
 108 described [here][1], since you will want the NICs to revert to the
 109 kernel if VPP crashes.
 110
 111 You also need to configure the NICs in the VPP startup config file in
 112 ``/etc/vpp/contiv-vswitch.conf``. For example, to use both the primary
 113 and secondary NIC, in a two-NIC node, your VPP startup config file would
 114 look something like this:
 115
 116 ::
 117
 118    unix {
 119        nodaemon
 120        cli-listen /run/vpp/cli.sock
 121        cli-no-pager
 122        coredump-size unlimited
 123        full-coredump
 124        poll-sleep-usec 100
 125    }
 126    nat {
 127        endpoint-dependent
 128    }
 129    dpdk {
 130        dev 0000:00:03.0
 131        dev 0000:00:04.0
 132    }
 133    api-trace {
 134       on
 135       nitems 500
 136    }
 137
 138 Installing ``lshw`` on CentOS/RedHat/Fedora
 139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 140
 141 Note: On CentOS/RedHat/Fedora distributions, ``lshw`` may not be
 142 available by default, install it by
 143
 144 ::
 145
 146    sudo yum -y install lshw
 147
 148 Power-saving Mode
 149 -----------------
 150
 151 In regular operation, VPP takes 100% of one CPU core at all times (poll
 152 loop). If high performance and low latency is not required you can
 153 “slow-down” the poll-loop and drastically reduce CPU utilization by
 154 adding the following stanza to the ``unix`` section of the VPP startup
 155 config file:
 156
 157 ::
 158
 159    unix {
 160        ...
 161        poll-sleep-usec 100
 162        ...
 163    }
 164
 165 The power-saving mode is especially useful in VM-based development
 166 environments running on laptops or less powerful servers.
 167
 168 VPP API Trace
 169 -------------
 170
 171 To troubleshoot VPP configuration issues in production environments, it
 172 is strongly recommended to configure VPP API trace. This is done by
 173 adding the following stanza to the VPP startup config file:
 174
 175 ::
 176
 177    api-trace {
 178        on
 179        nitems 500
 180    }
 181
 182 You can set the size of the trace buffer with the attribute.
 183