man/nbdtab.5.sgml.in

   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: 2006-10-18 15:01:57 +0200 (wo, 18 okt 2006) $</date>">
  17   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
  18        allowed: see man(7), man(1). -->
  19   <!ENTITY dhsection   "<manvolnum>5</manvolnum>">
  20   <!ENTITY dhemail     "<email>wouter@debian.org</email>">
  21   <!ENTITY dhusername  "Wouter Verhelst">
  22   <!ENTITY dhucpackage "<refentrytitle>nbdtab</refentrytitle>">
  23   <!ENTITY dhpackage   "@MAN_SYSCONFDIR@/nbdtab">
  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>2015</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>configuration file for nbd-client</refpurpose>
  53   </refnamediv>
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>&dhpackage; </command>
  57
  58     </cmdsynopsis>
  59   </refsynopsisdiv>
  60   <refsect1>
  61     <title>DESCRIPTION</title>
  62
  63     <para>This file allows to configure predefined connections for
  64       nbd-client. It may contain multiple definitions, one per line,
  65       each of which contains four space-separated fields.</para>
  66
  67     <para>To connect a device specified in the nbdtab file,
  68       run <command>nbd-client</command>(8) with the short name of that
  69       device as the sole argument. It will then look up the required
  70       information in <filename>nbdtab</filename>, and make the
  71       connection.</para>
  72
  73     <para>Fields are separated from one another by any number of space
  74       or tab characters; records are separated from one another by
  75       newline characters. The file may also contain any number of
  76       comments, which start with a '#' character and continue until the
  77       end of the line or the end of the file, whichever is first.</para>
  78     <refsect2>
  79       <title>Fields</title>
  80       <para>The file contains the following fields:</para>
  81       <orderedlist>
  82         <listitem>
  83           <para>The short name of the device file. That is, it should
  84           contain the name of the device without the leading
  85           <filename>/dev/</filename> part; e.g., it could say
  86           <filename>nbd0</filename>.</para>
  87         </listitem>
  88         <listitem>
  89           <para>The hostname (in case of a TCP socket) or filename (in
  90           case of a unix domain socket) on which the server is
  91           listening.</para>
  92         </listitem>
  93         <listitem>
  94           <para>The name of the export as exported by
  95           <command>nbd-server</command>.</para>
  96         </listitem>
  97         <listitem>
  98           <para>Any extra options. This field is optional (no pun
  99           intended), and need not appear in a file if no options are
 100           necessary. The options recognized by
 101           <command>nbd-client</command>(8) are specified below, in the
 102           section "Options". Any unknown options in
 103           this field will produce a warning by
 104           <command>nbd-client</command>, unless they are prepended by
 105           an underscore ('_') character; the underscore is
 106           specifically reserved for local use, or for distribution
 107           customization.</para>
 108         </listitem>
 109       </orderedlist>
 110     </refsect2>
 111     <refsect2>
 112       <title>Options</title>
 113       <para>Every command-line <command>nbd-client</command> option
 114         which allows to configure specific options for a particular
 115         device node has a corresponding option in the
 116         <filename>nbdtab</filename> file, and vice versa; where this
 117         isn't the case, that is a bug.</para>
 118       <para>Individual options in this field should be separated from
 119         one another by the comma character.</para>
 120       <variablelist>
 121         <varlistentry>
 122           <term><option>bs=<replaceable>block size</replaceable></option></term>
 123           <listitem>
 124             <para>The block size for this export. If this option is
 125             not used, the kernel's default will be used
 126             instead.</para>
 127             <para>Corresponds to the <option>-b</option> option on the
 128             command line.</para>
 129           </listitem>
 130         </varlistentry>
 131         <varlistentry>
 132           <term><option>cacertfile=<replaceable>certificate
 133           file</replaceable></option></term>
 134           <listitem>
 135             <para>The CA certificate file for TLS. Corresponds to the
 136             <option>-A</option> option on the command line.</para>
 137           </listitem>
 138         </varlistentry>
 139         <varlistentry>
 140           <term><option>certfile=<replaceable>certificate file</replaceable></option></term>
 141           <listitem>
 142             <para>The certificate file for TLS. Corresponds to the
 143             <option>-F</option> option on the command line.</para>
 144           </listitem>
 145         </varlistentry>
 146         <varlistentry>
 147           <term><option>conns=<replaceable>number</replaceable></option></term>
 148           <listitem>
 149             <para>The number of connections to use for this device.
 150             Corresponds to the <option>-C</option> option on the command
 151             line; see nbd-client(8) for more details on that
 152             option.</para>
 153           </listitem>
 154         </varlistentry>
 155         <varlistentry>
 156           <term><option>keyfile=<replaceable>key
 157           file</replaceable></option></term>
 158           <listitem>
 159             <para>The private key file for TLS. Corresponds to the
 160             <option>-K</option> option on the command line.</para>
 161           </listitem>
 162         </varlistentry>
 163         <varlistentry>
 164           <term><option>no_optgo</option></term>
 165           <listitem>
 166             <para>Disable the use of NBD_OPT_GO in the conversation.
 167             Corresponds to the <option>-g</option> option on the command
 168             line.</para>
 169           </listitem>
 170         </varlistentry>
 171         <varlistentry>
 172           <term><option>persist</option></term>
 173           <listitem>
 174             <para>Persist the connection, using the semantics of the
 175             <option>-p</option> command-line option.</para>
 176           </listitem>
 177         </varlistentry>
 178         <varlistentry>
 179           <term><option>port=<replaceable>port number</replaceable></option></term>
 180           <listitem>
 181             <para>The port on which to communicate with the
 182             <command>nbd-server</command>. Defaults to the
 183             IANA-assigned port for NBD, 10809.</para>
 184           </listitem>
 185         </varlistentry>
 186         <varlistentry>
 187           <term><option>priority=<replaceable>GnuTLS priority string</replaceable></option>
 188           <listitem>
 189             <para>The GnuTLS priority string to use.</para>
 190             <para>Corresponds to the <option>-y</option> option on the
 191             command line.</para>
 192           </listitem>
 193         </varlistentry>
 194         <varlistentry>
 195           <term><option>swap</option></term>
 196           <listitem>
 197             <para>Optimize for swap; <option>-s</option>.</para>
 198           </listitem>
 199         </varlistentry>
 200         <varlistentry>
 201           <term><option>timeout=<replaceable>timeout</replaceable></option></term>
 202           <listitem>
 203             <para>The timeout. If this option is not specified, no
 204             timeout is configured.</para>
 205             <para>Corresponds to the <option>-t</option> option on the
 206             command line.</para>
 207           </listitem>
 208         </varlistentry>
 209         <varlistentry>
 210           <term><option>tlshostname=<replaceable>TLS
 211           hostname</replaceable></option></term>
 212           <listitem>
 213             <para>The hostname for TLS purposes;
 214             <option>-H</option></para>
 215           </listitem>
 216         </varlistentry>
 217         <varlistentry>
 218           <term><option>unix</option></term>
 219           <listitem>
 220             <para>Use a Unix Domain socket to connect to the server;
 221             <option>-u</option>.</para>
 222           </listitem>
 223         </varlistentry>
 224       </variablelist>
 225     </refsect2>
 226   </refsect1>
 227   <refsect1>
 228     <title>SEE ALSO</title>
 229
 230     <para>nbd-server (1), nbd-client (8), nbd-trdump (8)</para>
 231
 232
 233   </refsect1>
 234   <refsect1>
 235     <title>AUTHOR</title>
 236     <para>The NBD kernel module and the NBD tools were originally
 237       written by Pavel Machek (pavel@ucw.cz)</para>
 238
 239     <para>The Linux kernel module is now maintained by Paul Clements
 240       (Paul.Clements@steeleye.com), while the userland tools are
 241       maintained by &dhusername; (&dhemail;)</para>
 242
 243     <para>On The Hurd there is a regular translator available to perform the
 244       client side of the protocol, and the use of
 245       <command>nbd-client</command> is not required. Please see the
 246       relevant documentation for more information.</para>
 247
 248     <para>This manual page was written by &dhusername; (&dhemail;).
 249       Permission is granted to copy, distribute and/or modify this
 250       document under the terms of the <acronym>GNU</acronym> General
 251       Public License, version 2, as published by the Free Software
 252       Foundation.</para>
 253
 254   </refsect1>
 255   <refsect1>
 256     <title>EXAMPLES</title>
 257     <para>A simple <filename>nbdtab</filename> file could look like
 258     this:</para>
 259     <programlisting>
 260 # swap space, called "swapexport" on the server
 261 # optimize for swap, and try to reconnect upon disconnect.
 262 nbd0 nbdserver.example.com swapexport swap,persist
 263 # other export, called "data" on the server. No options for this one.
 264 nbd1 nbdserver.example.com data
 265 </programlisting>
 266   </refsect1>
 267 </refentry>