--- /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>
projects / nbd.git / blobdiff