From a67dc53ff99faf44981b4825e81f04af90f03812 Mon Sep 17 00:00:00 2001 From: yoe Date: Mon, 23 Oct 2006 18:45:02 +0000 Subject: [PATCH] r202: Documentation update --- Makefile.am | 11 +- configure.ac | 2 +- nbd-server.1.sgml | 62 ++++--- nbd-server.5.sgml | 488 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 534 insertions(+), 29 deletions(-) create mode 100644 nbd-server.5.sgml diff --git a/Makefile.am b/Makefile.am index 2306635..6750d7f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -8,14 +8,17 @@ nbd_server_CFLAGS = @CFLAGS@ @GLIB_CFLAGS@ nbd_tester_client_CFLAGS = @CFLAGS@ @GLIB_CFLAGS@ nbd_server_LDADD = @GLIB_LIBS@ nbd_tester_client_LDADD = @GLIB_LIBS@ -man_MANS = nbd-server.1 nbd-client.8 -EXTRA_DIST = nbd-client.8.sgml nbd-server.1.sgml gznbd winnbd lfs.h nbd-client.8 nbd-server.1 CodingStyle +man_MANS = nbd-server.1 nbd-server.5 nbd-client.8 +EXTRA_DIST = nbd-client.8.sgml nbd-server.1.sgml nbd-server.5.sgml gznbd winnbd lfs.h nbd-client.8 CodingStyle MAINTAINERCLEANFILES = nbd-client.8 nbd-server.1 -nbd-server.1: nbd-server.1.sgml +nbd-server.1.in: nbd-server.1.sgml docbook2man nbd-server.1.sgml - mv NBD-SERVER.1 nbd-server.1 + mv NBD-SERVER.1 nbd-server.1.in nbd-client.8: nbd-client.8.sgml docbook2man nbd-client.8.sgml mv NBD-CLIENT.8 nbd-client.8 +nbd-server.5.in: nbd-server.5.sgml + docbook2man nbd-server.5.sgml + mv NBD-SERVER.5 nbd-server.5.in dist-hook: rm -Rf `find $(distdir) -name 'CVS' -type d -print` diff --git a/configure.ac b/configure.ac index d300bd8..545a0c5 100644 --- a/configure.ac +++ b/configure.ac @@ -108,6 +108,6 @@ AC_SUBST(sbin_PROGRAMS) nbd_server_CPPFLAGS=$nbd_server_CPPFLAGS" -DSYSCONFDIR='\"$sysconfdir\"'" AC_SUBST(nbd_server_CPPFLAGS) AC_CONFIG_HEADERS([config.h]) -AC_CONFIG_FILES([Makefile Doxyfile]) +AC_CONFIG_FILES([Makefile Doxyfile nbd-server.1 nbd-server.5]) AC_OUTPUT diff --git a/nbd-server.1.sgml b/nbd-server.1.sgml index 4a3fd13..d79608d 100644 --- a/nbd-server.1.sgml +++ b/nbd-server.1.sgml @@ -157,40 +157,54 @@ manpage.1: manpage.sgml Copy on write. When this option is provided, - write-operations are not done to the exported file, but to a - separate file. This separate file is removed when the - connection is closed, which means that serving this way will - make nbd-server slow down (especially on large block devices - with lots of writes), and that after disconnecting and - reconnecting the client or the server, all changes are - lost. + write-operations are not done to the exported file, but to a + separate file. This separate file is removed when the + connection is closed, which means that serving this way will + make nbd-server slow down (especially on large block devices + with lots of writes), and that after disconnecting and + reconnecting the client or the server, all changes are + lost. + + + + + + Specify configuration file. The default configuration + file, if this parameter is not specified, is + @sysconfdir@/nbd-server/config. + Note that the configuration file is always parsed and + the entries in the file used, even if an extra server is + specified on the command line. To disable the configuration + file entirely, either move it away or use the -C option to + point nbd-server(1) to a non-existing or + empty configuration file. Maximum number of idle seconds. If a connection is - inactive for this amount of time, it is terminated; this is to - avoid stale nbd-server processes staying in memory. Use of - this option is strongly recommended. + inactive for this amount of time, it is terminated; this is to + avoid stale nbd-server processes staying in memory. Use of + this option is strongly recommended. This argument should contain a list of IP-addresses - for hosts that may connect to the server. Wildcards are - not allowed. If the file does not - exist, it is ignored (and any host can connect); If the file - does exist, but is empty, no host can connect. By default, - the name 'nbd_server.allow' is used, and looked for in the - current directory, unless nbd-server is compiled as a - daemon, in which case it is looked for in the - root-directory. + for hosts that may connect to the server. Wildcards are + not allowed. If the file does not + exist, it is ignored (and any host can connect); If the file + does exist, but is empty, no host can connect. By default, + the name 'nbd_server.allow' is used, and looked for in the + current directory, unless nbd-server is compiled as a + daemon, in which case it is looked for in the + root-directory. - + EXAMPLES @@ -209,21 +223,21 @@ manpage.1: manpage.sgml changes are lost after restarting the client or the server: nbd-server 2000 /export/nbd/exp-bl-dev - -c + -c SEE ALSO - - nbd-client (8), http://nbd.sourceforge.net/roadmap.html - + + nbd-client (8), nbd-server (5), http://nbd.sourceforge.net/roadmap.html + AUTHOR The NBD kernel module and the NBD tools were originally written by Pavel Machek (pavel@ucw.cz) - + The Linux kernel module is now maintained by Paul Clements (Paul.Clements@steeleye.com), while the userland tools are maintained by &dhusername; (&dhemail;) diff --git a/nbd-server.5.sgml b/nbd-server.5.sgml new file mode 100644 index 0000000..c1066ed --- /dev/null +++ b/nbd-server.5.sgml @@ -0,0 +1,488 @@ + manpage.1'. You may view + the manual page with: `docbook-to-man manpage.sgml | nroff -man | + less'. A typical entry in a Makefile or Makefile.am is: + +manpage.1: manpage.sgml + docbook-to-man $< > $@ + --> + + + Wouter"> + Verhelst"> + + $Date: 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $"> + + 5"> + wouter@debian.org"> + + NBD-SERVER"> + + + Debian GNU/Linux"> + GNU"> +]> + + + +
+ &dhemail; +
+ + &dhfirstname; + &dhsurname; + + + 2006 + &dhusername; + + &dhdate; + + + &dhucpackage; + + &dhsection; + + + &dhpackage; + + configuration file for nbd-server + + + + &dhpackage; + + + + + DESCRIPTION + + &dhpackage; allows to configure the + nbd-server. + + The default configuration file is + @SCD@/nbd-server/config, but this + can be varied with the option to + nbd-server(1). + + + The configuration file consists of section header lines, comment + lines, and option lines. + + + A section header is a unique name that + is enclosed in square brackets ("[" and "]"). A section header + denotes the beginning of a section; a section continues until + the next section or the end of the file, whichever is first. The + first section in the configuration file must be called + , and is used for global options that + apply to more than one export. This section must always be + 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) + + + A comment line is a line that starts with optional whitespace, + followed by a pound sign ("#"), and continues until the end of + the line. Comments may not be used on + option lines or section header lines. + + + An option line is a line that starts with an option name, + 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, + leading whitespace is stripped (but trailing whitespace is not). + + + + + OPTIONS FOR SECTION [generic] + + + + + + + + Optional; string. + + + The name of the group this server must run as. If this + parameter is not specified, then nbd-server will not + attempt to change its GID (so the GID it runs as will be + the primary group of the user who starts nbd-server). If + it is specified, then nbd-server will change its GID after + opening ports, but before accepting connections or opening + files. + + + + + + + + Optional; string. + + + The name of the user this server must run as. If this + parameter is not specified, then nbd-server will not + attempt to change its UID (so the UID it runs as will be + the user who starts nbd-server). If it is specified, then + nbd-server will change its UID after opening ports, but + before accepting connections or opening files. + + + + + + OPTIONS FOR EXPORT SECTIONS + + + + + + + + Optional; string; default + @SCD@/nbd-server/allow. + + + The name of the authorization file for this export. This + file should contain one line per IP-address, and must not + contain wildcards of any kind or empty lines. If the file + does not exist, everyone is allowed to connect. If the + file exists but is empty, nobody is allowed to + connect. Otherwise, nbd-server will + only allow clients to connect whose IP-adres is listed in + this file. + + Corresponds to the option on the + command line + + + + + + 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. + + + + + + + + Optional; boolean. + + + Whether this is a copy-on-write export. If it is, then any + 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. + + Corresponds to the option on the + command line + + + + + + 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. + + + Note that nbd-server will only try to + find and open the exported file when a client actually + connects; as a result, nbd-server must + be able to open and read this file + after changing to the user and group + that have been specified by use of the + and options; + also, nbd-server will only detect + errors in this option upon connection of a client. + + When specified on the command line, this should be the + second argument. + + + + + + + Optional; integer; default autodetected. + + Disable autodetection of file or block device size, and + forcibly specify a size. Sizes must be specified in + bytes. If the option is in + effect, this option specifies the size of the + entire export, not of individual + files. + + When specified on the command line, this should be the + third argument. + + + + + + + Optional; boolean. + + If this option is set to true, then + nbd-server will search for files of the + form + exportname.integer, + with exportname being the + 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. + + + The size of the individual files will be autodetected, + even if the + option has been specified. See the documentation for the + for details. + + + Corresponds to the option on the + command line. + + + + + + + Required; 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. + + + When specified on the command line, this should be the + first argument. + + + + + + + Optional; boolean. + + Disallow writes to the device. If this option is + specified, nbd-server will issue an + error to any client that tries to write to the device. + + + Use of this option in conjunction with + is possible, but silly. + + Corresponds to the option on the + command line. + + + + + + Optional; boolean. + + When this option is enabled, nbd-server + 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. + + + If this option is disabled, nbd-server + will map every newly written block to the end of the + copy-on-write file, which means that + nbd-server will have to lseek(2) to the + right position after every 4096-byte block. + + + Using this option may be faster when much is being written + during a connection. + + + + + + + Optional; integer; default 0 + + How many seconds a connection may be idle for this + export. When a connection is idle for a longer time, + nbd-server will forcibly disconnect the + connection. If you specify 0 (the default), then a + connection may be idle forever. + + + Corresponds to the option on the + command line + + + + + + + Optional; string; default "ipliteral" + + 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: + + + + + + + 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 + /export/192.168.1.100 + + + + + + + + Same as above, except that + nbd-server will replace the dots + in the IP address by forward slashes ('/'); in the + same example, nbd-server would + open /export/192/168/1/100 + instead. + + + + + + + + This option requires one to add a space and a number + 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 + nbd-server will try to open + /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. + + + + + + + + + + + EXAMPLES + Some examples of nbd-server usage: + + + To export a file /export/nbd/exp-bl-dev on port 2000: + nbd-server 2000 /export/nbd/exp-bl-dev + + + To export a the same file read-only: + nbd-server 2000 /export/nbd/exp-bl-dev -r + + + To export the same file read-write, but make sure + changes are lost after restarting the client or the + server: + nbd-server 2000 /export/nbd/exp-bl-dev + -c + + + + + SEE ALSO + + nbd-server (1), nbd-client (8), + http://nbd.sourceforge.net/roadmap.html + + + + AUTHOR + The NBD kernel module and the NBD tools were originally + written by Pavel Machek (pavel@ucw.cz) + + The Linux kernel module is now maintained by Paul Clements + (Paul.Clements@steeleye.com), while the userland tools are + maintained by &dhusername; (&dhemail;) + + On The Hurd there is a regular translator available to perform the + client side of the protocol, and the use of + nbd-client is not required. Please see the + relevant documentation for more information. + + This manual page was written by &dhusername; (&dhemail;) for + the &debian; system (but may be used by others). Permission is + granted to copy, distribute and/or modify this document under + the terms of the GNU General Public License, + version 2, as published by the Free Software Foundation. + + + + + -- 1.7.10.4