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

FreeBSD Manual Pages

  
 
  

home | help
QEMU-NBD(8)			     QEMU			   QEMU-NBD(8)

NAME
       qemu-nbd	- QEMU Disk Network Block Device Server

SYNOPSIS
       qemu-nbd	[OPTION]... filename

       qemu-nbd	-L [OPTION]...

       qemu-nbd	-d dev

DESCRIPTION
       Export a	QEMU disk image	using the NBD protocol.

       Other uses:

       o Bind a	/dev/nbdX block	device to a QEMU server	(on Linux).

       o As a client to	query exports of a remote NBD server.

OPTIONS
       filename	 is a disk image filename, or a	set of block driver options if
       --image-opts is specified.

       dev is an NBD device.

       --object	type,id=ID,...props...
	      Define a new instance of the type	object class identified	by ID.
	      See  the	qemu(1)	manual page for	full details of	the properties
	      supported. The common object types that it makes sense to	define
	      are  the secret object, which is used to supply passwords	and/or
	      encryption keys, and the tls-creds object, which is used to sup-
	      ply TLS credentials for the qemu-nbd server or client.

       -p, --port=PORT
	      TCP  port	 to  listen  on	as a server, or	connect	to as a	client
	      (default 10809).

       -o, --offset=OFFSET
	      The offset into the image.

       -b, --bind=IFACE
	      The interface to bind to as a server, or connect to as a	client
	      (default 0.0.0.0).

       -k, --socket=PATH
	      Use a unix socket	with path PATH.

       --image-opts
	      Treat  filename  as  a  set of image options, instead of a plain
	      filename.	If this	flag is	specified, the -f flag should  not  be
	      used, instead the	format=	option should be set.

       -f, --format=FMT
	      Force  the  use  of  the	block driver for format	FMT instead of
	      auto-detecting.

       -r, --read-only
	      Export the disk as read-only.

       -B, --bitmap=NAME
	      If filename has a	qcow2 persistent bitmap	NAME, expose that bit-
	      map  via	the  qemu:dirty-bitmap:NAME context accessible through
	      NBD_OPT_SET_META_CONTEXT.

       -s, --snapshot
	      Use filename as an external snapshot, create  a  temporary  file
	      with  backing_file=filename, redirect the	write to the temporary
	      one.

       -l, --load-snapshot=SNAPSHOT_PARAM
	      Load an internal snapshot	inside filename	and export  it	as  an
	      read-only	    device,    SNAPSHOT_PARAM	 format	   is	 snap-
	      shot.id=[ID],snapshot.name=[NAME]	or [ID_OR_NAME]

       --cache=CACHE
	      The cache	mode to	be used	with the file.	See the	 documentation
	      of the emulator's	-drive cache=... option	for allowed values.

       -n, --nocache
	      Equivalent to --cache=none.

       --aio=AIO
	      Set the asynchronous I/O mode between threads (the default), na-
	      tive (Linux only), and io_uring (Linux 5.1+).

       --discard=DISCARD
	      Control whether discard (also known as trim or  unmap)  requests
	      are  ignored  or passed to the filesystem. DISCARD is one	of ig-
	      nore (or off), unmap (or on).  The default is ignore.

       --detect-zeroes=DETECT_ZEROES
	      Control the automatic conversion of plain	zero writes by the  OS
	      to driver-specific optimized zero	write commands.	 DETECT_ZEROES
	      is one of	off, on, or unmap.  unmap converts a zero write	to  an
	      unmap operation and can only be used if DISCARD is set to	unmap.
	      The default is off.

       -c, --connect=DEV
	      Connect filename to NBD device DEV (Linux	only).

       -d, --disconnect
	      Disconnect the device DEV	(Linux only).

       -e, --shared=NUM
	      Allow up to NUM clients to share the device  (default  1).  Safe
	      for  readers, but	for now, consistency is	not guaranteed between
	      multiple writers.

       -t, --persistent
	      Don't exit on the	last connection.

       -x, --export-name=NAME
	      Set the  NBD  volume  export  name  (default  of	a  zero-length
	      string).

       -D, --description=DESCRIPTION
	      Set  the	NBD  volume  export  description,  as a	human-readable
	      string.

       -L, --list
	      Connect as a client and list all details about the  exports  ex-
	      posed  by	 a  remote NBD server.	This enables list mode,	and is
	      incompatible with	options	that change behavior related to	a spe-
	      cific export (such as --export-name, --offset, ...).

       --tls-creds=ID
	      Enable mandatory TLS encryption for the server by	setting	the ID
	      of the TLS credentials object previously created with the	 --ob-
	      ject option; or provide the credentials needed for connecting as
	      a	client in list mode.

       --fork Fork off the server process and exit the parent once the	server
	      is running.

       --pid-file=PATH
	      Store the	server's process ID in the given file.

       --tls-authz=ID
	      Specify  the  ID	of a qauthz object previously created with the
	      --object option. This will be used to authorize connecting users
	      against their x509 distinguished name.

       -v, --verbose
	      Display extra debugging information.

       -h, --help
	      Display this help	and exit.

       -V, --version
	      Display version information and exit.

       -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
	      Specify tracing options.

	      [enable=]PATTERN
		     Immediately  enable events	matching PATTERN (either event
		     name or a globbing	pattern).  This	option is only	avail-
		     able  if  QEMU  has been compiled with the	simple,	log or
		     ftrace tracing backend.  To specify  multiple  events  or
		     patterns, specify the -trace option multiple times.

		     Use -trace	help to	print a	list of	names of trace points.

	      events=FILE
		     Immediately  enable events	listed in FILE.	 The file must
		     contain one event name (as	listed in the trace-events-all
		     file) per line; globbing patterns are accepted too.  This
		     option is only available if QEMU has been	compiled  with
		     the simple, log or	ftrace tracing backend.

	      file=FILE
		     Log output	traces to FILE.	 This option is	only available
		     if	QEMU has been compiled with the	simple	tracing	 back-
		     end.

