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

4
Makefile
View File

@@ -109,10 +109,10 @@ acceptance:
test: check acceptance test: check acceptance
build/flexnbd.1: README.txt build/flexnbd.1: README.txt
a2x --destination-dir build --format manpage $< txt2man -t flexnbd -s 1 $< > $@
build/flexnbd-proxy.1: README.proxy.txt 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 # If we don't pipe to file, gzip clobbers the original, causing make
# to rebuild each time # to rebuild each time

134
README.proxy.txt
View File

@@ -1,19 +1,14 @@
FLEXNBD-PROXY(1)
================
:doctype: manpage
NAME NAME
----
flexnbd-proxy - A simple NBD proxy flexnbd-proxy - A simple NBD proxy
SYNOPSIS 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 DESCRIPTION
-----------
flexnbd-proxy is a simple NBD proxy server that implements resilient flexnbd-proxy is a simple NBD proxy server that implements resilient
connection logic for the client. It connects to an upstream NBD server 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. returning the response to the client.
USAGE USAGE
-----
$ flexnbd-proxy --addr <ADDR> [ --port <PORT> ]
--conn-addr <ADDR> --conn-port <PORT>
[--bind <ADDR>] [--cache[=<CACHE_BYTES>]] [option]*
Proxy requests from an NBD client to an NBD server, resiliently. Only one 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 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 doesn't seem to slow things down much relative to alternative options, but may
be changed in the future if it becomes an issue. 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 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 a UNIX domain socket to create. Otherwise, it should be an IPv4 or IPv6
address. address.
*--port, -p PORT*:
--port, -p PORT
The port to listen on, if --addr is not a UNIX socket. 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. 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. 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 If given, the size in bytes of read cache to use. CACHE_BYTES
defaults to 4096. defaults to 4096.
*--help, -h* : --help, -h
Show command or global help. Show command or global help.
*--verbose, -v* : --verbose, -v
Output all available log information to STDERR. Output all available log information to STDERR.
*--quiet, -q* : --quiet, -q
Output as little log information as possible to STDERR. Output as little log information as possible to STDERR.
LOGGING LOGGING
-------
Log output is sent to STDERR. If --quiet is set, no output will be seen Log output is sent to STDERR. If --quiet is set, no output will be
unless the program termintes abnormally. If neither --quiet nor seen unless the program termintes abnormally. If neither --quiet nor
--verbose are set, no output will be seen unless something goes wrong --verbose are set, no output will be seen unless something goes wrong
with a specific request. If --verbose is given, every available log 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 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. error to set both --verbose and --quiet. The last one wins.
The log line format is: The log line format is:
<TIMESTAMP>:<LEVEL>:<PID> <THREAD> <SOURCEFILE>:<SOURCELINE>: <MSG> <TIMESTAMP>:<LEVEL>:<PID> <THREAD> <SOURCEFILE>:<SOURCELINE>: <MSG>
*TIMESTAMP*: <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*: <LEVEL>
This will be one of 'D', 'I', 'W', 'E', 'F' in increasing order of 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 severity. If flexnbd is started with the --quiet flag, only 'F' will
seen. If it is started with the --verbose flag, any from 'I' upwards be seen. If it is started with the --verbose flag, any from 'I'
will be seen. Only if you have a debug build and start it with upwards will be seen. Only if you have a debug build and start it
--verbose will you see 'D' entries. with --verbose will you see 'D' entries.
*PID*: <PID>
This is the process ID. This is the process ID.
*THREAD*: <THREAD>
flexnbd-proxy is currently single-threaded, so this should be the same flexnbd-proxy is currently single-threaded, so this should be the
for all lines. That may not be the case in the future. same for all lines. That may not be the case in the future.
*SOURCEFILE:SOURCELINE*: <SOURCEFILE:SOURCELINE>
Identifies where in the source code this log line can be found. 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 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.
Proxying EXAMPLES
~~~~~~~~
The main point of the proxy mode is to allow clients that would otherwise break 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 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. client process having to be disturbed at all.
READ CACHE READ CACHE
----------
If the --cache option is given at the command line, either without an 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 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 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 matches the region held in the buffer, flexnbd-proxy responds from the
cache without making a request to the server. cache without making a request to the server.
This pattern is designed to match sequential reads, such as those This pattern is designed to match sequential reads, such as those
performed by a booting virtual machine. 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 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 If no cache size is given, a size of 4096 bytes is assumed. Caching can
be explicitly disabled by setting a size of 0. be explicitly disabled by setting a size of 0.
BUGS BUGS
----
Should be reported to nick@bytemark.co.uk. Should be reported via GitHub.
* https://github.com/BytemarkHosting/flexnbd-c/issues
Current issues include: Current issues include:
* Only old-style NBD negotiation is supported * only old-style NBD negotiation is supported;
* Only one request may be in-flight at a time * only one request may be in-flight at a time;
* All I/O is blocking, and signals terminate the process immediately * all I/O is blocking, and signals terminate the process immediately;
* UNIX socket support is limited to the listen address * UNIX socket support is limited to the listen address;
* FLUSH and TRIM commands, and the FUA flag, are not supported * FLUSH and TRIM commands, and the FUA flag, are not supported;
* DISCONNECT requests do not get passed through to the NBD server * 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 * no active timeout-retry of requests - we trust the kernel's idea of
failure.
AUTHOR 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>. Original concept and core code by Matthew Bloch <matthew@bytemark.co.uk>.
Proxy mode written 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 SEE ALSO
granted under the terms of the GNU General Public License version 3 or
later. 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.

