1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN" [
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:
8 manpage.1: manpage.sgml
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">
25 <!ENTITY debian "<productname>Debian GNU/Linux</productname>">
26 <!ENTITY gnu "<acronym>GNU</acronym>">
40 <holder>&dhusername;</holder>
50 <refname>&dhpackage;</refname>
52 <refpurpose>connect to a server running nbd-server(1), to use its
53 exported block device</refpurpose>
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>
65 <arg>-block-size <replaceable>block size</replaceable></arg>
66 <arg>-timeout <replaceable>seconds</replaceable></arg>
67 <arg>-name <replaceable>name</replaceable></arg>
70 <command>&dhpackage;</command>
71 <arg choice=plain><option>-d <replaceable>nbd-device</replaceable></option></arg>
74 <command>&dhpackage;</command>
75 <arg choice="plain"><option>-c <replaceable>nbd-device</replaceable></option></arg>
79 <title>DESCRIPTION</title>
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
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
92 <para>Optionally, long options can also be specified with two
93 leading dashes.</para>
96 <title>OPTIONS</title>
98 <para>The following options are supported:</para>
102 <term><option>-block-size <replaceable>block size</replaceable></option></term>
103 <term><option>-b</option></term>
105 <para>Use a blocksize of "block size". Default is 1024;
106 allowed values are either 512, 1024, 2048 or 4096</para>
110 <term><option>host</option></term>
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>
118 <term><option>-timeout
119 <replaceable>seconds</replaceable></option></term>
120 <term><option>-t</option></term>
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>
129 <term><option>port</option></term>
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>
138 <term><option>nbd-device</option></term>
140 <para>The block special file this nbd-client should connect
145 <term><option>-check</option></term>
146 <term><option>-c</option></term>
148 <para>Check whether the specified nbd device is
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>
162 <term><option>-disconnect</option></term>
163 <term><option>-d</option></term>
165 <para>Disconnect the specified nbd device from the
170 <term><option>-persist</option></term>
171 <term><option>-p</option></term>
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>
180 <term><option>-sdp</option></term>
181 <term><option>-S</option></term>
183 <para>Connect to the server using the Socket Direct Protocol
184 (SDP), rather than IP. See nbd-server(1) for details.
189 <term><option>-swap</option></term>
190 <term><option>-s</option></term>
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>
199 <term><option>-nofork</option></term>
200 <term><option>-n</option></term>
202 <para>Specifies that the NBD client should not detach and
203 daemonize itself. This is mostly useful for debugging.</para>
207 <term><option>-name</option></term>
208 <term><option>-N</option></term>
211 Specifies the name of the export that we want to use. Required if
212 the port is not specified, not allowed in the other case.
219 <title>EXAMPLES</title>
221 <para>Some examples of nbd-client usage:</para>
222 <itemizedlist mark="none">
224 <para>To connect to a server running on port 2000 at host
225 "server.domain.com", using the client's block special file
227 <para><command>nbd-client server.domain.com 2000
228 /dev/nbd0</command></para>
231 <para>To connect to a server running on port 2001 at host
232 "swapserver.domain.com", using the client's block special
233 file "/dev/nb1", for swap purposes:</para>
234 <para><command>nbd-client swapserver.domain.com 2001 /dev/nb1
235 -swap</command></para>
238 <para>To disconnect the above connection again (after making
239 sure the block special file is not in use anymore):</para>
240 <para><command>nbd-client -d /dev/nb1</command></para>
245 <title>SEE ALSO</title>
247 <para>nbd-server (1).</para>
251 <title>AUTHOR</title>
252 <para>The NBD kernel module and the NBD tools have been written by
253 Pavel Macheck (pavel@ucw.cz).</para>
255 <para>The kernel module is now maintained by Paul Clements
256 (Paul.Clements@steeleye.com), while the userland tools are maintained by
257 Wouter Verhelst (wouter@debian.org)</para>
259 <para>This manual page was written by &dhusername; (&dhemail;) for
260 the &debian; system (but may be used by others). Permission is
261 granted to copy, distribute and/or modify this document under the
262 terms of the <acronym>GNU</acronym> General Public License,
263 version 2, as published by the Free Software Foundation.</para>
268 <!-- Keep this comment at the end of the file
273 sgml-minimize-attributes:nil
274 sgml-always-quote-attributes:t
277 sgml-parent-document:nil
278 sgml-default-dtd-file:nil
279 sgml-exposed-tags:nil
280 sgml-local-catalogs:nil
281 sgml-local-ecat-files:nil