From dd6ff182bc1508eeb97cf6f09065447099aa8331 Mon Sep 17 00:00:00 2001 From: Wouter Verhelst Date: Sat, 3 Jan 2009 06:24:04 +0100 Subject: [PATCH] Avoid i18n when we don't need it Manpages aren't translated, so translated dates there are sucky. --- Makefile.am | 6 +- Makefile.in | 6 +- nbd-server.1.in | 169 ++++++++++++++++++++++++ nbd-server.5.in | 389 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 564 insertions(+), 6 deletions(-) diff --git a/Makefile.am b/Makefile.am index d909a2b..c3e79de 100644 --- a/Makefile.am +++ b/Makefile.am @@ -15,13 +15,13 @@ 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 simple_test INSTALL MAINTAINERCLEANFILES = nbd-client.8 nbd-server.1 nbd-server.1.in: nbd-server.1.sgml - docbook2man nbd-server.1.sgml + LC_ALL=C docbook2man nbd-server.1.sgml mv NBD-SERVER.1 nbd-server.1.in nbd-client.8: nbd-client.8.sgml - docbook2man nbd-client.8.sgml + LC_ALL=C 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 + LC_ALL=C docbook2man nbd-server.5.sgml mv NBD-SERVER.5 nbd-server.5.in dist-hook: rm -Rf `find $(distdir) -name '.svn' -type d -print` diff --git a/Makefile.in b/Makefile.in index 2562e62..95914c4 100644 --- a/Makefile.in +++ b/Makefile.in @@ -900,13 +900,13 @@ uninstall-man: uninstall-man1 uninstall-man5 uninstall-man8 uninstall-sbinPROGRAMS nbd-server.1.in: nbd-server.1.sgml - docbook2man nbd-server.1.sgml + LC_ALL=C docbook2man nbd-server.1.sgml mv NBD-SERVER.1 nbd-server.1.in nbd-client.8: nbd-client.8.sgml - docbook2man nbd-client.8.sgml + LC_ALL=C 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 + LC_ALL=C docbook2man nbd-server.5.sgml mv NBD-SERVER.5 nbd-server.5.in dist-hook: rm -Rf `find $(distdir) -name '.svn' -type d -print` diff --git a/nbd-server.1.in b/nbd-server.1.in index e69de29..c9187eb 100644 --- a/nbd-server.1.in +++ b/nbd-server.1.in @@ -0,0 +1,169 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng . +.TH "NBD-SERVER" "1" "03 January 2009" "" "" + +.SH NAME +nbd-server \- serve a file as a block device to other computers running the GNU/Linux(tm) or GNU/Hurd Operating System +.SH SYNOPSIS + +\fBnbd-server \fR \fB\fI[ip:]port\fB\fR \fB\fIfilename\fB\fR [ \fB\fIsize\fB\fR ] [ \fB-r\fR ] [ \fB-m\fR ] [ \fB-c\fR ] [ \fB-a \fItimeout\fB\fR ] [ \fB-l \fIhost list filename\fB\fR ] [ \fB-o \fIsection name\fB\fR ] [ \fB-C \fIconfig file\fB\fR ] + +.SH "DESCRIPTION" +.PP +\fBnbd-server\fR is the server for the Linux +Network Block Device (NBD). With NBD, a client can use a file, +exported over the network from a server, as a block device. It can +then be used for whatever purpose a normal block device (harddisk, +CD-ROM, ...) can be used for. +.PP +NBD can be useful for diskless clients that need swapspace, +but you can also create a filesystem on it and use it as though it +were a local filesystem. +.PP +\fBnbd-server\fR 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. +.SH "OPTIONS" +.TP +\fBip\fR +The ip address the server should listen on. If +omitted, 0.0.0.0 (aka "any address") is used. +.TP +\fBport \fR +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) +.TP +\fBfilename\fR +The filename of the file that should be exported. This +can be any file, including "real" blockdevices (i.e. a file +from /dev). If the filename includes the literal string +"%s", then this %s will be substituded with the IP-address +of the client trying to connect. +.TP +\fBsize\fR +The size of the block device at the client side. This +is especially usefull 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 +or k) or 1048576 (M or m) +.TP +\fB-r\fR +Export the file read-only. If a client tries to write +to a read-only exported file, it will receive an error, but +the connection will stay up. +.TP +\fB-m\fR +Work with multiple files. This can be used to export +blockdevices that are larger than the maximum allowed +filesize on a given filesystem; i.e. when the filesystem +does not allow files larger than 2GB (which is true for +Linux 2.2 and below), you can use this option to store the +data in multiple files and export a larger filesystem, if +needed. + +To use this option, you must create a number of files +with names in the format "name.X", where "name" is given as +the filename argument to nbd-server, and "X" is a number +starting by 0 and going up for each file. + +Allowing more flexibility for this option is planned for +future versions. +.TP +\fB-c\fR +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. +.TP +\fB-C\fR +Specify configuration file. The default configuration +file, if this parameter is not specified, is +\fI@sysconfdir@/nbd-server/config\fR\&. + +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 \fBnbd-server\fR(1) to a non-existing or +empty configuration file. +.TP +\fBtimeout\fR +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. +.TP +\fBhost list filename\fR +This argument should contain a list of IP-addresses +for hosts that may connect to the server. Wildcards are +\fBnot\fR 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. +.TP +\fBsection name\fR +If the \fB-o\fR argument is given on the +command line, then nbd-server will output a configuration +file section with this as the header that is functionally +equivalent to the other options specified on the command line, +and exit. This is useful for migrating pre-2.9 nbd-server +initscript configuration files to the new format. +.SH "EXAMPLES" +.PP +Some examples of nbd-server usage: +.TP 0.2i +\(bu +To export a file /export/nbd/exp-bl-dev on port 2000: + +\fBnbd-server 2000 /export/nbd/exp-bl-dev\fR +.TP 0.2i +\(bu +To export a the same file read-only: + +\fBnbd-server 2000 /export/nbd/exp-bl-dev -r\fR +.TP 0.2i +\(bu +To export the same file read-write, but make sure +changes are lost after restarting the client or the +server: + +\fBnbd-server 2000 /export/nbd/exp-bl-dev +-c\fR +.SH "SEE ALSO" +.PP +nbd-client (8), nbd-server (5), http://nbd.sourceforge.net/roadmap.html +.SH "AUTHOR" +.PP +The NBD kernel module and the NBD tools were originally +written by Pavel Machek (pavel@ucw.cz) +.PP +The Linux kernel module is now maintained by Paul Clements +(Paul.Clements@steeleye.com), while the userland tools are +maintained by Wouter Verhelst () +.PP +On The Hurd there is a regular translator available to perform the +client side of the protocol, and the use of +\fBnbd-client\fR is not required. Please see the +relevant documentation for more information. +.PP +This manual page was written by Wouter Verhelst () for +the Debian GNU/Linux 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. diff --git a/nbd-server.5.in b/nbd-server.5.in index e69de29..ddcede2 100644 --- a/nbd-server.5.in +++ b/nbd-server.5.in @@ -0,0 +1,389 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng . +.TH "NBD-SERVER" "5" "03 January 2009" "" "" + +.SH NAME +/etc/nbd-server/config \- configuration file for nbd-server +.SH SYNOPSIS + +\fB/etc/nbd-server/config \fR + +.SH "DESCRIPTION" +.PP +\fB/etc/nbd-server/config\fR allows to configure the +nbd-server. +.PP +While +\fI@sysconfdir@/nbd-server/config\fR is the default +configuration file, this can be varied with the \fB-C\fR +option to \fBnbd-server\fR(1). +.PP +The configuration file consists of section header lines, comment +lines, and option lines. +.PP +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 +\fBgeneric\fR, 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 +\fBnbd-server\fR may use the section name to refer +to an export) +.PP +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 \fBnot\fR be used on +option lines or section header lines. +.PP +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). +.SH "OPTIONS FOR SECTION [GENERIC]" +.TP +\fBgroup\fR +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. +.TP +\fBuser\fR +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. +.SH "OPTIONS FOR EXPORT SECTIONS" +.TP +\fBauthfile\fR +Optional; string; default +\fI@sysconfdir@/nbd-server/allow\fR\&. + +The name of the authorization file for this export. This +file should contain one line per IP-address, or per +network (which must be specified in CIDR-style +\fB\fInetwork\fB/\fImasklen\fB\fR) +and must not contain 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, \fBnbd-server\fR will +only allow clients to connect whose IP-adres is listed in +this file. + +Corresponds to the \fB-l\fR option on the +command line +.TP +\fBcopyonwrite\fR +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 \fB-c\fR option on the +command line +.TP +\fBexportname\fR +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 \fBnbd-server\fR will only try to +find and open the exported file when a client actually +connects; as a result, \fBnbd-server\fR must +be able to open and read this file +\fBafter\fR changing to the user and group +that have been specified by use of the +\fBuser\fR and \fBgroup\fR options; +also, \fBnbd-server\fR will only detect +errors in this option upon connection of a client. + +When specified on the command line, this should be the +second argument. +.TP +\fBfilesize\fR +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 \fBmultifile\fR option is in +effect, this option specifies the size of the +\fBentire\fR export, not of individual +files. + +When specified on the command line, this should be the +third argument. +.TP +\fBlistenaddr\fR +Optional; string + +If this option is set, it should contain the local IP +address (in "dotted-quad" notation) on which we should +listen to \fBnbd-client\fR(8) connections. If +it is not set, 0.0.0.0 is used (i.e., "listen on all local +IP addresses") +.TP +\fBmultifile\fR +Optional; boolean. + +If this option is set to true, then +\fBnbd-server\fR will search for files of the +form +\fIexportname\fR\&.\fIinteger\fR, +with \fIexportname\fR being the +filename that would otherwise have been used (after +name transformation for virtualization, if any, has been +performed) and \fIinteger\fR an +integer number, starting with 0 and ending when no more +files can be found. + +The size of the individual files will be autodetected, +\fBeven\fR if the \fBfilesize\fR +option has been specified. See the documentation for the +\fBmultifile\fR for details. + +Corresponds to the \fB-m\fR option on the +command line. +.TP +\fBport\fR +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 \fBnbd-server\fR may add this +functionality. + +When specified on the command line, this should be the +first argument. +.TP +\fBreadonly\fR +Optional; boolean. + +Disallow writes to the device. If this option is +specified, \fBnbd-server\fR will issue an +error to any client that tries to write to the device. + +Use of this option in conjunction with +\fBcopyonwrite\fR is possible, but silly. + +Corresponds to the \fB-r\fR option on the +command line. +.TP +\fBsdp\fR +Optional; boolean. + +When this option is enabled, \fBnbd-server\fR +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 \fB--enable-sdp\fR option +to the \fBconfigure\fR script. If this option +is found in a configuration file and +\fBnbd-server\fR does not have support for SDP, +then \fBnbd-server\fR will exit with an error +message. +.TP +\fBsparse_cow\fR +Optional; boolean. + +When this option is enabled, \fBnbd-server\fR +will use sparse files to implement the copy-on-write +option; such files take up less space then they appear to, +which allows \fBnbd-server\fR to handle the +file as if it was just as large as the block device it's +for. + +If this option is disabled, \fBnbd-server\fR +will map every newly written block to the end of the +copy-on-write file, which means that +\fBnbd-server\fR 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. +.TP +\fBtimeout\fR +Optional; integer; default 0 + +How many seconds a connection may be idle for this +export. When a connection is idle for a longer time, +\fBnbd-server\fR will forcibly disconnect the +connection. If you specify 0 (the default), then a +connection may be idle forever. + +Corresponds to the \fB-a\fR option on the +command line +.TP +\fBvirtstyle\fR +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 \fBnbd-server\fR supports: +.RS +.TP +\fBnone\fR +No virtualization. Will attempt to open the filename +as it was written, even if it contains '%s' in the +name. +.TP +\fBipliteral\fR +\fBnbd-server\fR will look for the +literal string '%s' in the +\fBexportname\fR, 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 \fBnbd-server\fR will attempt to +open. As an example, if a client connects from +192.168.1.100 and \fBexportname\fR is +specified as \fI/export/%s\fR, then +nbd-server will attempt to serve +\fI/export/192.168.1.100\fR +.TP +\fBiphash\fR +Same as above, except that +\fBnbd-server\fR will replace the dots +in the IP address by forward slashes ('/'); in the +same example, \fBnbd-server\fR would +open \fI/export/192/168/1/100\fR +instead. +.TP +\fBcidrhash\fR +This option requires one to add a space and a number +after it. \fBnbd-server\fR will use the +number as a network mask in CIDR style, and use that +as a hash cutoff point. In the above example, if +\fBvirtstyle\fR has been specified as +cidrhash 16, then +\fBnbd-server\fR will try to open +\fI/export/192.168.0.0/192.168.1.100\fR; +if \fBvirtstyle\fR were specified as +cidrhash 26, then +\fBnbd-server\fR will try to open +\fI/export/192.168.1.64/192.168.1.100\fR\&. +.RE +.TP +\fBprerun\fR +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. +.TP +\fBpostrun\fR +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 \fBprerun\fR 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 \fBprerun\fR option, +the exit state of \fBpostrun\fR is +\fBignored\fR\&. +.SH "SEE ALSO" +.PP +nbd-server (1), nbd-client (8), +http://nbd.sourceforge.net/roadmap.html +.SH "AUTHOR" +.PP +The NBD kernel module and the NBD tools were originally +written by Pavel Machek (pavel@ucw.cz) +.PP +The Linux kernel module is now maintained by Paul Clements +(Paul.Clements@steeleye.com), while the userland tools are +maintained by Wouter Verhelst () +.PP +On The Hurd there is a regular translator available to perform the +client side of the protocol, and the use of +\fBnbd-client\fR is not required. Please see the +relevant documentation for more information. +.PP +This manual page was written by Wouter Verhelst () for +the Debian GNU/Linux 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. +.SH "EXAMPLES" +.PP +A simple \fBnbd-server\fR configuration file +would look like this: + +.nf + [generic] + [export] + exportname = /export/blkdev + port = 12345 + +.fi +.PP +For increased security, one might want to create an +authorization file, and set the UID and GID to run as: + +.nf + [generic] + user = nbd + group = nbd + [export] + exportname = /export/blkdev + port = 12345 + authfile = /etc/nbd-server/allow + +.fi +.PP +With /etc/nbd-server/allow containing the following: + +.nf + 127.0.0.1 + 192.168.0.0/8 + 192.168.1.1 + +.fi -- 1.7.10.4