--- name: "xnbd-server" section: "8" platform: "linux" package: "xnbd-server" version: "0.3.0-3" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/xnbd-server" --- # xnbd-server(8) Serve a file as a block device to other computers via the NBD protocol ## 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)](/xnbd-bgctl/1.md) 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)](/xnbd-wrapper/8.md) 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-client/1.md), [xnbd-bgctl(1)](/xnbd-bgctl/1.md), [xnbd-wrapper(8)](/xnbd-wrapper/8.md) ## 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.