Added a README.txt and a man page
Spoiler: they're the same thing. Added a `rake man` task to build the man page. Depends on asciidoc.
This commit is contained in:
Alex Young
370
README.txt
Normal file
370
README.txt
Normal file
@@ -0,0 +1,370 @@
|
|||||||
|
FLEXNBD(1)
|
||||||
|
==========
|
||||||
|
:doctype: manpage
|
||||||
|
|
||||||
|
NAME
|
||||||
|
----
|
||||||
|
flexnbd - A fast NBD server
|
||||||
|
|
||||||
|
SYNOPSIS
|
||||||
|
--------
|
||||||
|
*flexnbd* 'COMMAND' ['OPTIONS']
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Flexnbd tries quite hard to preserve sparsity of files it is serving,
|
||||||
|
even across migrations.
|
||||||
|
|
||||||
|
COMMANDS
|
||||||
|
--------
|
||||||
|
|
||||||
|
serve
|
||||||
|
~~~~~
|
||||||
|
$ flexnbd serve --addr <ADDR> --port <PORT> --file <FILE>
|
||||||
|
[--sock <SOCK>] [--default-deny] [global option]* [acl entry]*
|
||||||
|
|
||||||
|
Serve a file. 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
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
*--addr, -l ADDR*:
|
||||||
|
The address to listen on. Required.
|
||||||
|
|
||||||
|
*--port, -p PORT*:
|
||||||
|
The port to listen on. Required.
|
||||||
|
|
||||||
|
*--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
|
||||||
|
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
|
||||||
|
empty ACL will let any client connect.
|
||||||
|
|
||||||
|
listen
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
$ flexnbd listen --addr <ADDR> --port <PORT> --file <FILE>
|
||||||
|
[--rebind-addr <REBIND-ADDR>] [--rebind-port <REBIND-PORT>]
|
||||||
|
[--sock <SOCK>] [--default-deny] [global option]* [acl entry]*
|
||||||
|
|
||||||
|
Listen for an inbound migration, then serve it as normal once it has
|
||||||
|
completed.
|
||||||
|
|
||||||
|
flexnbd will wait for a successful migration, and then switch into
|
||||||
|
'serve' mode. 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 the server is not
|
||||||
|
available to clients while the migration is taking place.
|
||||||
|
|
||||||
|
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 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.
|
||||||
|
|
||||||
|
To support transparently replacing an existing server, flexnbd can
|
||||||
|
switch addresses once it has received a successful migration.
|
||||||
|
|
||||||
|
Options
|
||||||
|
^^^^^^^
|
||||||
|
As for 'serve', with these additions:
|
||||||
|
|
||||||
|
*--rebind-addr, -L REBIND_ADDR*:
|
||||||
|
The address to rebind to once migration has completed.
|
||||||
|
|
||||||
|
*--rebind-port, -P REBIND_PORT*:
|
||||||
|
The port to rebind to once migration has completed.
|
||||||
|
|
||||||
|
Either, both, or neither of --rebind-port and rebind-addr may be given.
|
||||||
|
If rebinding fails, flexnbd will retry every second until it succeeds.
|
||||||
|
|
||||||
|
mirror
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
$ flexnbd mirror --addr <ADDR> --port <PORT> --sock SOCK
|
||||||
|
[--bind <BIND-ADDR>] [global option]*
|
||||||
|
|
||||||
|
Start a migration from the server with control socket SOCK to the server
|
||||||
|
listening at ADDR:PORT.
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
because the source can't see that the backing store behind the
|
||||||
|
destination is intact, or even on the same machine.
|
||||||
|
|
||||||
|
Note: files smaller than 4096 bytes cannot be migrated.
|
||||||
|
|
||||||
|
Options
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
*--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.
|
||||||
|
|
||||||
|
*--sock, -s SOCK*:
|
||||||
|
The control socket of the local server to migrate from. 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.
|
||||||
|
|
||||||
|
acl
|
||||||
|
~~~
|
||||||
|
|
||||||
|
$ flexnbd acl --sock <SOCK> [acl entry]+ [global option]*
|
||||||
|
|
||||||
|
Set the access control list of the server with the control socket SOCK
|
||||||
|
to the given access control list entries.
|
||||||
|
|
||||||
|
ACL entries are given as IP addresses.
|
||||||
|
|
||||||
|
Options
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
*--sock, -s SOCK*:
|
||||||
|
The control socket of the server whose ACL to replace.
|
||||||
|
|
||||||
|
status
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
$ flexnbd status --sock <SOCK> [global option]*
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
*is_mirroring*:
|
||||||
|
'true' if this server is sending migration data, 'false' otherwise.
|
||||||
|
|
||||||
|
*has_control*:
|
||||||
|
'false' if this server was started in 'listen' mode and has not yet
|
||||||
|
received a successful migration. 'true' otherwise.
|
||||||
|
|
||||||
|
read
|
||||||
|
~~~~
|
||||||
|
|
||||||
|
$ flexnbd read --addr <ADDR> --port <PORT> --from <OFFSET>
|
||||||
|
--size <SIZE> [--bind BIND-ADDR] [global option]*
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Options
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
*--addr, -l ADDR*:
|
||||||
|
The address of the remote server. Required.
|
||||||
|
|
||||||
|
*--port, -p PORT*:
|
||||||
|
The port of the remote server. Required.
|
||||||
|
|
||||||
|
*--from, -F OFFSET*:
|
||||||
|
The byte offset to start reading from. Required. Maximum 2^62.
|
||||||
|
|
||||||
|
*--size, -S SIZE*:
|
||||||
|
The number of bytes to read. Required. Maximum 2^30.
|
||||||
|
|
||||||
|
*--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
|
||||||
|
~~~~~
|
||||||
|
|
||||||
|
$ cat ... | flexnbd write --addr <ADDR> --port <PORT> --from <OFFSET>
|
||||||
|
--size <SIZE> [--bind BIND-ADDR] [global option]*
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Options
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
*--addr, -l ADDR*:
|
||||||
|
The address of the remote server. Required.
|
||||||
|
|
||||||
|
*--port, -p PORT*:
|
||||||
|
The port of the remote server. Required.
|
||||||
|
|
||||||
|
*--from, -F OFFSET*:
|
||||||
|
The byte offset to start writing from. Required. Maximum 2^62.
|
||||||
|
|
||||||
|
*--size, -S SIZE*:
|
||||||
|
The number of bytes to write. Required. Maximum 2^30.
|
||||||
|
|
||||||
|
*--bind, -b BIND-ADDR*:
|
||||||
|
The local address to bind to. You may need this if the remote server
|
||||||
|
is using an access control list.
|
||||||
|
|
||||||
|
help
|
||||||
|
~~~~
|
||||||
|
|
||||||
|
$ flexnbd help [command] [global option]*
|
||||||
|
|
||||||
|
Without 'command', show the list of available commands. With 'command',
|
||||||
|
show help for that command.
|
||||||
|
|
||||||
|
GLOBAL OPTIONS
|
||||||
|
--------------
|
||||||
|
|
||||||
|
*--help, -h* :
|
||||||
|
Show command or global help.
|
||||||
|
|
||||||
|
*--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
|
||||||
|
--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.
|
||||||
|
|
||||||
|
The log line format is:
|
||||||
|
|
||||||
|
<LEVEL>:<PID> <THREAD> <SOURCEFILE>:<SOURCELINE>: <MSG>
|
||||||
|
|
||||||
|
*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.
|
||||||
|
|
||||||
|
*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.
|
||||||
|
|
||||||
|
*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.
|
||||||
|
|
||||||
|
EXAMPLES
|
||||||
|
--------
|
||||||
|
|
||||||
|
Serving a file
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The simplest case is serving a file on the default nbd port:
|
||||||
|
|
||||||
|
$ cp /etc/passwd /tmp
|
||||||
|
$ flexnbd serve --file /tmp/passwd --addr 0.0.0.0 --port 4777 &
|
||||||
|
$ flexnbd read --addr 127.0.0.1 --port 4777 --from 0 --size 7
|
||||||
|
root:x:
|
||||||
|
$
|
||||||
|
|
||||||
|
Reading server status
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
In order to read a server's status, we need it to open a control socket.
|
||||||
|
|
||||||
|
$ flexnbd serve --file /tmp/passwd --addr 0.0.0.0 --port 4777 \
|
||||||
|
--sock /tmp/flexnbd.sock
|
||||||
|
$ flexnbd status --sock /tmp/flexnbd.sock
|
||||||
|
is_mirroring=false has_control=true
|
||||||
|
|
||||||
|
$
|
||||||
|
|
||||||
|
Note that the status output is newline-terminated.
|
||||||
|
|
||||||
|
Migrating
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
To migrate, we need to provide a destination file of the right size.
|
||||||
|
|
||||||
|
$ dd if=/dev/random of=/tmp/data bs=1M count=1
|
||||||
|
$ truncate -s 1M /tmp/data.copy
|
||||||
|
$ flexnbd serve --file /tmp/data --addr 0.0.0.0 --port 4778 \
|
||||||
|
--sock /tmp/flex-source.sock &
|
||||||
|
$ flexnbd listen --file /tmp/data.copy --addr 0.0.0.0 --port 4779 \
|
||||||
|
--sock /tmp/flex-dest.sock &
|
||||||
|
$
|
||||||
|
|
||||||
|
Now we check the status of each server, to check that they are both in
|
||||||
|
the right state:
|
||||||
|
|
||||||
|
$ flexnbd status --sock /tmp/flex-source.sock
|
||||||
|
is_mirroring=false has_control=true
|
||||||
|
$ flexnbd status --sock /tmp/flex-dest.sock
|
||||||
|
is_mirroring=false has_control=false
|
||||||
|
$
|
||||||
|
|
||||||
|
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
|
||||||
|
$
|
||||||
|
|
||||||
|
Note that because the file is so small in this case, we see the source
|
||||||
|
server quit soon after we start the migration.
|
||||||
|
|
||||||
|
We can check the status of the destination server, to ensure that it
|
||||||
|
took control:
|
||||||
|
|
||||||
|
$ flexnbd status --sock /tmp/flex-dest.sock
|
||||||
|
is_mirroring=false has_control=true
|
||||||
|
|
||||||
|
BUGS
|
||||||
|
----
|
||||||
|
|
||||||
|
Should be reported to alex@bytemark.co.uk.
|
||||||
|
|
||||||
|
AUTHOR
|
||||||
|
------
|
||||||
|
|
||||||
|
Written by Alex Young <alex@bytemark.co.uk>.
|
||||||
|
Original concept and core code by Matthew Bloch
|
||||||
|
<matthew@bytemark.co.uk>.
|
||||||
|
|
||||||
|
COPYING
|
||||||
|
-------
|
||||||
|
|
||||||
|
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.
|
||||||
Reference in New Issue
Block a user