share/man/man4/xdisk.4

   1 .\" Copyright (c) 2012-2021 The DragonFly Project.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to The DragonFly Project
   4 .\" by Matthew Dillon <dillon@backplane.com>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. Neither the name of The DragonFly Project nor the names of its
  17 .\"    contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific, prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .Dd October 30, 2021
  34 .Dt XDISK 4
  35 .Os
  36 .Sh NAME
  37 .Nm xdisk
  38 .Nd Remote disk block device dmsg service
  39 .Sh SYNOPSIS
  40 To compile this driver into the kernel,
  41 place the following line in your
  42 kernel configuration file:
  43 .Bd -ragged -offset indent
  44 .Cd "device xdisk"
  45 .Ed
  46 .Pp
  47 Alternatively, to load the driver as a
  48 module at boot time, place the following line in
  49 .Xr loader.conf 5 :
  50 .Bd -literal -offset indent
  51 xdisk_load="YES"
  52 .Ed
  53 .Pp
  54 Note that
  55 .Dx
  56 does not compile this driver into the kernel by default.
  57 .Pp
  58 Since the userland hammer2 service daemon must be running, you cannot use
  59 xdisk block devices as boot devices.
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 driver exports local block devices and imports remote block devices.
  64 The devices show up under
  65 .Pa /dev/xa* ,
  66 .Pa /dev/serno ,
  67 .Pa /dev/by-label ,
  68 and
  69 .Pa /dev/*-by-uuid .
  70 It is recommended that all drive references go via
  71 .Pa /dev/serno ,
  72 .Pa /dev/by-label ,
  73 or
  74 .Pa /dev/*-by-uuid .
  75 The
  76 .Pa /dev/xa*
  77 paths can change at a whim depending on the order of operations.
  78 .Pp
  79 If a device goes away or the connection is lost, the device entry
  80 remains until the ref-count drops to 0.
  81 Any active I/O will hard-block.
  82 Resumption of the connection resumes operations where they left off.
  83 No I/O requests are lost.
  84 The driver is robust across reconnection, crashes, and reboots, but
  85 possibly not across power failures if the target drive loses buffered
  86 write data for completed I/Os.
  87 .Pp
  88 Over a 1Gbe network, synchronous D1 latency still allows for around
  89 30-40 MBytes/sec.
  90 Filesystem mounts can usually max-out the line rate
  91 (in excess of 100 MBytes/sec) due to filesystem read-ahead and write
  92 buffering.
  93 .Pp
  94 The
  95 .Xr hammer2 8
  96 service daemon is used as an intermediary and must be running on all
  97 machines in question.
  98 .Sh SEE ALSO
  99 .Xr ahci 4 ,
 100 .Xr nvme 4 ,
 101 .Xr hammer2 8
 102 .Sh HISTORY
 103 The
 104 .Nm
 105 driver has been in the source tree a while
 106 but is now automatically built and part of base as of
 107 .Dx 6.1 .
 108 .Sh AUTHORS
 109 .An -nosplit
 110 The
 111 .Nm
 112 driver was written by
 113 .An Matthew Dillon Aq Mt dillon@backplane.com