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.Dd June 6, 2014 32.Dt XNB 4 33.Os 34.Sh NAME 35.Nm xnb 36.Nd "Xen Paravirtualized Backend Ethernet Driver" 37.Sh SYNOPSIS 38To compile this driver into the kernel, place the following lines in your 39kernel configuration file: 40.Bd -ragged -offset indent 41.Cd "options XENHVM" 42.Cd "device xenpci" 43.Ed 44.Sh DESCRIPTION 45The 46.Nm 47driver provides the back half of a paravirtualized 48.Xr xen 4 49network connection. 50The netback and netfront drivers appear to their respective operating 51systems as Ethernet devices linked by a crossover cable. 52Typically, 53.Nm 54will run on Domain 0 and the netfront driver will run on a guest domain. 55However, it is also possible to run 56.Nm 57on a guest domain. 58It may be bridged or routed to provide the netfront 59domain access to other guest domains or to a physical network. 60.Pp 61In most respects, the 62.Nm 63device appears to the OS as any other Ethernet device. 64It can be configured at runtime entirely with 65.Xr ifconfig 8 . 66In particular, it supports MAC changing, arbitrary MTU sizes, checksum 67offload for IP, UDP, and TCP for both receive and transmit, and TSO. 68However, see 69.Sx CAVEATS 70before enabling txcsum, rxcsum, or tso. 71.Sh SYSCTL VARIABLES 72The following read-only variables are available via 73.Xr sysctl 8 : 74.Bl -tag -width indent 75.It Va dev.xnb.%d.dump_rings 76Displays information about the ring buffers used to pass requests between the 77netfront and netback. 78Mostly useful for debugging, but can also be used to 79get traffic statistics. 80.It Va dev.xnb.%d.unit_test_results 81Runs a builtin suite of unit tests and displays the results. 82Does not affect the operation of the driver in any way. 83Note that the test suite simulates error conditions; this will result in 84error messages being printed to the system log. 85.El 86.Sh SEE ALSO 87.Xr arp 4 , 88.Xr netintro 4 , 89.Xr ng_ether 4 , 90.Xr xen 4 , 91.Xr ifconfig 8 92.Sh HISTORY 93The 94.Nm 95device driver first appeared in 96.Fx 10.0 . 97.Sh AUTHORS 98.An -nosplit 99The 100.Nm 101driver was written by 102.An Alan Somers Aq Mt asomers@FreeBSD.org 103and John Suykerbuyk. 104.Sh CAVEATS 105Packets sent through Xennet pass over shared memory, so the protocol includes 106no form of link-layer checksum or CRC. 107Furthermore, Xennet drivers always report to their hosts that they support 108receive and transmit checksum offloading. 109They "offload" the checksum calculation by simply skipping it. 110That works fine for packets that are exchanged between two domains on the same 111machine. 112However, when a Xennet interface is bridged to a physical interface, 113a correct checksum must be attached to any packets bound for that physical 114interface. 115Currently, 116.Fx 117lacks any mechanism for an Ethernet device to 118inform the OS that newly received packets are valid even though their checksums 119are not. 120So if the netfront driver is configured to offload checksum calculations, 121it will pass non-checksumed packets to 122.Nm , 123which must then calculate the checksum in software before passing the packet 124to the OS. 125.Pp 126For this reason, it is recommended that if 127.Nm 128is bridged to a physical interface, then transmit checksum offloading should be 129disabled on the netfront. 130The Xennet protocol does not have any mechanism for the netback to request 131the netfront to do this; the operator must do it manually. 132.Sh BUGS 133The 134.Nm 135driver does not properly checksum UDP datagrams that span more than one 136Ethernet frame. 137Nor does it correctly checksum IPv6 packets. 138To workaround that bug, disable transmit checksum offloading on the 139netfront driver. 140