XNBD-CLIENT(1)
==============
:man source:   {manual_package}
:man version:  {manual_version}
:man manual:   {manual_title}


NAME
----
xnbd-client - Connect to a server running xnbd-server(8), to use its exported block device


SYNOPSIS
--------
*xnbd-client* ['OPTIONS'] [bs='SIZE'] [timeout='SECONDS'] 'HOST' 'PORT' 'NBD-DEVICE'

*xnbd-client* ['OPTIONS'] --connect 'NBD-DEVICE' 'HOST' 'PORT' ['HOST' 'PORT' ..]

*xnbd-client* --disconnect 'NBD-DEVICE'

*xnbd-client* --check 'NBD-DEVICE'

*xnbd-client* ['OPTIONS'] --getsize64 'HOST' 'PORT' ['HOST' 'PORT' ..]


DESCRIPTION
-----------
With *xnbd-client*, 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.

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.

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
*xnbd-client* a plug-in replacement for nbd-client.


OPTIONS
-------
The following options are supported:

*--blocksize* 'SIZE'::
    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='SIZE'.

*--check*|*-c*::
    Check whether the specified nbd device is connected.
    +
    If the device is connected, *xnbd-client* will exit with an exit state
    of 0 and print the PID of the *xnbd-client* instance that connected it
    to stdout.
    +
    If the device exists but is not connected (i.e. is free for use),
    *xnbd-client* 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, *xnbd-client* will exit with a positive return code
    other than 2 and not print anything on stdout, either.

*--connect*|*-C*::
    Connect to the nbd-server

*--disconnect*|*-d*::
    Disconnect the specified nbd device from the server. Terminates
    execution with an exit state of 0 on success.

*--getsize64*::
    Report remote disk size in bytes, mimicking blockdev(8).

*--exportname* 'NAME'::
    If the server supports to access devices by an identifier, use 'NAME'
    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.

*--retry* 'COUNT'::
    Try up to "COUNT" times to connect to the associated nbd-server.
    Default is 1, that is *xnbd-client* will stop after the first
    unsuccessful try.

*--recovery-command* 'COMMAND'::
    Invoke the specified command on unexpected disconnection

*--recovery-command-reboot*:
    Invoke the reboot(8) command on unexpected disconnection

*--timeout* 'SECONDS'::
    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='SECONDS'


POSITIONAL ARGUMENTS
--------------------
The following positional options are supported:

'HOST'::
    The site to connect to a remote xnbd-server. You can specify any
    resolvable hostname, IPv4 or IPv6 address.

'PORT'::
    The port number to connect to on remote side

'NBD-DEVICE'::
    The local nbd-device to be associated with the remote xnbd-server.

You can specify multiple host port tuples. *xnbd-client* will try to connect
to each of them in order until it succeeds to establish a connection to a
server.


BUGS
----
The NBD device is known to deadlock when not being used altogether with the
deadline scheduler. Make sure to do:

-----------------
echo deadline > /sys/block/nbd0/queue/scheduler
-----------------

SEE ALSO
--------
xnbd-server(8), xnbd-wrapper(8)


AUTHOR
------
include::author_xnbd.txt[]

include::author_verhelst_toell.txt[]
