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 40To compile this driver into the kernel, 41place the following line in your 42kernel configuration file: 43.Bd -ragged -offset indent 44.Cd "device xdisk" 45.Ed 46.Pp 47Alternatively, to load the driver as a 48module at boot time, place the following line in 49.Xr loader.conf 5 : 50.Bd -literal -offset indent 51xdisk_load="YES" 52.Ed 53.Pp 54Note that 55.Dx 56does not compile this driver into the kernel by default. 57.Pp 58Since the userland hammer2 service daemon must be running, you cannot use 59xdisk block devices as boot devices. 60.Sh DESCRIPTION 61The 62.Nm 63driver exports local block devices and imports remote block devices. 64The devices show up under 65.Pa /dev/xa* , 66.Pa /dev/serno , 67.Pa /dev/by-label , 68and 69.Pa /dev/*-by-uuid . 70It is recommended that all drive references go via 71.Pa /dev/serno , 72.Pa /dev/by-label , 73or 74.Pa /dev/*-by-uuid . 75The 76.Pa /dev/xa* 77paths can change at a whim depending on the order of operations. 78.Pp 79If a device goes away or the connection is lost, the device entry 80remains until the ref-count drops to 0. 81Any active I/O will hard-block. 82Resumption of the connection resumes operations where they left off. 83No I/O requests are lost. 84The driver is robust across reconnection, crashes, and reboots, but 85possibly not across power failures if the target drive loses buffered 86write data for completed I/Os. 87.Pp 88Over a 1Gbe network, synchronous D1 latency still allows for around 8930-40 MBytes/sec. 90Filesystem mounts can usually max-out the line rate 91(in excess of 100 MBytes/sec) due to filesystem read-ahead and write 92buffering. 93.Pp 94The 95.Xr hammer2 8 96service daemon is used as an intermediary and must be running on all 97machines in question. 98.Sh SEE ALSO 99.Xr ahci 4 , 100.Xr nvme 4 , 101.Xr hammer2 8 102.Sh HISTORY 103The 104.Nm 105driver has been in the source tree a while 106but is now automatically built and part of base as of 107.Dx 6.1 . 108.Sh AUTHORS 109.An -nosplit 110The 111.Nm 112driver was written by 113.An Matthew Dillon Aq Mt dillon@backplane.com 114