bytemark/flexnbd-c
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Updated manpages, replaces a2x with txt2man

Browse Source 
This simplifies the build-deps for Debian packages a little, and brings
the docs up to date.
This commit is contained in:
Patrick J Cherry
2016-10-06 12:55:05 +01:00
parent 04b6637451
commit 091aacd16d
3 changed files with 255 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
README.txt
View File

@@ -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 <ADDR> --port <PORT> --file <FILE>
[--sock <SOCK>] [--default-deny] [-k] [global option]* [acl entry]*
[--sock <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 <ADDR> --port <PORT> --file <FILE>
[--sock <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 <ADDR> --port <PORT> --sock SOCK
[--unlink] [--bind <BIND-ADDR>] [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 <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 <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 <ADDR> --port <PORT> --from <OFFSET>
--size <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 <ADDR> --port <PORT> --from <OFFSET>
--size <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>:<LEVEL>:<PID> <THREAD> <SOURCEFILE>:<SOURCELINE>: <MSG>
<TIMESTAMP>:<LEVEL>:<PID> <THREAD> <SOURCEFILE:SOURCELINE>: <MSG>
*TIMESTAMP*:
Time the log entry was made. This is expressed in terms of monotonic ms.
<TIMESTAMP>
Time the log entry was made. This is expressed in terms of monotonic
ms.
*LEVEL*:
<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*:
<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.
<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.
*SOURCEFILE:SOURCELINE*:
<SOURCEFILE:SOURCELINE>
Identifies where in the source code this log line can be found.
*MSG*:
<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 <alex@bytemark.co.uk>.
Originally written by Alex Young <alex@blackkettle.org>.
Original concept and core code by Matthew Bloch <matthew@bytemark.co.uk>.
Some additions by Nick Thomas <nick@bytemark.co.uk>
Proxy mode written by Nick Thomas <me@ur.gs>.
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.