share/man/man4/xnb.4

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