'\" t .\" Title: xnbd-client .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 02/12/2014 .\" Manual: xNBD Manual .\" Source: xNBD 0.3.0 .\" Language: English .\" .TH "XNBD\-CLIENT" "1" "02/12/2014" "xNBD 0\&.3\&.0" "xNBD Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" xnbd-client \- Connect to a server running xnbd\-server(8), to use its exported block device .SH "SYNOPSIS" .sp \fBxnbd\-client\fR [\fIOPTIONS\fR] [bs=\fISIZE\fR] [timeout=\fISECONDS\fR] \fIHOST\fR \fIPORT\fR \fINBD\-DEVICE\fR .sp \fBxnbd\-client\fR [\fIOPTIONS\fR] \-\-connect \fINBD\-DEVICE\fR \fIHOST\fR \fIPORT\fR [\fIHOST\fR \fIPORT\fR \&.\&.] .sp \fBxnbd\-client\fR \-\-disconnect \fINBD\-DEVICE\fR .sp \fBxnbd\-client\fR \-\-check \fINBD\-DEVICE\fR .sp \fBxnbd\-client\fR [\fIOPTIONS\fR] \-\-getsize64 \fIHOST\fR \fIPORT\fR [\fIHOST\fR \fIPORT\fR \&.\&.] .SH "DESCRIPTION" .sp With \fBxnbd\-client\fR, you can connect to a server running xnbd\-server or xnbd\-wrapper, thus using raw diskspace from that server as a block device on the local client\&. .sp To do this, support from the Linux Kernel is necessary, in the form of the Network Block Device (NBD)\&. When you have that, either in the kernel, or as a module, you can connect to an NBD server and use its exported file through a block special file with major mode 43\&. .sp Long options can also be specified with two leading dashes\&. Some options are call\-compatible to nbd\-client(1) as are most behavioural switches\&. This makes \fBxnbd\-client\fR a plug\-in replacement for nbd\-client\&. .SH "OPTIONS" .sp The following options are supported: .PP \fB\-\-blocksize\fR \fISIZE\fR .RS 4 Use the provided value as block size\&. Default is 1024; allowed values are either 512, 1024, 2048 or 4096\&. For best results use a block size value of 4096\&. For compatibility to nbd\-client(1) you can also use bs=\fISIZE\fR\&. .RE .PP \fB\-\-check\fR|\fB\-c\fR .RS 4 Check whether the specified nbd device is connected\&. If the device is connected, \fBxnbd\-client\fR will exit with an exit state of 0 and print the PID of the \fBxnbd\-client\fR instance that connected it to stdout\&. If the device exists but is not connected (i\&.e\&. is free for use), \fBxnbd\-client\fR will exit with code 2 and not print anything on stdout\&. If the device does not exist (for example because the nbd module was not loaded) or if an error occurred, \fBxnbd\-client\fR will exit with a positive return code other than 2 and not print anything on stdout, either\&. .RE .PP \fB\-\-connect\fR|\fB\-C\fR .RS 4 Connect to the nbd\-server .RE .PP \fB\-\-disconnect\fR|\fB\-d\fR .RS 4 Disconnect the specified nbd device from the server\&. Terminates execution with an exit state of 0 on success\&. .RE .PP \fB\-\-getsize64\fR .RS 4 Report remote disk size in bytes, mimicking blockdev(8)\&. .RE .PP \fB\-\-exportname\fR \fINAME\fR .RS 4 If the server supports to access devices by an identifier, use \fINAME\fR to request access to a particular volume\&. This command is useful in combination with an xnbd\-wrapper and only succeeds, if the remote host is exporting the requested device\&. .RE .PP \fB\-\-retry\fR \fICOUNT\fR .RS 4 Try up to "COUNT" times to connect to the associated nbd\-server\&. Default is 1, that is \fBxnbd\-client\fR will stop after the first unsuccessful try\&. .RE .PP \fB\-\-recovery\-command\fR \fICOMMAND\fR .RS 4 Invoke the specified command on unexpected disconnection .RE .sp \fB\-\-recovery\-command\-reboot\fR: Invoke the reboot(8) command on unexpected disconnection .PP \fB\-\-timeout\fR \fISECONDS\fR .RS 4 Use a timeout period (default is 0 which means not to use a timeout)\&. Please do not use this option for now, as it seems not to work due to a bug in the kernel module\&. For compatibility to nbd\-client(1) you can also use timeout=\fISECONDS\fR .RE .SH "POSITIONAL ARGUMENTS" .sp The following positional options are supported: .PP \fIHOST\fR .RS 4 The site to connect to a remote xnbd\-server\&. You can specify any resolvable hostname, IPv4 or IPv6 address\&. .RE .PP \fIPORT\fR .RS 4 The port number to connect to on remote side .RE .PP \fINBD\-DEVICE\fR .RS 4 The local nbd\-device to be associated with the remote xnbd\-server\&. .RE .sp You can specify multiple host port tuples\&. \fBxnbd\-client\fR will try to connect to each of them in order until it succeeds to establish a connection to a server\&. .SH "BUGS" .sp The NBD device is known to deadlock when not being used altogether with the deadline scheduler\&. Make sure to do: .sp .if n \{\ .RS 4 .\} .nf echo deadline > /sys/block/nbd0/queue/scheduler .fi .if n \{\ .RE .\} .SH "SEE ALSO" .sp xnbd\-server(8), xnbd\-wrapper(8) .SH "AUTHOR" .sp The NBD kernel module and the NBD tools have been written by Pavel Macheck (pavel@ucw\&.cz) and is now maintained by Paul Clements (Paul\&.Clements@steeleye\&.com)\&. .sp The xNBD userland programs have been written by Takahiro Hirofuchi (t\&.hirofuchi@aist\&.go\&.jp)\&. .sp This manual page was written by Arno Toell (arno@debian\&.org) for the Debian GNU/Linux system (but may be used by others)\&. Large parts are verbatim copies of the original nbd\-server and nbd\-client manual pages written by Wouter Verhelst (wouter@debian\&.org)\&. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation\&.