nbd-client(8)

1NBD-CLIENT(8)                                                    NBD-CLIENT(8)
2
3
4

NAME

6       nbd-client  -  connect  to  a  server running nbd-server(1), to use its
7       exported block device
8

SYNOPSIS

10       nbd-client host [ port ] nbd-device [ -sdp ] [ -swap ] [ -persist  ]  [
11       -nofork  ] [ -block-size block size ] [ -timeout seconds ] [ -name name
12       ]
13
14
15       nbd-client -d nbd-device
16
17
18       nbd-client -c nbd-device
19
20

DESCRIPTION

22       With nbd-client, you can connect to a server running  nbd-server,  thus
23       using  raw  diskspace  from  that  server as a blockdevice on the local
24       client.
25
26       To do this, support from the Linux Kernel is necessary, in the form  of
27       the  Network Block Device (NBD). When you have that, either in the ker‐
28       nel, or as a module, you can connect to  an  NBD  server  and  use  its
29       exported file through a block special file with major mode 43.
30
31       Optionally, long options can also be specified with two leading dashes.
32

OPTIONS

34       The following options are supported:
35
36       -block-size block size
37
38       -b     Use a blocksize of "block size". Default is 1024; allowed values
39              are either 512, 1024, 2048 or 4096
40
41       host   The hostname or IP address of the  machine  running  nbd-server.
42              Since 2.9.15, the NBD utilities support IPv6.
43
44       -timeout seconds
45
46       -t     Set  the  connection timeout to "seconds". For this to work, you
47              need a kernel with support for the NBD_SET_TIMEOUT  ioctl;  this
48              was  introduced into Linus' tree on 2007-10-11, and will be part
49              of kernel 2.6.24.
50
51       port   The TCP port on which nbd-server is running at the server.
52
53              This option is required, unless the -N option is  specified,  in
54              which case it is not allowed.
55
56       nbd-device
57              The block special file this nbd-client should connect to.
58
59       -check
60
61       -c     Check whether the specified nbd device is connected.
62
63              If  the  device  is connected, nbd-client will exit with an exit
64              state of 0 and print the PID of  the  nbd-client  instance  that
65              connected it to stdout.
66
67              If  the  device  is not connected or does not exist (for example
68              because the nbd module was not  loaded),  nbd-client  will  exit
69              with an exit state of 1 and not print anything on stdout.
70
71              If an error occurred, nbd-client will exit with an exit state of
72              2, and not print anything on stdout either.
73
74       -disconnect
75
76       -d     Disconnect the specified nbd device from the server
77
78       -persist
79
80       -p     When this option is specified, nbd-client will  immediately  try
81              to  reconnect  an  nbd device if the connection ever drops unex‐
82              pectedly due to a lost server or something similar.
83
84       -sdp
85
86       -S     Connect to the server using the Socket  Direct  Protocol  (SDP),
87              rather than IP. See nbd-server(1) for details.
88
89       -swap
90
91       -s     Specifies  that  this NBD device will be used as swapspace. This
92              option attempts to prevent deadlocks by performing mlockall() at
93              an  appropriate  time.  It  does not however guarantee that such
94              deadlocks can be avoided.
95
96       -nofork
97
98       -n     Specifies that the NBD client should not  detach  and  daemonize
99              itself. This is mostly useful for debugging.
100
101              Note  that  nbd-client will still fork once to trigger an update
102              to the device node's partition table. It is not possible to dis‐
103              able this.
104
105       -name
106
107       -N     Specifies  the  name of the export that we want to use. Required
108              if the port is not specified, not allowed in the other case.
109

EXAMPLES

111       Some examples of nbd-client usage:
112
113       · To  connect  to   a   server   running   on   port   2000   at   host
114         "server.domain.com",   using   the   client's   block   special  file
115         "/dev/nbd0":
116
117         nbd-client server.domain.com 2000 /dev/nbd0
118
119       · To  connect  to   a   server   running   on   port   2001   at   host
120         "swapserver.domain.com",   using  the  client's  block  special  file
121         "/dev/nbd1", for swap purposes:
122
123         nbd-client swapserver.domain.com 2001 /dev/nbd1 -swap
124
125       · To disconnect the above connection again (after making sure the block
126         special file is not in use anymore):
127
128         nbd-client -d /dev/nbd1
129

AUTHOR

134       The  NBD  kernel  module  and  the NBD tools have been written by Pavel
135       Macheck (pavel@ucw.cz).
136
137       The   kernel   module   is   now   maintained    by    Paul    Clements
138       (Paul.Clements@steeleye.com),  while  the userland tools are maintained
139       by Wouter Verhelst (wouter@debian.org)
140
141       This manual page was written by Wouter  Verhelst  (<wouter@debian.org>)
142       for  the  Debian GNU/Linux system (but may be used by others).  Permis‐
143       sion is granted to copy, distribute and/or modify this  document  under
144       the terms of the GNU General Public License, version 2, as published by
145       the Free Software Foundation.
146
147
148
149                                27 January 2011                  NBD-CLIENT(8)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

SEE ALSO

AUTHOR