man/nbd-client.8.in.sgml

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.5//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><replaceable>host</replaceable></arg>
  59       <arg><replaceable>port</replaceable></arg>
  60       <arg choice=plain><replaceable>nbd-device</replaceable></arg>
  61       <arg>-sdp</arg>
  62       <arg>-swap</arg>
  63       <arg>-persist</arg>
  64       <arg>-nofork</arg>
  65       <arg>-block-size <replaceable>block size</replaceable></arg>
  66       <arg>-timeout <replaceable>seconds</replaceable></arg>
  67       <arg>-name <replaceable>name</replaceable></arg>
  68     </cmdsynopsis>
  69     <cmdsynopsis>
  70       <command>&dhpackage;</command>
  71       <arg choice=plain><option>-d <replaceable>nbd-device</replaceable></option></arg>
  72     </cmdsynopsis>
  73     <cmdsynopsis>
  74       <command>&dhpackage;</command>
  75       <arg choice="plain"><option>-c <replaceable>nbd-device</replaceable></option></arg>
  76     </cmdsynopsis>
  77   </refsynopsisdiv>
  78   <refsect1>
  79     <title>DESCRIPTION</title>
  80
  81     <para>With <command>&dhpackage;</command>, you can connect to a
  82     server running <command>nbd-server</command>, thus using raw
  83     diskspace from that server as a blockdevice on the local
  84     client.</para>
  85
  86     <para>To do this, support from the Linux Kernel is necessary, in
  87     the form of the Network Block Device (NBD). When you have that,
  88     either in the kernel, or as a module, you can connect to an NBD
  89     server and use its exported file through a block special file with
  90     major mode 43.</para>
  91
  92     <para>Optionally, long options can also be specified with two
  93       leading dashes.</para>
  94   </refsect1>
  95   <refsect1>
  96     <title>OPTIONS</title>
  97
  98     <para>The following options are supported:</para>
  99
 100     <variablelist>
 101       <varlistentry>
 102         <term><option>-block-size <replaceable>block size</replaceable></option></term>
 103         <term><option>-b</option></term>
 104         <listitem>
 105           <para>Use a blocksize of "block size". Default is 1024;
 106             allowed values are either 512, 1024, 2048 or 4096</para>
 107         </listitem>
 108       </varlistentry>
 109       <varlistentry>
 110         <term><option>host</option></term>
 111         <listitem>
 112           <para>The hostname or IP address of the machine running
 113             <command>nbd-server</command>. Since 2.9.15, the NBD
 114             utilities support IPv6.</para>
 115         </listitem>
 116       </varlistentry>
 117       <varlistentry>
 118         <term><option>-timeout
 119         <replaceable>seconds</replaceable></option></term>
 120         <term><option>-t</option></term>
 121         <listitem>
 122           <para>Set the connection timeout to "seconds". For this to
 123           work, you need a kernel with support for the NBD_SET_TIMEOUT
 124           ioctl; this was introduced into Linus' tree on 2007-10-11,
 125           and will be part of kernel 2.6.24.</para>
 126         </listitem>
 127       </varlistentry>
 128       <varlistentry>
 129         <term><option>port</option></term>
 130         <listitem>
 131           <para>The TCP port on which <command>nbd-server</command> is
 132             running at the server.</para>
 133           <para>This option is required, unless the -N option is
 134             specified, in which case it is not allowed.</para>
 135         </listitem>
 136       </varlistentry>
 137       <varlistentry>
 138         <term><option>nbd-device</option></term>
 139         <listitem>
 140           <para>The block special file this nbd-client should connect
 141             to.</para>
 142         </listitem>
 143       </varlistentry>
 144       <varlistentry>
 145         <term><option>-check</option></term>
 146         <term><option>-c</option></term>
 147         <listitem>
 148           <para>Check whether the specified nbd device is
 149           connected.</para>
 150           <para>If the device is connected, &dhpackage; will exit
 151           with an exit state of 0 and print the PID of the &dhpackage;
 152           instance that connected it to stdout.
 153           <para>If the device is not
 154           connected or does not exist (for example because the nbd
 155           module was not loaded), &dhpackage; will exit with an exit
 156           state of 1 and not print anything on stdout.</para>
 157           <para>If an error occurred, &dhpackage; will exit with an exit
 158           state of 2, and not print anything on stdout either.</para>
 159         </listitem>
 160       </varlistentry>
 161       <varlistentry>
 162         <term><option>-disconnect</option></term>
 163         <term><option>-d</option></term>
 164         <listitem>
 165           <para>Disconnect the specified nbd device from the
 166           server</para>
 167         </listitem>
 168       </varlistentry>
 169       <varlistentry>
 170         <term><option>-persist</option></term>
 171         <term><option>-p</option></term>
 172         <listitem>
 173           <para>When this option is specified, &dhpackage; will
 174             immediately try to reconnect an nbd device if the
 175             connection ever drops unexpectedly due to a lost
 176             server or something similar.</para>
 177         </listitem>
 178       </varlistentry>
 179       <varlistentry>
 180         <term><option>-sdp</option></term>
 181         <term><option>-S</option></term>
 182         <listitem>
 183           <para>Connect to the server using the Socket Direct Protocol
 184             (SDP), rather than IP. See nbd-server(1) for details.
 185           </para>
 186         </listitem>
 187       </varlistentry>
 188       <varlistentry>
 189         <term><option>-swap</option></term>
 190         <term><option>-s</option></term>
 191         <listitem>
 192           <para>Specifies that this NBD device will be used as
 193           swapspace. This option attempts to prevent deadlocks by
 194           performing mlockall() at an appropriate time. It does not
 195           however guarantee that such deadlocks can be avoided.</para>
 196         </listitem>
 197       </varlistentry>
 198       <varlistentry>
 199         <term><option>-nofork</option></term>
 200         <term><option>-n</option></term>
 201         <listitem>
 202           <para>Specifies that the NBD client should not detach and
 203           daemonize itself. This is mostly useful for debugging.</para>
 204           <para>
 205             Note that nbd-client will still fork once to trigger an
 206             update to the device node's partition table. It is not
 207             possible to disable this.
 208           </para>
 209         </listitem>
 210       </varlistentry>
 211       <varlistentry>
 212         <term><option>-name</option></term>
 213         <term><option>-N</option></term>
 214         <listitem>
 215           <para>
 216             Specifies the name of the export that we want to use. Required if
 217             the port is not specified, not allowed in the other case.
 218           </para>
 219         </listitem>
 220       </varlistentry>
 221     </variablelist>
 222   </refsect1>
 223   <refsect1>
 224     <title>EXAMPLES</title>
 225
 226     <para>Some examples of nbd-client usage:</para>
 227     <itemizedlist mark="none">
 228       <listitem>
 229         <para>To connect to a server running on port 2000 at host
 230           "server.domain.com", using the client's block special file
 231           "/dev/nbd0":</para>
 232         <para><command>nbd-client server.domain.com 2000
 233           /dev/nbd0</command></para>
 234       </listitem>
 235       <listitem>
 236         <para>To connect to a server running on port 2001 at host
 237           "swapserver.domain.com", using the client's block special
 238           file "/dev/nbd1", for swap purposes:</para>
 239         <para><command>nbd-client swapserver.domain.com 2001 /dev/nbd1
 240           -swap</command></para>
 241       </listitem>
 242       <listitem>
 243         <para>To disconnect the above connection again (after making
 244           sure the block special file is not in use anymore):</para>
 245         <para><command>nbd-client -d /dev/nbd1</command></para>
 246       </listitem>
 247     </itemizedlist>
 248   </refsect1>
 249   <refsect1>
 250     <title>SEE ALSO</title>
 251
 252     <para>nbd-server (1).</para>
 253
 254   </refsect1>
 255   <refsect1>
 256     <title>AUTHOR</title>
 257     <para>The NBD kernel module and the NBD tools have been written by
 258     Pavel Macheck (pavel@ucw.cz).</para>
 259
 260     <para>The kernel module is now maintained by Paul Clements
 261     (Paul.Clements@steeleye.com), while the userland tools are maintained by
 262     Wouter Verhelst (wouter@debian.org)</para>
 263
 264     <para>This manual page was written by &dhusername; (&dhemail;) for
 265     the &debian; system (but may be used by others).  Permission is
 266     granted to copy, distribute and/or modify this document under the
 267     terms of the <acronym>GNU</acronym> General Public License,
 268     version 2, as published by the Free Software Foundation.</para>
 269
 270   </refsect1>
 271 </refentry>