369
README.txt
View File

@@ -1,17 +1,36 @@
FLEXNBD(1)
==========
:doctype: manpage
NAME NAME
----
flexnbd - A fast NBD server flexnbd - A fast NBD server
SYNOPSIS 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 DESCRIPTION
-----------
Flexnbd is a fast NBD server which supports live migration. Live 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 is performed by writing the data to a new server. A failed
migration will be invisible to any connected clients. 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, Flexnbd tries quite hard to preserve sparsity of files it is serving,
even across migrations. even across migrations.
COMMANDS SERVE MODE
--------
Serve a file.
serve
~~~~~
$ flexnbd serve --addr <ADDR> --port <PORT> --file <FILE> $ 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. addresses), only those clients listed will be permitted to connect.
flexnbd will continue to serve until a SIGINT, SIGQUIT, or a successful flexnbd will continue to serve until a SIGINT, SIGQUIT, or a successful
migration. migration.
Options OPTIONS
^^^^^^^
*--addr, -l ADDR*: --addr, -l ADDR
The address to listen on. Required. The address to listen on. Required.
*--port, -p PORT*: --port, -p PORT
The port to listen on. Required. The port to listen on. Required.
*--file, -f FILE*: --file, -f FILE
The file to serve. Must already exist. Required. The file to serve. Must already exist. Required.
*--sock, -s SOCK*: --sock, -s SOCK
Path to a control socket to open. You will need this if you want to 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 migrate, get the current status, or manipulate the access control
list. list.
*--default-deny, -d*: --default-deny, -d
How to interpret an empty ACL. If --default-deny is given, an 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 no clients connect. If it is not given, an
empty ACL will let any client connect. empty ACL will let any client connect.
*--killswitch, -k*: --killswitch, -k
If set, we implement a 2-minute timeout on NBD requests and If set, we implement a 2-minute timeout on NBD requests and
responses. If a request takes longer than that to complete, responses. If a request takes longer than that to complete,
the client is disconnected. This is useful to keep broken the client is disconnected. This is useful to keep broken
clients from breaking migrations, among other things. clients from breaking migrations, among other things.
listen LISTEN MODE
~~~~~~
$ flexnbd listen --addr <ADDR> --port <PORT> --file <FILE>
[--sock <SOCK>] [--default-deny] [global option]* [acl entry]*
Listen for an inbound migration, and quit with a status of 0 on Listen for an inbound migration, and quit with a status of 0 on
completion. 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 flexnbd will wait for a successful migration, and then quit. The file
to write the inbound migration data to must already exist before you to write the inbound migration data to must already exist before you
run 'flexnbd listen'. run 'flexnbd listen'.
Only one sender may connect to send data, and if the sender Only one sender may connect to send data, and if the sender
disconnects part-way through the migration, the destination will 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 to assume that a partial migration can be resumed because the
destination has no knowledge of whether a client has made a write to destination has no knowledge of whether a client has made a write to
the source in the interim. 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 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 status. In this case, the sender will continually retry the migration
until it succeeds, and you will need to restart the `flexnbd listen` until it succeeds, and you will need to restart the 'flexnbd listen'
process to allow that to happen. process to allow that to happen.
Options OPTIONS
^^^^^^^
As for 'serve'.
mirror As for serve.
~~~~~~
$ flexnbd mirror --addr <ADDR> --port <PORT> --sock SOCK MIRROR MODE
[--unlink] [--bind <BIND-ADDR>] [global option]*
Start a migration from the server with control socket SOCK to the server Start a migration from the server with control socket SOCK to the server
listening at ADDR:PORT. 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' Migration can be a slow process. Rather than block the 'flexnbd mirror'
process until it completes, it will exit with a message of "Migration process until it completes, it will exit with a message of "Migration
started" once it has confirmation that the local server was able to 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'. progress of a running migration, use 'flexnbd status'.
If the destination unexpectedly disconnects part-way through the If the destination unexpectedly disconnects part-way through the
migration, the source will attempt to reconnect and start the migration 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 because the source can't see that the backing store behind the
destination is intact, or even on the same machine. destination is intact, or even on the same machine.
If the `--unlink` option is given, the local file will be deleted If the --unlink option is given, the local file will be deleted
immediately before the mirror connection is terminated. This allows immediately before the mirror connection is terminated. This allows
an otherwise-ambiguous situation to be resolved: if you don't unlink 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 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 unlink happens as soon as the sender knows that it has transmitted all
the data, there can be no ambiguity. the data, there can be no ambiguity.
Note: files smaller than 4096 bytes cannot be mirrored. Note: files smaller than 4096 bytes cannot be mirrored.
Options OPTIONS
^^^^^^^
*--addr, -l ADDR*: --addr, -l ADDR
The address of the remote server to migrate to. Required. The address of the remote server to migrate to. Required.
*--port, -p PORT*: --port, -p PORT
The port of the remote server to migrate to. Required. The port of the remote server to migrate to. Required.
*--sock, -s SOCK*: --sock, -s SOCK
The control socket of the local server to migrate from. Required. The control socket of the local server to migrate from. Required.
*--unlink, -u*: --unlink, -u
Unlink the served file from the local filesystem after successfully Unlink the served file from the local filesystem after
mirroring. successfully mirroring.
*--bind, -b BIND-ADDR*: --bind, -b BIND_ADDR
The local address to bind to. You may need this if the remote server The local address to bind to. You may need this if the remote
is using an access control list. server is using an access control list.
break BREAK MODE
~~~~~
$ flexnbd mirror --sock SOCK [global option]*
Stop a running migration. Stop a running migration.
Options $ flexnbd break --sock SOCK [global_option]*
^^^^^^^
*--sock, -s SOCK*: OPTIONS
The control socket of the local server whose emigration to stop.
Required.
--sock, -s SOCK
The control socket of the local server whose migration to stop.
Required.
acl ACL MODE
~~~
$ flexnbd acl --sock <SOCK> [acl entry]+ [global option]*
Set the access control list of the server with the control socket SOCK Set the access control list of the server with the control socket SOCK
to the given access control list entries. to the given access control list entries.
$ flexnbd acl --sock SOCK [acl_entry]+ [global_option]*
ACL entries are given as IP addresses. ACL entries are given as IP addresses.
Options OPTIONS
^^^^^^^
*--sock, -s SOCK*: --sock, -s SOCK
The control socket of the server whose ACL to replace. The control socket of the server whose ACL to replace. Required
status STATUS MODE
~~~~~~
$ flexnbd status --sock <SOCK> [global option]*
Get the current status of the server with control socket SOCK. 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 $ flexnbd status --sock SOCK [global_option]*
key=value pairs. The space character will never appear in a key or
value. Currently reported values are:
*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. The process id of the server listening on SOCK.
*is_mirroring*: is_mirroring
'true' if this server is sending migration data, 'false' otherwise. '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. 'false' if this server was started in 'listen' mode. 'true' otherwise.
read OPTIONS
~~~~
$ flexnbd read --addr <ADDR> --port <PORT> --from <OFFSET> --sock, -s SOCK
--size <SIZE> [--bind BIND-ADDR] [global option]* The control socket of the server of interest. Required.
READ MODE
Connect to the server at ADDR:PORT, and read SIZE bytes starting at 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 OFFSET in a single NBD query.
STDOUT. In case of a remote ACL, set the local source address to
BIND-ADDR.
Options $ flexnbd read --addr ADDR --port PORT --from OFFSET --size SIZE
^^^^^^^ [--bind BIND_ADDR] [global_option]*
*--addr, -l ADDR*: The returned data will be echoed to STDOUT. In case of a remote ACL,
The address of the remote server. Required. set the local source address to BIND_ADDR.
*--port, -p PORT*: OPTIONS
The port of the remote server. Required.
*--from, -F OFFSET*: --addr, -l ADDR
The byte offset to start reading from. Required. Maximum 2^62. The address of the remote server. Required.
*--size, -S SIZE*: --port, -p PORT
The number of bytes to read. Required. Maximum 2^30. The port of the remote server. Required.
*--bind, -b BIND-ADDR*: --from, -F OFFSET
The local address to bind to. You may need this if the remote server The byte offset to start reading from. Required. Maximum 2^62.
is using an access control list.
write --size, -S SIZE
~~~~~ The number of bytes to read. Required. Maximum 2^30.
$ cat ... | flexnbd write --addr <ADDR> --port <PORT> --from <OFFSET> --bind, -b BIND_ADDR
--size <SIZE> [--bind BIND-ADDR] [global option]* 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 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 starting at OFFSET in a single NBD query.
the local source address to BIND-ADDR.
Options $ cat ... | flexnbd write --addr ADDR --port PORT --from OFFSET
^^^^^^^ --size SIZE [--bind BIND_ADDR] [global_option]*
*--addr, -l ADDR*: In case of a remote ACL, set the local source address to BIND_ADDR.
The address of the remote server. Required.
*--port, -p PORT*: OPTIONS
The port of the remote server. Required.
*--from, -F OFFSET*: --addr, -l ADDR
The byte offset to start writing from. Required. Maximum 2^62. The address of the remote server. Required.
*--size, -S SIZE*: --port, -p PORT
The number of bytes to write. Required. Maximum 2^30. The port of the remote server. Required.
*--bind, -b BIND-ADDR*: --from, -F OFFSET
The local address to bind to. You may need this if the remote server The byte offset to start writing from. Required. Maximum 2^62.
is using an access control list.
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', HELP MODE
show help for that command.
$ flexnbd help [mode] [global_option]*
Without mode, show the list of available modes. With mode, show help for that mode.
GLOBAL OPTIONS GLOBAL OPTIONS
--------------
*--help, -h* : --help, -h Show mode or global help.
Show command or global help.
*--verbose, -v* : --verbose, -v Output all available log information to STDERR.
Output all available log information to STDERR.
*--quiet, -q* :
Output as little log information as possible to STDERR.
--quiet, -q Output as little log information as possible to STDERR.
LOGGING LOGGING
-------
Log output is sent to STDERR. If --quiet is set, no output will be seen Log output is sent to STDERR. If --quiet is set, no output will be
unless the program termintes abnormally. If neither --quiet nor seen unless the program termintes abnormally. If neither --quiet nor
--verbose are set, no output will be seen unless something goes wrong --verbose are set, no output will be seen unless something goes wrong
with a specific request. If --verbose is given, every available log 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 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. error to set both --verbose and --quiet. The last one wins.
The log line format is: The log line format is:
<TIMESTAMP>:<LEVEL>:<PID> <THREAD> <SOURCEFILE>:<SOURCELINE>: <MSG> <TIMESTAMP>:<LEVEL>:<PID> <THREAD> <SOURCEFILE:SOURCELINE>: <MSG>
*TIMESTAMP*: <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*: <LEVEL>
This will be one of 'D', 'I', 'W', 'E', 'F' in increasing order of 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 severity. If flexnbd is started with the --quiet flag, only 'F'
seen. If it is started with the --verbose flag, any from 'I' upwards will be seen. If it is started with the --verbose flag, any from 'I'
will be seen. Only if you have a debug build and start it with upwards will be seen. Only if you have a debug build and start it
--verbose will you see 'D' entries. with --verbose will you see 'D' entries.
*PID*: <PID>
This is the process ID. This is the process ID.
*THREAD*: <THREAD>
There are several pthreads per flexnbd process: a main thread, a serve There are several pthreads per flexnbd process: a main thread, a
thread, a thread per client, and possibly a pair of mirror threads and a serve thread, a thread per client, and possibly a pair of mirror
control thread. This field identifies which thread was responsible for threads and a control thread. This field identifies which thread was
the log line. responsible for the log line.
*SOURCEFILE:SOURCELINE*: <SOURCEFILE:SOURCELINE>
Identifies where in the source code this log line can be found. 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 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 EXAMPLES
--------
Serving a file SERVING A FILE
~~~~~~~~~~~~~~
The simplest case is serving a file on the default nbd port: 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: root:x:
$ $
Reading server status READING SERVER STATUS
~~~~~~~~~~~~~~~~~~~~~
In order to read a server's status, we need it to open a control socket. In order to read a server's status, we need it to open a control socket.
@@ -340,8 +344,7 @@ In order to read a server's status, we need it to open a control socket.
Note that the status output is newline-terminated. Note that the status output is newline-terminated.
Migrating MIGRATING
~~~~~~~~~
To migrate, we need to provide a destination file of the right size. 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 \ $ flexnbd mirror --addr 127.0.0.1 --port 4779 \
--sock /tmp/flex-source.sock --sock /tmp/flex-source.sock
Migration started Migration started
[1] + 9648 done build/flexnbd serve --addr 0.0.0.0 --port 4778 [1] + 9648 done flexnbd serve --addr 0.0.0.0 --port 4778
[2] + 9651 done build/flexnbd listen --addr 0.0.0.0 --port 4779 [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 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. exited at roughly the same time.
BUGS BUGS
----
Should be reported to alex@bytemark.co.uk. Should be reported on GitHub at
* https://github.com/BytemarkHosting/flexnbd-c/issues
AUTHOR 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>. 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 SEE ALSO
granted under the terms of the GNU General Public License version 3 or
later.
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.