3 @command{qemu-nbd} [OPTION]... @var{filename}
5 @command{qemu-nbd} @option{-d} @var{dev}
9 @c man begin DESCRIPTION
11 Export a QEMU disk image using the NBD protocol.
16 Bind a /dev/nbdX block device to a QEMU server (on Linux).
22 @var{filename} is a disk image filename, or a set of block
23 driver options if @option{--image-opts} is specified.
25 @var{dev} is an NBD device.
28 @item --object type,id=@var{id},...props...
29 Define a new instance of the @var{type} object class identified by @var{id}.
30 See the @code{qemu(1)} manual page for full details of the properties
31 supported. The common object types that it makes sense to define are the
32 @code{secret} object, which is used to supply passwords and/or encryption
33 keys, and the @code{tls-creds} object, which is used to supply TLS
34 credentials for the qemu-nbd server.
35 @item -p, --port=@var{port}
36 The TCP port to listen on (default @samp{10809}).
37 @item -o, --offset=@var{offset}
38 The offset into the image.
39 @item -b, --bind=@var{iface}
40 The interface to bind to (default @samp{0.0.0.0}).
41 @item -k, --socket=@var{path}
42 Use a unix socket with path @var{path}.
44 Treat @var{filename} as a set of image options, instead of a plain
45 filename. If this flag is specified, the @var{-f} flag should
46 not be used, instead the '@code{format=}' option should be set.
47 @item -f, --format=@var{fmt}
48 Force the use of the block driver for format @var{fmt} instead of
51 Export the disk as read-only.
52 @item -P, --partition=@var{num}
53 Only expose MBR partition @var{num}. Understands physical partitions
54 1-4 and logical partitions 5-8.
55 @item -B, --bitmap=@var{name}
56 If @var{filename} has a qcow2 persistent bitmap @var{name}, expose
57 that bitmap via the ``qemu:dirty-bitmap:@var{name}'' context
58 accessible through NBD_OPT_SET_META_CONTEXT.
60 Use @var{filename} as an external snapshot, create a temporary
61 file with backing_file=@var{filename}, redirect the write to
63 @item -l, --load-snapshot=@var{snapshot_param}
64 Load an internal snapshot inside @var{filename} and export it
65 as an read-only device, @var{snapshot_param} format is
66 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'
68 @itemx --cache=@var{cache}
69 The cache mode to be used with the file. See the documentation of
70 the emulator's @code{-drive cache=...} option for allowed values.
72 Set the asynchronous I/O mode between @samp{threads} (the default)
73 and @samp{native} (Linux only).
74 @item --discard=@var{discard}
75 Control whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})
76 requests are ignored or passed to the filesystem. @var{discard} is one of
77 @samp{ignore} (or @samp{off}), @samp{unmap} (or @samp{on}). The default is
79 @item --detect-zeroes=@var{detect-zeroes}
80 Control the automatic conversion of plain zero writes by the OS to
81 driver-specific optimized zero write commands. @var{detect-zeroes} is one of
82 @samp{off}, @samp{on} or @samp{unmap}. @samp{unmap}
83 converts a zero write to an unmap operation and can only be used if
84 @var{discard} is set to @samp{unmap}. The default is @samp{off}.
85 @item -c, --connect=@var{dev}
86 Connect @var{filename} to NBD device @var{dev} (Linux only).
87 @item -d, --disconnect
88 Disconnect the device @var{dev} (Linux only).
89 @item -e, --shared=@var{num}
90 Allow up to @var{num} clients to share the device (default
91 @samp{1}). Safe for readers, but for now, consistency is not
92 guaranteed between multiple writers.
93 @item -t, --persistent
94 Don't exit on the last connection.
95 @item -x, --export-name=@var{name}
96 Set the NBD volume export name (default of a zero-length string).
97 @item -D, --description=@var{description}
98 Set the NBD volume export description, as a human-readable
101 Enable mandatory TLS encryption for the server by setting the ID
102 of the TLS credentials object previously created with the --object
105 Fork off the server process and exit the parent once the server is running.
107 Display extra debugging information.
109 Display this help and exit.
111 Display version information and exit.
112 @item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
114 @include qemu-option-trace.texi
119 @c man begin EXAMPLES
120 Start a server listening on port 10809 that exposes only the
121 guest-visible contents of a qcow2 file, with no TLS encryption, and
122 with the default export name (an empty string). The command is
123 one-shot, and will block until the first successful client
127 qemu-nbd -f qcow2 file.qcow2
130 Start a long-running server listening with encryption on port 10810,
131 and require clients to have a correct X.509 certificate to connect to
132 a 1 megabyte subset of a raw file, using the export name 'subset':
136 --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
137 --tls-creds tls0 -t -x subset -p 10810 \
138 --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
141 Serve a read-only copy of just the first MBR partition of a guest
142 image over a Unix socket with as many as 5 simultaneous readers, with
143 a persistent process forked as a daemon:
146 qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
147 --partition=1 --read-only --format=qcow2 file.qcow2
150 Expose the guest-visible contents of a qcow2 file via a block device
151 /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
152 partitions found within), then disconnect the device when done.
153 Access to bind qemu-nbd to an /dev/nbd device generally requires root
154 privileges, and may also require the execution of @code{modprobe nbd}
155 to enable the kernel NBD client module. @emph{CAUTION}: Do not use
156 this method to mount filesystems from an untrusted guest image - a
157 malicious guest may have prepared the image to attempt to trigger
158 kernel bugs in partition probing or file system mounting.
161 qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
162 qemu-nbd -d /dev/nbd0
169 @setfilename qemu-nbd
170 @settitle QEMU Disk Network Block Device Server
173 Copyright (C) 2006 Anthony Liguori <anthony@codemonkey.ws>.
174 This is free software; see the source for copying conditions. There is NO
175 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.