X-Git-Url: http://git.alex.org.uk
diff --git a/nbd-server.5.sgml b/nbd-server.5.sgml
index d44abd0..cfa07f3 100644
--- a/nbd-server.5.sgml
+++ b/nbd-server.5.sgml
@@ -63,10 +63,10 @@ manpage.1: manpage.sgml
&dhpackage; allows to configure the
nbd-server.
- The default configuration file is
- @sysconfdir@/nbd-server/config, but this
- can be varied with the option to
- nbd-server(1).
+ While
+ @sysconfdir@/nbd-server/config is the default
+ configuration file, this can be varied with the
+ option to nbd-server(1).
The configuration file consists of section header lines, comment
@@ -98,9 +98,9 @@ manpage.1: manpage.sgml
followed by an equals sign ("="), followed by the option
value. An option can be of type string, of type integer, or of
type boolean. The value of a boolean option can be denoted with
- either true or false (so not yes, no, on, off, 1, or 0); all
- booleans default to false unless specified otherwise; no value
- may be quoted (always enter it directly); for a string option,
+ either true or false (so not yes, no, on, off, 1, or 0). All
+ booleans default to false unless specified otherwise. No value
+ may be quoted (always enter it directly). For a string option,
leading whitespace is stripped (but trailing whitespace is not).
@@ -143,7 +143,54 @@ manpage.1: manpage.sgml
+
+
+
+
+ Optional; boolean
+
+
+ If this option is set to true, nbd-server will export all
+ exports on a separate port with the old (pre-2.9.17)
+ handshake protocol. In that case, the 'port' option for
+ individual exports is mandatory.
+
+
+ If the option is set to false, the 'port' option for
+ individual exports is optional (and will be ignored if
+ specified). The server will only export devices on the
+ standard port.
+
+
+ For upgrades from pre-2.9.17 versions of nbd, it may be
+ appropriate to enable the oldstyle parameter until all
+ clients have been converted to using name-based exports.
+
+
+ Note that exports specified on the command line will
+ always use the old handshake protocol and will not allow
+ name-based exports.
+
+
+
+
+
+
+
+ Optional; string
+
+ If this option is set, it should contain the local IP
+ address on which we should listen to
+ nbd-client(8) connections. If it is not
+ set, nbd-server will listen to all
+ local IPv4 and IPv6 addresses. To limit to IPv6, specify the
+ address as "::". To limit to IPv4, specify as "0.0.0.0". It
+ is not possible to specify more than one IP address
+ here.
+
+
+
OPTIONS FOR EXPORT SECTIONS
@@ -173,23 +220,6 @@ manpage.1: manpage.sgml
-
-
- Optional; boolean.
-
- If this option is set to true, then
- nbd-server will automatically switch to
- readonly if it cannot write to the file.
-
- Does not have a corresponding command-line
- argument
- TODO: verify whether this option actually works as
- documented. I have a feeling I've been terribly
- stupid.
-
-
-
-
@@ -212,9 +242,9 @@ manpage.1: manpage.sgml
Required; string.
- The name of the file that will be exported. This must be a
- fully-qualified path and filename; relative paths are not
- allowed.
+ The name of the file (or block device) that will be
+ exported. This must be a fully-qualified path and filename;
+ relative paths are not allowed.
Note that nbd-server will only try to
@@ -250,6 +280,20 @@ manpage.1: manpage.sgml
+ listenaddr
+
+
+ Optional; string
+
+
+ If the 'oldstyle' global parameter is specified, works
+ similarly to the global listenaddr parameter, but for the
+ individual port of this particular export. If the 'oldstyle'
+ parameter is not set, this parameter is ignored.
+
+
+
+ Optional; boolean.
@@ -259,8 +303,8 @@ manpage.1: manpage.sgml
form
exportname.integer,
with exportname being the
- filename that would otherwise have been used (after
- name transformation for virtualization, if any, has been
+ filename that would otherwise have been used (after name
+ transformation for virtualization, if any, has been
performed) and integer an
integer number, starting with 0 and ending when no more
files can be found.
@@ -280,7 +324,7 @@ manpage.1: manpage.sgml
- Required; integer.
+ Required if 'oldstyle' global parameter is set; integer.
The port on which this export is to be served. Currently
it is not possible to export multiple block devices on the
@@ -312,6 +356,45 @@ manpage.1: manpage.sgml
+
+
+ Optional; boolean.
+
+ When this option is enabled, nbd-server
+ will use the Socket Direct Protocol (SDP) to serve the
+ export, rather than just IP. This is faster, but requires
+ special hardware (usually something like InfiniBand) and
+ support in the kernel.
+
+
+ Additionally, support for this option must be enabled at
+ compile time, using the option
+ to the configure script. If this option
+ is found in a configuration file and
+ nbd-server does not have support for SDP,
+ then nbd-server will exit with an error
+ message.
+
+
+
+
+
+
+ Optional; boolean.
+ When this option is enabled,
+ nbd-server will call an fsync() after every
+ write to the backend storage. Calling fsync() increases
+ reliability in case of an unclean shutdown of nbd-server; but,
+ depending on the file system used on the nbd-server side, may
+ degrade performance. The use of this option isn't always
+ necessary; e.g., on ext3 filesystems, it is recommended that
+ it is not enabled, since it seriously
+ reduces performance on ext3 filesystems while not
+ importantly impacting reliability.
+
+
+
+ Optional; boolean.
@@ -320,7 +403,8 @@ manpage.1: manpage.sgml
will use sparse files to implement the copy-on-write
option; such files take up less space then they appear to,
which allows nbd-server to handle the
- file as if it was just as large as the block device it's for.
+ file as if it was just as large as the block device it's
+ for.
If this option is disabled, nbd-server
@@ -381,14 +465,14 @@ manpage.1: manpage.sgml
nbd-server will look for the
literal string '%s' in the
, and replace it by the
- IP address of the connecting host in dotted-quad
- notation. The string that results from this
- transformation will be used as an absolute pathname
- that nbd-server will attempt to
- open. As an example, if a client connects from
- 192.168.1.100 and is
- specified as /export/%s, then
- nbd-server will attempt to serve
+ address of the connecting host. The string that
+ results from this transformation will be used as an
+ absolute pathname that nbd-server
+ will attempt to open. As an example, if a client
+ connects from 192.168.1.100 and
+ is specified as
+ /export/%s, then nbd-server
+ will attempt to serve
/export/192.168.1.100
@@ -404,6 +488,11 @@ manpage.1: manpage.sgml
open /export/192/168/1/100
instead.
+
+ Since there are no dots in most IPv6 addresses, the
+ effect of using this option when IPv6 is in use is
+ indistinguishable from the ipliteral option.
+
@@ -414,22 +503,70 @@ manpage.1: manpage.sgml
after it. nbd-server will use the
number as a network mask in CIDR style, and use that
as a hash cutoff point. In the above example, if
- has been specified
- as cidrhash 16, then
+ has been specified as
+ cidrhash 16, then
nbd-server will try to open
- /export/192.168.0.0/192.168.1.100; if
- were specified as
+ /export/192.168.0.0/192.168.1.100;
+ if were specified as
cidrhash 26, then
nbd-server will try to open
/export/192.168.1.64/192.168.1.100.
+ This option works as expected for IPv6.
+
+
+
+ Optional; string
+
+ If specified, then this command will be ran after a
+ client has connected to the server (and has been
+ accepted), but before the server starts serving. If
+ the command contains the literal string '%s', then
+ this string will be replaced by the filename of the
+ file which nbd-server wants to export.
+
+
+ This is useful to create export files on the fly, or
+ to verify that a file can be used for export, to
+ write something to a log file, or similar.
+
+
+ If the command runs with a non-zero exit status,
+ then nbd-server will assume the export will fail,
+ and refuse to serve it.
+
+
+
+
+
+
+ Optional; string
+
+ If specified, then it is assumed to be a command
+ that will be ran when a client has
+ disconnected. This can be useful to clean up
+ whatever has set up, to log
+ something, or similar.
+
+
+ If the literal string '%s' is present in the
+ command, it will be replaced by the file name that
+ has just been closed.
+
+
+ In contrast to the option,
+ the exit state of is
+ ignored.
+
+
+
-
+
SEE ALSO