nbd-client.8.sgml

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2
   3 <!-- Process this file with docbook-to-man to generate an nroff manual
   4      page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
   5      the manual page with: `docbook-to-man manpage.sgml | nroff -man |
   6      less'.  A typical entry in a Makefile or Makefile.am is:
   7
   8 manpage.1: manpage.sgml
   9         docbook-to-man $< > $@
  10   -->
  11
  12   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  13   <!ENTITY dhfirstname "<firstname>Wouter</firstname>">
  14   <!ENTITY dhsurname   "<surname>Verhelst</surname>">
  15   <!-- Please adjust the date whenever revising the manpage. -->
  16   <!ENTITY dhdate      "<date>$Date$</date>">
  17   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
  18        allowed: see man(7), man(1). -->
  19   <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
  20   <!ENTITY dhemail     "<email>wouter@debian.org</email>">
  21   <!ENTITY dhusername  "Wouter Verhelst">
  22   <!ENTITY dhucpackage "<refentrytitle>NBD-CLIENT</refentrytitle>">
  23   <!ENTITY dhpackage   "nbd-client">
  24
  25   <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  26   <!ENTITY gnu         "<acronym>GNU</acronym>">
  27 ]>
  28
  29 <refentry>
  30   <refentryinfo>
  31     <address>
  32       &dhemail;
  33     </address>
  34     <author>
  35       &dhfirstname;
  36       &dhsurname;
  37     </author>
  38     <copyright>
  39       <year>2001</year>
  40       <holder>&dhusername;</holder>
  41     </copyright>
  42     &dhdate;
  43   </refentryinfo>
  44   <refmeta>
  45     &dhucpackage;
  46
  47     &dhsection;
  48   </refmeta>
  49   <refnamediv>
  50     <refname>&dhpackage;</refname>
  51
  52     <refpurpose>connect to a server running nbd-server(1), to use its
  53     exported block device</refpurpose>
  54   </refnamediv>
  55   <refsynopsisdiv>
  56     <cmdsynopsis>
  57       <command>&dhpackage;</command>
  58       <arg choice=plain><option><replaceable>host</replaceable></option></arg>
  59       <arg choice=plain><option><replaceable>port</replaceable></option></arg>
  60       <arg choice=plain><option><replaceable>nbd-device</replaceable></option></arg>
  61       <arg><option>-sdp</option></arg>
  62       <arg><option>-swap</option></arg>
  63       <arg><option>-persist</option></arg>
  64       <arg><option>-nofork</option></arg>
  65       <arg><option>-block-size <replaceable>block size</replaceable></option></arg>
  66       <arg><option>-timeout <replaceable>seconds</replaceable></option></arg>
  67     </cmdsynopsis>
  68     <cmdsynopsis>
  69       <command>&dhpackage;</command>
  70       <arg choice=plain><option>-d <replaceable>nbd-device</replaceable></option></arg>
  71     </cmdsynopsis>
  72     <cmdsynopsis>
  73       <command>&dhpackage;</command>
  74       <arg choice="plain"><option>-c <replaceable>nbd-device</replaceable></option></arg>
  75     </cmdsynopsis>
  76   </refsynopsisdiv>
  77   <refsect1>
  78     <title>DESCRIPTION</title>
  79
  80     <para>With <command>&dhpackage;</command>, you can connect to a
  81     server running <command>nbd-server</command>, thus using raw
  82     diskspace from that server as a blockdevice on the local
  83     client.</para>
  84
  85     <para>To do this, support from the Linux Kernel is necessary, in
  86     the form of the Network Block Device (NBD). When you have that,
  87     either in the kernel, or as a module, you can connect to an NBD
  88     server and use its exported file through a block special file with
  89     major mode 43.</para>
  90
  91     <para>Optionally, long options can also be specified with two
  92       leading dashes.</para>
  93   </refsect1>
  94   <refsect1>
  95     <title>OPTIONS</title>
  96
  97     <para>The following options are supported:</para>
  98
  99     <variablelist>
 100       <varlistentry>
 101         <term><option>-block-size <replaceable>block size</replaceable></option></term>
 102         <listitem>
 103           <para>Use a blocksize of "block size". Default is 1024;
 104             allowed values are either 512, 1024, 2048 or 4096</para>
 105         </listitem>
 106       </varlistentry>
 107       <varlistentry>
 108         <term><option>host</option></term>
 109         <listitem>
 110           <para>The hostname or IP address of the machine running
 111             <command>nbd-server</command>. Since 2.9.15, the NBD
 112             utilities support IPv6.</para>
 113         </listitem>
 114       </varlistentry>
 115       <varlistentry>
 116         <term><option>-timeout <replaceable>seconds</replaceable></option></term>
 117         <listitem>
 118           <para>Set the connection timeout to "seconds". For this to
 119           work, you need a kernel with support for the NBD_SET_TIMEOUT
 120           ioctl; this was introduced into Linus' tree on 2007-10-11,
 121           and will be part of kernel 2.6.24.</para>
 122         </listitem>
 123       </varlistentry>
 124       <varlistentry>
 125         <term><option>port</option></term>
 126         <listitem>
 127           <para>The TCP port on which <command>nbd-server</command> is
 128             running at the server.</para>
 129         </listitem>
 130       </varlistentry>
 131       <varlistentry>
 132         <term><option>nbd-device</option></term>
 133         <listitem>
 134           <para>The block special file this nbd-client should connect
 135             to.</para>
 136         </listitem>
 137       </varlistentry>
 138       <varlistentry>
 139         <term>-c</term>
 140         <listitem>
 141           <para>Check whether the specified nbd device is
 142           connected.</para>
 143           <para>If the device is connected, &dhpackage; will exit
 144           with an exit state of 0 and print the PID of the &dhpackage;
 145           instance that connected it to stdout.
 146           <para>If the device is not
 147           connected or does not exist (for example because the nbd
 148           module was not loaded), &dhpackage; will exit with an exit
 149           state of 1 and not print anything on stdout.</para>
 150           <para>If an error occurred, &dhpackage; will exit with an exit
 151           state of 2, and not print anything on stdout either.</para>
 152         </listitem>
 153       </varlistentry>
 154       <varlistentry>
 155         <term>-d</term>
 156         <listitem>
 157           <para>Disconnect the specified nbd device from the
 158           server</para>
 159         </listitem>
 160       </varlistentry>
 161       <varlistentry>
 162         <term>-persist</term>
 163         <listitem>
 164           <para>When this option is specified, &dhpackage; will
 165             immediately try to reconnect an nbd device if the
 166             connection ever drops unexpectedly due to a lost
 167             server or something similar.</para>
 168         </listitem>
 169       </varlistentry>
 170       <varlistentry>
 171         <term><option>-sdp</option></term>
 172         <listitem>
 173           <para>Connect to the server using the Socket Direct Protocol
 174             (SDP), rather than IP. See nbd-server(1) for details.
 175           </para>
 176         </listitem>
 177       </varlistentry>
 178       <varlistentry>
 179         <term><option>-swap</option></term>
 180         <listitem>
 181           <para>Specifies that this NBD device will be used as
 182           swapspace. This option attempts to prevent deadlocks by
 183           performing mlockall() at an appropriate time. It does not
 184           however guarantee that such deadlocks can be avoided.</para>
 185         </listitem>
 186       </varlistentry>
 187       <varlistentry>
 188         <term><option>-nofork</option></term>
 189         <listitem>
 190           <para>Specifies that the NBD client should not detach and
 191           daemonize itself. This is mostly useful for debugging.</para>
 192       </varlistentry>
 193     </variablelist>
 194   </refsect1>
 195   <refsect1>
 196     <title>EXAMPLES</title>
 197
 198     <para>Some examples of nbd-client usage:</para>
 199     <itemizedlist mark="none">
 200       <listitem>
 201         <para>To connect to a server running on port 2000 at host
 202           "server.domain.com", using the client's block special file
 203           "/dev/nbd0":</para>
 204         <para><command>nbd-client server.domain.com 2000
 205           /dev/nbd0</command></para>
 206       </listitem>
 207       <listitem>
 208         <para>To connect to a server running on port 2001 at host
 209           "swapserver.domain.com", using the client's block special
 210           file "/dev/nb1", for swap purposes:</para>
 211         <para><command>nbd-client swapserver.domain.com 2001 /dev/nb1
 212           -swap</command></para>
 213       </listitem>
 214       <listitem>
 215         <para>To disconnect the above connection again (after making
 216           sure the block special file is not in use anymore):</para>
 217         <para><command>nbd-client -d /dev/nb1</command></para>
 218       </listitem>
 219     </itemizedlist>
 220   </refsect1>
 221   <refsect1>
 222     <title>SEE ALSO</title>
 223
 224     <para>nbd-server (1).</para>
 225
 226   </refsect1>
 227   <refsect1>
 228     <title>AUTHOR</title>
 229     <para>The NBD kernel module and the NBD tools have been written by
 230     Pavel Macheck (pavel@ucw.cz).</para>
 231
 232     <para>The kernel module is now maintained by Paul Clements
 233     (Paul.Clements@steeleye.com), while the userland tools are maintained by
 234     Wouter Verhelst (wouter@debian.org)</para>
 235
 236     <para>This manual page was written by &dhusername; (&dhemail;) for
 237     the &debian; system (but may be used by others).  Permission is
 238     granted to copy, distribute and/or modify this document under the
 239     terms of the <acronym>GNU</acronym> General Public License,
 240     version 2, as published by the Free Software Foundation.</para>
 241
 242   </refsect1>
 243 </refentry>
 244
 245 <!-- Keep this comment at the end of the file
 246 Local variables:
 247 mode: sgml
 248 sgml-omittag:t
 249 sgml-shorttag:t
 250 sgml-minimize-attributes:nil
 251 sgml-always-quote-attributes:t
 252 sgml-indent-step:2
 253 sgml-indent-data:t
 254 sgml-parent-document:nil
 255 sgml-default-dtd-file:nil
 256 sgml-exposed-tags:nil
 257 sgml-local-catalogs:nil
 258 sgml-local-ecat-files:nil
 259 End:
 260 -->