NAME¶
xnbd-server — serve a file as a block device to other computers running
the GNU/Linux(tm) Operating System
SYNOPSIS¶
xnbd-server [--bgctlprefix
PATH] [--cow] [--daemonize] [--help]
[--inetd] [--logpath
PATH] [--lport
PORT] [--proxy] [--readonly]
[--target] [--version]
FILE
xnbd-server [--proxy] [
options]
TARGET_HOST
TARGET_PORT CACHE_IMAGE BITMAP_IMAGE
xnbd-server [--target] [
options]
CACHE_IMAGE
xnbd-server [--help] [--version]
DESCRIPTION¶
xnbd-server is the server for the Linux Network Block Device (NBD). With
xNBD, a client can use a file, exported over the network from a server, as a
block device. It can then be used for whatever purpose a normal block device
(hard disk, CD-ROM, ...) can be used for.
xNBD can be useful for diskless clients that need swap space, but you can also
create a file system on it and use it as though it were a local file system.
xNBD offers several advantages over the original NBD implementation. In addition
to features offered by NBD, xNBD supports better performance, (distributed)
Copy-on-Write, (basic) snapshot support and Live Storage Migration along with
IPv6 support.
xNBD can operate in two modes, the target mode and the alternative proxy mode.
In target mode, xNBD offers a listening TCP connection which allows a
xnbd-client(1) to access the exported
CACHE_IMAGE. In proxy
mode, xNBD connects another running xnbd-server instance and acts as
transparent proxy to the origin target server. This is very useful for storage
migration for Virtual Machine Monitors.
OPTIONS¶
The following options are supported:
- --bgctlprefix PATH
- The xNBD server can be controlled through a control socket.
When given, use prefix as file name, default is
/tmp/xnbd-bg.ctl).
- --cow
- Enable Copy-on-Write mode. When this option is provided,
write-operations are not committed to the exported FILE, but to a
separate file. This separate file is removed when the connection is
closed, which means that serving this way will make xnbd-server slow down
(especially on large block devices with lots of writes), and that after
disconnecting and reconnecting the client or the server, all changes are
lost.
- --daemonize
- Go into background as soon as the xnbd-server is started
up
- --inetd
- If xNBD shall be run from a Internet super-server, (e.g.
inetd), this argument instructs xNBD to redirect output to stderr
instead of a log file.
- --logpath FILE
- Log informational messages to the given FILE if
given. Defaults to /var/log/xnbd-server.log
- --lport PORT
- Accept incoming connections on the given PORT. A
valid port is any number between 1 and 65536. You may not use the same
listeing port more than once per system. If this argument is not given,
xNBD will listen on port 8520 by default.
- --proxy
- In the proxy server mode of xNBD, all I/O requests are
intercepted, and redirected to a origin target server if needed. All
updated blocks are saved at the proxy server, and read blocks are also
cached. No write does not happen at the target server.
-
- This feature is used for distributed Copy-on-Write NBD
disks; one read-only disk image is shared among multiple clients, and
updated disk data is saved at each proxy
- --readonly
- Export the FILE read only. If a client tries to
write to a read-only exported file, it will receive an error, but the
connection will stay up.
- --target
- Start an xNBD server in target mode, that is it will export
block level access to the given FILE.
-
- WARNING: If you need concurrent access from multiple
clients, you can access an exported image concurrently from multiple
clients. Yet xNBD does not do any locking or synchronization. In most
cases you WILL need a cluster file system on the exported FILE
image to avoid damage on your data.
POSITIONAL ARGUMENTS¶
The following positional options are supported:
- FILE
- The filename of the FILE that should be exported.
This can be an arbitrary file, including disk images and real block
devices (i.e. a block device like /dev/sda1).
- TARGET_HOST
- When in proxy mode, use the given TARGET_HOST as
origin host. The resulting xnbd-server instance will forward requests
transparently to this remote side.
- TARGET_PORT
- The target origin port to connect in proxy mode
- BITMAP_IMAGE
- The bitmap file uses for synchronization when connecting to
a target origin host. A bitmap file records block numbers of updated and
cached blocks.
SIGNALS¶
- SIGHUP
- When in proxy mode, a SIGHUP instructs the
nbd-server to detach from its origin. From there and beyond, the
nbd server instance will run as if it would have been started in target
mode.
SEE ALSO¶
xnbd-client (1).
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 (client and server) have been written by Takahiro Hirofuchi
(t.hirofuchi@aist.go.jp)
This manual page was written by Arno Toell (debian@toell.net) 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.