From fef6be71025049d4582f5ad64023067d291987b4 Mon Sep 17 00:00:00 2001 From: Wouter Verhelst Date: Thu, 2 Sep 2010 12:55:11 +0200 Subject: [PATCH] Revisit documentation There were a few issues with the documentation, where it grew some hairy and weird phrasing. Fix those. --- nbd-client.8.sgml | 28 +++++----------- nbd-server.1.sgml | 43 ++++++++---------------- nbd-server.5.sgml | 95 +++++++++++++++++++++++++++++++++++------------------ 3 files changed, 85 insertions(+), 81 deletions(-) diff --git a/nbd-client.8.sgml b/nbd-client.8.sgml index 421397d..af19bbc 100644 --- a/nbd-client.8.sgml +++ b/nbd-client.8.sgml @@ -201,6 +201,11 @@ manpage.1: manpage.sgml Specifies that the NBD client should not detach and daemonize itself. This is mostly useful for debugging. + + Note that nbd-client will still fork once to trigger an + update to the device node's partition table. It is not + possible to disable this. + @@ -230,14 +235,14 @@ manpage.1: manpage.sgml To connect to a server running on port 2001 at host "swapserver.domain.com", using the client's block special - file "/dev/nb1", for swap purposes: - nbd-client swapserver.domain.com 2001 /dev/nb1 + file "/dev/nbd1", for swap purposes: + nbd-client swapserver.domain.com 2001 /dev/nbd1 -swap To disconnect the above connection again (after making sure the block special file is not in use anymore): - nbd-client -d /dev/nb1 + nbd-client -d /dev/nbd1 @@ -264,20 +269,3 @@ manpage.1: manpage.sgml - - diff --git a/nbd-server.1.sgml b/nbd-server.1.sgml index 008176d..c9190b0 100644 --- a/nbd-server.1.sgml +++ b/nbd-server.1.sgml @@ -82,10 +82,12 @@ manpage.1: manpage.sgml were a local filesystem. &dhpackage; implements some security - through a file called "nbd_server.allow" in the current directory (by default; a different file can be chosen with the '-l' option). - This file must list the IP-addresses of clients that are allowed - to connect. If it does not exist, all clients are able to connect. - If the file is empty, no clients can connect. + through a file called "@sysconfdir@/nbd-server/allow" (by default; a + different file can be chosen with the '-l' option or through a + config file specification). This file must list the IP-addresses or + network masks of clients that are allowed to connect. If it does not + exist, all clients are able to connect. If the file is empty, no + clients can connect. Note that while the command line allows for specifying an export, the use of this option is deprecated. It is preferred to @@ -114,14 +116,14 @@ manpage.1: manpage.sgml - - - - The port the server should listen to. A valid port is + + + + The port the server should listen to. A valid port is any number between 1 and 65536; if 0 is used, nbd-server will listen on stdin (so that nbd-server can be ran from inetd) - + @@ -137,7 +139,7 @@ manpage.1: manpage.sgml The size of the block device at the client side. This - is especially usefull in conjunction with the -m + is especially useful in conjunction with the -m option Can optionally be followed by one of K,k,M or m, in which case the size will be multiplied by 1024 (K @@ -187,7 +189,7 @@ manpage.1: manpage.sgml - + Specify configuration file. The default configuration file, if this parameter is not specified, is @@ -220,7 +222,7 @@ manpage.1: manpage.sgml - + If the argument is given on the command line, then &dhpackage; will output a configuration @@ -282,20 +284,3 @@ manpage.1: manpage.sgml - - diff --git a/nbd-server.5.sgml b/nbd-server.5.sgml index cfa07f3..bf245e3 100644 --- a/nbd-server.5.sgml +++ b/nbd-server.5.sgml @@ -83,9 +83,9 @@ manpage.1: manpage.sgml present, even if it holds no options. Every other section defines one export; the names of these sections are not important, except that you should take care to make sure that - each section name is unique (future versions of - nbd-server may use the section name to refer - to an export) + each section name is unique. The section name is used as the name + for the export in case the client connects with a name rather than + a port to specify an export, and must therefore be unique. A comment line is a line that starts with optional whitespace, @@ -100,7 +100,7 @@ manpage.1: manpage.sgml 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, + may be quoted; always enter it directly. For a string option, leading whitespace is stripped (but trailing whitespace is not). @@ -144,7 +144,7 @@ manpage.1: manpage.sgml - + Optional; boolean @@ -171,10 +171,18 @@ manpage.1: manpage.sgml always use the old handshake protocol and will not allow name-based exports. + + Also note that even if this parameter is set to true, all + exports will also be made available using the new handshake + protocol; it is not possible to switch that off. The reason + for this is that the old style protocol will eventually be + deprecated, and this option is only available to allow for + smooth upgrades. + - + Optional; string @@ -230,8 +238,8 @@ manpage.1: manpage.sgml writes to this export will not be written to the master file, but to a separate file which will be removed upon disconnect. The result of using this option is that - nbd-server will be slower, and that any writes will be - lost upon disconnect. + nbd-server will be somewhat slower, and that any writes will + be lost upon disconnect. Corresponds to the option on the command line @@ -312,8 +320,7 @@ manpage.1: manpage.sgml The size of the individual files will be autodetected, even if the - option has been specified. See the documentation for the - for details. + option has been specified. Corresponds to the option on the @@ -326,11 +333,20 @@ manpage.1: manpage.sgml 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 - same port unless virtualization is used; future versions - of nbd-server may add this - functionality. + The port on which this export is to be served using the + old-style handshake protocol. + + + This parameter only makes sense when the 'oldstyle' + parameter is set to true in the 'generic' section. If that + parameter is not set, but this parameter is found in an + export section, then nbd-server will issue a warning upon + startup but should otherwise continue to function correctly. + + + It is not possible to combine multiple exports on the same + port using the old style handshake. Please use the new style + handshake for that purpose. When specified on the command line, this should be the @@ -356,7 +372,7 @@ manpage.1: manpage.sgml - + Optional; boolean. @@ -444,8 +460,16 @@ manpage.1: manpage.sgml Defines the style of virtualization. Virtualization allows one to create one export that will serve a different file depending on the IP address that is connecting. When - virtualization is There are three types of virtualization - that nbd-server supports: + virtualization is active, the + exportname parameter needs to + contain the string '%s'; this will then be replaced by the + IP address of the client connecting, in accordance with the + option selected here. The result of this transformation is + then used as the filename to be opened. + + + There are four types of virtualization that + nbd-server supports: @@ -462,18 +486,20 @@ manpage.1: manpage.sgml - nbd-server will look for the - literal string '%s' in the - , and replace it by the - 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 + The %s is replaced by the IP address of the connecting + host is used as-is. For IPv4, this is done in + dotted-quad notation; for IPv6, in hexadecimal form + with leading zeros omitted. + + + 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. For IPv6, + with a client connecting from 2001:6f8:32f::39, the + filename would be + /export/2001:6f8:32f:0:0:0:0:39 @@ -491,7 +517,9 @@ manpage.1: manpage.sgml 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. + indistinguishable from the ipliteral option. It was + thought that having to create an eight-deep directory + structure would not be as useful. @@ -512,7 +540,10 @@ manpage.1: manpage.sgml nbd-server will try to open /export/192.168.1.64/192.168.1.100. - This option works as expected for IPv6. + For IPv6, in the above example, with + cidrhash 42, the filename would + be + /export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39. -- 1.7.10.4