-bin_PROGRAMS = nbd-server
+SUBDIRS = man
+bin_PROGRAMS = nbd-server @NBD_CLIENT_NAME@
EXTRA_PROGRAMS = nbd-client knbd-client
TESTS_ENVIRONMENT=$(srcdir)/simple_test
TESTS = cmd cfg1 cfgmulti cfgnew
nbd_tester_client_CFLAGS = @CFLAGS@ @GLIB_CFLAGS@
nbd_server_LDADD = @GLIB_LIBS@
nbd_tester_client_LDADD = @GLIB_LIBS@
-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 simple_test
-MAINTAINERCLEANFILES = nbd-client.8 nbd-server.1 nbd-server.5
-nbd-server.1.in: $(srcdir)/nbd-server.1.sgml
- LC_ALL=C docbook2man nbd-server.1.sgml
- mv NBD-SERVER.1 nbd-server.1.in
-nbd-client.8.in: $(srcdir)/nbd-client.8.sgml
- LC_ALL=C docbook2man nbd-client.8.sgml
- mv NBD-CLIENT.8 nbd-client.8.in
-nbd-server.5.in: $(srcdir)/nbd-server.5.sgml
- LC_ALL=C docbook2man nbd-server.5.sgml
- mv NBD-SERVER.5 nbd-server.5.in
+EXTRA_DIST = gznbd simple_test
dist-hook:
rm -Rf `find $(distdir) -name '.svn' -type d -print`
cmd:
#!/bin/sh
set -ex
-srcdir=. make -f Makefile.am nbd-server.1.in nbd-server.5.in nbd-client.8.in
+make -C man -f Makefile.am infiles
exec autoreconf -f -i
AC_FUNC_SETVBUF_REVERSED
AC_MSG_CHECKING(whether client should be built)
case $host_os in
- linux*) sbin_PROGRAMS="$sbin_PROGRAMS nbd-client"
- AC_MSG_RESULT(yes)
- ;;
- *) AC_MSG_RESULT(no) ;;
+ linux*) NBD_CLIENT_NAME="nbd-client"
+ AC_MSG_RESULT(yes)
+ ;;
+ *) NBD_CLIENT_NAME=""
+ AC_MSG_RESULT(no)
+ ;;
esac
+AC_SUBST(NBD_CLIENT_NAME)
AC_SEARCH_LIBS(bind, socket,, AC_MSG_ERROR([Could not find an implementation of the bind() system call]))
AC_SEARCH_LIBS(inet_ntoa, nsl,, AC_MSG_ERROR([Could not find an implementation of the inet_ntoa() system call]))
AC_SEARCH_LIBS(daemon, resolv,, AC_MSG_ERROR([Could not find an implementation of the daemon() system call]))
AC_HEADER_SYS_WAIT
AC_TYPE_OFF_T
AC_TYPE_PID_T
-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 nbd-server.1 nbd-server.5 nbd-client.8])
+AC_CONFIG_FILES([Makefile Doxyfile man/Makefile man/nbd-client.8 man/nbd-server.5 man/nbd-server.1])
AC_OUTPUT
--- /dev/null
+man_MANS = nbd-server.1 nbd-server.5 nbd-client.8
+CLEANFILES = manpage.links manpage.refs
+MAINTAINERCLEANFILES = nbd-server.1 nbd-client.8 nbd-server.5
+EXTRA_DIST = nbd-server.1.in.sgml nbd-client.8.in.sgml nbd-server.5.in.sgml
+
+infiles: nbd-server.1.in nbd-client.8.in nbd-server.5.in
+
+nbd-server.1.in: nbd-server.1.in.sgml
+ LC_ALL=C docbook2man nbd-server.1.in.sgml
+ mv NBD-SERVER.1 nbd-server.1.in
+nbd-client.8.in: nbd-client.8.in.sgml
+ LC_ALL=C docbook2man nbd-client.8.in.sgml
+ mv NBD-CLIENT.8 nbd-client.8.in
+nbd-server.5.in: nbd-server.5.in.sgml
+ LC_ALL=C docbook2man nbd-server.5.in.sgml
+ mv NBD-SERVER.5 nbd-server.5.in
--- /dev/null
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN" [
+
+<!-- Process this file with docbook-to-man to generate an nroff manual
+ page: `docbook-to-man manpage.sgml > 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 $< > $@
+ -->
+
+ <!-- Fill in your name for FIRSTNAME and SURNAME. -->
+ <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
+ <!ENTITY dhsurname "<surname>Verhelst</surname>">
+ <!-- Please adjust the date whenever revising the manpage. -->
+ <!ENTITY dhdate "<date>$Date$</date>">
+ <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
+ allowed: see man(7), man(1). -->
+ <!ENTITY dhsection "<manvolnum>8</manvolnum>">
+ <!ENTITY dhemail "<email>wouter@debian.org</email>">
+ <!ENTITY dhusername "Wouter Verhelst">
+ <!ENTITY dhucpackage "<refentrytitle>NBD-CLIENT</refentrytitle>">
+ <!ENTITY dhpackage "nbd-client">
+
+ <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
+ <!ENTITY gnu "<acronym>GNU</acronym>">
+]>
+
+<refentry>
+ <refentryinfo>
+ <address>
+ &dhemail;
+ </address>
+ <author>
+ &dhfirstname;
+ &dhsurname;
+ </author>
+ <copyright>
+ <year>2001</year>
+ <holder>&dhusername;</holder>
+ </copyright>
+ &dhdate;
+ </refentryinfo>
+ <refmeta>
+ &dhucpackage;
+
+ &dhsection;
+ </refmeta>
+ <refnamediv>
+ <refname>&dhpackage;</refname>
+
+ <refpurpose>connect to a server running nbd-server(1), to use its
+ exported block device</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>&dhpackage;</command>
+ <arg choice=plain><replaceable>host</replaceable></arg>
+ <arg><replaceable>port</replaceable></arg>
+ <arg choice=plain><replaceable>nbd-device</replaceable></arg>
+ <arg>-sdp</arg>
+ <arg>-swap</arg>
+ <arg>-persist</arg>
+ <arg>-nofork</arg>
+ <arg>-block-size <replaceable>block size</replaceable></arg>
+ <arg>-timeout <replaceable>seconds</replaceable></arg>
+ <arg>-name <replaceable>name</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>&dhpackage;</command>
+ <arg choice=plain><option>-d <replaceable>nbd-device</replaceable></option></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>&dhpackage;</command>
+ <arg choice="plain"><option>-c <replaceable>nbd-device</replaceable></option></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>DESCRIPTION</title>
+
+ <para>With <command>&dhpackage;</command>, you can connect to a
+ server running <command>nbd-server</command>, thus using raw
+ diskspace from that server as a blockdevice on the local
+ client.</para>
+
+ <para>To do this, support from the Linux Kernel is necessary, in
+ the form of the Network Block Device (NBD). When you have that,
+ either in the kernel, or as a module, you can connect to an NBD
+ server and use its exported file through a block special file with
+ major mode 43.</para>
+
+ <para>Optionally, long options can also be specified with two
+ leading dashes.</para>
+ </refsect1>
+ <refsect1>
+ <title>OPTIONS</title>
+
+ <para>The following options are supported:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-block-size <replaceable>block size</replaceable></option></term>
+ <term><option>-b</option></term>
+ <listitem>
+ <para>Use a blocksize of "block size". Default is 1024;
+ allowed values are either 512, 1024, 2048 or 4096</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>host</option></term>
+ <listitem>
+ <para>The hostname or IP address of the machine running
+ <command>nbd-server</command>. Since 2.9.15, the NBD
+ utilities support IPv6.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-timeout
+ <replaceable>seconds</replaceable></option></term>
+ <term><option>-t</option></term>
+ <listitem>
+ <para>Set the connection timeout to "seconds". For this to
+ work, you need a kernel with support for the NBD_SET_TIMEOUT
+ ioctl; this was introduced into Linus' tree on 2007-10-11,
+ and will be part of kernel 2.6.24.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>port</option></term>
+ <listitem>
+ <para>The TCP port on which <command>nbd-server</command> is
+ running at the server.</para>
+ <para>This option is required, unless the -N option is
+ specified, in which case it is not allowed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>nbd-device</option></term>
+ <listitem>
+ <para>The block special file this nbd-client should connect
+ to.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-check</option></term>
+ <term><option>-c</option></term>
+ <listitem>
+ <para>Check whether the specified nbd device is
+ connected.</para>
+ <para>If the device is connected, &dhpackage; will exit
+ with an exit state of 0 and print the PID of the &dhpackage;
+ instance that connected it to stdout.
+ <para>If the device is not
+ connected or does not exist (for example because the nbd
+ module was not loaded), &dhpackage; will exit with an exit
+ state of 1 and not print anything on stdout.</para>
+ <para>If an error occurred, &dhpackage; will exit with an exit
+ state of 2, and not print anything on stdout either.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-disconnect</option></term>
+ <term><option>-d</option></term>
+ <listitem>
+ <para>Disconnect the specified nbd device from the
+ server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-persist</option></term>
+ <term><option>-p</option></term>
+ <listitem>
+ <para>When this option is specified, &dhpackage; will
+ immediately try to reconnect an nbd device if the
+ connection ever drops unexpectedly due to a lost
+ server or something similar.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-sdp</option></term>
+ <term><option>-S</option></term>
+ <listitem>
+ <para>Connect to the server using the Socket Direct Protocol
+ (SDP), rather than IP. See nbd-server(1) for details.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-swap</option></term>
+ <term><option>-s</option></term>
+ <listitem>
+ <para>Specifies that this NBD device will be used as
+ swapspace. This option attempts to prevent deadlocks by
+ performing mlockall() at an appropriate time. It does not
+ however guarantee that such deadlocks can be avoided.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-nofork</option></term>
+ <term><option>-n</option></term>
+ <listitem>
+ <para>Specifies that the NBD client should not detach and
+ daemonize itself. This is mostly useful for debugging.</para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-name</option></term>
+ <term><option>-N</option></term>
+ <listitem>
+ <para>
+ Specifies the name of the export that we want to use. Required if
+ the port is not specified, not allowed in the other case.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>EXAMPLES</title>
+
+ <para>Some examples of nbd-client usage:</para>
+ <itemizedlist mark="none">
+ <listitem>
+ <para>To connect to a server running on port 2000 at host
+ "server.domain.com", using the client's block special file
+ "/dev/nbd0":</para>
+ <para><command>nbd-client server.domain.com 2000
+ /dev/nbd0</command></para>
+ </listitem>
+ <listitem>
+ <para>To connect to a server running on port 2001 at host
+ "swapserver.domain.com", using the client's block special
+ file "/dev/nbd1", for swap purposes:</para>
+ <para><command>nbd-client swapserver.domain.com 2001 /dev/nbd1
+ -swap</command></para>
+ </listitem>
+ <listitem>
+ <para>To disconnect the above connection again (after making
+ sure the block special file is not in use anymore):</para>
+ <para><command>nbd-client -d /dev/nbd1</command></para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+ <refsect1>
+ <title>SEE ALSO</title>
+
+ <para>nbd-server (1).</para>
+
+ </refsect1>
+ <refsect1>
+ <title>AUTHOR</title>
+ <para>The NBD kernel module and the NBD tools have been written by
+ Pavel Macheck (pavel@ucw.cz).</para>
+
+ <para>The kernel module is now maintained by Paul Clements
+ (Paul.Clements@steeleye.com), while the userland tools are maintained by
+ Wouter Verhelst (wouter@debian.org)</para>
+
+ <para>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 <acronym>GNU</acronym> General Public License,
+ version 2, as published by the Free Software Foundation.</para>
+
+ </refsect1>
+</refentry>
--- /dev/null
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+
+<!-- Process this file with docbook-to-man to generate an nroff manual
+ page: `docbook-to-man manpage.sgml > 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 $< > $@
+ -->
+
+ <!-- Fill in your name for FIRSTNAME and SURNAME. -->
+ <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
+ <!ENTITY dhsurname "<surname>Verhelst</surname>">
+ <!-- Please adjust the date whenever revising the manpage. -->
+ <!ENTITY dhdate "<date>$Date$</date>">
+ <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
+ allowed: see man(7), man(1). -->
+ <!ENTITY dhsection "<manvolnum>1</manvolnum>">
+ <!ENTITY dhemail "<email>wouter@debian.org</email>">
+ <!ENTITY dhusername "Wouter Verhelst">
+ <!ENTITY dhucpackage "<refentrytitle>NBD-SERVER</refentrytitle>">
+ <!ENTITY dhpackage "nbd-server">
+
+ <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
+ <!ENTITY gnu "<acronym>GNU</acronym>">
+]>
+
+<refentry>
+ <refentryinfo>
+ <address>
+ &dhemail;
+ </address>
+ <author>
+ &dhfirstname;
+ &dhsurname;
+ </author>
+ <copyright>
+ <year>2001</year>
+ <holder>&dhusername;</holder>
+ </copyright>
+ &dhdate;
+ </refentryinfo>
+ <refmeta>
+ &dhucpackage;
+
+ &dhsection;
+ </refmeta>
+ <refnamediv>
+ <refname>&dhpackage;</refname>
+
+ <refpurpose>serve a file as a block device to other computers
+ running the &gnu;/Linux(tm) or &gnu;/Hurd Operating
+ System</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>&dhpackage; </command>
+
+ <arg choice=plain><replaceable>[ip@]port</replaceable</arg>
+ <arg choice=plain><replaceable>filename</replaceable></arg>
+ <arg><replaceable>size</replaceable></arg>
+ <arg><option>-r</option></arg>
+ <arg><option>-m</option></arg>
+ <arg><option>-c</option></arg>
+ <arg><option>-l <replaceable>host list filename</replaceable></option></arg>
+ <arg><option>-o <replaceable>section name</replaceable></option></arg>
+ <arg><option>-C <replaceable>config file</replaceable></option></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>DESCRIPTION</title>
+
+ <para><command>&dhpackage;</command> 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.</para>
+
+ <para>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.</para>
+
+ <para><command>&dhpackage;</command> implements some security
+ 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.</para>
+
+ <para>Note that while the command line allows for specifying an
+ export, the use of this option is deprecated. It is preferred to
+ make use of a configuration file instead, the format of which is
+ defined in nbd-server(5).</para>
+ </refsect1>
+ <refsect1>
+ <title>OPTIONS</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ip</term>
+ <listitem>
+ <para>The ip address the server should listen on. This may
+ be an IPv4 address, an IPv6 address, or a hostname. In the
+ latter case, nbd-server will do a hostname lookup for the
+ name specified, and will listen on the first address that is
+ returned. For compatibility with past versions of
+ nbd-server, if an IPv4 address is specified, the @ sign that
+ serves as separator between the address and port may be
+ replaced by a colon.</para>
+ <para>If this parameter is not specified, nbd-server will
+ listen on all local addresses on both IPv4 and IPv6. To
+ limit to IPv4, specify the address as 0.0.0.0; to limit to
+ IPv6, specify it as ::.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>port</option>
+ </term>
+ <listitem>
+ <para>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)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>filename</option></term>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>size</option></term>
+ <listitem>
+ <para>The size of the block device at the client side. This
+ is especially useful in conjunction with the -m
+ option</para>
+ <para>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)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r</option></term>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m</option></term>
+ <listitem>
+ <para>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.</para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Allowing more flexibility for this option is planned for
+ future versions.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c</option></term>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-C</option></term>
+ <listitem>
+ <para>Specify configuration file. The default configuration
+ file, if this parameter is not specified, is
+ <filename>@sysconfdir@/nbd-server/config</filename>.</para>
+ <para>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 <command>nbd-server</command>(1) to a non-existing or
+ empty configuration file.</para>
+ <para>Also note that if an empty, incomplete, or invalid
+ configuration file is specified, nbd-server will produce a
+ warning about failure to parse the config file. If the
+ command line contains a fully specified configuration, this
+ warning is harmless and may be ignored.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>host list filename</option></term>
+ <listitem>
+ <para>This argument should contain a list of IP-addresses
+ for hosts that may connect to the server. Wildcards are
+ <emphasis>not</emphasis> 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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>section name</option></term>
+ <listitem>
+ <para>If the <option>-o</option> argument is given on the
+ command line, then &dhpackage; 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.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsect1>
+ <refsect1>
+ <title>EXAMPLES</title>
+ <para>Some examples of nbd-server usage:</para>
+ <itemizedlist mark="none">
+ <listitem>
+ <para>To export a file /export/nbd/exp-bl-dev on port 2000:</para>
+ <para><command>nbd-server 2000 /export/nbd/exp-bl-dev</command></para>
+ </listitem>
+ <listitem>
+ <para>To export a the same file read-only:</para>
+ <para><command>nbd-server 2000 /export/nbd/exp-bl-dev -r</command></para>
+ </listitem>
+ <listitem>
+ <para>To export the same file read-write, but make sure
+ changes are lost after restarting the client or the
+ server:</para>
+ <para><command>nbd-server 2000 /export/nbd/exp-bl-dev
+ -c</command></para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+ <refsect1>
+ <title>SEE ALSO</title>
+
+ <para>nbd-client (8), nbd-server (5), http://nbd.sourceforge.net/roadmap.html</para>
+
+ </refsect1>
+ <refsect1>
+ <title>AUTHOR</title>
+ <para>The NBD kernel module and the NBD tools were originally
+ written by Pavel Machek (pavel@ucw.cz)</para>
+
+ <para>The Linux kernel module is now maintained by Paul Clements
+ (Paul.Clements@steeleye.com), while the userland tools are
+ maintained by &dhusername; (&dhemail;)</para>
+
+ <para>On The Hurd there is a regular translator available to perform the
+ client side of the protocol, and the use of
+ <command>nbd-client</command> is not required. Please see the
+ relevant documentation for more information.</para>
+
+ <para>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 <acronym>GNU</acronym> General Public License,
+ version 2, as published by the Free Software Foundation.</para>
+
+ </refsect1>
+</refentry>
--- /dev/null
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+
+<!-- Process this file with docbook-to-man to generate an nroff manual
+ page: `docbook-to-man manpage.sgml > 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 $< > $@
+ -->
+
+ <!-- Fill in your name for FIRSTNAME and SURNAME. -->
+ <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
+ <!ENTITY dhsurname "<surname>Verhelst</surname>">
+ <!-- Please adjust the date whenever revising the manpage. -->
+ <!ENTITY dhdate "<date>$Date: 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $</date>">
+ <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
+ allowed: see man(7), man(1). -->
+ <!ENTITY dhsection "<manvolnum>5</manvolnum>">
+ <!ENTITY dhemail "<email>wouter@debian.org</email>">
+ <!ENTITY dhusername "Wouter Verhelst">
+ <!ENTITY dhucpackage "<refentrytitle>NBD-SERVER</refentrytitle>">
+ <!ENTITY dhpackage "@sysconfdir@/nbd-server/config">
+
+ <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
+ <!ENTITY gnu "<acronym>GNU</acronym>">
+]>
+
+<refentry>
+ <refentryinfo>
+ <address>
+ &dhemail;
+ </address>
+ <author>
+ &dhfirstname;
+ &dhsurname;
+ </author>
+ <copyright>
+ <year>2006</year>
+ <holder>&dhusername;</holder>
+ </copyright>
+ &dhdate;
+ </refentryinfo>
+ <refmeta>
+ &dhucpackage;
+
+ &dhsection;
+ </refmeta>
+ <refnamediv>
+ <refname>&dhpackage;</refname>
+
+ <refpurpose>configuration file for nbd-server</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>&dhpackage; </command>
+
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>DESCRIPTION</title>
+
+ <para><command>&dhpackage;</command> allows to configure the
+ nbd-server.</para>
+
+ <para>While
+ <filename>@sysconfdir@/nbd-server/config</filename> is the default
+ configuration file, this can be varied with the <option>-C</option>
+ option to <command>nbd-server</command>(1).
+ </para>
+ <para>
+ The configuration file consists of section header lines, comment
+ lines, and option lines.
+ </para>
+ <para>
+ 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
+ <option>generic</option>, 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. 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.
+ </para>
+ <para>
+ 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 <emphasis>not</emphasis> be used on
+ option lines or section header lines.
+ </para>
+ <para>
+ 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).
+ </para>
+
+ </refsect1>
+ <refsect1>
+ <title>OPTIONS FOR SECTION [generic]</title>
+
+ <!-- These are in alphabetical order, please keep it that way -->
+ <variablelist>
+ <varlistentry>
+ <term><option>group</option></term>
+ <listitem>
+ <para>
+ Optional; string.
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>user</option></term>
+ <listitem>
+ <para>
+ Optional; string.
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>oldstyle</option></term>
+ <listitem>
+ <para>
+ Optional; boolean
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Note that exports specified on the command line will
+ always use the old handshake protocol and will not allow
+ name-based exports.
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>listenaddr</option></term>
+ <listitem>
+ <para>
+ Optional; string
+ </para>
+ <para>If this option is set, it should contain the local IP
+ address on which we should listen to
+ <command>nbd-client</command>(8) connections. If it is not
+ set, <command>nbd-server</command> 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.</para>
+ </listitem>
+ </varlistentry
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>OPTIONS FOR EXPORT SECTIONS</title>
+
+ <!-- These are in alphabetical order, please keep it that way -->
+ <variablelist>
+ <varlistentry>
+ <term><option>authfile</option></term>
+ <listitem>
+ <para>
+ Optional; string; default
+ <filename>@sysconfdir@/nbd-server/allow</filename>.
+ </para>
+ <para>
+ 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
+ <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
+ 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, <command>nbd-server</command> will
+ only allow clients to connect whose IP-adres is listed in
+ this file.
+ </para>
+ <para>Corresponds to the <option>-l</option> option on the
+ command line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>copyonwrite</option></term>
+ <listitem>
+ <para>
+ Optional; boolean.
+ </para>
+ <para>
+ 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 somewhat slower, and that any writes will
+ be lost upon disconnect.
+ </para>
+ <para>Corresponds to the <option>-c</option> option on the
+ command line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>exportname</option></term>
+ <listitem>
+ <para>Required; string.</para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Note that <command>nbd-server</command> will only try to
+ find and open the exported file when a client actually
+ connects; as a result, <command>nbd-server</command> must
+ be able to open and read this file
+ <emphasis>after</emphasis> changing to the user and group
+ that have been specified by use of the
+ <option>user</option> and <option>group</option> options;
+ also, <command>nbd-server</command> will only detect
+ errors in this option upon connection of a client.
+ </para>
+ <para>When specified on the command line, this should be the
+ second argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>filesize</option></term>
+ <listitem>
+ <para>Optional; integer; default autodetected.</para>
+ <para>
+ Disable autodetection of file or block device size, and
+ forcibly specify a size. Sizes must be specified in
+ bytes. If the <option>multifile</option> option is in
+ effect, this option specifies the size of the
+ <emphasis>entire</emphasis> export, not of individual
+ files.
+ </para>
+ <para>When specified on the command line, this should be the
+ third argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>listenaddr</term>
+ <listitem>
+ <para>
+ Optional; string
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>multifile</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>
+ If this option is set to true, then
+ <command>nbd-server</command> will search for files of the
+ form
+ <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
+ with <replaceable>exportname</replaceable> being the
+ filename that would otherwise have been used (after name
+ transformation for virtualization, if any, has been
+ performed) and <replaceable>integer</replaceable> an
+ integer number, starting with 0 and ending when no more
+ files can be found.
+ </para>
+ <para>
+ The size of the individual files will be autodetected,
+ <emphasis>even</emphasis> if the <option>filesize</option>
+ option has been specified.
+ </para>
+ <para>
+ Corresponds to the <option>-m</option> option on the
+ command line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>port</option></term>
+ <listitem>
+ <para>Required if 'oldstyle' global parameter is set; integer.</para>
+ <para>
+ The port on which this export is to be served using the
+ old-style handshake protocol.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ When specified on the command line, this should be the
+ first argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>readonly</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>
+ Disallow writes to the device. If this option is
+ specified, <command>nbd-server</command> will issue an
+ error to any client that tries to write to the device.
+ </para>
+ <para>
+ Use of this option in conjunction with
+ <option>copyonwrite</option> is possible, but silly.
+ </para>
+ <para>Corresponds to the <option>-r</option> option on the
+ command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>sdp</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>
+ When this option is enabled, <command>nbd-server</command>
+ 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.
+ </para>
+ <para>
+ Additionally, support for this option must be enabled at
+ compile time, using the <option>--enable-sdp</option> option
+ to the <command>configure</command> script. If this option
+ is found in a configuration file and
+ <command>nbd-server</command> does not have support for SDP,
+ then <command>nbd-server</command> will exit with an error
+ message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>sync</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>When this option is enabled,
+ <command>nbd-server</command> 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 <emphasis>not</emphasis> enabled, since it seriously
+ reduces performance on ext3 filesystems while not
+ importantly impacting reliability.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>sparse_cow</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>
+ When this option is enabled, <command>nbd-server</command>
+ will use sparse files to implement the copy-on-write
+ option; such files take up less space then they appear to,
+ which allows <command>nbd-server</command> to handle the
+ file as if it was just as large as the block device it's
+ for.
+ </para>
+ <para>
+ If this option is disabled, <command>nbd-server</command>
+ will map every newly written block to the end of the
+ copy-on-write file, which means that
+ <command>nbd-server</command> will have to lseek(2) to the
+ right position after every 4096-byte block.
+ </para>
+ <para>
+ Using this option may be faster when much is being written
+ during a connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>timeout</option></term>
+ <listitem>
+ <para>Optional; integer; default 0</para>
+ <para>
+ How many seconds a connection may be idle for this
+ export. When a connection is idle for a longer time,
+ <command>nbd-server</command> will forcibly disconnect the
+ connection. If you specify 0 (the default), then a
+ connection may be idle forever.
+ </para>
+ <para>
+ Corresponds to the <option>-a</option> option on the
+ command line
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>virtstyle</option></term>
+ <listitem>
+ <para>Optional; string; default "ipliteral"</para>
+ <para>
+ 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 active, the
+ <replaceable>exportname</replaceable> 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.
+ </para>
+ <para>
+ There are four types of virtualization that
+ <command>nbd-server</command> supports:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><option>none</option></term>
+ <listitem>
+ <para>
+ No virtualization. Will attempt to open the filename
+ as it was written, even if it contains '%s' in the
+ name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>ipliteral</option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ <para>
+ As an example, if a client connects from 192.168.1.100
+ and <option>exportname</option> is specified as
+ <filename>/export/%s</filename>, then nbd-server will
+ attempt to serve
+ <filename>/export/192.168.1.100</filename>. For IPv6,
+ with a client connecting from 2001:6f8:32f::39, the
+ filename would be
+ <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>iphash</option></term>
+ <listitem>
+ <para>
+ Same as above, except that
+ <command>nbd-server</command> will replace the dots
+ in the IP address by forward slashes ('/'); in the
+ same example, <command>nbd-server</command> would
+ open <filename>/export/192/168/1/100</filename>
+ instead.
+ </para>
+ <para>
+ 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. It was
+ thought that having to create an eight-deep directory
+ structure would not be as useful.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>cidrhash</option></term>
+ <listitem>
+ <para>
+ This option requires one to add a space and a number
+ after it. <command>nbd-server</command> will use the
+ number as a network mask in CIDR style, and use that
+ as a hash cutoff point. In the above example, if
+ <option>virtstyle</option> has been specified as
+ <constant>cidrhash 16</constant>, then
+ <command>nbd-server</command> will try to open
+ <filename>/export/192.168.0.0/192.168.1.100</filename>;
+ if <option>virtstyle</option> were specified as
+ <constant>cidrhash 26</constant>, then
+ <command>nbd-server</command> will try to open
+ <filename>/export/192.168.1.64/192.168.1.100</filename>.
+ </para>
+ <para>For IPv6, in the above example, with
+ <constant>cidrhash 42</constant>, the filename would
+ be
+ <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>prerun</option></term>
+ <listitem>
+ <para>Optional; string</para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ If the command runs with a non-zero exit status,
+ then nbd-server will assume the export will fail,
+ and refuse to serve it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>postrun</option></term>
+ <listitem>
+ <para>Optional; string</para>
+ <para>
+ 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 <option>prerun</option> has set up, to log
+ something, or similar.
+ </para>
+ <para>
+ If the literal string '%s' is present in the
+ command, it will be replaced by the file name that
+ has just been closed.
+ </para>
+ <para>
+ In contrast to the <option>prerun</option> option,
+ the exit state of <option>postrun</option> is
+ <emphasis>ignored</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsect1>
+ <refsect1>
+ <title>SEE ALSO</title>
+
+ <para>nbd-server (1), nbd-client (8),
+ http://nbd.sourceforge.net/roadmap.html</para>
+
+ </refsect1>
+ <refsect1>
+ <title>AUTHOR</title>
+ <para>The NBD kernel module and the NBD tools were originally
+ written by Pavel Machek (pavel@ucw.cz)</para>
+
+ <para>The Linux kernel module is now maintained by Paul Clements
+ (Paul.Clements@steeleye.com), while the userland tools are
+ maintained by &dhusername; (&dhemail;)</para>
+
+ <para>On The Hurd there is a regular translator available to perform the
+ client side of the protocol, and the use of
+ <command>nbd-client</command> is not required. Please see the
+ relevant documentation for more information.</para>
+
+ <para>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 <acronym>GNU</acronym> General Public License,
+ version 2, as published by the Free Software Foundation.</para>
+
+ </refsect1>
+ <refsect1>
+ <title>EXAMPLES</title>
+ <para>A simple <command>nbd-server</command> configuration file
+ would look like this:</para>
+ <programlisting>
+ [generic]
+ [export]
+ exportname = /export/blkdev
+ port = 12345
+ </programlisting>
+ <para>For increased security, one might want to create an
+ authorization file, and set the UID and GID to run as:</para>
+ <programlisting>
+ [generic]
+ user = nbd
+ group = nbd
+ [export]
+ exportname = /export/blkdev
+ port = 12345
+ authfile = @sysconfdir@/nbd-server/allow
+ </programlisting>
+ <para>With @sysconfdir@/nbd-server/allow containing the following:</para>
+ <programlisting>
+ 127.0.0.1
+ 192.168.0.0/8
+ 192.168.1.1
+ </programlisting>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
+++ /dev/null
-<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN" [
-
-<!-- Process this file with docbook-to-man to generate an nroff manual
- page: `docbook-to-man manpage.sgml > 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 $< > $@
- -->
-
- <!-- Fill in your name for FIRSTNAME and SURNAME. -->
- <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
- <!ENTITY dhsurname "<surname>Verhelst</surname>">
- <!-- Please adjust the date whenever revising the manpage. -->
- <!ENTITY dhdate "<date>$Date$</date>">
- <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
- allowed: see man(7), man(1). -->
- <!ENTITY dhsection "<manvolnum>8</manvolnum>">
- <!ENTITY dhemail "<email>wouter@debian.org</email>">
- <!ENTITY dhusername "Wouter Verhelst">
- <!ENTITY dhucpackage "<refentrytitle>NBD-CLIENT</refentrytitle>">
- <!ENTITY dhpackage "nbd-client">
-
- <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
- <!ENTITY gnu "<acronym>GNU</acronym>">
-]>
-
-<refentry>
- <refentryinfo>
- <address>
- &dhemail;
- </address>
- <author>
- &dhfirstname;
- &dhsurname;
- </author>
- <copyright>
- <year>2001</year>
- <holder>&dhusername;</holder>
- </copyright>
- &dhdate;
- </refentryinfo>
- <refmeta>
- &dhucpackage;
-
- &dhsection;
- </refmeta>
- <refnamediv>
- <refname>&dhpackage;</refname>
-
- <refpurpose>connect to a server running nbd-server(1), to use its
- exported block device</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>&dhpackage;</command>
- <arg choice=plain><replaceable>host</replaceable></arg>
- <arg><replaceable>port</replaceable></arg>
- <arg choice=plain><replaceable>nbd-device</replaceable></arg>
- <arg>-sdp</arg>
- <arg>-swap</arg>
- <arg>-persist</arg>
- <arg>-nofork</arg>
- <arg>-block-size <replaceable>block size</replaceable></arg>
- <arg>-timeout <replaceable>seconds</replaceable></arg>
- <arg>-name <replaceable>name</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhpackage;</command>
- <arg choice=plain><option>-d <replaceable>nbd-device</replaceable></option></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhpackage;</command>
- <arg choice="plain"><option>-c <replaceable>nbd-device</replaceable></option></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>DESCRIPTION</title>
-
- <para>With <command>&dhpackage;</command>, you can connect to a
- server running <command>nbd-server</command>, thus using raw
- diskspace from that server as a blockdevice on the local
- client.</para>
-
- <para>To do this, support from the Linux Kernel is necessary, in
- the form of the Network Block Device (NBD). When you have that,
- either in the kernel, or as a module, you can connect to an NBD
- server and use its exported file through a block special file with
- major mode 43.</para>
-
- <para>Optionally, long options can also be specified with two
- leading dashes.</para>
- </refsect1>
- <refsect1>
- <title>OPTIONS</title>
-
- <para>The following options are supported:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-block-size <replaceable>block size</replaceable></option></term>
- <term><option>-b</option></term>
- <listitem>
- <para>Use a blocksize of "block size". Default is 1024;
- allowed values are either 512, 1024, 2048 or 4096</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>host</option></term>
- <listitem>
- <para>The hostname or IP address of the machine running
- <command>nbd-server</command>. Since 2.9.15, the NBD
- utilities support IPv6.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-timeout
- <replaceable>seconds</replaceable></option></term>
- <term><option>-t</option></term>
- <listitem>
- <para>Set the connection timeout to "seconds". For this to
- work, you need a kernel with support for the NBD_SET_TIMEOUT
- ioctl; this was introduced into Linus' tree on 2007-10-11,
- and will be part of kernel 2.6.24.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>port</option></term>
- <listitem>
- <para>The TCP port on which <command>nbd-server</command> is
- running at the server.</para>
- <para>This option is required, unless the -N option is
- specified, in which case it is not allowed.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>nbd-device</option></term>
- <listitem>
- <para>The block special file this nbd-client should connect
- to.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-check</option></term>
- <term><option>-c</option></term>
- <listitem>
- <para>Check whether the specified nbd device is
- connected.</para>
- <para>If the device is connected, &dhpackage; will exit
- with an exit state of 0 and print the PID of the &dhpackage;
- instance that connected it to stdout.
- <para>If the device is not
- connected or does not exist (for example because the nbd
- module was not loaded), &dhpackage; will exit with an exit
- state of 1 and not print anything on stdout.</para>
- <para>If an error occurred, &dhpackage; will exit with an exit
- state of 2, and not print anything on stdout either.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-disconnect</option></term>
- <term><option>-d</option></term>
- <listitem>
- <para>Disconnect the specified nbd device from the
- server</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-persist</option></term>
- <term><option>-p</option></term>
- <listitem>
- <para>When this option is specified, &dhpackage; will
- immediately try to reconnect an nbd device if the
- connection ever drops unexpectedly due to a lost
- server or something similar.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-sdp</option></term>
- <term><option>-S</option></term>
- <listitem>
- <para>Connect to the server using the Socket Direct Protocol
- (SDP), rather than IP. See nbd-server(1) for details.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-swap</option></term>
- <term><option>-s</option></term>
- <listitem>
- <para>Specifies that this NBD device will be used as
- swapspace. This option attempts to prevent deadlocks by
- performing mlockall() at an appropriate time. It does not
- however guarantee that such deadlocks can be avoided.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-nofork</option></term>
- <term><option>-n</option></term>
- <listitem>
- <para>Specifies that the NBD client should not detach and
- daemonize itself. This is mostly useful for debugging.</para>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-name</option></term>
- <term><option>-N</option></term>
- <listitem>
- <para>
- Specifies the name of the export that we want to use. Required if
- the port is not specified, not allowed in the other case.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>EXAMPLES</title>
-
- <para>Some examples of nbd-client usage:</para>
- <itemizedlist mark="none">
- <listitem>
- <para>To connect to a server running on port 2000 at host
- "server.domain.com", using the client's block special file
- "/dev/nbd0":</para>
- <para><command>nbd-client server.domain.com 2000
- /dev/nbd0</command></para>
- </listitem>
- <listitem>
- <para>To connect to a server running on port 2001 at host
- "swapserver.domain.com", using the client's block special
- file "/dev/nbd1", for swap purposes:</para>
- <para><command>nbd-client swapserver.domain.com 2001 /dev/nbd1
- -swap</command></para>
- </listitem>
- <listitem>
- <para>To disconnect the above connection again (after making
- sure the block special file is not in use anymore):</para>
- <para><command>nbd-client -d /dev/nbd1</command></para>
- </listitem>
- </itemizedlist>
- </refsect1>
- <refsect1>
- <title>SEE ALSO</title>
-
- <para>nbd-server (1).</para>
-
- </refsect1>
- <refsect1>
- <title>AUTHOR</title>
- <para>The NBD kernel module and the NBD tools have been written by
- Pavel Macheck (pavel@ucw.cz).</para>
-
- <para>The kernel module is now maintained by Paul Clements
- (Paul.Clements@steeleye.com), while the userland tools are maintained by
- Wouter Verhelst (wouter@debian.org)</para>
-
- <para>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 <acronym>GNU</acronym> General Public License,
- version 2, as published by the Free Software Foundation.</para>
-
- </refsect1>
-</refentry>
+++ /dev/null
-<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-
-<!-- Process this file with docbook-to-man to generate an nroff manual
- page: `docbook-to-man manpage.sgml > 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 $< > $@
- -->
-
- <!-- Fill in your name for FIRSTNAME and SURNAME. -->
- <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
- <!ENTITY dhsurname "<surname>Verhelst</surname>">
- <!-- Please adjust the date whenever revising the manpage. -->
- <!ENTITY dhdate "<date>$Date$</date>">
- <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
- allowed: see man(7), man(1). -->
- <!ENTITY dhsection "<manvolnum>1</manvolnum>">
- <!ENTITY dhemail "<email>wouter@debian.org</email>">
- <!ENTITY dhusername "Wouter Verhelst">
- <!ENTITY dhucpackage "<refentrytitle>NBD-SERVER</refentrytitle>">
- <!ENTITY dhpackage "nbd-server">
-
- <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
- <!ENTITY gnu "<acronym>GNU</acronym>">
-]>
-
-<refentry>
- <refentryinfo>
- <address>
- &dhemail;
- </address>
- <author>
- &dhfirstname;
- &dhsurname;
- </author>
- <copyright>
- <year>2001</year>
- <holder>&dhusername;</holder>
- </copyright>
- &dhdate;
- </refentryinfo>
- <refmeta>
- &dhucpackage;
-
- &dhsection;
- </refmeta>
- <refnamediv>
- <refname>&dhpackage;</refname>
-
- <refpurpose>serve a file as a block device to other computers
- running the &gnu;/Linux(tm) or &gnu;/Hurd Operating
- System</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>&dhpackage; </command>
-
- <arg choice=plain><replaceable>[ip@]port</replaceable</arg>
- <arg choice=plain><replaceable>filename</replaceable></arg>
- <arg><replaceable>size</replaceable></arg>
- <arg><option>-r</option></arg>
- <arg><option>-m</option></arg>
- <arg><option>-c</option></arg>
- <arg><option>-l <replaceable>host list filename</replaceable></option></arg>
- <arg><option>-o <replaceable>section name</replaceable></option></arg>
- <arg><option>-C <replaceable>config file</replaceable></option></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>DESCRIPTION</title>
-
- <para><command>&dhpackage;</command> 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.</para>
-
- <para>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.</para>
-
- <para><command>&dhpackage;</command> implements some security
- 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.</para>
-
- <para>Note that while the command line allows for specifying an
- export, the use of this option is deprecated. It is preferred to
- make use of a configuration file instead, the format of which is
- defined in nbd-server(5).</para>
- </refsect1>
- <refsect1>
- <title>OPTIONS</title>
-
- <variablelist>
- <varlistentry>
- <term>ip</term>
- <listitem>
- <para>The ip address the server should listen on. This may
- be an IPv4 address, an IPv6 address, or a hostname. In the
- latter case, nbd-server will do a hostname lookup for the
- name specified, and will listen on the first address that is
- returned. For compatibility with past versions of
- nbd-server, if an IPv4 address is specified, the @ sign that
- serves as separator between the address and port may be
- replaced by a colon.</para>
- <para>If this parameter is not specified, nbd-server will
- listen on all local addresses on both IPv4 and IPv6. To
- limit to IPv4, specify the address as 0.0.0.0; to limit to
- IPv6, specify it as ::.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>port</option>
- </term>
- <listitem>
- <para>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)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>filename</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>size</option></term>
- <listitem>
- <para>The size of the block device at the client side. This
- is especially useful in conjunction with the -m
- option</para>
- <para>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)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-r</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-m</option></term>
- <listitem>
- <para>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.</para>
- <para>
- 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.
- </para>
- <para>
- Allowing more flexibility for this option is planned for
- future versions.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-c</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-C</option></term>
- <listitem>
- <para>Specify configuration file. The default configuration
- file, if this parameter is not specified, is
- <filename>@sysconfdir@/nbd-server/config</filename>.</para>
- <para>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 <command>nbd-server</command>(1) to a non-existing or
- empty configuration file.</para>
- <para>Also note that if an empty, incomplete, or invalid
- configuration file is specified, nbd-server will produce a
- warning about failure to parse the config file. If the
- command line contains a fully specified configuration, this
- warning is harmless and may be ignored.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>host list filename</option></term>
- <listitem>
- <para>This argument should contain a list of IP-addresses
- for hosts that may connect to the server. Wildcards are
- <emphasis>not</emphasis> 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.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>section name</option></term>
- <listitem>
- <para>If the <option>-o</option> argument is given on the
- command line, then &dhpackage; 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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </refsect1>
- <refsect1>
- <title>EXAMPLES</title>
- <para>Some examples of nbd-server usage:</para>
- <itemizedlist mark="none">
- <listitem>
- <para>To export a file /export/nbd/exp-bl-dev on port 2000:</para>
- <para><command>nbd-server 2000 /export/nbd/exp-bl-dev</command></para>
- </listitem>
- <listitem>
- <para>To export a the same file read-only:</para>
- <para><command>nbd-server 2000 /export/nbd/exp-bl-dev -r</command></para>
- </listitem>
- <listitem>
- <para>To export the same file read-write, but make sure
- changes are lost after restarting the client or the
- server:</para>
- <para><command>nbd-server 2000 /export/nbd/exp-bl-dev
- -c</command></para>
- </listitem>
- </itemizedlist>
- </refsect1>
- <refsect1>
- <title>SEE ALSO</title>
-
- <para>nbd-client (8), nbd-server (5), http://nbd.sourceforge.net/roadmap.html</para>
-
- </refsect1>
- <refsect1>
- <title>AUTHOR</title>
- <para>The NBD kernel module and the NBD tools were originally
- written by Pavel Machek (pavel@ucw.cz)</para>
-
- <para>The Linux kernel module is now maintained by Paul Clements
- (Paul.Clements@steeleye.com), while the userland tools are
- maintained by &dhusername; (&dhemail;)</para>
-
- <para>On The Hurd there is a regular translator available to perform the
- client side of the protocol, and the use of
- <command>nbd-client</command> is not required. Please see the
- relevant documentation for more information.</para>
-
- <para>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 <acronym>GNU</acronym> General Public License,
- version 2, as published by the Free Software Foundation.</para>
-
- </refsect1>
-</refentry>
+++ /dev/null
-<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-
-<!-- Process this file with docbook-to-man to generate an nroff manual
- page: `docbook-to-man manpage.sgml > 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 $< > $@
- -->
-
- <!-- Fill in your name for FIRSTNAME and SURNAME. -->
- <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
- <!ENTITY dhsurname "<surname>Verhelst</surname>">
- <!-- Please adjust the date whenever revising the manpage. -->
- <!ENTITY dhdate "<date>$Date: 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $</date>">
- <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
- allowed: see man(7), man(1). -->
- <!ENTITY dhsection "<manvolnum>5</manvolnum>">
- <!ENTITY dhemail "<email>wouter@debian.org</email>">
- <!ENTITY dhusername "Wouter Verhelst">
- <!ENTITY dhucpackage "<refentrytitle>NBD-SERVER</refentrytitle>">
- <!ENTITY dhpackage "/etc/nbd-server/config">
-
- <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
- <!ENTITY gnu "<acronym>GNU</acronym>">
-]>
-
-<refentry>
- <refentryinfo>
- <address>
- &dhemail;
- </address>
- <author>
- &dhfirstname;
- &dhsurname;
- </author>
- <copyright>
- <year>2006</year>
- <holder>&dhusername;</holder>
- </copyright>
- &dhdate;
- </refentryinfo>
- <refmeta>
- &dhucpackage;
-
- &dhsection;
- </refmeta>
- <refnamediv>
- <refname>&dhpackage;</refname>
-
- <refpurpose>configuration file for nbd-server</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>&dhpackage; </command>
-
- </cmdsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>DESCRIPTION</title>
-
- <para><command>&dhpackage;</command> allows to configure the
- nbd-server.</para>
-
- <para>While
- <filename>@sysconfdir@/nbd-server/config</filename> is the default
- configuration file, this can be varied with the <option>-C</option>
- option to <command>nbd-server</command>(1).
- </para>
- <para>
- The configuration file consists of section header lines, comment
- lines, and option lines.
- </para>
- <para>
- 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
- <option>generic</option>, 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. 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.
- </para>
- <para>
- 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 <emphasis>not</emphasis> be used on
- option lines or section header lines.
- </para>
- <para>
- 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).
- </para>
-
- </refsect1>
- <refsect1>
- <title>OPTIONS FOR SECTION [generic]</title>
-
- <!-- These are in alphabetical order, please keep it that way -->
- <variablelist>
- <varlistentry>
- <term><option>group</option></term>
- <listitem>
- <para>
- Optional; string.
- </para>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>user</option></term>
- <listitem>
- <para>
- Optional; string.
- </para>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>oldstyle</option></term>
- <listitem>
- <para>
- Optional; boolean
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- Note that exports specified on the command line will
- always use the old handshake protocol and will not allow
- name-based exports.
- </para>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>listenaddr</option></term>
- <listitem>
- <para>
- Optional; string
- </para>
- <para>If this option is set, it should contain the local IP
- address on which we should listen to
- <command>nbd-client</command>(8) connections. If it is not
- set, <command>nbd-server</command> 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.</para>
- </listitem>
- </varlistentry
- </variablelist>
- </refsect1>
- <refsect1>
- <title>OPTIONS FOR EXPORT SECTIONS</title>
-
- <!-- These are in alphabetical order, please keep it that way -->
- <variablelist>
- <varlistentry>
- <term><option>authfile</option></term>
- <listitem>
- <para>
- Optional; string; default
- <filename>@sysconfdir@/nbd-server/allow</filename>.
- </para>
- <para>
- 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
- <option><replaceable>network</replaceable>/<replaceable>masklen</replaceable></option>)
- 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, <command>nbd-server</command> will
- only allow clients to connect whose IP-adres is listed in
- this file.
- </para>
- <para>Corresponds to the <option>-l</option> option on the
- command line</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>copyonwrite</option></term>
- <listitem>
- <para>
- Optional; boolean.
- </para>
- <para>
- 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 somewhat slower, and that any writes will
- be lost upon disconnect.
- </para>
- <para>Corresponds to the <option>-c</option> option on the
- command line</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>exportname</option></term>
- <listitem>
- <para>Required; string.</para>
- <para>
- 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.
- </para>
- <para>
- Note that <command>nbd-server</command> will only try to
- find and open the exported file when a client actually
- connects; as a result, <command>nbd-server</command> must
- be able to open and read this file
- <emphasis>after</emphasis> changing to the user and group
- that have been specified by use of the
- <option>user</option> and <option>group</option> options;
- also, <command>nbd-server</command> will only detect
- errors in this option upon connection of a client.
- </para>
- <para>When specified on the command line, this should be the
- second argument.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>filesize</option></term>
- <listitem>
- <para>Optional; integer; default autodetected.</para>
- <para>
- Disable autodetection of file or block device size, and
- forcibly specify a size. Sizes must be specified in
- bytes. If the <option>multifile</option> option is in
- effect, this option specifies the size of the
- <emphasis>entire</emphasis> export, not of individual
- files.
- </para>
- <para>When specified on the command line, this should be the
- third argument.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>listenaddr</term>
- <listitem>
- <para>
- Optional; string
- </para>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>multifile</option></term>
- <listitem>
- <para>Optional; boolean.</para>
- <para>
- If this option is set to true, then
- <command>nbd-server</command> will search for files of the
- form
- <replaceable>exportname</replaceable>.<replaceable>integer</replaceable>,
- with <replaceable>exportname</replaceable> being the
- filename that would otherwise have been used (after name
- transformation for virtualization, if any, has been
- performed) and <replaceable>integer</replaceable> an
- integer number, starting with 0 and ending when no more
- files can be found.
- </para>
- <para>
- The size of the individual files will be autodetected,
- <emphasis>even</emphasis> if the <option>filesize</option>
- option has been specified.
- </para>
- <para>
- Corresponds to the <option>-m</option> option on the
- command line.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>port</option></term>
- <listitem>
- <para>Required if 'oldstyle' global parameter is set; integer.</para>
- <para>
- The port on which this export is to be served using the
- old-style handshake protocol.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- When specified on the command line, this should be the
- first argument.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>readonly</option></term>
- <listitem>
- <para>Optional; boolean.</para>
- <para>
- Disallow writes to the device. If this option is
- specified, <command>nbd-server</command> will issue an
- error to any client that tries to write to the device.
- </para>
- <para>
- Use of this option in conjunction with
- <option>copyonwrite</option> is possible, but silly.
- </para>
- <para>Corresponds to the <option>-r</option> option on the
- command line.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>sdp</option></term>
- <listitem>
- <para>Optional; boolean.</para>
- <para>
- When this option is enabled, <command>nbd-server</command>
- 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.
- </para>
- <para>
- Additionally, support for this option must be enabled at
- compile time, using the <option>--enable-sdp</option> option
- to the <command>configure</command> script. If this option
- is found in a configuration file and
- <command>nbd-server</command> does not have support for SDP,
- then <command>nbd-server</command> will exit with an error
- message.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>sync</option></term>
- <listitem>
- <para>Optional; boolean.</para>
- <para>When this option is enabled,
- <command>nbd-server</command> 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 <emphasis>not</emphasis> enabled, since it seriously
- reduces performance on ext3 filesystems while not
- importantly impacting reliability.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>sparse_cow</option></term>
- <listitem>
- <para>Optional; boolean.</para>
- <para>
- When this option is enabled, <command>nbd-server</command>
- will use sparse files to implement the copy-on-write
- option; such files take up less space then they appear to,
- which allows <command>nbd-server</command> to handle the
- file as if it was just as large as the block device it's
- for.
- </para>
- <para>
- If this option is disabled, <command>nbd-server</command>
- will map every newly written block to the end of the
- copy-on-write file, which means that
- <command>nbd-server</command> will have to lseek(2) to the
- right position after every 4096-byte block.
- </para>
- <para>
- Using this option may be faster when much is being written
- during a connection.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>timeout</option></term>
- <listitem>
- <para>Optional; integer; default 0</para>
- <para>
- How many seconds a connection may be idle for this
- export. When a connection is idle for a longer time,
- <command>nbd-server</command> will forcibly disconnect the
- connection. If you specify 0 (the default), then a
- connection may be idle forever.
- </para>
- <para>
- Corresponds to the <option>-a</option> option on the
- command line
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>virtstyle</option></term>
- <listitem>
- <para>Optional; string; default "ipliteral"</para>
- <para>
- 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 active, the
- <replaceable>exportname</replaceable> 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.
- </para>
- <para>
- There are four types of virtualization that
- <command>nbd-server</command> supports:
- </para>
- <variablelist>
- <varlistentry>
- <term><option>none</option></term>
- <listitem>
- <para>
- No virtualization. Will attempt to open the filename
- as it was written, even if it contains '%s' in the
- name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>ipliteral</option></term>
- <listitem>
- <para>
- 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.
- </para>
- <para>
- As an example, if a client connects from 192.168.1.100
- and <option>exportname</option> is specified as
- <filename>/export/%s</filename>, then nbd-server will
- attempt to serve
- <filename>/export/192.168.1.100</filename>. For IPv6,
- with a client connecting from 2001:6f8:32f::39, the
- filename would be
- <filename>/export/2001:6f8:32f:0:0:0:0:39</filename>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>iphash</option></term>
- <listitem>
- <para>
- Same as above, except that
- <command>nbd-server</command> will replace the dots
- in the IP address by forward slashes ('/'); in the
- same example, <command>nbd-server</command> would
- open <filename>/export/192/168/1/100</filename>
- instead.
- </para>
- <para>
- 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. It was
- thought that having to create an eight-deep directory
- structure would not be as useful.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>cidrhash</option></term>
- <listitem>
- <para>
- This option requires one to add a space and a number
- after it. <command>nbd-server</command> will use the
- number as a network mask in CIDR style, and use that
- as a hash cutoff point. In the above example, if
- <option>virtstyle</option> has been specified as
- <constant>cidrhash 16</constant>, then
- <command>nbd-server</command> will try to open
- <filename>/export/192.168.0.0/192.168.1.100</filename>;
- if <option>virtstyle</option> were specified as
- <constant>cidrhash 26</constant>, then
- <command>nbd-server</command> will try to open
- <filename>/export/192.168.1.64/192.168.1.100</filename>.
- </para>
- <para>For IPv6, in the above example, with
- <constant>cidrhash 42</constant>, the filename would
- be
- <filename>/export/2001:32f:6c0:0:0:0:0:0/2001:32f:6f8:0:0:0:0:39</filename>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>prerun</option></term>
- <listitem>
- <para>Optional; string</para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- If the command runs with a non-zero exit status,
- then nbd-server will assume the export will fail,
- and refuse to serve it.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>postrun</option></term>
- <listitem>
- <para>Optional; string</para>
- <para>
- 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 <option>prerun</option> has set up, to log
- something, or similar.
- </para>
- <para>
- If the literal string '%s' is present in the
- command, it will be replaced by the file name that
- has just been closed.
- </para>
- <para>
- In contrast to the <option>prerun</option> option,
- the exit state of <option>postrun</option> is
- <emphasis>ignored</emphasis>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </refsect1>
- <refsect1>
- <title>SEE ALSO</title>
-
- <para>nbd-server (1), nbd-client (8),
- http://nbd.sourceforge.net/roadmap.html</para>
-
- </refsect1>
- <refsect1>
- <title>AUTHOR</title>
- <para>The NBD kernel module and the NBD tools were originally
- written by Pavel Machek (pavel@ucw.cz)</para>
-
- <para>The Linux kernel module is now maintained by Paul Clements
- (Paul.Clements@steeleye.com), while the userland tools are
- maintained by &dhusername; (&dhemail;)</para>
-
- <para>On The Hurd there is a regular translator available to perform the
- client side of the protocol, and the use of
- <command>nbd-client</command> is not required. Please see the
- relevant documentation for more information.</para>
-
- <para>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 <acronym>GNU</acronym> General Public License,
- version 2, as published by the Free Software Foundation.</para>
-
- </refsect1>
- <refsect1>
- <title>EXAMPLES</title>
- <para>A simple <command>nbd-server</command> configuration file
- would look like this:</para>
- <programlisting>
- [generic]
- [export]
- exportname = /export/blkdev
- port = 12345
- </programlisting>
- <para>For increased security, one might want to create an
- authorization file, and set the UID and GID to run as:</para>
- <programlisting>
- [generic]
- user = nbd
- group = nbd
- [export]
- exportname = /export/blkdev
- port = 12345
- authfile = /etc/nbd-server/allow
- </programlisting>
- <para>With /etc/nbd-server/allow containing the following:</para>
- <programlisting>
- 127.0.0.1
- 192.168.0.0/8
- 192.168.1.1
- </programlisting>
- </refsect1>
-</refentry>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:2
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->