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><option>bs=<replaceable>blocksize</replaceable></option></arg>
  59       <arg><option>timeout=<replaceable>seconds</replaceable></option></arg>
  60       <arg choice=plain><option><replaceable>host</replaceable></option></arg>
  61       <arg choice=plain><option><replaceable>port</replaceable></option></arg>
  62       <arg choice=plain><option><replaceable>nbd-device</replaceable></option></arg>
  63       <arg><option>-sdp</option></arg>
  64       <arg><option>-swap</option></arg>
  65       <arg><option>-persist</option></arg>
  66       <arg><option>-nofork</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   </refsect1>
  92   <refsect1>
  93     <title>OPTIONS</title>
  94
  95     <para>The following options are supported:</para>
  96
  97     <variablelist>
  98       <varlistentry>
  99         <term><option>bs=<replaceable>blocksize</replaceable></option></term>
 100         <listitem>
 101           <para>Use a blocksize of "blocksize". Default is 1024;
 102             allowed values are either 512, 1024, 2048 or 4096</para>
 103         </listitem>
 104       </varlistentry>
 105       <varlistentry>
 106         <term><option>host</option></term>
 107         <listitem>
 108           <para>The hostname of the machine running
 109             <command>nbd-server</command>.</para>
 110         </listitem>
 111       </varlistentry>
 112       <varlistentry>
 113         <term><option>timeout=<replaceable>seconds</replaceable></option></term>
 114         <listitem>
 115           <para>Set the connection timeout to "seconds". For this to
 116           work, you need a kernel with support for the NBD_SET_TIMEOUT
 117           ioctl; this was introduced into Linus' tree on 2007-10-11,
 118           and will be part of kernel 2.6.24.</para>
 119         </listitem>
 120       </varlistentry>
 121       <varlistentry>
 122         <term><option>port</option></term>
 123         <listitem>
 124           <para>The TCP port on which <command>nbd-server</command> is
 125             running at the server.</para>
 126         </listitem>
 127       </varlistentry>
 128       <varlistentry>
 129         <term><option>nbd-device</option></term>
 130         <listitem>
 131           <para>The block special file this nbd-client should connect
 132             to.</para>
 133         </listitem>
 134       </varlistentry>
 135       <varlistentry>
 136         <term>-c</term>
 137         <listitem>
 138           <para>Check whether the specified nbd device is
 139           connected.</para>
 140           <para>If the device is connected, &dhpackage; will exit
 141           with an exit state of 0 and print the PID of the &dhpackage;
 142           instance that connected it to stdout.
 143           <para>If the device is not
 144           connected or does not exist (for example because the nbd
 145           module was not loaded), &dhpackage; will exit with an exit
 146           state of 1 and not print anything on stdout.</para>
 147           <para>If an error occurred, &dhpackage; will exit with an exit
 148           state of 2, and not print anything on stdout either.</para>
 149         </listitem>
 150       </varlistentry>
 151       <varlistentry>
 152         <term>-d</term>
 153         <listitem>
 154           <para>Disconnect the specified nbd device from the
 155           server</para>
 156         </listitem>
 157       </varlistentry>
 158       <varlistentry>
 159         <term>-persist</term>
 160         <listitem>
 161           <para>When this option is specified, &dhpackage; will
 162             immediately try to reconnect an nbd device if the
 163             connection ever drops unexpectedly due to a lost
 164             server or something similar.</para>
 165         </listitem>
 166       </varlistentry>
 167       <varlistentry>
 168         <term><option>-sdp</option></term>
 169         <listitem>
 170           <para>Connect to the server using the Socket Direct Protocol
 171             (SDP), rather than IP. See nbd-server(1) for details.
 172           </para>
 173         </listitem>
 174       </varlistentry>
 175       <varlistentry>
 176         <term><option>-swap</option></term>
 177         <listitem>
 178           <para>Specifies that this NBD device will be used as
 179             swapspace. If you intend to do that, please use this
 180             option to prevent deadlocks. You'll need a special kernel
 181             patch, available at NBD's homepage:
 182             http://atrey.karlin.mff.cuni.cz/~pavel</para>
 183         </listitem>
 184       </varlistentry>
 185       <varlistentry>
 186         <term><option>-nofork</option></term>
 187         <listitem>
 188           <para>Specifies that the NBD client should not detach and
 189           daemonize itself. This is mostly useful for debugging.</para>
 190       </varlistentry>
 191     </variablelist>
 192   </refsect1>
 193   <refsect1>
 194     <title>EXAMPLES</title>
 195
 196     <para>Some examples of nbd-client usage:</para>
 197     <itemizedlist mark="none">
 198       <listitem>
 199         <para>To connect to a server running on port 2000 at host
 200           "server.domain.com", using the client's block special file
 201           "/dev/nb0":</para>
 202         <para><command>nbd-client server.domain.com 2000
 203           /dev/nb0</command></para>
 204       </listitem>
 205       <listitem>
 206         <para>To connect to a server running on port 2001 at host
 207           "swapserver.domain.com", using the client's block special
 208           file "/dev/nb1", for swap purposes:</para>
 209         <para><command>nbd-client swapserver.domain.com 2001 /dev/nb1
 210           -swap</command></para>
 211       </listitem>
 212       <listitem>
 213         <para>To disconnect the above connection again (after making
 214           sure the block special file is not in use anymore):</para>
 215         <para><command>nbd-client -d /dev/nb1</command></para>
 216       </listitem>
 217     </itemizedlist>
 218   </refsect1>
 219   <refsect1>
 220     <title>SEE ALSO</title>
 221
 222     <para>nbd-server (1).</para>
 223
 224   </refsect1>
 225   <refsect1>
 226     <title>AUTHOR</title>
 227     <para>The NBD kernel module and the NBD tools have been written by
 228     Pavel Macheck (pavel@ucw.cz).</para>
 229
 230     <para>The kernel module is now maintained by Paul Clements
 231     (Paul.Clements@steeleye.com), while the userland tools are maintained by
 232     Wouter Verhelst (wouter@debian.org)</para>
 233
 234     <para>This manual page was written by &dhusername; (&dhemail;) for
 235     the &debian; system (but may be used by others).  Permission is
 236     granted to copy, distribute and/or modify this document under the
 237     terms of the <acronym>GNU</acronym> General Public License,
 238     version 2, as published by the Free Software Foundation.</para>
 239
 240   </refsect1>
 241 </refentry>
 242
 243 <!-- Keep this comment at the end of the file
 244 Local variables:
 245 mode: sgml
 246 sgml-omittag:t
 247 sgml-shorttag:t
 248 sgml-minimize-attributes:nil
 249 sgml-always-quote-attributes:t
 250 sgml-indent-step:2
 251 sgml-indent-data:t
 252 sgml-parent-document:nil
 253 sgml-default-dtd-file:nil
 254 sgml-exposed-tags:nil
 255 sgml-local-catalogs:nil
 256 sgml-local-ecat-files:nil
 257 End:
 258 -->