VTNET(4) FreeBSD Kernel Interfaces Manual VTNET(4)
NAME
vtnet - VirtIO Ethernet driver
SYNOPSIS
To compile this driver into the kernel, place the following lines in your
kernel configuration file:
device vtnet
Alternatively, to load the driver as a module at boot time, place the
following line in loader.conf(5):
if_vtnet_load="YES"
DESCRIPTION
The vtnet device driver provides support for VirtIO Ethernet devices.
If the hypervisor advertises the appropriate features, the vtnet driver
supports TCP/UDP checksum offload for both transmit and receive, TCP
segmentation offload (TSO), TCP large receive offload (LRO), hardware
VLAN tag stripping/insertion features, a multicast hash filter, as well
as Jumbo Frames (up to 9216 bytes), which can be configured via the
interface MTU setting.
Two flavors of TCP LRO are supported: Hardware TCP LRO, which is
performed by the host providing TCP segments larger than the MTU to the
guest, and Software TCP LRO, which is performed by the network stack of
the guest processing TCP segments in an optimized way. Only one flavour
of TCP LRO should be used. Since hardware TCP LRO can have bad
interactions with IP forwarding and software TCP LRO mitigates several
drawbacks of hardware TCP LRO, the default setting is to disable hardware
TCP LRO. See the loader tunable hw.vtnet.X.lro_disable.
TCP/UDP receive checksum offload cannot be configured independently for
IPv4 and IPv6. Selecting an MTU larger than 1500 bytes with the
ifconfig(8) utility configures the adapter to receive and transmit Jumbo
Frames.
For more information on configuring this device, see ifconfig(8).
LOADER TUNABLES
Tunables can be set at the loader(8) prompt before booting the kernel or
stored in loader.conf(5).
hw.vtnet.csum_disable
hw.vtnet.X.csum_disable
This tunable disables receive and transmit checksum offloading
for TCP and UDP. This also implies that TCP segmentation
offloading and large receive offload are disabled. The default
value is 0.
hw.vtnet.fixup_needs_csum
hw.vtnet.X.fixup_needs_csum
This tunable enforces the calculation of a valid TCP or UDP
checksum for packets received with VIRTIO_NET_HDR_F_NEEDS_CSUM
being set in the flags field of the structure struct
virtio_net_hdr. It also marks the checksum as being correct in
the mbuf packet header. The default value is 0. This tunable is
deprecated and will be removed in FreeBSD 16.
hw.vtnet.tso_disable
hw.vtnet.X.tso_disable
This tunable disables TCP segmentation offloading. The default
value is 0.
hw.vtnet.lro_disable
hw.vtnet.X.lro_disable
This tunable disables hardware TCP LRO. The default value is 1.
hw.vtnet.mq_disable
hw.vtnet.X.mq_disable
This tunable disables multiqueue. The default value is 0.
hw.vtnet.mq_max_pairs
hw.vtnet.X.mq_max_pairs
This tunable sets the maximum number of transmit and receive
queue pairs. Multiple queues are only supported when the
Multiqueue feature is negotiated. This driver supports a maximum
of 8 queue pairs. The number of queue pairs used is the lesser
of the maximum supported by the driver and the hypervisor, the
number of CPUs present in the guest, and this tunable if not
zero. The default value is 0.
hw.vtnet.tso_maxlen
hw.vtnet.X.tso_maxlen
This tunable sets the TSO burst limit. The default value is
65535.
hw.vtnet.rx_process_limit
hw.vtnet.X.rx_process_limit
This tunable sets the number of RX segments processed in one
pass. The default value is 1024.
hw.vtnet.lro_entry_count
hw.vtnet.X.lro_entry_count
This tunable sets the software TCP LRO entry count. The default
value is 128, the minimum value is 8.
hw.vtnet.lro_mbufq_depth
hw.vtnet.X.lro_mbufq_depth
This tunable sets the depth of the software TCP LRO mbuf queue.
The default value is 0.
hw.vtnet.altq_disable
This tunable disables ALTQ support, allowing the use of
multiqueue instead. This option applies to all interfaces. The
default value is 0.
TRANSMIT QUEUE STATISTICS
For each transmit queue of each interface the following read-only
statistics are provided:
dev.vtnet.X.txqY.rescheduled
The number of times the transmit interrupt handler was
rescheduled.
dev.vtnet.X.txqY.tso
The number of times TCP segment offloading was performed.
dev.vtnet.X.txqY.csum
The number of times transmit checksum offloading for UDP or TCP
was performed.
dev.vtnet.X.txqY.omcasts
The number of multicast packets that were transmitted.
dev.vtnet.X.txqY.obytes
The number of bytes that were transmitted (based on Ethernet
frames).
dev.vtnet.X.txqY.opackets
The number of packets that were transmitted (Ethernet frames).
RECEIVE QUEUE STATISTICS
For each receive queue of each interface the following read-only
statistics are provided:
dev.vtnet.X.rxqY.rescheduled
The number of times the receive interrupt handler was
rescheduled.
dev.vtnet.X.rxqY.host_lro
The number of times TCP large receive offload was performed.
dev.vtnet.X.rxqY.csum_failed
The number of times a packet with a request for receive or
transmit checksum offloading was received and this request
failed. The different reasons for the failure are counted by
dev.vtnet.X.rx_csum_inaccessible_ipproto,
dev.vtnet.X.rx_csum_bad_ipproto, dev.vtnet.X.rx_csum_bad_ethtype,
and dev.vtnet.X.rx_csum_bad_offset.
dev.vtnet.X.rxqY.csum
The number of times receive checksum offloading for UDP or TCP
was performed.
dev.vtnet.X.rxqY.ierrors
The number of times an error occurred during input processing.
dev.vtnet.X.rxqY.iqdrops
The number of times a packet was dropped during input processing.
dev.vtnet.X.rxqY.ibytes
The number of bytes that were received (based on Ethernet
frames).
dev.vtnet.X.rxqY.ipackets
The number of packets that were received (Ethernet frames).
INTERFACE TRANSMIT STATISTICS
For each interface the following read-only transmit statistics are
provided:
dev.vtnet.X.tx_task_rescheduled
The sum of dev.vtnet.X.txqY.rescheduled over all transmit queues
of the interface.
dev.vtnet.X.tx_tso_offloaded
The sum of dev.vtnet.X.txqY.tso over all transmit queues of the
interface.
dev.vtnet.X.tx_csum_offloaded
The sum of dev.vtnet.X.txqY.csum over all transmit queues of the
interface.
dev.vtnet.X.tx_defrag_failed
The number of times an attempt to defragment an mbuf chain failed
during a transmit operation.
dev.vtnet.X.tx_defragged
The number of times an mbuf chain was defragmented during a
transmit operation.
dev.vtnet.X.tx_tso_without_csum
The number of times TCP segment offloading was attempted without
transmit checksum offloading.
dev.vtnet.X.tx_tso_not_tcp
The number of times TCP segment offloading was attempted for a
non-TCP packet.
dev.vtnet.X.tx_csum_proto_mismatch
The number of times the IP protocol version of the transmit
checksum offloading request did not match the IP protocol version
of the packet.
dev.vtnet.X.tx_csum_unknown_ethtype
The number of times a transmit offload operation was requested
for an ethernet frame for which the EtherType was neither IPv4
nor IPv6 (considering simple VLAN tagging).
INTERFACE RECEIVE STATISTICS
For each interface the following read-only receive statistics are
provided:
dev.vtnet.X.rx_task_rescheduled
The sum of dev.vtnet.X.rxqY.rescheduled over all receive queues
of the interface.
dev.vtnet.X.rx_csum_offloaded
The sum of dev.vtnet.X.rxqY.csum over all receive queues of the
interface.
dev.vtnet.X.rx_csum_failed
The sum of dev.vtnet.X.rxqY.csum_failed over all receive queues
of the interface.
dev.vtnet.X.rx_csum_inaccessible_ipproto
The number of times a packet with a request for receive or
transmit checksum offloading was received where the IP protocol
was not accessible.
dev.vtnet.X.rx_csum_bad_offset
The number of times fixing the checksum required by
hw.vtnet.fixup_needs_csum or hw.vtnet.X.fixup_needs_csum was
attempted for a packet where the csum is not located in the first
mbuf.
dev.vtnet.X.rx_csum_bad_ipproto
The number of times a packet with a request for receive or
transmit checksum offloading was received where the IP protocol
was neither TCP nor UDP.
dev.vtnet.X.rx_csum_bad_ethtype
The number of times a packet with a request for receive or
transmit checksum offloading was received where the EtherType was
neither IPv4 nor IPv6.
dev.vtnet.X.rx_mergeable_failed
The number of times receiving a mergable buffer failed.
dev.vtnet.X.rx_enq_replacement_failed
The number of times the enqueuing the replacement receive mbuf
chain failed.
dev.vtnet.X.rx_frame_too_large
The number of times the frame was loger than the mbuf chain
during large receive offload without mergeable buffers.
dev.vtnet.X.mbuf_alloc_failed
The number of times an mbuf cluster allocation for the receive
buffer failed.
INTERFACE CONFIGURATION PARAMETER
For each interface the following read-only configuration parameters are
provided:
dev.vtnet.X.act_vq_pairs
The number of active virtqueue pairs.
dev.vtnet.X.req_vq_pairs
The number of requested virtqueue pairs.
dev.vtnet.X.max_vq_pairs
The maximum number of supported virtqueue pairs.
dev.vtnet.X.flags
The flags of the interface. Mostly for debugging purposes.
dev.vtnet.X.features
The features of the interface as defined by the virtio
specification.
SEE ALSO
arp(4), netintro(4), ng_ether(4), virtio(4), vlan(4), ifconfig(8)
HISTORY
The vtnet driver was written by Bryan Venteicher <bryanv@FreeBSD.org>.
It first appeared in FreeBSD 9.0.
CAVEATS
The vtnet driver only supports LRO when the hypervisor advertises the
mergeable buffer feature.
FreeBSD 15.1-STABLE-HBSD December 19, 2025 VTNET(4)