Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

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

       nbd-client host [ port ]	nbd-device [ -sdp ] [ -swap ] [	-persist  ]  [
       -nofork	] [ -block-size	block size ] [ -timeout	seconds	] [ -name name

       nbd-client -d nbd-device

       nbd-client -c nbd-device

       nbd-client -l host [ port ]

       With nbd-client,	you can	connect	to a server running  nbd-server,  thus
       using  raw  diskspace  from  that  server as a blockdevice on the local

       To do this, support from	the Linux Kernel is necessary, in the form  of
       the  Network Block Device (NBD).	When you have that, either in the ker-
       nel, or as a module, you	can connect to an NBD server and use  its  ex-
       ported file through a block special file	with major mode	43.

       Optionally, long	options	can also be specified with two leading dashes.

       The following options are supported:

       -block-size block size

       -b     Use a blocksize of "block	size". Default is 1024;	allowed	values
	      are either 512, 1024, 2048 or 4096

       host   The hostname or IP address of the	 machine  running  nbd-server.
	      Since 2.9.15, the	NBD utilities support IPv6.

       -timeout	seconds

       -t     Set  the	connection timeout to "seconds". For this to work, you
	      need a kernel with support for the NBD_SET_TIMEOUT  ioctl;  this
	      was  introduced into Linus' tree on 2007-10-11, and will be part
	      of kernel	2.6.24.

       port   The TCP port on which nbd-server is running at the server.

	      For the deprecated oldstyle protocol, passing a port  number  is
	      required.	 In  the oldstyle protocol, exports are	defined	by the
	      port on which they are running.

	      For the newstyle protocol, the port number  defaults  to	10809,
	      the  IANA-assigned  port	number for the NBD protocol.  The new-
	      style protocol is	selected automatically by nbd-client when  one
	      of the -list or -name options are	used.

	      The block	special	file this nbd-client should connect to.


       -c     Check whether the	specified nbd device is	connected.

	      If  the  device  is connected, nbd-client	will exit with an exit
	      state of 0 and print the PID of  the  nbd-client	instance  that
	      connected	it to stdout.

	      If  the  device  is not connected	or does	not exist (for example
	      because the nbd module was not  loaded),	nbd-client  will  exit
	      with an exit state of 1 and not print anything on	stdout.

	      If an error occurred, nbd-client will exit with an exit state of
	      2, and not print anything	on stdout either.


       -d     Disconnect the specified nbd device from the server


       -l     Ask the server for a list	of available exports. If the server is
	      exporting	over IPv6 as well as over IPv4,	this will list all ex-
	      ports twice; otherwise, it should	list them all only once.

	      Note that	this option only works with nbd-server processes  run-
	      ning version 3.1 or above, and must be enabled in	server config-
	      uration (with the	"allowlist" option) before it can be used.


       -p     When this	option is specified, nbd-client	will  immediately  try
	      to  reconnect  an	 nbd device if the connection ever drops unex-
	      pectedly due to a	lost server or something similar.


       -S     Connect to the server using the Socket  Direct  Protocol	(SDP),
	      rather than IP. See nbd-server(5)	for details.


       -s     Specifies	 that  this NBD	device will be used as swapspace. This
	      option attempts to prevent deadlocks  by	performing  mlockall()
	      and  adjusting  the  oom-killer score at an appropriate time. It
	      does not however guarantee that such deadlocks can be avoided.


       -n     Specifies	that the NBD client should not	detach	and  daemonize
	      itself. This is mostly useful for	debugging.

	      Note  that  nbd-client will still	fork once to trigger an	update
	      to the device node's partition table. It is not possible to dis-
	      able this.


       -N     Specifies	 the name of the export	that we	want to	use.  Required
	      if the port is not specified; changes the	default	port for  new-
	      style negotiation	from 10809 in the other	case.

	      When this	option is specified, nbd-client	uses the newstyle ver-
	      sion of the negotiation protocol.	 This  version	is  much  more
	      flexible	than  the oldstyle negotiation,	and should be used for
	      new configurations.

       Some examples of	nbd-client usage:

       o To connect to a server	running	 on  port  2000	 at  host  "", using the client's block special file "/dev/nbd0":

	 nbd-client 2000 /dev/nbd0

       o To  connect  to a server running on port 2001 at host "", using the client's block  special  file  "/dev/nbd1",  for
	 swap purposes:

	 nbd-client 2001 /dev/nbd1 -swap

       o To disconnect the above connection again (after making	sure the block
	 special file is not in	use anymore):

	 nbd-client -d /dev/nbd1

       nbd-server (1).

       The NBD kernel module and the NBD tools	have  been  written  by	 Pavel
       Macheck (

       The    kernel	module	  is   now   maintained	  by   Paul   Clements
       (, while the userland	tools  are  maintained
       by Wouter Verhelst (

       This  manual  page was written by Wouter	Verhelst (<>)
       for the Debian GNU/Linux	system (but may	be used	by  others).   Permis-
       sion  is	 granted to copy, distribute and/or modify this	document under
       the terms of the	GNU General Public License, version 2, as published by
       the Free	Software Foundation.

				       $			 NBD-CLIENT(8)


Want to link to this manual page? Use this URL:

home | help