src/plugins/rdma/rdma_doc.md

   1 # RDMA (ibverb) Ethernet driver {#rdma_doc}
   2
   3 This driver relies on Linux rdma-core (libibverb) userspace poll-mode driver
   4 to rx/tx Ethernet packets. Despite using the RDMA APIs, this is **not** about
   5 RDMA (no Infiniband, no RoCE, no iWARP), just pure traditional Ethernet
   6 packets.
   7
   8 ## Maturity level
   9 Under development: it should work, but has not been thoroughly tested.
  10
  11 ## Supported Hardware
  12  - Mellanox ConnectX-4
  13  - Mellanox ConnectX-5
  14
  15 ## Features
  16  - bifurcation: MAC based flow steering for transparent sharing of a single
  17 physical port between multiple virtual interfaces including Linux netdev
  18  - multiqueue
  19
  20 ## Security considerations
  21 When creating a rdma interface, it will receive all packets to the MAC address
  22 attributed to the interface plus a copy of all broadcast and multicast
  23 traffic.
  24 The MAC address is under the control of VPP: **the user controlling VPP can
  25 divert all traffic of any MAC address to the VPP process, including the Linux
  26 netdev MAC address as long as it can create a rdma interface**.
  27 The rights to create a rdma interface are controlled by the access rights of
  28 the `/dev/infiniband/uverbs[0-9]+`device nodes.
  29
  30 ## Quickstart
  31 1. Make sure the `ib_uverbs` module is loaded:
  32 ```
  33 ~# modprobe ib_uverbs
  34 ```
  35 2. In VPP, create a new rdma virtual interface tied to the Linux netdev of the
  36 physical port you want to use (`enp94s0f0` in this example):
  37 ```
  38 vpp# create int rdma host-if enp94s0f0 name rdma-0
  39 ```
  40 3. Use the interface as usual, eg.:
  41 ```
  42 vpp# set int ip addr rdma-0 1.1.1.1/24
  43 vpp# set int st rdma-0 up
  44 vpp# ping 1.1.1.100`
  45 ```
  46
  47 ### Containers support
  48 It should work in containers as long as:
  49  - the `ib_uverbs` module is loaded
  50  - the device nodes `/dev/infiniband/uverbs[0-9]+` are usable from the
  51    container (but see [security considerations](#Security considerations))
  52
  53 ### SR-IOV VFs support
  54 It should work on SR-IOV VFs the same way it does with PFs. Because of VFs
  55 security containment features, make sure the MAC address of the rdma VPP
  56 interface matches the MAC address assigned to the underlying VF.
  57 For example:
  58 ```
  59 host# echo 1 > /sys/class/infiniband/mlx5_0/device/sriov_numvfs
  60 host# ip l set dev enp94s0f0 vf 0 mac 92:5d:f5:df:b1:6f spoof on trust off
  61 host# ip l set dev enp94s0f2 up
  62 vpp# create int rdma host-if enp94s0f2 name rdma-0
  63 vpp# set int mac address rdma-0 92:5d:f5:df:b1:6f
  64 ```
  65 If you plan to use L2 features such as switching, make sure the underlying
  66 VF is configured in trusted mode and spoof-checking is disabled (of course, be
  67 aware of the [security considerations](#Security considerations)):
  68 ```
  69 host# ip l set dev enp94s0f0 vf 0 spoof off trust on
  70 ```