1.\" Copyright (c) 2012 Spectra Logic Corporation 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions, and the following disclaimer, 9.\" without modification. 10.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer 11.\" substantially similar to the "NO WARRANTY" disclaimer below 12.\" ("Disclaimer") and any redistribution must be conditioned upon 13.\" including a substantially similar Disclaimer requirement for further 14.\" binary redistribution. 15.\" 16.\" NO WARRANTY 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR 20.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 25.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 26.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGES. 28.\" 29.\" Authors: Alan Somers (Spectra Logic Corporation) 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd June 6, 2014 34.Dt XNB 4 35.Os 36.Sh NAME 37.Nm xnb 38.Nd "Xen Paravirtualized Backend Ethernet Driver" 39.Sh SYNOPSIS 40To compile this driver into the kernel, place the following lines in your 41kernel configuration file: 42.Bd -ragged -offset indent 43.Cd "options XENHVM" 44.Cd "device xenpci" 45.Ed 46.Sh DESCRIPTION 47The 48.Nm 49driver provides the back half of a paravirtualized 50.Xr xen 4 51network connection. 52The netback and netfront drivers appear to their respective operating 53systems as Ethernet devices linked by a crossover cable. 54Typically, 55.Nm 56will run on Domain 0 and the netfront driver will run on a guest domain. 57However, it is also possible to run 58.Nm 59on a guest domain. 60It may be bridged or routed to provide the netfront's 61domain access to other guest domains or to a physical network. 62.Pp 63In most respects, the 64.Nm 65device appears to the OS as an other Ethernet device. 66It can be configured at runtime entirely with 67.Xr ifconfig 8 . 68In particular, it supports MAC changing, arbitrary MTU sizes, checksum 69offload for IP, UDP, and TCP for both receive and transmit, and TSO. 70However, see 71.Sx CAVEATS 72before enabling txcsum, rxcsum, or tso. 73.Sh SYSCTL VARIABLES 74The following read-only variables are available via 75.Xr sysctl 8 : 76.Bl -tag -width indent 77.It Va dev.xnb.%d.dump_rings 78Displays information about the ring buffers used to pass requests between the 79netfront and netback. 80Mostly useful for debugging, but can also be used to 81get traffic statistics. 82.It Va dev.xnb.%d.unit_test_results 83Runs a builtin suite of unit tests and displays the results. 84Does not affect the operation of the driver in any way. 85Note that the test suite simulates error conditions; this will result in 86error messages being printed to the system log. 87.El 88.Sh SEE ALSO 89.Xr arp 4 , 90.Xr netintro 4 , 91.Xr ng_ether 4 , 92.Xr xen 4 , 93.Xr ifconfig 8 94.Sh HISTORY 95The 96.Nm 97device driver first appeared in 98.Fx 10.0 . 99.Sh AUTHORS 100.An -nosplit 101The 102.Nm 103driver was written by 104.An Alan Somers Aq Mt alans@spectralogic.com 105and 106.An John Suykerbuyk Aq Mt johns@spectralogic.com . 107.Sh CAVEATS 108Packets sent through Xennet pass over shared memory, so the protocol includes 109no form of link-layer checksum or CRC. 110Furthermore, Xennet drivers always report to their hosts that they support 111receive and transmit checksum offloading. 112They "offload" the checksum calculation by simply skipping it. 113That works fine for packets that are exchanged between two domains on the same 114machine. 115However, when a Xennet interface is bridged to a physical interface, 116a correct checksum must be attached to any packets bound for that physical 117interface. 118Currently, 119.Fx 120lacks any mechanism for an Ethernet device to 121inform the OS that newly received packets are valid even though their checksums 122are not. 123So if the netfront driver is configured to offload checksum calculations, 124it will pass non-checksumed packets to 125.Nm , 126which must then calculate the checksum in software before passing the packet 127to the OS. 128.Pp 129For this reason, it is recommended that if 130.Nm 131is bridged to a physical interface, then transmit checksum offloading should be 132disabled on the netfront. 133The Xennet protocol does not have any mechanism for the netback to request 134the netfront to do this; the operator must do it manually. 135.Sh BUGS 136The 137.Nm 138driver does not properly checksum UDP datagrams that span more than one 139Ethernet frame. 140Nor does it correctly checksum IPv6 packets. 141To workaround that bug, disable transmit checksum offloading on the 142netfront driver. 143