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>-no-optgo</option></term>
 316         <term><option>-g</option></term>
 317         <listitem>
 318           <para>Disable the use of the NBD_OPT_GO protocol message, and
 319           force the use of NBD_OPT_EXPORT_NAME instead.</para>
 320           <para>
 321             The NBD protocol has two phases: the negotiation phase, and
 322             the transmission phase. To move from negotation to
 323             transmission, older clients sent the NBD_OPT_EXPORT_NAME
 324             message, for which the server could not produce an error
 325             message in case the export name did not exist (or the client
 326             had insufficient permissions to access it). Due to those
 327             limitations, a replacement message NBD_OPT_GO was created
 328             instead, which allows the server to reply with an error in
 329             case of any problems.</para>
 330           <para>
 331             The protocol allows for a server to discard a message which
 332             it does not understand; however, unfortunately some
 333             implementations (including older versions of nbd-server) did
 334             not handle that situation correctly and would get out of
 335             sync with the client when it sent a message which the server
 336             did not understand.</para>
 337           <para>
 338             When sending NBD_OPT_GO, nbd-client will try to do the right
 339             thing and fall back to NBD_OPT_EXPORT_NAME. However, when
 340             the server has the above-described bug, then this does not
 341             work. In such a situation, the client will issue a
 342             diagnostic suggesting the use of this option.
 343           </para>
 344           <para>
 345             Note that there is a corresponding option for nbdtab, too.
 346           </para>
 347         </listitem>
 348       </varlistentry>
 349       <varlistentry>
 350         <term><option>-name</option></term>
 351         <term><option>-N</option></term>
 352         <listitem>
 353           <para>
 354             Specifies the name of the export that we want to use. If not
 355             specified, nbd-client will ask for a "default" export, if
 356             one exists on the server.
 357           </para>
 358         </listitem>
 359       </varlistentry>
 360       <varlistentry>
 361         <term><option>-netlink</option></term>
 362         <term><option>-L</option></term>
 363         <listitem>
 364           <para>
 365             Use the netlink interface to setup a new device.  If no device is
 366             specified then an empty one will be selected or a new one will be
 367             created if there are no existing empty devices available.  This
 368             option does not leave the client waiting for the device to exit.
 369           </para>
 370           <para>
 371             If this is used with disconnect then you must specify a device.
 372           </para>
 373         </listitem>
 374       </varlistentry>
 375       <varlistentry>
 376         <term><option>-unix</option></term>
 377         <term><option>-u</option></term>
 378         <listitem>
 379           <para>
 380             Connect to the server over a unix domain socket at
 381             <replaceable>path</replaceable>, rather than to a server
 382             over a TCP socket. The server must be listening on the given
 383             socket.
 384           </para>
 385         </listitem>
 386       </varlistentry>
 387     </variablelist>
 388     <refsect2>
 389       <title>TLS support</title>
 390       <para>Enabling any of the TLS-related options causes the client to
 391         use the NBD_OPT_STARTTLS command to upgrade the connection to
 392         TLS. Since negotiating TLS support from userspace for a kernel
 393         socket would be very involved (if passing keys to kernel space
 394         were even possible, which it isn't), the way this is implemented
 395         is that the nbd-client process creates a socketpair, one side of
 396         which it hands to the kernel, and the other side of which is
 397         handed to an encrypting/decrypting proxy. This has the effect
 398         that all communication will be encrypted before being sent over
 399         the wire; however, doing so is not safe in combination with
 400         swapping over an NBD device:</para>
 401       <para>
 402         In order to free memory by swapping, the kernel needs to be sure
 403         that the write to the nbd device has finalized. For this, it
 404         needs to be able to receive an NBD_CMD_WRITE reply which informs
 405         it that the write has completed successfully and that the memory
 406         may be released. Receiving data over the network, however,
 407         requires that the kernel <emphasis>allocate</emphasis> memory
 408         first, which is impossible if we're low on memory (a likely
 409         situation when trying to swap). This is likely to cause a
 410         deadlock when we're low on memory and there are high amounts of
 411         network traffic.</para>
 412       <para>To remedy this situation, the kernel sets the PF_MEMALLOC
 413         option on the nbd socket; when low on memory, it will throw away
 414         all packets except for those destined to a socket with that
 415         option set, relying on the normal TCP retransmit system to
 416         ensure that data is not lost. This avoids the deadlock described
 417         above.</para>
 418       <para>However, the PF_MEMALLOC option is set on the socket that is
 419         connected to the nbd device, not the encrypted socket connected
 420         to the encrypting/decrypting proxy. As such, when using TLS, the
 421         PF_MEMALLOC option is not set on the socket that actually
 422         receives data from the network, which means that the deadlock
 423         reappears.</para>
 424       <para>For this reason, if the <option>-swap</option> option is
 425         used when TLS is in use, &dhpackage; will issue an appropriate
 426         warning.</para>
 427       <variablelist>
 428         <varlistentry>
 429           <term><option>-certfile <replaceable>file</replaceable></option></term>
 430           <term><option>-F</option></term>
 431           <listitem>
 432             <para>
 433               Use the specified file as the client certificate for TLS
 434               authentication to the server.
 435             </para>
 436           </listitem>
 437         </varlistentry>
 438         <varlistentry>
 439           <term><option>-keyfile <replaceable>file</replaceable></option></term>
 440           <term><option>-K</option></term>
 441           <listitem>
 442             <para>
 443               Use the specified file as the private key for the client
 444               cerificate.
 445             </para>
 446           </listitem>
 447         </varlistentry>
 448         <varlistentry>
 449           <term><option>-cacertfile <replaceable>file</replaceable></option></term>
 450           <term><option>-A</option></term>
 451           <listitem>
 452             <para>
 453               Use the specified file as the CA certificate for TLS
 454               authentication to the server.
 455             </para>
 456           </listitem>
 457         </varlistentry>
 458         <varlistentry>
 459           <term><option>-tlshostname <replaceable>hostname</replaceable></option></term>
 460           <term><option>-H</option></term>
 461           <listitem>
 462             <para>
 463               Use the specified hostname for the TLS context. If not
 464               specified, the hostname used to connect to the server will
 465               be used.</para>
 466           </listitem>
 467         </varlistentry>
 468       </variablelist>
 469     </refsect2>
 470   </refsect1>
 471   <refsect1>
 472     <title>EXAMPLES</title>
 473
 474     <para>Some examples of nbd-client usage:</para>
 475     <itemizedlist mark="none">
 476       <listitem>
 477         <para>To connect to a server running on port 2000 at host
 478           "server.domain.com", using the client's block special file
 479           "/dev/nbd0":</para>
 480         <para><command>nbd-client server.domain.com 2000
 481           /dev/nbd0</command></para>
 482       </listitem>
 483       <listitem>
 484         <para>To connect to a server running on port 2001 at host
 485           "swapserver.domain.com", using the client's block special
 486           file "/dev/nbd1", for swap purposes:</para>
 487         <para><command>nbd-client swapserver.domain.com 2001 /dev/nbd1
 488           -swap</command></para>
 489       </listitem>
 490       <listitem>
 491         <para>To disconnect the above connection again (after making
 492           sure the block special file is not in use anymore):</para>
 493         <para><command>nbd-client -d /dev/nbd1</command></para>
 494       </listitem>
 495     </itemizedlist>
 496   </refsect1>
 497   <refsect1>
 498     <title>SEE ALSO</title>
 499
 500     <para>nbd-server (1).</para>
 501
 502   </refsect1>
 503   <refsect1>
 504     <title>AUTHOR</title>
 505     <para>The NBD kernel module and the NBD tools have been written by
 506     Pavel Macheck (pavel@ucw.cz).</para>
 507
 508     <para>The kernel module is now maintained by Paul Clements
 509     (Paul.Clements@steeleye.com), while the userland tools are maintained by
 510     Wouter Verhelst (wouter@debian.org)</para>
 511
 512     <para>This manual page was written by &dhusername; (&dhemail;) for
 513     the &debian; system (but may be used by others).  Permission is
 514     granted to copy, distribute and/or modify this document under the
 515     terms of the <acronym>GNU</acronym> General Public License,
 516     version 2, as published by the Free Software Foundation.</para>
 517
 518   </refsect1>
 519 </refentry>