EXAMPLES
       Start a server listening	on port	10809 that exposes only	the guest-vis-
       ible contents of	a qcow2	file, with no TLS encryption, and with the de-
       fault  export name (an empty string). The command is one-shot, and will
       block until the first successful	client disconnects:

	  qemu-nbd -f qcow2 file.qcow2

       Start a long-running server listening with encryption  on  port	10810,
       and whitelist clients with a specific X.509 certificate to connect to a
       1 megabyte subset of a raw file,	using the export name 'subset':

	  qemu-nbd \
	    --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
	    --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\
		      O=Example	Org,,L=London,,ST=London,,C=GB'	\
	    --tls-creds	tls0 --tls-authz auth0 \
	    -t -x subset -p 10810 \
	    --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw

       Serve a read-only copy of a guest image over a Unix socket with as many
       as  5  simultaneous readers, with a persistent process forked as	a dae-
       mon:

	  qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
	    --read-only	--format=qcow2 file.qcow2

       Expose the guest-visible	contents of a qcow2 file via  a	 block	device
       /dev/nbd0 (and possibly creating	/dev/nbd0p1 and	friends	for partitions
       found within), then disconnect the device when done.   Access  to  bind
       qemu-nbd	 to an /dev/nbd	device generally requires root privileges, and
       may also	require	the execution of modprobe nbd to enable	the kernel NBD
       client  module.	 CAUTION:  Do not use this method to mount filesystems
       from an untrusted guest image - a malicious guest may have prepared the
       image  to  attempt  to trigger kernel bugs in partition probing or file
       system mounting.

	  qemu-nbd -c /dev/nbd0	-f qcow2 file.qcow2
	  qemu-nbd -d /dev/nbd0

       Query a remote server to	see details about what export(s) it is serving
       on port 10809, and authenticating via PSK:

	  qemu-nbd \
	    --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
	    --tls-creds	tls0 -L	-b remote.example.com

SEE ALSO
       qemu(1),	qemu-img(1)

AUTHOR
       Anthony Liguori <anthony@codemonkey.ws>

COPYRIGHT
       2020, The QEMU Project Developers

5.0.0				 Aug 31, 2020			   QEMU-NBD(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=qemu-nbd&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help