From 091aacd16dfe5c23c38b47bbd97c98afb5ced446 Mon Sep 17 00:00:00 2001 From: Patrick J Cherry Date: Thu, 6 Oct 2016 12:55:05 +0100 Subject: [PATCH] Updated manpages, replaces a2x with txt2man This simplifies the build-deps for Debian packages a little, and brings the docs up to date. --- Makefile | 4 +- README.proxy.txt | 134 ++++++++--------- README.txt | 371 ++++++++++++++++++++++++----------------------- 3 files changed, 255 insertions(+), 254 deletions(-) diff --git a/Makefile b/Makefile index 77c1c20..ecc58ed 100644 --- a/Makefile +++ b/Makefile @@ -109,10 +109,10 @@ acceptance: test: check acceptance build/flexnbd.1: README.txt - a2x --destination-dir build --format manpage $< + txt2man -t flexnbd -s 1 $< > $@ build/flexnbd-proxy.1: README.proxy.txt - a2x --destination-dir build --format manpage $< + txt2man -t flexnbd-proxy -s 1 $< > $@ # If we don't pipe to file, gzip clobbers the original, causing make # to rebuild each time diff --git a/README.proxy.txt b/README.proxy.txt index cc20c9c..c50bb23 100644 --- a/README.proxy.txt +++ b/README.proxy.txt @@ -1,19 +1,14 @@ -FLEXNBD-PROXY(1) -================ -:doctype: manpage - NAME ----- -flexnbd-proxy - A simple NBD proxy + flexnbd-proxy - A simple NBD proxy SYNOPSIS --------- -*flexnbd-proxy* ['OPTIONS'] + flexnbd-proxy --addr ADDR [--port PORT] --conn-addr ADDR + --conn-port PORT [--bind ADDR] [--cache[=CACHE_BYTES]] + [--help] [--verbose] [--quiet] DESCRIPTION ------------ flexnbd-proxy is a simple NBD proxy server that implements resilient connection logic for the client. It connects to an upstream NBD server @@ -25,11 +20,6 @@ of view of the client) reconnects and retransmits the request, before returning the response to the client. USAGE ------ - - $ flexnbd-proxy --addr [ --port ] - --conn-addr --conn-port - [--bind ] [--cache[=]] [option]* Proxy requests from an NBD client to an NBD server, resiliently. Only one client can be connected at a time, and ACLs cannot be applied to the client, as they @@ -58,75 +48,73 @@ Only one request may be in-flight at a time under the current architecture; that doesn't seem to slow things down much relative to alternative options, but may be changed in the future if it becomes an issue. -Options -~~~~~~~ +OPTIONS -*--addr, -l ADDR*: + --addr, -l ADDR The address to listen on. If this begins with a '/', it is assumed to be a UNIX domain socket to create. Otherwise, it should be an IPv4 or IPv6 address. -*--port, -p PORT*: + + --port, -p PORT The port to listen on, if --addr is not a UNIX socket. -*--conn-addr, -C ADDR*: + --conn-addr, -C ADDR The address of the NBD server to connect to. Required. -*--conn-port, -P PORT*: + --conn-port, -P PORT The port of the NBD server to connect to. Required. -*--cache, -c=CACHE_BYTES*: + --cache, -c=CACHE_BYTES If given, the size in bytes of read cache to use. CACHE_BYTES defaults to 4096. -*--help, -h* : + --help, -h Show command or global help. -*--verbose, -v* : + --verbose, -v Output all available log information to STDERR. -*--quiet, -q* : + --quiet, -q Output as little log information as possible to STDERR. - LOGGING -------- -Log output is sent to STDERR. If --quiet is set, no output will be seen -unless the program termintes abnormally. If neither --quiet nor + +Log output is sent to STDERR. If --quiet is set, no output will be +seen unless the program termintes abnormally. If neither --quiet nor --verbose are set, no output will be seen unless something goes wrong -with a specific request. If --verbose is given, every available log -message will be seen (which, for a debug build, is many). It is not an -error to set both --verbose and --quiet. The last one wins. +with a specific request. If --verbose is given, every available log +message will be seen (which, for a debug build, is many). It is not an +error to set both --verbose and --quiet. The last one wins. The log line format is: - :: :: + :: :: -*TIMESTAMP*: + Time the log entry was made. This is expressed in terms of monotonic ms -*LEVEL*: + This will be one of 'D', 'I', 'W', 'E', 'F' in increasing order of -severity. If flexnbd is started with the --quiet flag, only 'F' will be -seen. If it is started with the --verbose flag, any from 'I' upwards -will be seen. Only if you have a debug build and start it with ---verbose will you see 'D' entries. + severity. If flexnbd is started with the --quiet flag, only 'F' will + be seen. If it is started with the --verbose flag, any from 'I' + upwards will be seen. Only if you have a debug build and start it + with --verbose will you see 'D' entries. -*PID*: + This is the process ID. -*THREAD*: - flexnbd-proxy is currently single-threaded, so this should be the same -for all lines. That may not be the case in the future. + + flexnbd-proxy is currently single-threaded, so this should be the + same for all lines. That may not be the case in the future. -*SOURCEFILE:SOURCELINE*: + Identifies where in the source code this log line can be found. -*MSG*: - A short message describing what's happening, how it's being done, or -if you're very lucky *why* it's going on. + + A short message describing what's happening, how it's being done, or + if you're very lucky why it's going on. -Proxying -~~~~~~~~ +EXAMPLES The main point of the proxy mode is to allow clients that would otherwise break when the NBD server goes away (during a migration, for instance) to see a @@ -160,53 +148,59 @@ The data in myfile has been moved between physical servers without the nbd client process having to be disturbed at all. READ CACHE ----------- If the --cache option is given at the command line, either without an argument or with an argument greater than 0, flexnbd-proxy will use a -read-ahead cache. The cache as currently implemented doubles each read +read-ahead cache. The cache as currently implemented doubles each read request size, up to a maximum of 2xCACHE_BYTES, and retains the latter -half in a buffer. If the next read request from the client exactly +half in a buffer. If the next read request from the client exactly matches the region held in the buffer, flexnbd-proxy responds from the cache without making a request to the server. This pattern is designed to match sequential reads, such as those performed by a booting virtual machine. -Note: If specifying a cache size, you *must* use this form: +Note: If specifying a cache size, you must use this form: nbd-client$ flexnbd-proxy --cache=XXXX -That is, the '=' is required. This is a limitation of getopt-long. +That is, the '=' is required. This is a limitation of getopt-long. If no cache size is given, a size of 4096 bytes is assumed. Caching can be explicitly disabled by setting a size of 0. BUGS ----- -Should be reported to nick@bytemark.co.uk. +Should be reported via GitHub. + +* https://github.com/BytemarkHosting/flexnbd-c/issues Current issues include: -* Only old-style NBD negotiation is supported -* Only one request may be in-flight at a time -* All I/O is blocking, and signals terminate the process immediately -* UNIX socket support is limited to the listen address -* FLUSH and TRIM commands, and the FUA flag, are not supported -* DISCONNECT requests do not get passed through to the NBD server -* No active timeout-retry of requests - we trust the kernel's idea of failure +* only old-style NBD negotiation is supported; +* only one request may be in-flight at a time; +* all I/O is blocking, and signals terminate the process immediately; +* UNIX socket support is limited to the listen address; +* FLUSH and TRIM commands, and the FUA flag, are not supported; +* DISCONNECT requests do not get passed through to the NBD server; +* no active timeout-retry of requests - we trust the kernel's idea of + failure. AUTHOR ------- -Written by Alex Young . + +Originally written by Alex Young . Original concept and core code by Matthew Bloch . -Proxy mode written by Nick Thomas +Proxy mode written by Nick Thomas . -COPYING -------- +The full commit history is available on GitHub. -Copyright (c) 2012 Bytemark Hosting Ltd. Free use of this software is -granted under the terms of the GNU General Public License version 3 or -later. +SEE ALSO + +flexnbd(1), nbd-client(8), xnbd-server(8), xnbd-client(8) + +COPYRIGHT + +Copyright (c) 2012-2016 Bytemark Hosting Ltd. Free use of this +software is granted under the terms of the GNU General Public License +version 3 or later. diff --git a/README.txt b/README.txt index ad017f0..8adc836 100644 --- a/README.txt +++ b/README.txt @@ -1,17 +1,36 @@ -FLEXNBD(1) -========== -:doctype: manpage - NAME ----- + flexnbd - A fast NBD server SYNOPSIS --------- -*flexnbd* 'COMMAND' ['OPTIONS'] + + flexnbd MODE [ ARGS ] + + flexnbd serve --addr ADDR --port PORT --file FILE [--sock SOCK] + [--default-deny] [--killswitch] [global_option]* [acl_entry]* + + flexnbd listen --addr ADDR --port PORT --file FILE [--sock SOCK] + [--default-deny] [global_option]* [acl_entry]* + + flexnbd mirror --addr ADDR --port PORT --sock SOCK [--unlink] + [--bind BIND_ADDR] [global_option]* + + flexnbd acl --sock SOCK [acl_entry]+ [global_option]* + + flexnbd break --sock SOCK [global_option]* + + flexnbd status --sock SOCK [global_option]* + + flexnbd read --addr ADDR --port PORT --from OFFSET --size SIZE + [--bind BIND_ADDR] [global_option]* + + flexnbd write --addr ADDR --port PORT --from OFFSET --size SIZE + [--bind BIND_ADDR] [global_option]* + + flexnbd help [mode] [global_option]* DESCRIPTION ------------ + Flexnbd is a fast NBD server which supports live migration. Live migration is performed by writing the data to a new server. A failed migration will be invisible to any connected clients. @@ -19,304 +38,290 @@ migration will be invisible to any connected clients. Flexnbd tries quite hard to preserve sparsity of files it is serving, even across migrations. -COMMANDS --------- +SERVE MODE + +Serve a file. -serve -~~~~~ $ flexnbd serve --addr --port --file - [--sock ] [--default-deny] [-k] [global option]* [acl entry]* + [--sock ] [--default-deny] [-k] [global_option]* + [acl_entry]* -Serve a file. If any ACL entries are given (which should be IP +If any ACL entries are given (which should be IP addresses), only those clients listed will be permitted to connect. flexnbd will continue to serve until a SIGINT, SIGQUIT, or a successful migration. -Options -^^^^^^^ + OPTIONS -*--addr, -l ADDR*: + --addr, -l ADDR The address to listen on. Required. -*--port, -p PORT*: + --port, -p PORT The port to listen on. Required. -*--file, -f FILE*: + --file, -f FILE The file to serve. Must already exist. Required. -*--sock, -s SOCK*: - Path to a control socket to open. You will need this if you want to + --sock, -s SOCK + Path to a control socket to open. You will need this if you want to migrate, get the current status, or manipulate the access control list. -*--default-deny, -d*: - How to interpret an empty ACL. If --default-deny is given, an - empty ACL will let no clients connect. If it is not given, an + --default-deny, -d + How to interpret an empty ACL. If --default-deny is given, an + empty ACL will let no clients connect. If it is not given, an empty ACL will let any client connect. -*--killswitch, -k*: + --killswitch, -k If set, we implement a 2-minute timeout on NBD requests and responses. If a request takes longer than that to complete, the client is disconnected. This is useful to keep broken clients from breaking migrations, among other things. -listen -~~~~~~ - - $ flexnbd listen --addr --port --file - [--sock ] [--default-deny] [global option]* [acl entry]* +LISTEN MODE Listen for an inbound migration, and quit with a status of 0 on completion. + $ flexnbd listen --addr ADDR --port PORT --file FILE + [--sock SOCK] [--default-deny] [global_option]* + [acl_entry]* + flexnbd will wait for a successful migration, and then quit. The file to write the inbound migration data to must already exist before you run 'flexnbd listen'. Only one sender may connect to send data, and if the sender disconnects part-way through the migration, the destination will -expect it to reconnect and retry the whole migration. It isn't safe +expect it to reconnect and retry the whole migration. It isn't safe to assume that a partial migration can be resumed because the destination has no knowledge of whether a client has made a write to the source in the interim. -If the migration fails for a reason which the `flexnbd listen` process +If the migration fails for a reason which the 'flexnbd listen' process can't fix (say, a failed local write), it will exit with an error -status. In this case, the sender will continually retry the migration -until it succeeds, and you will need to restart the `flexnbd listen` +status. In this case, the sender will continually retry the migration +until it succeeds, and you will need to restart the 'flexnbd listen' process to allow that to happen. -Options -^^^^^^^ -As for 'serve'. + OPTIONS -mirror -~~~~~~ +As for serve. - $ flexnbd mirror --addr --port --sock SOCK - [--unlink] [--bind ] [global option]* +MIRROR MODE Start a migration from the server with control socket SOCK to the server listening at ADDR:PORT. + $ flexnbd mirror --addr ADDR --port PORT --sock SOCK [--unlink] + [--bind BIND_ADDR] [global_option]* + Migration can be a slow process. Rather than block the 'flexnbd mirror' process until it completes, it will exit with a message of "Migration started" once it has confirmation that the local server was able to -connect to ADDR:PORT and got an NBD header back. To check on the +connect to ADDR:PORT and got an NBD header back. To check on the progress of a running migration, use 'flexnbd status'. If the destination unexpectedly disconnects part-way through the migration, the source will attempt to reconnect and start the migration -again. It is not safe to resume the migration from where it left off +again. It is not safe to resume the migration from where it left off because the source can't see that the backing store behind the destination is intact, or even on the same machine. -If the `--unlink` option is given, the local file will be deleted -immediately before the mirror connection is terminated. This allows +If the --unlink option is given, the local file will be deleted +immediately before the mirror connection is terminated. This allows an otherwise-ambiguous situation to be resolved: if you don't unlink the file and the flexnbd process at either end is terminated, it's not -possible to tell which copy of the data is canonical. Since the +possible to tell which copy of the data is canonical. Since the unlink happens as soon as the sender knows that it has transmitted all the data, there can be no ambiguity. Note: files smaller than 4096 bytes cannot be mirrored. -Options -^^^^^^^ + OPTIONS -*--addr, -l ADDR*: - The address of the remote server to migrate to. Required. + --addr, -l ADDR + The address of the remote server to migrate to. Required. -*--port, -p PORT*: - The port of the remote server to migrate to. Required. + --port, -p PORT + The port of the remote server to migrate to. Required. -*--sock, -s SOCK*: - The control socket of the local server to migrate from. Required. + --sock, -s SOCK + The control socket of the local server to migrate from. Required. -*--unlink, -u*: - Unlink the served file from the local filesystem after successfully - mirroring. + --unlink, -u + Unlink the served file from the local filesystem after + successfully mirroring. -*--bind, -b BIND-ADDR*: - The local address to bind to. You may need this if the remote server - is using an access control list. + --bind, -b BIND_ADDR + The local address to bind to. You may need this if the remote + server is using an access control list. -break -~~~~~ - - $ flexnbd mirror --sock SOCK [global option]* +BREAK MODE Stop a running migration. -Options -^^^^^^^ + $ flexnbd break --sock SOCK [global_option]* -*--sock, -s SOCK*: - The control socket of the local server whose emigration to stop. - Required. + OPTIONS + --sock, -s SOCK + The control socket of the local server whose migration to stop. + Required. -acl -~~~ - - $ flexnbd acl --sock [acl entry]+ [global option]* +ACL MODE Set the access control list of the server with the control socket SOCK to the given access control list entries. + $ flexnbd acl --sock SOCK [acl_entry]+ [global_option]* + ACL entries are given as IP addresses. -Options -^^^^^^^ + OPTIONS -*--sock, -s SOCK*: - The control socket of the server whose ACL to replace. + --sock, -s SOCK + The control socket of the server whose ACL to replace. Required -status -~~~~~~ - - $ flexnbd status --sock [global option]* +STATUS MODE Get the current status of the server with control socket SOCK. -The status will be printed to STDOUT. It is a space-separated list of -key=value pairs. The space character will never appear in a key or -value. Currently reported values are: + $ flexnbd status --sock SOCK [global_option]* -*pid*: +The status will be printed to STDOUT. It is a space-separated list of +key=value pairs. The space character will never appear in a key or +value. Currently reported values are: + +pid The process id of the server listening on SOCK. -*is_mirroring*: +is_mirroring 'true' if this server is sending migration data, 'false' otherwise. -*has_control*: +has_control 'false' if this server was started in 'listen' mode. 'true' otherwise. -read -~~~~ + OPTIONS - $ flexnbd read --addr --port --from - --size [--bind BIND-ADDR] [global option]* + --sock, -s SOCK + The control socket of the server of interest. Required. + +READ MODE Connect to the server at ADDR:PORT, and read SIZE bytes starting at -OFFSET in a single NBD query. The returned data will be echoed to -STDOUT. In case of a remote ACL, set the local source address to -BIND-ADDR. +OFFSET in a single NBD query. -Options -^^^^^^^ + $ flexnbd read --addr ADDR --port PORT --from OFFSET --size SIZE + [--bind BIND_ADDR] [global_option]* -*--addr, -l ADDR*: - The address of the remote server. Required. +The returned data will be echoed to STDOUT. In case of a remote ACL, +set the local source address to BIND_ADDR. -*--port, -p PORT*: - The port of the remote server. Required. + OPTIONS -*--from, -F OFFSET*: - The byte offset to start reading from. Required. Maximum 2^62. + --addr, -l ADDR + The address of the remote server. Required. -*--size, -S SIZE*: - The number of bytes to read. Required. Maximum 2^30. + --port, -p PORT + The port of the remote server. Required. -*--bind, -b BIND-ADDR*: - The local address to bind to. You may need this if the remote server - is using an access control list. + --from, -F OFFSET + The byte offset to start reading from. Required. Maximum 2^62. -write -~~~~~ + --size, -S SIZE + The number of bytes to read. Required. Maximum 2^30. - $ cat ... | flexnbd write --addr --port --from - --size [--bind BIND-ADDR] [global option]* + --bind, -b BIND_ADDR + The local address to bind to. You may need this if the remote + server is using an access control list. + +WRITE MODE Connect to the server at ADDR:PORT, and write SIZE bytes from STDIN -starting at OFFSET in a single NBD query. In case of a remote ACL, set -the local source address to BIND-ADDR. +starting at OFFSET in a single NBD query. -Options -^^^^^^^ + $ cat ... | flexnbd write --addr ADDR --port PORT --from OFFSET + --size SIZE [--bind BIND_ADDR] [global_option]* -*--addr, -l ADDR*: - The address of the remote server. Required. +In case of a remote ACL, set the local source address to BIND_ADDR. -*--port, -p PORT*: - The port of the remote server. Required. + OPTIONS -*--from, -F OFFSET*: - The byte offset to start writing from. Required. Maximum 2^62. + --addr, -l ADDR + The address of the remote server. Required. -*--size, -S SIZE*: - The number of bytes to write. Required. Maximum 2^30. + --port, -p PORT + The port of the remote server. Required. -*--bind, -b BIND-ADDR*: - The local address to bind to. You may need this if the remote server - is using an access control list. + --from, -F OFFSET + The byte offset to start writing from. Required. Maximum 2^62. -help -~~~~ + --size, -S SIZE + The number of bytes to write. Required. Maximum 2^30. - $ flexnbd help [command] [global option]* + --bind, -b BIND_ADDR + The local address to bind to. You may need this if the remote + server is using an access control list. -Without 'command', show the list of available commands. With 'command', -show help for that command. +HELP MODE + + $ flexnbd help [mode] [global_option]* + +Without mode, show the list of available modes. With mode, show help for that mode. GLOBAL OPTIONS --------------- -*--help, -h* : - Show command or global help. +--help, -h Show mode or global help. -*--verbose, -v* : - Output all available log information to STDERR. - -*--quiet, -q* : - Output as little log information as possible to STDERR. +--verbose, -v Output all available log information to STDERR. +--quiet, -q Output as little log information as possible to STDERR. LOGGING -------- -Log output is sent to STDERR. If --quiet is set, no output will be seen -unless the program termintes abnormally. If neither --quiet nor + +Log output is sent to STDERR. If --quiet is set, no output will be +seen unless the program termintes abnormally. If neither --quiet nor --verbose are set, no output will be seen unless something goes wrong -with a specific request. If --verbose is given, every available log -message will be seen (which, for a debug build, is many). It is not an -error to set both --verbose and --quiet. The last one wins. +with a specific request. If --verbose is given, every available log +message will be seen (which, for a debug build, is many). It is not an +error to set both --verbose and --quiet. The last one wins. The log line format is: - :: :: + :: : -*TIMESTAMP*: - Time the log entry was made. This is expressed in terms of monotonic ms. + + Time the log entry was made. This is expressed in terms of monotonic + ms. -*LEVEL*: + This will be one of 'D', 'I', 'W', 'E', 'F' in increasing order of -severity. If flexnbd is started with the --quiet flag, only 'F' will be -seen. If it is started with the --verbose flag, any from 'I' upwards -will be seen. Only if you have a debug build and start it with ---verbose will you see 'D' entries. + severity. If flexnbd is started with the --quiet flag, only 'F' + will be seen. If it is started with the --verbose flag, any from 'I' + upwards will be seen. Only if you have a debug build and start it + with --verbose will you see 'D' entries. -*PID*: + This is the process ID. -*THREAD*: - There are several pthreads per flexnbd process: a main thread, a serve -thread, a thread per client, and possibly a pair of mirror threads and a -control thread. This field identifies which thread was responsible for -the log line. + + There are several pthreads per flexnbd process: a main thread, a + serve thread, a thread per client, and possibly a pair of mirror + threads and a control thread. This field identifies which thread was + responsible for the log line. -*SOURCEFILE:SOURCELINE*: + Identifies where in the source code this log line can be found. -*MSG*: + A short message describing what's happening, how it's being done, or -if you're very lucky *why* it's going on. + if you're very lucky why it's going on. EXAMPLES --------- -Serving a file -~~~~~~~~~~~~~~ + SERVING A FILE The simplest case is serving a file on the default nbd port: @@ -326,8 +331,7 @@ The simplest case is serving a file on the default nbd port: root:x: $ -Reading server status -~~~~~~~~~~~~~~~~~~~~~ + READING SERVER STATUS In order to read a server's status, we need it to open a control socket. @@ -335,13 +339,12 @@ In order to read a server's status, we need it to open a control socket. --sock /tmp/flexnbd.sock $ flexnbd status --sock /tmp/flexnbd.sock pid=9635 is_mirroring=false has_control=true - + $ Note that the status output is newline-terminated. -Migrating -~~~~~~~~~ + MIGRATING To migrate, we need to provide a destination file of the right size. @@ -367,8 +370,8 @@ With this knowledge in hand, we can start the migration: $ flexnbd mirror --addr 127.0.0.1 --port 4779 \ --sock /tmp/flex-source.sock Migration started - [1] + 9648 done build/flexnbd serve --addr 0.0.0.0 --port 4778 - [2] + 9651 done build/flexnbd listen --addr 0.0.0.0 --port 4779 + [1] + 9648 done flexnbd serve --addr 0.0.0.0 --port 4778 + [2] + 9651 done flexnbd listen --addr 0.0.0.0 --port 4779 $ Note that because the file is so small in this case, we see the source @@ -376,21 +379,25 @@ server quit soon after we start the migration, and the destination exited at roughly the same time. BUGS ----- -Should be reported to alex@bytemark.co.uk. +Should be reported on GitHub at + + * https://github.com/BytemarkHosting/flexnbd-c/issues AUTHOR ------- -Written by Alex Young . +Originally written by Alex Young . Original concept and core code by Matthew Bloch . -Some additions by Nick Thomas +Proxy mode written by Nick Thomas . -COPYING -------- +The full commit history is available on GitHub. -Copyright (c) 2012 Bytemark Hosting Ltd. Free use of this software is -granted under the terms of the GNU General Public License version 3 or -later. +SEE ALSO +flexnbd-proxy(1), nbd-client(8), xnbd-server(8), xnbd-client(8) + +COPYRIGHT + +Copyright (c) 2012-2016 Bytemark Hosting Ltd. Free use of this +software is granted under the terms of the GNU General Public License +version 3 or later.