10 Create a vHost User interface. Once created, a new virtual interface
11 will exist with the name '*VirtualEthernet0/0/x*', where '*x*' is the
14 There are several parameters associated with a vHost interface:
16 - **socket <socket-filename>** - Name of the linux socket used by
17 hypervisor and VPP to manage the vHost interface. If in '*server*'
18 mode, VPP will create the socket if it does not already exist. If in
19 '*client*' mode, hypervisor will create the socket if it does not
20 already exist. The VPP code is indifferent to the file location.
21 However, if SELinux is enabled, then the socket needs to be created
23 - **server** - Optional flag to indicate that VPP should be the server
24 for the linux socket. If not provided, VPP will be the client. In
25 '*server*' mode, the VM can be reset without tearing down the vHost
26 Interface. In '*client*' mode, VPP can be reset without bringing down
27 the VM and tearing down the vHost Interface.
28 - **feature-mask <hex>** - Optional virtio/vhost feature set negotiated
29 at startup. **This is intended for degugging only.** It is
30 recommended that this parameter not be used except by experienced
31 users. By default, all supported features will be advertised.
32 Otherwise, provide the set of features desired.
34 - 0x000008000 (15) - VIRTIO_NET_F_MRG_RXBUF
35 - 0x000020000 (17) - VIRTIO_NET_F_CTRL_VQ
36 - 0x000200000 (21) - VIRTIO_NET_F_GUEST_ANNOUNCE
37 - 0x000400000 (22) - VIRTIO_NET_F_MQ
38 - 0x004000000 (26) - VHOST_F_LOG_ALL
39 - 0x008000000 (27) - VIRTIO_F_ANY_LAYOUT
40 - 0x010000000 (28) - VIRTIO_F_INDIRECT_DESC
41 - 0x040000000 (30) - VHOST_USER_F_PROTOCOL_FEATURES
42 - 0x100000000 (32) - VIRTIO_F_VERSION_1
44 - **hwaddr <mac-addr>** - Optional ethernet address, can be in either
45 X:X:X:X:X:X unix or X.X.X cisco format.
46 - **renumber <dev_instance>** - Optional parameter which allows the
47 instance in the name to be specified. If instance already exists,
48 name will be used anyway and multiple instances will have the same
49 name. Use with caution.
57 create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [hwaddr <mac-addr>] [renumber <dev_instance>]
63 Example of how to create a vhost interface with VPP as the client
64 and all features enabled:
66 .. code-block:: console
68 vpp# create vhost-user socket /var/run/vpp/vhost1.sock
71 Example of how to create a vhost interface with VPP as the server
72 and with just multiple queues enabled:
74 .. code-block:: console
76 vpp# create vhost-user socket /var/run/vpp/vhost2.sock server feature-mask 0x40400000
79 Once the vHost interface is created, enable the interface using:
81 .. code-block:: console
83 vpp# set interface state VirtualEthernet0/0/0 up
90 Display the attributes of a single vHost User interface (provide
91 interface name), multiple vHost User interfaces (provide a list of
92 interface names seperated by spaces) or all Vhost User interfaces (omit
93 an interface name to display all vHost interfaces).
100 show vhost-user [<interface> [<interface> [..]]] [descriptors].
104 Example of how to display a vhost interface:
106 .. code-block:: console
108 vpp# show vhost-user VirtualEthernet0/0/0
109 Virtio vhost-user interfaces
111 coalesce frames 32 time 1e-3
112 Interface: VirtualEthernet0/0/0 (ifindex 1)
114 features mask (0xffffffffffffffff):
115 features (0x50408000):
116 VIRTIO_NET_F_MRG_RXBUF (15)
118 VIRTIO_F_INDIRECT_DESC (28)
119 VHOST_USER_F_PROTOCOL_FEATURES (30)
120 protocol features (0x3)
121 VHOST_USER_PROTOCOL_F_MQ (0)
122 VHOST_USER_PROTOCOL_F_LOG_SHMFD (1)
124 socket filename /var/run/vpp/vhost1.sock type client errno "Success"
131 tx placement: spin-lock
136 Memory regions (total 2)
137 region fd guest_phys_addr memory_size userspace_addr mmap_offset mmap_addr
138 ====== ===== ================== ================== ================== ================== ==================
139 0 60 0x0000000000000000 0x00000000000a0000 0x00002aaaaac00000 0x0000000000000000 0x00002aab2b400000
140 1 61 0x00000000000c0000 0x000000003ff40000 0x00002aaaaacc0000 0x00000000000c0000 0x00002aababcc0000
143 qsz 256 last_avail_idx 0 last_used_idx 0
144 avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
145 kickfd 62 callfd 64 errfd -1
148 qsz 256 last_avail_idx 0 last_used_idx 0
149 avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
150 kickfd 65 callfd 66 errfd -1
153 qsz 256 last_avail_idx 0 last_used_idx 0
154 avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
155 kickfd 63 callfd 70 errfd -1
158 qsz 256 last_avail_idx 0 last_used_idx 0
159 avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
160 kickfd 72 callfd 74 errfd -1
162 Virtqueue 4 (TX disabled)
163 qsz 256 last_avail_idx 0 last_used_idx 0
164 avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
165 kickfd 76 callfd 78 errfd -1
167 Virtqueue 5 (RX disabled)
168 qsz 256 last_avail_idx 0 last_used_idx 0
169 avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
170 kickfd 80 callfd 82 errfd -1
172 Virtqueue 6 (TX disabled)
173 qsz 256 last_avail_idx 0 last_used_idx 0
174 avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
175 kickfd 84 callfd 86 errfd -1
177 Virtqueue 7 (RX disabled)
178 qsz 256 last_avail_idx 0 last_used_idx 0
179 avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
180 kickfd 88 callfd 90 errfd -1
182 The optional '*descriptors*' parameter will display the same output as the
183 previous example but will include the descriptor table for each queue. The output is truncated below:
185 .. code-block:: console
187 vpp# show vhost-user VirtualEthernet0/0/0 descriptors
189 Virtio vhost-user interfaces
191 coalesce frames 32 time 1e-3
192 Interface: VirtualEthernet0/0/0 (ifindex 1)
194 features mask (0xffffffffffffffff):
195 features (0x50408000):
196 VIRTIO_NET_F_MRG_RXBUF (15)
200 qsz 256 last_avail_idx 0 last_used_idx 0
201 avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
202 kickfd 62 callfd 64 errfd -1
205 id addr len flags next user_addr
206 ===== ================== ===== ====== ===== ==================
207 0 0x0000000010b6e974 2060 0x0002 1 0x00002aabbc76e974
208 1 0x0000000010b6e034 2060 0x0002 2 0x00002aabbc76e034
209 2 0x0000000010b6d6f4 2060 0x0002 3 0x00002aabbc76d6f4
210 3 0x0000000010b6cdb4 2060 0x0002 4 0x00002aabbc76cdb4
211 4 0x0000000010b6c474 2060 0x0002 5 0x00002aabbc76c474
212 5 0x0000000010b6bb34 2060 0x0002 6 0x00002aabbc76bb34
213 6 0x0000000010b6b1f4 2060 0x0002 7 0x00002aabbc76b1f4
214 7 0x0000000010b6a8b4 2060 0x0002 8 0x00002aabbc76a8b4
215 8 0x0000000010b69f74 2060 0x0002 9 0x00002aabbc769f74
216 9 0x0000000010b69634 2060 0x0002 10 0x00002aabbc769634
217 10 0x0000000010b68cf4 2060 0x0002 11 0x00002aabbc768cf4
219 249 0x0000000000000000 0 0x0000 250 0x00002aab2b400000
220 250 0x0000000000000000 0 0x0000 251 0x00002aab2b400000
221 251 0x0000000000000000 0 0x0000 252 0x00002aab2b400000
222 252 0x0000000000000000 0 0x0000 253 0x00002aab2b400000
223 253 0x0000000000000000 0 0x0000 254 0x00002aab2b400000
224 254 0x0000000000000000 0 0x0000 255 0x00002aab2b400000
225 255 0x0000000000000000 0 0x0000 32768 0x00002aab2b400000
228 qsz 256 last_avail_idx 0 last_used_idx 0
233 Turn on/off debug for vhost
239 .. code-block:: shell
241 debug vhost-user <on | off>.
244 ========================
245 Delete a vHost User interface using the interface name or the software
246 interface index. Use the '*show interface*' command to determine the
247 software interface index. On deletion, the linux socket will not be
253 .. code-block:: shell
255 delete vhost-user {<interface> | sw_if_index <sw_idx>}.
259 Example of how to delete a vhost interface by name:
261 .. code-block:: console
263 vpp# delete vhost-user VirtualEthernet0/0/1
265 Example of how to delete a vhost interface by software interface index:
267 .. code-block:: console
269 vpp# delete vhost-user sw_if_index 1