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

FreeBSD Manual Pages


home | help

       nbd-server  - serve a file as a block device to other computers	  run-
       ning the	GNU/Linux(tm) or GNU/Hurd Operating    System

       nbd-server  [ip@]port filename [	size ] [ -r ] [	-m ] [ -c ] [ -l  host
       list filename ] [ -o section name ] [ -C	config file ] [	-M max connec-
       tions ] [ -V ] [	-d ]

       nbd-server is the server	for the	Linux Network Block Device (NBD). With
       NBD,  a client can use a	file, exported over the	network	from a server,
       as a block device. It can then be used for whatever  purpose  a	normal
       block device (harddisk, CD-ROM, ...) can	be used	for.

       NBD can be useful for diskless clients that need	swapspace, but you can
       also create a filesystem	on it and use it as though  it	were  a	 local

       nbd-server  implements  some  security  through a file called "/usr/lo-
       cal/etc/nbd-server/allow" (by default; a	different file can  be	chosen
       with the	'-l' option or through a config	file specification). This file
       must list the IP-addresses or network masks of clients that are allowed
       to  connect.  If	it does	not exist, all clients are able	to connect. If
       the file	is empty, no clients can connect.

       Note that while the command line	allows for specifying an  export,  the
       use of this option is deprecated. It is preferred to make use of	a con-
       figuration file instead,	 the  format  of  which	 is  defined  in  nbd-

       While  nbd-server  is  running,	new exports can	be added by re-writing
       configuration files and	then  sending  SIGHUP  to  nbd-server.	SIGHUP
       causes nbd-server to re-read its	configuration files and	to start serv-
       ing all new exports which were not served earlier. Reconfiguration does
       not modify any existing export, it only appends new ones.

       ip     The  ip address the server should	listen on. This	may be an IPv4
	      address, an IPv6 address,	or a hostname.	In  the	 latter	 case,
	      nbd-server will do a hostname lookup for the name	specified, and
	      will listen on the first address that is returned. For  compati-
	      bility  with  past versions of nbd-server, if an IPv4 address is
	      specified, the @ sign that serves	as separator between  the  ad-
	      dress and	port may be replaced by	a colon.

	      If  this	parameter  is not specified, nbd-server	will listen on
	      all local	addresses on both IPv4 and IPv6.  To  limit  to	 IPv4,
	      specify  the address as; to limit	to IPv6, specify it as

       port   The port the server should listen	to. A valid port is any	number
	      between  1  and  65536;  if 0 is used, nbd-server	will listen on
	      stdin (so	that nbd-server	can be ran from	inetd)

	      The filename of the file that should be exported.	 This  can  be
	      any file,	including "real" blockdevices (i.e. a file from	/dev).
	      If the filename includes the literal string "%s",	then  this  %s
	      will  be substituded with	the IP-address of the client trying to

       size   The size of the block device at the client side. This  is	 espe-
	      cially useful in conjunction with	the -m option

	      Can  optionally  be followed by one of K,k,M or m, in which case
	      the size will be multiplied by 1024 (K or	k) or 1048576 (M or m)

       -r     Export the file read-only. If a client tries to write to a read-
	      only exported file, it will receive an error, but	the connection
	      will stay	up.

       -m     Work with	multiple files.	This can be used  to  export  blockde-
	      vices  that  are	larger	than the maximum allowed filesize on a
	      given filesystem;	i.e. when the filesystem does not allow	 files
	      larger than 2GB (which is	true for Linux 2.2 and below), you can
	      use this option to store the data	in multiple files and export a
	      larger filesystem, if needed.

	      To use this option, you must create a number of files with names
	      in the format "name.X", where "name" is given  as	 the  filename
	      argument	to  nbd-server,	 and "X" is a number starting by 0 and
	      going up for each	file.

	      Allowing more flexibility	for this option	is planned for	future

       -c     Copy  on	write.	When this option is provided, write-operations
	      are not done to the exported file, but to	a separate file.  This
	      separate	file  is  removed when the connection is closed, which
	      means that serving this way will make nbd-server slow down  (es-
	      pecially	on  large block	devices	with lots of writes), and that
	      after disconnecting and reconnecting the client or  the  server,
	      all changes are lost.

       -C     Specify  configuration  file. The	default	configuration file, if
	      this  parameter  is  not	 specified,   is   /usr/local/etc/nbd-

	      Note  that  the  configuration file is always parsed and the en-
	      tries in the file	used, even if an extra server is specified  on
	      the  command  line.  To disable the configuration	file entirely,
	      either move it away or use the -C	option to point	 nbd-server(1)
	      to a non-existing	or empty configuration file.

	      Also note	that if	an empty, incomplete, or invalid configuration
	      file is specified, nbd-server will produce a warning about fail-
	      ure  to  parse  the  config file.	If the command line contains a
	      fully specified configuration, this warning is harmless and  may
	      be ignored.

       -M     Specify the maximum number of opened connections.	If this	param-
	      eter is not specified, no	limit is set.

       -V     Output the version of nbd-server,	and exit.

       -d     Do not fork. Useful for debugging.

       host list filename
	      This argument should contain a list of  IP-addresses  for	 hosts
	      that  may	 connect  to the server. Wildcards are not allowed. If
	      the file does not	exist, it is ignored (and any  host  can  con-
	      nect);  If  the  file does exist,	but is empty, no host can con-
	      nect. By default,	 the  name  'nbd_server.allow'	is  used,  and
	      looked  for  in the current directory, unless nbd-server is com-
	      piled as a daemon, in which case it is looked for	in  the	 root-

       section name
	      If the -o	argument is given on the command line, then nbd-server
	      will output a configuration file section with this as the	header
	      that  is	functionally equivalent	to the other options specified
	      on the command line, and exit.  This  is	useful	for  migrating
	      pre-2.9  nbd-server  initscript  configuration  files to the new

       Some examples of	nbd-server usage:

       o To export a file /export/nbd/exp-bl-dev on port 2000:

	 nbd-server 2000 /export/nbd/exp-bl-dev

       o To export a the same file read-only:

	 nbd-server 2000 /export/nbd/exp-bl-dev	-r

       o To export the same file read-write, but make sure  changes  are  lost
	 after restarting the client or	the server:

	 nbd-server 2000 /export/nbd/exp-bl-dev	-c

       nbd-client (8), nbd-server (5), nbd-trdump (8)

       The  NBD	 kernel	 module	 and  the NBD tools were originally written by
       Pavel Machek (

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

       On The Hurd there is a regular  translator  available  to  perform  the
       client side of the protocol, and	the use	of nbd-client is not required.
       Please see the relevant documentation for more information.

       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-SERVER(1)


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

home | help