Setup NICs in Dataplane¶
Next, determine the device ID for the interfaces. Start the CLI (Entering the TNSR CLI) and run the following command to output the device IDs as seen by the dataplane:
tnsr# configure
tnsr(config)# dataplane dpdk dev ?
0000:02:01.0 Ethernet controller: Intel Corporation 82545EM Gigabit Ethernet
Controller (Copper) (rev 01) ( Active Interface eth0 )
0000:02:02.0 Ethernet controller: Intel Corporation 82545EM Gigabit Ethernet
Controller (Copper) (rev 01)
0000:02:03.0 Ethernet controller: Intel Corporation 82545EM Gigabit Ethernet
Controller (Copper) (rev 01)
Interfaces under host control will be noted in the output with Active Interface. Other listed interfaces are usable by TNSR.
Note
The best practice is to always define every interface required for use in the dataplane, even if only changing their names.
Host Interface Name to Dataplane ID Mapping¶
The output of the dataplane dpdk dev ?
command includes the device IDs in
the first column. The device IDs will map to the network cards in a way that is
typically easy to determine. For example:
Interface |
Identifier |
---|---|
enp0s20f0 |
0000:00:14.0 |
enp0s20f1 |
0000:00:14.1 |
enp0s20f2 |
0000:00:14.2 |
enp0s20f3 |
0000:00:14.3 |
enp3s0 |
0000:03:00.0 |
enp4s0 |
0000:04:00.0 |
The host OS interface name and VPP identifiers contain the same information represented in different ways. They both reference the PCI bus number, slot number, and function number. The Interface name contains the values in decimal while the identifier shown in VPP uses hexadecimal.
Deconstructing the first interface name, it contains the following:
Component |
Interface Value |
VPP ID Value |
---|---|---|
Device Type |
en (Ethernet) |
n/a |
PCI Bus |
p0 |
00 |
Bus Slot |
s20 |
14 (Decimal 20 in Hex) |
Function |
f0 |
.0 |
Using this pattern, make a note of the VPP identifiers for the next step. In
this example, since enp0s20f1
and enp0s20f2
are the interfaces to use,
the corresponding VPP IDs are 0000:00:14.1
and 0000:00:14.2
.
Configuring Interfaces for TNSR¶
Next, edit the dataplane configuration. Start the CLI (Entering the TNSR CLI) and enter configuration mode:
tnsr# configure
tnsr(config)#
There are two ways to proceed from here. First is to define only the interfaces TNSR will use individually. To do this, add the device IDs of the interfaces to be used by the VPP dataplane, determined previously:
tnsr(config)# dataplane dpdk dev 0000:00:14.1 network
tnsr(config)# dataplane dpdk dev 0000:00:14.2 network
Alternately, use the directive to automatically define entries for all interfaces not in use by the host OS:
tnsr(config)# dataplane dpdk dev all-inactive-network
This command will iterate over all available interfaces and add entries for unused interfaces automatically. When finished, the configuration is the same as if they had been individually defined manually.
tnsr(config)# dataplane dpdk dev all-inactive-network
dataplane dpdk dev 0000:00:14.0
dataplane dpdk dev 0000:00:14.1
dataplane dpdk dev 0000:00:14.2
dataplane dpdk dev 0000:00:14.3
# skip 0000:03:00.0 - active host interface enp3s0
dataplane dpdk dev 0000:04:00.0
Changes to dataplane startup settings require a dataplane restart to take effect.
tnsr(config)# show configuration running cli cfgfile | match network
dataplane dpdk dev 0000:00:14.0 network
dataplane dpdk dev 0000:00:14.1 network
dataplane dpdk dev 0000:00:14.2 network
dataplane dpdk dev 0000:00:14.3 network
dataplane dpdk dev 0000:04:00.0 network
Note
While this option is faster for getting the interfaces into TNSR with minimal typing, if administrators will be using custom names for interfaces they must still be added individually. See Customizing Interface Names later in this document.
No matter which method added the interfaces to the configuration, activating the interfaces requires a restart of the dataplane:
tnsr(config)# service dataplane restart
tnsr(config)# exit
The interfaces will now be available for TNSR. Now run show interface
and
verify that the interfaces appear in the output.
The output example below has been shortened for brevity:
tnsr# show interface
Interface: GigabitEthernet0/14/1
[...]
Interface: GigabitEthernet0/14/2
[...]
Interface: local0
[...]
The TNSR interface name also reflects the type, followed by the PCI Bus/Slot/Function ID of each interface, using the same hexadecimal notation as VPP.
Note
The dataplane uses hexadecimal values by default but can use decimal values
instead by setting dataplane dpdk decimal-interface-names
. See
DPDK Configuration for details.
Note
Once TNSR attaches to interfaces in this way, they will no longer be shown as devices in the host OS. To return a network interface back to host OS control, see Remove TNSR NIC for Host Use.
One exception to this behavior is Mellanox network interfaces as they use the same driver for both host OS and DPDK, they still appear in the host OS.
See also
The dataplane supports several additional per-device parameters which can fine-tune behavior. See DPDK Configuration for details.
Customizing Interface Names¶
The default interface names, such as GigabitEthernet0/14/1
, may be
customized by an administrator. To customize the names, the PCI ID of the device
must be known. The custom names can be used anywhere that an interface name is
necessary in TNSR.
Note
Only dataplane hardware interface names may be customized in this way. Interfaces from virtual sources such as loopback, IPsec, and GRE cannot be renamed.
The command to rename interfaces is dataplane dpdk dev <pci-id> network name
<name>
. To activate the change, the dataplane must be restarted after making
the name change.
Warning
Custom interface names cannot conflict with reserved keywords in the
dataplane. TNSR will return a warning and prevent use of a conflicting
name. Conflicting names include items such as dataplane graph node names both
directly and indirectly. New nodes are created based on interface names with
suffixes such as <name>-tx
and <name>-output
so TNSR checks for
potential collisions there as well.
This example changes the name of GigabitEthernet0/14/1
, PCI ID
0000:00:14.1
, to DMZ
:
First, look at the list of interfaces. Note that the interface is in the list with its original name:
tnsr# show interface
Interface: GigabitEthernet0/14/1
[...]
Interface: GigabitEthernet0/14/2
[...]
Interface: local0
[...]
Next, remove any references to the interface from TNSR, and then remove the interface configuration entirely:
tnsr(config)# no interface GigabitEthernet0/14/1
Now set the name of the device, then restart the dataplane:
tnsr(config)# dataplane dpdk dev 0000:00:14.1 network name DMZ
tnsr(config)# service dataplane restart
After the dataplane restarts, the interface will appear in the list with its new name:
tnsr# show interface
Interface: DMZ
[...]
Interface: GigabitEthernet0/14/2
[...]
Interface: local0
[...]
To change the name back at a later time, all references to the interface must first be removed, and then the name can be reset:
tnsr(config)# no interface DMZ
tnsr(config)# no dataplane dpdk dev 0000:00:14.1 name
tnsr(config)# service dataplane restart
Interface Driver Management¶
Depending on the hardware, changing the interface driver may be necessary to either see the interfaces at all or to achieve better performance.
See also
For a description of the available drivers, see Interface Drivers.
Check Current Driver¶
To check the current driver, see what is present in the configuration:
tnsr(config)# show configuration running cli cfgfile
[...]
dataplane dpdk uio-driver igb_uio
If there is no dataplane dpdk uio-driver
, then it would use the current
default driver which is vfio-pci
.
Check Driver List¶
To see a list of available drivers, use the following command from config
mode:
tnsr(config)# dataplane dpdk uio-driver ?
igb_uio UIO igb driver
uio_pci_generic Generic UIO driver
vfio-pci VFIO driver
Change Interface Driver¶
To enable a different driver, complete the command using the chosen driver name, restart the dataplane.
tnsr(config)# dataplane dpdk uio-driver igb_uio
tnsr(config)# service dataplane restart
tnsr(config)# exit
Then attempt to view the interfaces with show interface
again. If they are
listed, then the correct driver is now active. If not, save the running
configuration to the startup configuration and reboot so the driver can try
attaching at startup. If the interfaces still do not appear, try another driver.
Warning
When using the vfio-pci
driver, the DPDK IOVA mode must be
explicitly set to pa
. See vfio-pci.
tnsr(config)# dataplane dpdk iova-mode pa
tnsr(config)# dataplane dpdk uio-driver vfio-pci
tnsr(config)# service dataplane restart
tnsr(config)# exit
Troubleshooting¶
Dataplane Interface(s) Missing¶
If one or more expected interfaces do not appear in the show interface
output, the current driver did not attach to those interfaces.
The two most common reasons this happens are:
The host OS is using the interface.
See Disable Host OS NICs for TNSR for information on how to check and correct this.
The current interface driver does not support the hardware.
See Interface Drivers for more information on available drivers and Interface Driver Management for information on checking and changing the driver.
Note
Mellanox devices use RDMA and not UIO, so changing the driver may not have any effect on their behavior. If a Mellanox device does not appear automatically, TNSR may not support that device.