Tip

This is the documentation for the 23.02 version. Looking for the documentation of the latest version? Have a look here.

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.

For a fresh installation of TNSR, skip ahead to Configuring Interfaces for TNSR, otherwise continue on to identify host interfaces added after TNSR was installed.

Note

The default behavior of the dataplane with no interfaces defined in the configuration is to attach to all interfaces not in use by the host OS. Manually defining at least one device causes the dataplane to only attach to interfaces listed in the configuration. Thus, 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 Identifiers¶
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:

Interface Name Components¶
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)#

Add the device IDs of the interfaces to be used by the VPP dataplane, determined above:

tnsr(config)# dataplane dpdk dev 0000:00:14.1 network
tnsr(config)# dataplane dpdk dev 0000:00:14.2 network

Then commit the configuration:

tnsr(config)# configuration candidate commit

Restart the VPP dataplane:

tnsr(config)# service dataplane restart
tnsr(config)# exit

The interfaces will now be available for TNSR. Start the CLI again and 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.

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

Troubleshooting¶

If the interfaces do not appear in the show interface output, the default driver did not attach to those interfaces and they may require a different driver instead. 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

To enable a different driver, complete the command using the chosen driver name, then commit the configuration and restart the dataplane.

Note

Ethernet 700 Series Network Adapters based on the Intel Ethernet Controller X710/XL710/XXV710 and Intel Ethernet Connection X722 are not compatible with the uio_pci_generic DPDK driver. For these devices, use the igb_uio driver instead.

Note

Mellanox devices use RDMA and not UIO, so changing this driver will not have any effect on their behavior. If a Mellanox device does not appear automatically, TNSR may not support that device.

tnsr(config)# dataplane dpdk uio-driver igb_uio
tnsr(config)# configuration candidate commit
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.

Warning

When using the vfio-pci driver, the DPDK IOVA mode must be explicitly set to pa. See DPDK Configuration for more details.

Warning

When the uio-driver is set to vfio-pci TNSR automatically configures the driver with noiommu mode for compatibility with QAT and other functions. Some may consider noiommu mode unsafe as it provides the user full access to a DMA capable device without the security of I/O management. Take this into consideration when choosing the vfio-pci driver.