docs/usecases/contiv/VPP_CONFIG.md

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