share/man/man4/xnb.4

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