VTNET(4)

📦
version 15.1 · 2 versions
, in freebsd 15.1

VTNET 💖🦋 — the VirtIO Ethernet driver, explained by your fav Unix bestie

Okay so picture this: you're in a virtual machine, right, and you need network. That's literally where vtnet comes in. The manual page is vtnet(4) and it lives in the Kernel Interfaces Manual, and I'm about to walk you through every single line because you deserve to understand it, periodt. 🎀

✨ SYNOPSIS ✨

So you wanna get this driver into your kernel? Bestie, you got two options. Option one, drop these lines in your kernel configuration file:

device vtnet

Option two, if you'd rather load it as a module at boot time (lowkey easier), put this line in loader.conf(5):

if_vtnet_load="YES"

Both work. Choose your fighter. 💅

🌸 DESCRIPTION 🌸

The vtnet device driver provides support for VirtIO Ethernet devices. That's the whole vibe. 🫶

Okay so here's where it gets iconic. If the hypervisor advertises the appropriate features (iykyk), the vtnet driver supports so many things, let me list them because they all matter:

  • 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
  • Jumbo Frames (up to 9216 bytes)

That Jumbo Frames one can be configured via the interface MTU setting, ngl that's kinda the main character move. 🔥

Now, about TCP LRO, there are literally two flavors and you need to know both:

  • Hardware TCP LRO — this is performed by the host providing TCP segments larger than the MTU to the guest.
  • Software TCP LRO — this 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. One. Not both. Please. 😭 And 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 for that.

Also important, bestie: TCP/UDP receive checksum offload cannot be configured independently for IPv4 and IPv6. Not a thing. And if you select an MTU larger than 1500 bytes with the ifconfig(8) utility, that configures the adapter to receive and transmit Jumbo Frames. Slay.

For more info on configuring this device, see ifconfig(8). 💖

🎀 LOADER TUNABLES 🎀

Okay so these tunables can be set at the loader(8) prompt before booting the kernel or stored in loader.conf(5). Either way, here they all are, and yes I'm giving you every single one because I'm not about to skip the boring parts. 🙈

  • 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. > Heads up bestie: 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. (Note: this one has no hw.vtnet.X. version, just so you know. 🧚)

🌺 TRANSMIT QUEUE STATISTICS 🌺

For each transmit queue of each interface, the following read-only statistics are provided. Get your screenshot finger ready because these are all facts:

  • 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 🍓

Same energy but for receive queues. 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 🦋

Now we're zooming out to the whole interface. 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 🌈

And now the receive side, same deal. 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. (Yes, "loger" is in the original, I'm not fixing it, it's iconic. 💀)
  • dev.vtnet.X.mbuf_alloc_failed — The number of times an mbuf cluster allocation for the receive buffer failed.
Lowkey that "loger" typo is giving "the original author was tired" and I respect it. 🫶

👑 INTERFACE CONFIGURATION PARAMETER 👑

For each interface, the following read-only configuration parameters are provided. These are the big-picture vibes:

  • 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 💅

You already know, but here's where to go next, no cap:

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. Iconic behavior. 👑

💀 CAVEATS 💀

Only one big warning here but it matters: the vtnet driver only supports LRO when the hypervisor advertises the mergeable buffer feature. That's it. That's the caveat. Don't forget it. 🙈

And that's the whole page, bestie. This masterpiece of a man page is from the VTNET(4) kernel interfaces manual, dated December 19, 2025, on Debian. Go forth and configure your virtual ethernet with confidence. You got this. 💖✨🦋

📦 where this page comes from
  • freebsd 15.1: base 15.1
  • Copyright (c) 2011 Bryan Venteicher
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms