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>-unix</option></term>
 362         <term><option>-u</option></term>
 363         <listitem>
 364           <para>
 365             Connect to the server over a unix domain socket at
 366             <replaceable>path</replaceable>, rather than to a server
 367             over a TCP socket. The server must be listening on the given
 368             socket.
 369           </para>
 370         </listitem>
 371       </varlistentry>
 372         <varlistentry>
 373           <term><option>-certfile <replaceable>file</replaceable></option></term>
 374           <term><option>-F</option></term>
 375           <listitem>
 376             <para>
 377               Use the specified file as the client certificate for TLS
 378               authentication to the server.
 379             </para>
 380           </listitem>
 381         </varlistentry>
 382         <varlistentry>
 383           <term><option>-keyfile <replaceable>file</replaceable></option></term>
 384           <term><option>-K</option></term>
 385           <listitem>
 386             <para>
 387               Use the specified file as the private key for the client
 388               cerificate.
 389             </para>
 390           </listitem>
 391         </varlistentry>
 392         <varlistentry>
 393           <term><option>-cacertfile <replaceable>file</replaceable></option></term>
 394           <term><option>-A</option></term>
 395           <listitem>
 396             <para>
 397               Use the specified file as the CA certificate for TLS
 398               authentication to the server.
 399             </para>
 400           </listitem>
 401         </varlistentry>
 402         <varlistentry>
 403           <term><option>-tlshostname <replaceable>hostname</replaceable></option></term>
 404           <term><option>-H</option></term>
 405           <listitem>
 406             <para>
 407               Use the specified hostname for the TLS context. If not
 408               specified, the hostname used to connect to the server will
 409               be used.</para>
 410           </listitem>
 411         </varlistentry>
 412       </variablelist>
 413     <refsect2>
 414       <title>TLS support</title>
 415       <para>Enabling any of the TLS-related options causes the client to
 416         use the NBD_OPT_STARTTLS command to upgrade the connection to
 417         TLS. Since negotiating TLS support from userspace for a kernel
 418         socket would be very involved (if passing keys to kernel space
 419         were even possible, which it isn't), the way this is implemented
 420         is that the nbd-client process creates a socketpair, one side of
 421         which it hands to the kernel, and the other side of which is
 422         handed to an encrypting/decrypting proxy. This has the effect
 423         that all communication will be encrypted before being sent over
 424         the wire; however, doing so is not safe in combination with
 425         swapping over an NBD device:</para>
 426       <para>
 427         In order to free memory by swapping, the kernel needs to be sure
 428         that the write to the nbd device has finalized. For this, it
 429         needs to be able to receive an NBD_CMD_WRITE reply which informs
 430         it that the write has completed successfully and that the memory
 431         may be released. Receiving data over the network, however,
 432         requires that the kernel <emphasis>allocate</emphasis> memory
 433         first, which is impossible if we're low on memory (a likely
 434         situation when trying to swap). This is likely to cause a
 435         deadlock when we're low on memory and there are high amounts of
 436         network traffic.</para>
 437       <para>To remedy this situation, the kernel sets the PF_MEMALLOC
 438         option on the nbd socket; when low on memory, it will throw away
 439         all packets except for those destined to a socket with that
 440         option set, relying on the normal TCP retransmit system to
 441         ensure that data is not lost. This avoids the deadlock described
 442         above.</para>
 443       <para>However, the PF_MEMALLOC option is set on the socket that is
 444         connected to the nbd device, not the encrypted socket connected
 445         to the encrypting/decrypting proxy. As such, when using TLS, the
 446         PF_MEMALLOC option is not set on the socket that actually
 447         receives data from the network, which means that the deadlock
 448         reappears.</para>
 449       <para>For this reason, if the <option>-swap</option> option is
 450         used when TLS is in use, &dhpackage; will issue an appropriate
 451         warning.</para>
 452     </refsect2>
 453   </refsect1>
 454   <refsect1>
 455     <title>EXAMPLES</title>
 456
 457     <para>Some examples of nbd-client usage:</para>
 458     <itemizedlist mark="none">
 459       <listitem>
 460         <para>To connect to a server running on port 2000 at host
 461           "server.domain.com", using the client's block special file
 462           "/dev/nbd0":</para>
 463         <para><command>nbd-client server.domain.com 2000
 464           /dev/nbd0</command></para>
 465       </listitem>
 466       <listitem>
 467         <para>To connect to a server running on port 2001 at host
 468           "swapserver.domain.com", using the client's block special
 469           file "/dev/nbd1", for swap purposes:</para>
 470         <para><command>nbd-client swapserver.domain.com 2001 /dev/nbd1
 471           -swap</command></para>
 472       </listitem>
 473       <listitem>
 474         <para>To disconnect the above connection again (after making
 475           sure the block special file is not in use anymore):</para>
 476         <para><command>nbd-client -d /dev/nbd1</command></para>
 477       </listitem>
 478     </itemizedlist>
 479   </refsect1>
 480   <refsect1>
 481     <title>SEE ALSO</title>
 482
 483     <para>nbd-server (1).</para>
 484
 485   </refsect1>
 486   <refsect1>
 487     <title>AUTHOR</title>
 488     <para>The NBD kernel module and the NBD tools have been written by
 489     Pavel Macheck (pavel@ucw.cz).</para>
 490
 491     <para>The kernel module is now maintained by Paul Clements
 492     (Paul.Clements@steeleye.com), while the userland tools are maintained by
 493     Wouter Verhelst (wouter@debian.org)</para>
 494
 495     <para>This manual page was written by &dhusername; (&dhemail;) for
 496     the &debian; system (but may be used by others).  Permission is
 497     granted to copy, distribute and/or modify this document under the
 498     terms of the <acronym>GNU</acronym> General Public License,
 499     version 2, as published by the Free Software Foundation.</para>
 500
 501   </refsect1>
 502 </refentry>