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>-connections <replaceable>num</replaceable></arg>
  62       <arg>-sdp</arg>
  63       <arg>-swap</arg>
  64       <arg>-persist</arg>
  65       <arg>-nofork</arg>
  66       <arg>-nonetlink</arg>
  67       <arg>-systemd-mark</arg>
  68       <arg>-block-size <replaceable>block size</replaceable></arg>
  69       <arg>-timeout <replaceable>seconds</replaceable></arg>
  70       <arg>-name <replaceable>name</replaceable></arg>
  71       <arg>-certfile <replaceable>certfile</replaceable></arg>
  72       <arg>-keyfile <replaceable>keyfile</replaceable></arg>
  73       <arg>-cacertfile <replaceable>cacertfile</replaceable></arg>
  74       <arg>-tlshostname <replaceable>hostname</replaceable></arg>
  75     </cmdsynopsis>
  76     <cmdsynopsis>
  77       <command>&dhpackage;</command>
  78       <arg choice=plain><option>-unix <replaceable>path</replaceable></option></arg>
  79       <arg choice=plain><replaceable>nbd-device</replaceable></arg>
  80       <arg>-connections <replaceable>num</replaceable></arg>
  81       <arg>-sdp</arg>
  82       <arg>-swap</arg>
  83       <arg>-persist</arg>
  84       <arg>-nofork</arg>
  85       <arg>-nonetlink</arg>
  86       <arg>-systemd-mark</arg>
  87       <arg>-block-size <replaceable>block size</replaceable></arg>
  88       <arg>-timeout <replaceable>seconds</replaceable></arg>
  89       <arg>-name <replaceable>name</replaceable></arg>
  90     </cmdsynopsis>
  91     <cmdsynopsis>
  92       <command>&dhpackage;</command>
  93       <arg choice=plain><replaceable>nbd-device</replaceable></arg>
  94     </cmdsynopsis>
  95     <cmdsynopsis>
  96       <command>&dhpackage;</command>
  97       <arg choice=plain><option>-d <replaceable>nbd-device</replaceable></option></arg>
  98     </cmdsynopsis>
  99     <cmdsynopsis>
 100       <command>&dhpackage;</command>
 101       <arg choice="plain"><option>-c <replaceable>nbd-device</replaceable></option></arg>
 102     </cmdsynopsis>
 103     <cmdsynopsis>
 104       <command>&dhpackage;</command>
 105       <arg choice="plain"><option>-l <replaceable>host</replaceable></option></arg>
 106       <arg>port</arg>
 107     </cmdsynopsis>
 108     <cmdsynopsis>
 109       <command>&dhpackage;</command>
 110       <arg>-netlink</arg>
 111       <arg choice="plain"><option>-l <replaceable>host</replaceable></option></arg>
 112     </cmdsynopsis>
 113   </refsynopsisdiv>
 114   <refsect1>
 115     <title>DESCRIPTION</title>
 116
 117     <para>With <command>&dhpackage;</command>, you can connect to a
 118     server running <command>nbd-server</command>, thus using raw
 119     diskspace from that server as a blockdevice on the local
 120     client.</para>
 121
 122     <para>To do this, support from the Linux Kernel is necessary, in
 123     the form of the Network Block Device (NBD). When you have that,
 124     either in the kernel, or as a module, you can connect to an NBD
 125     server and use its exported file through a block special file with
 126     major mode 43.</para>
 127
 128     <para>Optionally, long options can also be specified with two
 129       leading dashes.</para>
 130   </refsect1>
 131   <refsect1>
 132     <title>OPTIONS</title>
 133
 134     <para>The following options are supported:</para>
 135
 136     <variablelist>
 137       <varlistentry>
 138         <term><option>-block-size <replaceable>block size</replaceable></option></term>
 139         <term><option>-b</option></term>
 140         <listitem>
 141           <para>Use a blocksize of "block size". Default is 1024;
 142             allowed values are either 512, 1024, 2048 or 4096</para>
 143         </listitem>
 144       </varlistentry>
 145       <varlistentry>
 146         <term><option>-connections <replaceable>num</replaceable></option></term>
 147         <term><option>-C</option></term>
 148         <listitem>
 149           <para>Use <replaceable>num</replaceable> connections to the
 150           server, to allow speeding up request handling, at the cost of higher
 151           resource usage on the server. Use of this option requires kernel
 152           support available first with Linux 4.9.
 153         </listitem>
 154       </varlistentry>
 155       <varlistentry>
 156         <term><option>host</option></term>
 157         <listitem>
 158           <para>The hostname or IP address of the machine running
 159             <command>nbd-server</command>. Since 2.9.15, the NBD
 160             utilities support IPv6.</para>
 161         </listitem>
 162       </varlistentry>
 163       <varlistentry>
 164         <term><option>-timeout
 165         <replaceable>seconds</replaceable></option></term>
 166         <term><option>-t</option></term>
 167         <listitem>
 168           <para>Set the connection timeout to "seconds". For this to
 169           work, you need a kernel with support for the NBD_SET_TIMEOUT
 170           ioctl; this was introduced into Linus' tree on 2007-10-11,
 171           and will be part of kernel 2.6.24.</para>
 172         </listitem>
 173       </varlistentry>
 174       <varlistentry>
 175         <term><option>port</option></term>
 176         <listitem>
 177           <para>The TCP port on which <command>nbd-server</command> is
 178             running at the server.</para>
 179           <para>The port number defaults to 10809, the IANA-assigned
 180             port number for the NBD protocol.</para>
 181           <para>Previous versions of the nbd tools supported an older
 182             version of the negotiation protocol known as "oldstyle".
 183             This protocol version is no longer supported as of version
 184             3.11 of the nbd support tools.</para>
 185         </listitem>
 186       </varlistentry>
 187       <varlistentry>
 188         <term><option>nbd-device</option></term>
 189         <listitem>
 190           <para>The block special file (<filename>/dev</filename> entry) which this
 191           nbd-client should connect to, specified as a full path.</para>
 192           <para>When the mode is used wherein no hostname or export name is
 193           specified, &dhpackage; will look up the necessary configuration in
 194           the <filename>nbdtab</filename> file. For more information, see
 195           nbdtab(5).</para>
 196         </listitem>
 197       </varlistentry>
 198       <varlistentry>
 199         <term><option>-check</option></term>
 200         <term><option>-c</option></term>
 201         <listitem>
 202           <para>Check whether the specified nbd device is
 203           connected.</para>
 204           <para>If the device is connected, &dhpackage; will exit
 205           with an exit state of 0 and print the PID of the &dhpackage;
 206           instance that connected it to stdout.
 207           <para>If the device is not
 208           connected or does not exist (for example because the nbd
 209           module was not loaded), &dhpackage; will exit with an exit
 210           state of 1 and not print anything on stdout.</para>
 211           <para>If an error occurred, &dhpackage; will exit with an exit
 212           state of 2, and not print anything on stdout either.</para>
 213         </listitem>
 214       </varlistentry>
 215       <varlistentry>
 216         <term><option>-disconnect</option></term>
 217         <term><option>-d</option></term>
 218         <listitem>
 219           <para>Disconnect the specified nbd device from the
 220           server</para>
 221         </listitem>
 222       </varlistentry>
 223       <varlistentry>
 224         <term><option>-list</option></term>
 225         <term><option>-l</option></term>
 226         <listitem>
 227           <para>
 228             Ask the server for a list of available exports. If the
 229             server is exporting over IPv6 as well as over IPv4, this
 230             will list all exports twice; otherwise, it should list them
 231             all only once.</para>
 232           <para>Note that this option <emphasis>only</emphasis> works
 233             with nbd-server processes running version 3.1 or above, and
 234             must be enabled in server configuration (with the
 235             "allowlist" option) before it can be used.
 236           </para>
 237         </listitem>
 238       </varlistentry>
 239       <varlistentry>
 240         <term><option>-nonetlink</option></term>
 241         <term><option>-L</option></term>
 242         <listitem>
 243           <para>Starting with version 3.17, &dhpackage; will default to
 244           using the netlink interface to configure an NBD device. This
 245           option allows to use the older ioctl() interface to configure
 246           the device.
 247           </para>
 248           <para>This option is only available if &dhpackage; was
 249           compiled against libnl-genl. If that is not the case,
 250           nbd-client will only be able to use the ioctl interface (and
 251           the option will not be available).</para>
 252           <para>Note that a future version of &dhpackage; will
 253           <emphasis>require</emphasis> the use of netlink, but it has
 254           not yet been decided when that will be the case.</para>
 255         </listitem>
 256       </varlistentry
 257       <varlistentry>
 258         <term><option>-persist</option></term>
 259         <term><option>-p</option></term>
 260         <listitem>
 261           <para>When this option is specified, &dhpackage; will
 262             immediately try to reconnect an nbd device if the
 263             connection ever drops unexpectedly due to a lost
 264             server or something similar.</para>
 265         </listitem>
 266       </varlistentry>
 267       <varlistentry>
 268         <term><option>-sdp</option></term>
 269         <term><option>-S</option></term>
 270         <listitem>
 271           <para>Connect to the server using the Socket Direct Protocol
 272             (SDP), rather than IP. See nbd-server(5) for details.
 273           </para>
 274         </listitem>
 275       </varlistentry>
 276       <varlistentry>
 277         <term><option>-swap</option></term>
 278         <term><option>-s</option></term>
 279         <listitem>
 280           <para>Specifies that this NBD device will be used as
 281           swapspace. This option attempts to prevent deadlocks by
 282           performing mlockall() and adjusting the oom-killer score
 283           at an appropriate time. It does not however guarantee
 284           that such deadlocks can be avoided.</para>
 285         </listitem>
 286       </varlistentry>
 287       <varlistentry>
 288         <term><option>-systemd-mark</option></term>
 289         <term><option>-m</option></term>
 290         <listitem>
 291           <para>The systemd init system requires that processes which
 292             should not be killed at shutdown time be marked appropriately
 293             by replacing the first letter of their argv[0] with an '@'
 294             sign.</para>
 295           <para>This option will cause nbd-client to do so.</para>
 296           <para>Note that this only works if nbd-client is run from an
 297             initrd; i.e., systemd will ignore such a mark if run from a
 298             systemd unit file or from the command line.</para>
 299         </listitem>
 300       </varlistentry>
 301       <varlistentry>
 302         <term><option>-nofork</option></term>
 303         <term><option>-n</option></term>
 304         <listitem>
 305           <para>Specifies that the NBD client should not detach and
 306           daemonize itself. This is mostly useful for debugging.</para>
 307           <para>
 308             Note that nbd-client will still fork once to trigger an
 309             update to the device node's partition table. It is not
 310             possible to disable this.
 311           </para>
 312         </listitem>
 313       </varlistentry>
 314       <varlistentry>
 315         <term><option>-name</option></term>
 316         <term><option>-N</option></term>
 317         <listitem>
 318           <para>
 319             Specifies the name of the export that we want to use. If not
 320             specified, nbd-client will ask for a "default" export, if
 321             one exists on the server.
 322           </para>
 323         </listitem>
 324       </varlistentry>
 325       <varlistentry>
 326         <term><option>-netlink</option></term>
 327         <term><option>-L</option></term>
 328         <listitem>
 329           <para>
 330             Use the netlink interface to setup a new device.  If no device is
 331             specified then an empty one will be selected or a new one will be
 332             created if there are no existing empty devices available.  This
 333             option does not leave the client waiting for the device to exit.
 334           </para>
 335           <para>
 336             If this is used with disconnect then you must specify a device.
 337           </para>
 338         </listitem>
 339       </varlistentry>
 340       <varlistentry>
 341         <term><option>-unix</option></term>
 342         <term><option>-u</option></term>
 343         <listitem>
 344           <para>
 345             Connect to the server over a unix domain socket at
 346             <replaceable>path</replaceable>, rather than to a server
 347             over a TCP socket. The server must be listening on the given
 348             socket.
 349           </para>
 350         </listitem>
 351       </varlistentry>
 352     </variablelist>
 353     <refsect2>
 354       <title>TLS support</title>
 355       <para>Enabling any of the TLS-related options causes the client to
 356         use the NBD_OPT_STARTTLS command to upgrade the connection to
 357         TLS. Since negotiating TLS support from userspace for a kernel
 358         socket would be very involved (if passing keys to kernel space
 359         were even possible, which it isn't), the way this is implemented
 360         is that the nbd-client process creates a socketpair, one side of
 361         which it hands to the kernel, and the other side of which is
 362         handed to an encrypting/decrypting proxy. This has the effect
 363         that all communication will be encrypted before being sent over
 364         the wire; however, doing so is not safe in combination with
 365         swapping over an NBD device:</para>
 366       <para>
 367         In order to free memory by swapping, the kernel needs to be sure
 368         that the write to the nbd device has finalized. For this, it
 369         needs to be able to receive an NBD_CMD_WRITE reply which informs
 370         it that the write has completed successfully and that the memory
 371         may be released. Receiving data over the network, however,
 372         requires that the kernel <emphasis>allocate</emphasis> memory
 373         first, which is impossible if we're low on memory (a likely
 374         situation when trying to swap). This is likely to cause a
 375         deadlock when we're low on memory and there are high amounts of
 376         network traffic.</para>
 377       <para>To remedy this situation, the kernel sets the PF_MEMALLOC
 378         option on the nbd socket; when low on memory, it will throw away
 379         all packets except for those destined to a socket with that
 380         option set, relying on the normal TCP retransmit system to
 381         ensure that data is not lost. This avoids the deadlock described
 382         above.</para>
 383       <para>However, the PF_MEMALLOC option is set on the socket that is
 384         connected to the nbd device, not the encrypted socket connected
 385         to the encrypting/decrypting proxy. As such, when using TLS, the
 386         PF_MEMALLOC option is not set on the socket that actually
 387         receives data from the network, which means that the deadlock
 388         reappears.</para>
 389       <para>For this reason, if the <option>-swap</option> option is
 390         used when TLS is in use, &dhpackage; will issue an appropriate
 391         warning.</para>
 392       <variablelist>
 393         <varlistentry>
 394           <term><option>-certfile <replaceable>file</replaceable></option></term>
 395           <term><option>-F</option></term>
 396           <listitem>
 397             <para>
 398               Use the specified file as the client certificate for TLS
 399               authentication to the server.
 400             </para>
 401           </listitem>
 402         </varlistentry>
 403         <varlistentry>
 404           <term><option>-keyfile <replaceable>file</replaceable></option></term>
 405           <term><option>-K</option></term>
 406           <listitem>
 407             <para>
 408               Use the specified file as the private key for the client
 409               cerificate.
 410             </para>
 411           </listitem>
 412         </varlistentry>
 413         <varlistentry>
 414           <term><option>-cacertfile <replaceable>file</replaceable></option></term>
 415           <term><option>-A</option></term>
 416           <listitem>
 417             <para>
 418               Use the specified file as the CA certificate for TLS
 419               authentication to the server.
 420             </para>
 421           </listitem>
 422         </varlistentry>
 423         <varlistentry>
 424           <term><option>-tlshostname <replaceable>hostname</replaceable></option></term>
 425           <term><option>-H</option></term>
 426           <listitem>
 427             <para>
 428               Use the specified hostname for the TLS context. If not
 429               specified, the hostname used to connect to the server will
 430               be used.</para>
 431           </listitem>
 432         </varlistentry>
 433       </variablelist>
 434     </refsect2>
 435   </refsect1>
 436   <refsect1>
 437     <title>EXAMPLES</title>
 438
 439     <para>Some examples of nbd-client usage:</para>
 440     <itemizedlist mark="none">
 441       <listitem>
 442         <para>To connect to a server running on port 2000 at host
 443           "server.domain.com", using the client's block special file
 444           "/dev/nbd0":</para>
 445         <para><command>nbd-client server.domain.com 2000
 446           /dev/nbd0</command></para>
 447       </listitem>
 448       <listitem>
 449         <para>To connect to a server running on port 2001 at host
 450           "swapserver.domain.com", using the client's block special
 451           file "/dev/nbd1", for swap purposes:</para>
 452         <para><command>nbd-client swapserver.domain.com 2001 /dev/nbd1
 453           -swap</command></para>
 454       </listitem>
 455       <listitem>
 456         <para>To disconnect the above connection again (after making
 457           sure the block special file is not in use anymore):</para>
 458         <para><command>nbd-client -d /dev/nbd1</command></para>
 459       </listitem>
 460     </itemizedlist>
 461   </refsect1>
 462   <refsect1>
 463     <title>SEE ALSO</title>
 464
 465     <para>nbd-server (1).</para>
 466
 467   </refsect1>
 468   <refsect1>
 469     <title>AUTHOR</title>
 470     <para>The NBD kernel module and the NBD tools have been written by
 471     Pavel Macheck (pavel@ucw.cz).</para>
 472
 473     <para>The kernel module is now maintained by Paul Clements
 474     (Paul.Clements@steeleye.com), while the userland tools are maintained by
 475     Wouter Verhelst (wouter@debian.org)</para>
 476
 477     <para>This manual page was written by &dhusername; (&dhemail;) for
 478     the &debian; system (but may be used by others).  Permission is
 479     granted to copy, distribute and/or modify this document under the
 480     terms of the <acronym>GNU</acronym> General Public License,
 481     version 2, as published by the Free Software Foundation.</para>
 482
 483   </refsect1>
 484 </refentry>