vHost User Interfaces¶

vHost User interfaces are a type of virtual interface for communicating with virtual machines. These virtual interfaces are backed by a socket and shared memory, through which TNSR and a virtual machine running on the same host can communicate as if it were a network connection. These interfaces allow TNSR to act in a role similar to a virtual switch or host OS bond interface.

Note

Configuring an environment where TNSR and a virtualization platform are both installed and running on the same host is outside the scope of this documentation.

Typically these interfaces are joined in a bridge domain (Bridge Interfaces) so that virtual machines can communicate with hosts connected to other TNSR interfaces as if they were part of the same layer 2 network.

Supported Platforms¶

vHost user interfaces are implemented using Virtio. Virtualization platforms which support Virtio vHost user interfaces include QEMU and solutions based on QEMU, such as KVM or Proxmox® VE. This could be QEMU or KVM running on a TNSR installation, TNSR running on a Proxmox VE host, or some other combination. Check the virtualization platform documentation for specifics on support and configuration.

vHost User Interface Configuration¶

See also

See vHost User Interface Startup Configuration for information on configuring dataplane startup options for vHost User interfaces.

A new vHost user interface is defined by the interface vhost-user <instance> command, which enters config-vhost-user mode. The <instance> parameter is an integer which is also the resulting interface ID.

Note

In most cases, the settings here should match the settings for the corresponding interface on the VM.

tnsr(config)# interface vhost-user <instance>
tnsr(config-vhost-user)#

In config-vhost-user mode, the following commands are available:

sock-filename <sock-filename-val>

Defines the full path to the socket file through which this interface will communicate with another endpoint.

Tip

Naming the socket file after the VM ID and/or name, along with the instance ID, makes it easier to locate the correct file later if necessary. For example, /var/run/vpp/vm-100-0.sock would be for a VM ID of 100 and vHost user interface instance 0.

server-mode

When present, the vHost interface acts in server mode. When not present, it acts in client mode.

The mode influences which side can be disrupted. The client side can reset without needing to reset the server side. Since TNSR will generally not be restarted as often as guest VMs, TNSR typically acts as the server.

disable (merge-rx-buffers|indirect-descriptors)

Disables certain options which are enabled by default:

merge-rx-buffers: Disable the use of merge receive buffers.
indirect-descriptors: Disable the use of indirect descriptors.

enable (gso|packed-ring|event-index)

Enables certain options which are disabled by default:

gso: Enable the use of Generic Segmentation Offload (GSO).
packed-ring: Enable the use of packed ring to increase efficiency by combining multiple separate ring buffers. This is experimental and support varies by virtualization platform and version. This feature must be supported and enabled by both ends.
event-index: Enable the use of event index.

After creating the interface it will be available for configuration in TNSR. The name of this interface is VirtualEthernet0/0/<n> where <n> is the instance ID. For example, if a vHost user interface was created with an instance ID of 5, the resulting interface is VirtualEthernet0/0/5.

vHost User Interface Example¶

First define and configure the vHost User interface:

tnsr(config)# interface vhost-user 0
tnsr(config-vhost-user)# server-mode
tnsr(config-vhost-user)# enable gso
tnsr(config-vhost-user)# enable packed
tnsr(config-vhost-user)# enable event-index
tnsr(config-vhost-user)# sock-filename /var/run/vpp/vm-100-0.sock
tnsr(config-vhost-user)# exit

Now there will be a new VirtualEthernet0/0/0 interface which can be configured as needed:

tnsr(config)# interface VirtualEthernet0/0/0
tnsr(config-interface)# mac 3c:ec:ef:d0:10:00
tnsr(config-interface)# bridge domain 2
tnsr(config-interface)# enable
tnsr(config-interface)# exit

Note

Manually configuring a MAC address allows it to use a consistent or known value. If the MAC address is not set, the MAC address will be randomized each time the interface is configured after the dataplane restarts.

When configuring the corresponding interface on a virtual machine as a part of a bridge domain, ensure it uses a different MAC address.

vHost User Interface Status¶

To view the status of vHost User interfaces, use the show interface vhost-user command:

tnsr(config)# show interface vhost-user
Interface: VirtualEthernet0/0/0
    Instance: 0
    Socket filename: /var/run/vpp/vm-100-0.sock
    Socket type: server
    Socket errno: Success
    Virtio net header size: 0
    Features (0x0):
    Memory regions: 0