Vhost cli reference
create vhost-user
create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [hwaddr <mac-addr>] [renumber <dev_instance>] [gso] [packed] [event-idx]
Create a vHost User interface. Once created, a new virtual interface
will exist with the name VirtualEthernet0/0/x, where x
is the next free index.
There are several parameters associated with a vHost interface:
socket <socket-filename> - Name of the linux socket used by hypervisor and VPP to manage the vHost interface. If in
servermode, VPP will create the socket if it does not already exist. If inclientmode, hypervisor will create the socket if it does not already exist. The VPP code is indifferent to the file location. However, if SELinux is enabled, then the socket needs to be created in/var/run/vpp/.server - Optional flag to indicate that VPP should be the server for the linux socket. If not provided, VPP will be the client. In
servermode, the VM can be reset without tearing down the vHost Interface. Inclientmode, VPP can be reset without bringing down the VM and tearing down the vHost Interface.feature-mask <hex> - Optional virtio/vhost feature set negotiated at startup. This is intended for degugging only. It is recommended that this parameter not be used except by experienced users. By default, all supported features will be advertised. Otherwise, provide the set of features desired.
0x000008000 (15) - VIRTIO_NET_F_MRG_RXBUF
0x000020000 (17) - VIRTIO_NET_F_CTRL_VQ
0x000200000 (21) - VIRTIO_NET_F_GUEST_ANNOUNCE
0x000400000 (22) - VIRTIO_NET_F_MQ
0x004000000 (26) - VHOST_F_LOG_ALL
0x008000000 (27) - VIRTIO_F_ANY_LAYOUT
0x010000000 (28) - VIRTIO_F_INDIRECT_DESC
0x040000000 (30) - VHOST_USER_F_PROTOCOL_FEATURES
0x100000000 (32) - VIRTIO_F_VERSION_1
hwaddr <mac-addr> - Optional ethernet address, can be in either X:X:X:X:X:X unix or X.X.X cisco format.
renumber <dev_instance> - Optional parameter which allows the instance in the name to be specified. If instance already exists, name will be used anyway and multiple instances will have the same name. Use with caution.
Example of how to create a vhost interface with VPP as the client and all features enabled:
create vhost-user socket /var/run/vpp/vhost1.sock
VirtualEthernet0/0/0
Example of how to create a vhost interface with VPP as the server and with just multiple queues enabled:
create vhost-user socket /var/run/vpp/vhost2.sock server feature-mask 0x40400000
VirtualEthernet0/0/1
Once the vHost interface is created, enable the interface using:
set interface state VirtualEthernet0/0/0 up
Declaration: vhost_user_connect_command src/plugins/vhost/vhost_user.c line 2397
Implementation: vhost_user_connect_command_fn
delete vhost-user
delete vhost-user {<interface> | sw_if_index <sw_idx>}
Delete a vHost User interface using the interface name or the
software interface index. Use the show interface
command to determine the software interface index. On deletion,
the linux socket will not be deleted.
Example of how to delete a vhost interface by name:
delete vhost-user VirtualEthernet0/0/1
Example of how to delete a vhost interface by software interface index:
delete vhost-user sw_if_index 1
Declaration: vhost_user_delete_command src/plugins/vhost/vhost_user.c line 2420
Implementation: vhost_user_delete_command_fn
show vhost-user
show vhost-user [<interface> [<interface> [..]]] [[descriptors] [verbose]]
Display the attributes of a single vHost User interface (provide interface name), multiple vHost User interfaces (provide a list of interface names separated by spaces) or all Vhost User interfaces (omit an interface name to display all vHost interfaces).
Example of how to display a vhost interface:
show vhost-user VirtualEthernet0/0/0
Virtio vhost-user interfaces
Global:
coalesce frames 32 time 1e-3
Interface: VirtualEthernet0/0/0 (ifindex 1)
virtio_net_hdr_sz 12
features mask (0xffffffffffffffff):
features (0x50408000):
VIRTIO_NET_F_MRG_RXBUF (15)
VIRTIO_NET_F_MQ (22)
VIRTIO_F_INDIRECT_DESC (28)
VHOST_USER_F_PROTOCOL_FEATURES (30)
protocol features (0x3)
VHOST_USER_PROTOCOL_F_MQ (0)
VHOST_USER_PROTOCOL_F_LOG_SHMFD (1)
socket filename /var/run/vpp/vhost1.sock type client errno "Success"
rx placement:
thread 1 on vring 1
thread 1 on vring 5
thread 2 on vring 3
thread 2 on vring 7
tx placement: spin-lock
thread 0 on vring 0
thread 1 on vring 2
thread 2 on vring 0
Memory regions (total 2)
region fd guest_phys_addr memory_size userspace_addr mmap_offset mmap_addr
====== == =============== =========== ============== =========== ==========
0 60 0x00000000 0x000a0000 0xaac00000 0x00000000 0x2b400000
1 61 0x000c0000 0x3ff40000 0xaacc0000 0x000c0000 0xabcc0000
Virtqueue 0 (TX)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
kickfd 62 callfd 64 errfd -1
Virtqueue 1 (RX)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
kickfd 65 callfd 66 errfd -1
Virtqueue 2 (TX)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
kickfd 63 callfd 70 errfd -1
Virtqueue 3 (RX)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
kickfd 72 callfd 74 errfd -1
Virtqueue 4 (TX disabled)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
kickfd 76 callfd 78 errfd -1
Virtqueue 5 (RX disabled)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
kickfd 80 callfd 82 errfd -1
Virtqueue 6 (TX disabled)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
kickfd 84 callfd 86 errfd -1
Virtqueue 7 (RX disabled)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
kickfd 88 callfd 90 errfd -1
The optional descriptors parameter will display the same output
as the previous example but will include the descriptor table for each
queue.
The output is truncated below:
show vhost-user VirtualEthernet0/0/0 descriptors
Virtio vhost-user interfaces
Global:
coalesce frames 32 time 1e-3
Interface: VirtualEthernet0/0/0 (ifindex 1)
virtio_net_hdr_sz 12
features mask (0xffffffffffffffff):
features (0x50408000):
VIRTIO_NET_F_MRG_RXBUF (15)
VIRTIO_NET_F_MQ (22)
:
Virtqueue 0 (TX)
qsz 256 last_avail_idx 0 last_used_idx 0
avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
kickfd 62 callfd 64 errfd -1
descriptor table:
id addr len flags next user_addr
===== ================== ===== ====== ===== ==================
0 0x0000000010b6e974 2060 0x0002 1 0x00002aabbc76e974
1 0x0000000010b6e034 2060 0x0002 2 0x00002aabbc76e034
2 0x0000000010b6d6f4 2060 0x0002 3 0x00002aabbc76d6f4
3 0x0000000010b6cdb4 2060 0x0002 4 0x00002aabbc76cdb4
4 0x0000000010b6c474 2060 0x0002 5 0x00002aabbc76c474
5 0x0000000010b6bb34 2060 0x0002 6 0x00002aabbc76bb34
6 0x0000000010b6b1f4 2060 0x0002 7 0x00002aabbc76b1f4
7 0x0000000010b6a8b4 2060 0x0002 8 0x00002aabbc76a8b4
8 0x0000000010b69f74 2060 0x0002 9 0x00002aabbc769f74
9 0x0000000010b69634 2060 0x0002 10 0x00002aabbc769634
10 0x0000000010b68cf4 2060 0x0002 11 0x00002aabbc768cf4
:
249 0x0000000000000000 0 0x0000 250 0x00002aab2b400000
250 0x0000000000000000 0 0x0000 251 0x00002aab2b400000
251 0x0000000000000000 0 0x0000 252 0x00002aab2b400000
252 0x0000000000000000 0 0x0000 253 0x00002aab2b400000
253 0x0000000000000000 0 0x0000 254 0x00002aab2b400000
254 0x0000000000000000 0 0x0000 255 0x00002aab2b400000
255 0x0000000000000000 0 0x0000 32768 0x00002aab2b400000
Virtqueue 1 (RX)
qsz 256 last_avail_idx 0 last_used_idx 0
:
Declaration: show_vhost_user_command src/plugins/vhost/vhost_user.c line 2561
Implementation: show_vhost_user_command_fn