table of contents
XNBD-SERVER(8) | xNBD Manual | XNBD-SERVER(8) |
NAME¶
xnbd-server - Serve a file as a block device to other computers via the NBD protocolSYNOPSIS¶
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 --versionDESCRIPTION¶
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.OPTIONS¶
The following options are supported: --daemonizeRun 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 NAMESet 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¶
SIGUSR1Take 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¶
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). The xNBD userland programs have been written by Takahiro Hirofuchi (t.hirofuchi@aist.go.jp). 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.02/12/2014 | xNBD 0.3.0 |