'\" t .\" Title: xnbd-server .\" 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\-SERVER" "8" "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-server \- Serve a file as a block device to other computers via the NBD protocol .SH "SYNOPSIS" .sp \fBxnbd\-server\fR \-\-target [options] \fIDISK_IMAGE\fR .sp \fBxnbd\-server\fR \-\-cow\-target [options] \fIBASE_DISK_IMAGE\fR .sp \fBxnbd\-server\fR \-\-proxy [options] [\-\-target\-exportname \fINAME\fR] \fIREMOTE_HOST\fR \fIREMOTE_PORT\fR \fICACHE_IMAGE\fR \fICACHE_BITMAP_IMAGE\fR \fICONTROL_SOCKET_PATH\fR .sp \fBxnbd\-server\fR \-\-help .sp \fBxnbd\-server\fR \-\-version .SH "DESCRIPTION" .sp \fBxnbd\-server\fR 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\&. .sp 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\&. .sp \fBxnbd\-server\fR can operate in three modes (i\&.e\&., the target mode, the copy\-on\-write target mode, and the proxy mode)\&. .sp \fBxnbd\-server\fR \fB\-\-target\fR exports \fIDISK_IMAGE\fR to clients\&. .sp \fBxnbd\-server\fR \fB\-\-cow\-target\fR exports \fIBASE_DISK_IMAGE\fR 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\&. .sp \fBxnbd\-server\fR \fB\-\-proxy\fR provides the image server of the NBD protocol, but it actually works as a proxy to a remote \fBxnbd\-server\fR specified with \fIREMOTE_HOST\fR and \fIREMOTE_PORT\fR\&. .sp 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\&. .sp Cached blocks are saved in \fICACHE_DISK_IMAGE\fR\&. The block numbers of cached blocks are saved in \fICACHE_BITMAP_IMAGE\fR\&. The proxy server is controlled by xnbd\-bgctl(1) through \fICONTROL_SOCKET_PATH\fR\&. .sp 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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBWarning\fR .ps -1 .br .sp Multiple clients can concurrently access to a single server instance\&. Yet \fBxnbd\-server\fR 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\&. .sp .5v .RE .SH "OPTIONS" .sp The following options are supported: .PP \fB\-\-daemonize\fR .RS 4 Run \fBxnbd\-server\fR in the background .RE .PP \fB\-\-inetd\fR .RS 4 Run \fBxnbd\-server\fR for an Internet super\-server daemon (e\&.g\&., inetd)\&. All network I/O is redirected to the stdin descriptor\&. .RE .PP \fB\-\-logpath\fR \fIFILE\fR .RS 4 Log informational messages to file \fIFILE\fR rather than stderr/syslog\&. .RE .PP \fB\-\-syslog\fR .RS 4 Log informational messages to syslog\&. .RE .PP \fB\-\-lport\fR \fIPORT\fR .RS 4 Listen incoming connections on the given PORT\&. If this argument is not given, \fBxnbd\-server\fR will listen on port 8520 by default\&. .RE .PP \fB\-\-readonly\fR .RS 4 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, \fBxnbd\-server\fR 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\&. .RE .PP \fB\-\-connected\-fd\fR \fINUMBER\fR .RS 4 Use file descriptor \fINUMBER\fR 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\&. .RE .SH "OPTIONS (PROXY MODE ONLY)" .PP \fB\-\-target\-exportname\fR \fINAME\fR .RS 4 Set the export name to request from an xnbd\-wrapper target\&. .RE .PP \fB\-\-clear\-bitmap\fR .RS 4 Clear an existing bitmap file\&. By default, previous state is re\-used\&. .RE .PP \fB\-\-max\-queue\-size\fR \fINUMBER\fR .RS 4 Limit the total number of queued requests to \fINUMBER\fR\&. 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\&. .RE .PP \fB\-\-max\-buf\-size\fR \fINUMBER\fR .RS 4 Limit the usage of internal buffer to approximately \fINUMBER\fR 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\&. .RE .SH "SIGNALS" .PP \fBSIGUSR1\fR .RS 4 Take a snapshot of the image file\&. Currently, this feature works only in the target mode\&. .RE .PP \fBSIGUSR2\fR .RS 4 Change the proxy mode to the target mode\&. Use xnbd\-bgctl \-\-switch instead of sending this signal\&. .RE .SH "SEE ALSO" .sp xnbd\-client(1), xnbd\-bgctl(1), 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\&.