XNBD-SERVER(8)
==============
:man source:   {manual_package}
:man version:  {manual_version}
:man manual:   {manual_title}


NAME
----
xnbd-server - Serve a file as a block device to other computers via the NBD protocol


SYNOPSIS
--------
*xnbd-server* --target [options] 'DISK_IMAGE'

*xnbd-server* --cow-target [options] 'BASE_DISK_IMAGE'

*xnbd-server* --proxy [options] [--target-exportname 'NAME']
'REMOTE_HOST' 'REMOTE_PORT' 'CACHE_IMAGE'
'CACHE_BITMAP_IMAGE' 'CONTROL_SOCKET_PATH'

*xnbd-server* --help

*xnbd-server* --version


DESCRIPTION
-----------
*xnbd-server* is a server program of the Network Block Device (NBD) protocol.
It exports an image file to the clients of the NBD protocol over network. A
client node can access to the exported file through a block-level I/O interface;
it is possible to create swap areas on it or create file systems on it.

The xNBD (i.e. extended NBD) programs offer several advantages over the original
NBD implementation. In addition to the original features, xNBD is
intended to achieve better performance. It supports (distributed) copy-on-write,
(basic) snapshot support, live storage migration for virtual machines,
and IPv6 networking.

*xnbd-server* can operate in three modes (i.e., the target mode, the copy-on-write
target mode, and the proxy mode).

*xnbd-server* *--target* exports 'DISK_IMAGE' to clients.

*xnbd-server* *--cow-target* exports 'BASE_DISK_IMAGE' to clients. Write operations
are not committed to the exported disk image, but to a separate
file. This separate file is removed when the server instance is shutdown, and
all changes are lost.

*xnbd-server* *--proxy* provides the image server of the NBD protocol,
but it actually works as a proxy to a remote *xnbd-server* specified with
'REMOTE_HOST' and 'REMOTE_PORT'.

The proxy server receives read/write requests from clients as a normal image
server does. But, it locally caches disk blocks, and retrieves disk blocks from
the remote server if necessary. No write operation does not happen at the
remote server.

Cached blocks are saved in 'CACHE_DISK_IMAGE'. The block numbers of cached
blocks are saved in 'CACHE_BITMAP_IMAGE'. The proxy server is controlled by
xnbd-bgctl(1) through 'CONTROL_SOCKET_PATH'.

The proxy server can be used to speed up remote access, share a read-only disk
image among multiple servers and clients, and replicate an exported image to
another node transparently. It also works for live storage migration of
virtual machines.

WARNING: Multiple clients can concurrently access to a single server instance.
Yet *xnbd-server* does not offer any locking or synchronization mechanism among
concurrent clients. In most cases you WILL need a cluster file system on the
exported image to avoid damage to your data.


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

*--daemonize*::
    Run *xnbd-server* in the background

*--inetd*::
    Run *xnbd-server* for an Internet super-server daemon (e.g., inetd).
    All network I/O is redirected to the stdin descriptor.

*--logpath* 'FILE'::
    Log informational messages to file 'FILE' rather than stderr/syslog.

*--syslog*::
    Log informational messages to syslog.

*--lport* 'PORT'::
    Listen incoming connections on the given PORT. If this argument is
    not given, *xnbd-server* will listen on port 8520 by default.

*--readonly*::
    Export the image file as read-only. If receiving a write request from a
    client, the server disconnects the client immediately. If this option is
    used in the proxy mode, *xnbd-server* rejects write requests from clients,
    but accepts read requests and may cache new blocks. The cache image file is
    updated if new blocks are cached.

*--connected-fd* 'NUMBER'::
    Use file descriptor 'NUMBER' as a bi-directional, pre-negotiated channel to a
    single client.  Used by xnbd-wrapper(8) on invocation of xnbd-server, internally.
    The file descriptor is turned to blocking mode by xnbd-server before usage.


OPTIONS (proxy mode only)
-------------------------
*--target-exportname* 'NAME'::
    Set the export name to request from an xnbd-wrapper target.

*--clear-bitmap*::
    Clear an existing bitmap file.  By default, previous state is re-used.

*--max-queue-size* 'NUMBER'::
    Limit the total number of queued requests to 'NUMBER'. If the current
    number of queued requests reaches this limitation, the server delays
    receiving new requests. By default (i.e., 0), there is no limitation.
    Use this option to keep memory usage in a safe level if a client
    asynchronously sends a large number of requests.

*--max-buf-size* 'NUMBER'::
    Limit the usage of internal buffer to approximately 'NUMBER' bytes. If the
    current buffer usage reaches this limitation, the server delays receiving
    new requests. By default (i.e., 0), there is no limitation.
    Use this option to keep memory usage in a safe level if a client
    asynchronously sends a large number of requests.


SIGNALS
-------
*SIGUSR1*::
    Take a snapshot of the image file. Currently, this feature works
    only in the target mode.

*SIGUSR2*::
    Change the proxy mode to the target mode. Use xnbd-bgctl --switch
    instead of sending this signal.


SEE ALSO
--------
xnbd-client(1), xnbd-bgctl(1), xnbd-wrapper(8)


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

include::author_verhelst_toell.txt[]
