]>
Commit | Line | Data |
---|---|---|
87c0868f PM |
1 | QEMU Disk Network Block Device Server |
2 | ===================================== | |
3 | ||
4 | Synopsis | |
5 | -------- | |
6 | ||
7 | **qemu-nbd** [*OPTION*]... *filename* | |
8 | ||
9 | **qemu-nbd** -L [*OPTION*]... | |
10 | ||
11 | **qemu-nbd** -d *dev* | |
12 | ||
13 | Description | |
14 | ----------- | |
15 | ||
16 | Export a QEMU disk image using the NBD protocol. | |
17 | ||
18 | Other uses: | |
19 | ||
20 | - Bind a /dev/nbdX block device to a QEMU server (on Linux). | |
21 | - As a client to query exports of a remote NBD server. | |
22 | ||
23 | Options | |
24 | ------- | |
25 | ||
26 | .. program:: qemu-nbd | |
27 | ||
28 | *filename* is a disk image filename, or a set of block | |
29 | driver options if ``--image-opts`` is specified. | |
30 | ||
31 | *dev* is an NBD device. | |
32 | ||
33 | .. option:: --object type,id=ID,...props... | |
34 | ||
35 | Define a new instance of the *type* object class identified by *ID*. | |
36 | See the :manpage:`qemu(1)` manual page for full details of the properties | |
37 | supported. The common object types that it makes sense to define are the | |
38 | ``secret`` object, which is used to supply passwords and/or encryption | |
39 | keys, and the ``tls-creds`` object, which is used to supply TLS | |
40 | credentials for the qemu-nbd server or client. | |
41 | ||
42 | .. option:: -p, --port=PORT | |
43 | ||
44 | TCP port to listen on as a server, or connect to as a client | |
45 | (default ``10809``). | |
46 | ||
47 | .. option:: -o, --offset=OFFSET | |
48 | ||
49 | The offset into the image. | |
50 | ||
51 | .. option:: -b, --bind=IFACE | |
52 | ||
53 | The interface to bind to as a server, or connect to as a client | |
54 | (default ``0.0.0.0``). | |
55 | ||
56 | .. option:: -k, --socket=PATH | |
57 | ||
58 | Use a unix socket with path *PATH*. | |
59 | ||
60 | .. option:: --image-opts | |
61 | ||
62 | Treat *filename* as a set of image options, instead of a plain | |
63 | filename. If this flag is specified, the ``-f`` flag should | |
64 | not be used, instead the :option:`format=` option should be set. | |
65 | ||
66 | .. option:: -f, --format=FMT | |
67 | ||
68 | Force the use of the block driver for format *FMT* instead of | |
69 | auto-detecting. | |
70 | ||
71 | .. option:: -r, --read-only | |
72 | ||
73 | Export the disk as read-only. | |
74 | ||
dbc7b014 EB |
75 | .. option:: -A, --allocation-depth |
76 | ||
77 | Expose allocation depth information via the | |
78 | ``qemu:allocation-depth`` metadata context accessible through | |
79 | NBD_OPT_SET_META_CONTEXT. | |
80 | ||
87c0868f PM |
81 | .. option:: -B, --bitmap=NAME |
82 | ||
83 | If *filename* has a qcow2 persistent bitmap *NAME*, expose | |
dbc7b014 | 84 | that bitmap via the ``qemu:dirty-bitmap:NAME`` metadata context |
87c0868f PM |
85 | accessible through NBD_OPT_SET_META_CONTEXT. |
86 | ||
87 | .. option:: -s, --snapshot | |
88 | ||
89 | Use *filename* as an external snapshot, create a temporary | |
90 | file with ``backing_file=``\ *filename*, redirect the write to | |
91 | the temporary one. | |
92 | ||
93 | .. option:: -l, --load-snapshot=SNAPSHOT_PARAM | |
94 | ||
95 | Load an internal snapshot inside *filename* and export it | |
96 | as an read-only device, SNAPSHOT_PARAM format is | |
97 | ``snapshot.id=[ID],snapshot.name=[NAME]`` or ``[ID_OR_NAME]`` | |
98 | ||
99 | .. option:: --cache=CACHE | |
100 | ||
101 | The cache mode to be used with the file. See the documentation of | |
102 | the emulator's ``-drive cache=...`` option for allowed values. | |
103 | ||
104 | .. option:: -n, --nocache | |
105 | ||
106 | Equivalent to :option:`--cache=none`. | |
107 | ||
108 | .. option:: --aio=AIO | |
109 | ||
7680274d AM |
110 | Set the asynchronous I/O mode between ``threads`` (the default), |
111 | ``native`` (Linux only), and ``io_uring`` (Linux 5.1+). | |
87c0868f PM |
112 | |
113 | .. option:: --discard=DISCARD | |
114 | ||
115 | Control whether ``discard`` (also known as ``trim`` or ``unmap``) | |
116 | requests are ignored or passed to the filesystem. *DISCARD* is one of | |
117 | ``ignore`` (or ``off``), ``unmap`` (or ``on``). The default is | |
118 | ``ignore``. | |
119 | ||
120 | .. option:: --detect-zeroes=DETECT_ZEROES | |
121 | ||
122 | Control the automatic conversion of plain zero writes by the OS to | |
123 | driver-specific optimized zero write commands. *DETECT_ZEROES* is one of | |
124 | ``off``, ``on``, or ``unmap``. ``unmap`` | |
125 | converts a zero write to an unmap operation and can only be used if | |
126 | *DISCARD* is set to ``unmap``. The default is ``off``. | |
127 | ||
128 | .. option:: -c, --connect=DEV | |
129 | ||
130 | Connect *filename* to NBD device *DEV* (Linux only). | |
131 | ||
132 | .. option:: -d, --disconnect | |
133 | ||
134 | Disconnect the device *DEV* (Linux only). | |
135 | ||
136 | .. option:: -e, --shared=NUM | |
137 | ||
138 | Allow up to *NUM* clients to share the device (default | |
3dcf56e6 EB |
139 | ``1``), 0 for unlimited. Safe for readers, but for now, |
140 | consistency is not guaranteed between multiple writers. | |
87c0868f PM |
141 | |
142 | .. option:: -t, --persistent | |
143 | ||
144 | Don't exit on the last connection. | |
145 | ||
146 | .. option:: -x, --export-name=NAME | |
147 | ||
148 | Set the NBD volume export name (default of a zero-length string). | |
149 | ||
150 | .. option:: -D, --description=DESCRIPTION | |
151 | ||
152 | Set the NBD volume export description, as a human-readable | |
153 | string. | |
154 | ||
155 | .. option:: -L, --list | |
156 | ||
157 | Connect as a client and list all details about the exports exposed by | |
158 | a remote NBD server. This enables list mode, and is incompatible | |
159 | with options that change behavior related to a specific export (such as | |
160 | :option:`--export-name`, :option:`--offset`, ...). | |
161 | ||
162 | .. option:: --tls-creds=ID | |
163 | ||
164 | Enable mandatory TLS encryption for the server by setting the ID | |
165 | of the TLS credentials object previously created with the --object | |
166 | option; or provide the credentials needed for connecting as a client | |
167 | in list mode. | |
168 | ||
169 | .. option:: --fork | |
170 | ||
171 | Fork off the server process and exit the parent once the server is running. | |
172 | ||
173 | .. option:: --pid-file=PATH | |
174 | ||
175 | Store the server's process ID in the given file. | |
176 | ||
177 | .. option:: --tls-authz=ID | |
178 | ||
179 | Specify the ID of a qauthz object previously created with the | |
180 | :option:`--object` option. This will be used to authorize connecting users | |
181 | against their x509 distinguished name. | |
182 | ||
183 | .. option:: -v, --verbose | |
184 | ||
185 | Display extra debugging information. | |
186 | ||
187 | .. option:: -h, --help | |
188 | ||
189 | Display this help and exit. | |
190 | ||
191 | .. option:: -V, --version | |
192 | ||
193 | Display version information and exit. | |
194 | ||
195 | .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] | |
196 | ||
bb43ee6c | 197 | .. include:: ../qemu-option-trace.rst.inc |
87c0868f PM |
198 | |
199 | Examples | |
200 | -------- | |
201 | ||
202 | Start a server listening on port 10809 that exposes only the | |
203 | guest-visible contents of a qcow2 file, with no TLS encryption, and | |
204 | with the default export name (an empty string). The command is | |
205 | one-shot, and will block until the first successful client | |
206 | disconnects: | |
207 | ||
208 | :: | |
209 | ||
210 | qemu-nbd -f qcow2 file.qcow2 | |
211 | ||
212 | Start a long-running server listening with encryption on port 10810, | |
213 | and whitelist clients with a specific X.509 certificate to connect to | |
214 | a 1 megabyte subset of a raw file, using the export name 'subset': | |
215 | ||
216 | :: | |
217 | ||
218 | qemu-nbd \ | |
219 | --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \ | |
220 | --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\ | |
221 | O=Example Org,,L=London,,ST=London,,C=GB' \ | |
222 | --tls-creds tls0 --tls-authz auth0 \ | |
223 | -t -x subset -p 10810 \ | |
224 | --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw | |
225 | ||
0bc16997 EB |
226 | Serve a read-only copy of a guest image over a Unix socket with as |
227 | many as 5 simultaneous readers, with a persistent process forked as a | |
228 | daemon: | |
87c0868f PM |
229 | |
230 | :: | |
231 | ||
232 | qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ | |
0bc16997 | 233 | --read-only --format=qcow2 file.qcow2 |
87c0868f PM |
234 | |
235 | Expose the guest-visible contents of a qcow2 file via a block device | |
236 | /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for | |
237 | partitions found within), then disconnect the device when done. | |
238 | Access to bind qemu-nbd to an /dev/nbd device generally requires root | |
239 | privileges, and may also require the execution of ``modprobe nbd`` | |
240 | to enable the kernel NBD client module. *CAUTION*: Do not use | |
241 | this method to mount filesystems from an untrusted guest image - a | |
242 | malicious guest may have prepared the image to attempt to trigger | |
243 | kernel bugs in partition probing or file system mounting. | |
244 | ||
245 | :: | |
246 | ||
247 | qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2 | |
248 | qemu-nbd -d /dev/nbd0 | |
249 | ||
250 | Query a remote server to see details about what export(s) it is | |
251 | serving on port 10809, and authenticating via PSK: | |
252 | ||
253 | :: | |
254 | ||
255 | qemu-nbd \ | |
256 | --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \ | |
257 | --tls-creds tls0 -L -b remote.example.com | |
258 | ||
259 | See also | |
260 | -------- | |
261 | ||
262 | :manpage:`qemu(1)`, :manpage:`qemu-img(1)` |