]>
Commit | Line | Data |
---|---|---|
8a1f7d29 | 1 | =================== |
1982e160 SH |
2 | QEMU Storage Daemon |
3 | =================== | |
4 | ||
5 | Synopsis | |
6 | -------- | |
7 | ||
8 | **qemu-storage-daemon** [options] | |
9 | ||
10 | Description | |
11 | ----------- | |
12 | ||
c5ba6219 PMD |
13 | ``qemu-storage-daemon`` provides disk image functionality from QEMU, |
14 | ``qemu-img``, and ``qemu-nbd`` in a long-running process controlled via QMP | |
15 | commands without running a virtual machine. | |
16 | It can export disk images, run block job operations, and | |
1982e160 SH |
17 | perform other disk-related operations. The daemon is controlled via a QMP |
18 | monitor and initial configuration from the command-line. | |
19 | ||
20 | The daemon offers the following subset of QEMU features: | |
21 | ||
22 | * Block nodes | |
23 | * Block jobs | |
24 | * Block exports | |
25 | * Throttle groups | |
26 | * Character devices | |
27 | * Crypto and secrets | |
28 | * QMP | |
29 | * IOThreads | |
30 | ||
31 | Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the | |
32 | :manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the | |
33 | commands. | |
34 | ||
35 | The daemon runs until it is stopped using the ``quit`` QMP command or | |
36 | SIGINT/SIGHUP/SIGTERM. | |
37 | ||
38 | **Warning:** Never modify images in use by a running virtual machine or any | |
39 | other process; this may destroy the image. Also, be aware that querying an | |
40 | image that is being modified by another process may encounter inconsistent | |
41 | state. | |
42 | ||
43 | Options | |
44 | ------- | |
45 | ||
46 | .. program:: qemu-storage-daemon | |
47 | ||
48 | Standard options: | |
49 | ||
50 | .. option:: -h, --help | |
51 | ||
52 | Display help and exit | |
53 | ||
54 | .. option:: -V, --version | |
55 | ||
56 | Display version information and exit | |
57 | ||
58 | .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] | |
59 | ||
60 | .. include:: ../qemu-option-trace.rst.inc | |
61 | ||
62 | .. option:: --blockdev BLOCKDEVDEF | |
63 | ||
64 | is a block node definition. See the :manpage:`qemu(1)` manual page for a | |
65 | description of block node properties and the :manpage:`qemu-block-drivers(7)` | |
66 | manual page for a description of driver-specific parameters. | |
67 | ||
68 | .. option:: --chardev CHARDEVDEF | |
69 | ||
70 | is a character device definition. See the :manpage:`qemu(1)` manual page for | |
71 | a description of character device properties. A common character device | |
72 | definition configures a UNIX domain socket:: | |
73 | ||
e246bf3d | 74 | --chardev socket,id=char1,path=/var/run/qsd-qmp.sock,server=on,wait=off |
1982e160 SH |
75 | |
76 | .. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>] | |
77 | --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>] | |
78 | --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>] | |
cb90ec3a | 79 | --export [type=]fuse,id=<id>,node-name=<node-name>,mountpoint=<file>[,growable=on|off][,writable=on|off][,allow-other=on|off|auto] |
779d82e1 | 80 | --export [type=]vduse-blk,id=<id>,node-name=<node-name>,name=<vduse-name>[,writable=on|off][,num-queues=<num-queues>][,queue-size=<queue-size>][,logical-block-size=<block-size>][,serial=<serial-number>] |
1982e160 SH |
81 | |
82 | is a block export definition. ``node-name`` is the block node that should be | |
83 | exported. ``writable`` determines whether or not the export allows write | |
84 | requests for modifying data (the default is off). | |
85 | ||
86 | The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is | |
ef809f70 KW |
87 | the NBD export name (if not specified, it defaults to the given |
88 | ``node-name``). ``bitmap`` is the name of a dirty bitmap reachable from the | |
89 | block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the | |
1982e160 SH |
90 | metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap. |
91 | ||
92 | The ``vhost-user-blk`` export type takes a vhost-user socket address on which | |
93 | it accept incoming connections. Both | |
94 | ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and | |
95 | ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported. | |
96 | ``logical-block-size`` sets the logical block size in bytes (the default is | |
97 | 512). ``num-queues`` sets the number of virtqueues (the default is 1). | |
98 | ||
220222a0 HR |
99 | The ``fuse`` export type takes a mount point, which must be a regular file, |
100 | on which to export the given block node. That file will not be changed, it | |
101 | will just appear to have the block node's content while the export is active | |
102 | (very much like mounting a filesystem on a directory does not change what the | |
103 | directory contains, it only shows a different content while the filesystem is | |
104 | mounted). Consequently, applications that have opened the given file before | |
105 | the export became active will continue to see its original content. If | |
106 | ``growable`` is set, writes after the end of the exported file will grow the | |
cb90ec3a HR |
107 | block node to fit. The ``allow-other`` option controls whether users other |
108 | than the user running the process will be allowed to access the export. Note | |
109 | that enabling this option as a non-root user requires enabling the | |
110 | user_allow_other option in the global fuse.conf configuration file. Setting | |
111 | ``allow-other`` to auto (the default) will try enabling this option, and on | |
112 | error fall back to disabling it. | |
220222a0 | 113 | |
779d82e1 XY |
114 | The ``vduse-blk`` export type takes a ``name`` (must be unique across the host) |
115 | to create the VDUSE device. | |
ca941c40 SH |
116 | ``num-queues`` sets the number of virtqueues (the default is 1). |
117 | ``queue-size`` sets the virtqueue descriptor table size (the default is 256). | |
118 | ||
119 | The instantiated VDUSE device must then be added to the vDPA bus using the | |
120 | vdpa(8) command from the iproute2 project:: | |
121 | ||
122 | # vdpa dev add name <id> mgmtdev vduse | |
123 | ||
124 | The device can be removed from the vDPA bus later as follows:: | |
125 | ||
126 | # vdpa dev del <id> | |
127 | ||
128 | For more information about attaching vDPA devices to the host with | |
129 | virtio_vdpa.ko or attaching them to guests with vhost_vdpa.ko, see | |
130 | https://vdpa-dev.gitlab.io/. | |
131 | ||
132 | For more information about VDUSE, see | |
133 | https://docs.kernel.org/userspace-api/vduse.html. | |
134 | ||
1982e160 SH |
135 | .. option:: --monitor MONITORDEF |
136 | ||
137 | is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for | |
138 | a description of QMP monitor properties. A common QMP monitor definition | |
139 | configures a monitor on character device ``char1``:: | |
140 | ||
141 | --monitor chardev=char1 | |
142 | ||
143 | .. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>] | |
144 | --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>] | |
3f14b909 | 145 | --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>] |
1982e160 SH |
146 | |
147 | is a server for NBD exports. Both TCP and UNIX domain sockets are supported. | |
3f14b909 SH |
148 | A listen socket can be provided via file descriptor passing (see Examples |
149 | below). TLS encryption can be configured using ``--object`` tls-creds-* and | |
150 | authz-* secrets (see below). | |
1982e160 | 151 | |
e246bf3d SH |
152 | To configure an NBD server on UNIX domain socket path |
153 | ``/var/run/qsd-nbd.sock``:: | |
1982e160 | 154 | |
e246bf3d | 155 | --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock |
1982e160 SH |
156 | |
157 | .. option:: --object help | |
158 | --object <type>,help | |
159 | --object <type>[,<property>=<value>...] | |
160 | ||
161 | is a QEMU user creatable object definition. List object types with ``help``. | |
162 | List object properties with ``<type>,help``. See the :manpage:`qemu(1)` | |
163 | manual page for a description of the object properties. | |
164 | ||
03d2b412 SH |
165 | .. option:: --pidfile PATH |
166 | ||
167 | is the path to a file where the daemon writes its pid. This allows scripts to | |
168 | stop the daemon by sending a signal:: | |
169 | ||
170 | $ kill -SIGTERM $(<path/to/qsd.pid) | |
171 | ||
172 | A file lock is applied to the file so only one instance of the daemon can run | |
173 | with a given pid file path. The daemon unlinks its pid file when terminating. | |
174 | ||
175 | The pid file is written after chardevs, exports, and NBD servers have been | |
176 | created but before accepting connections. The daemon has started successfully | |
177 | when the pid file is written and clients may begin connecting. | |
178 | ||
2525edd8 HR |
179 | .. option:: --daemonize |
180 | ||
181 | Daemonize the process. The parent process will exit once startup is complete | |
182 | (i.e., after the pid file has been or would have been written) or failure | |
183 | occurs. Its exit code reflects whether the child has started up successfully | |
184 | or failed to do so. | |
185 | ||
1982e160 SH |
186 | Examples |
187 | -------- | |
188 | Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute | |
189 | QMP commands:: | |
190 | ||
191 | $ qemu-storage-daemon \ | |
c2387413 | 192 | --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \ |
1982e160 SH |
193 | --monitor chardev=char1 |
194 | ||
3f14b909 SH |
195 | Launch the daemon from Python with a QMP monitor socket using file descriptor |
196 | passing so there is no need to busy wait for the QMP monitor to become | |
197 | available:: | |
198 | ||
199 | #!/usr/bin/env python3 | |
200 | import subprocess | |
201 | import socket | |
202 | ||
203 | sock_path = '/var/run/qmp.sock' | |
204 | ||
205 | with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock: | |
206 | listen_sock.bind(sock_path) | |
207 | listen_sock.listen() | |
208 | ||
209 | fd = listen_sock.fileno() | |
210 | ||
211 | subprocess.Popen( | |
212 | ['qemu-storage-daemon', | |
213 | '--chardev', f'socket,fd={fd},server=on,id=char1', | |
214 | '--monitor', 'chardev=char1'], | |
215 | pass_fds=[fd], | |
216 | ) | |
217 | ||
218 | # listen_sock was automatically closed when leaving the 'with' statement | |
219 | # body. If the daemon process terminated early then the following connect() | |
220 | # will fail with "Connection refused" because no process has the listen | |
221 | # socket open anymore. Launch errors can be detected this way. | |
222 | ||
223 | qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) | |
224 | qmp_sock.connect(sock_path) | |
225 | ...QMP interaction... | |
226 | ||
227 | The same socket spawning approach also works with the ``--nbd-server | |
228 | addr.type=fd,addr.str=<fd>`` and ``--export | |
229 | type=vhost-user-blk,addr.type=fd,addr.str=<fd>`` options. | |
230 | ||
1982e160 SH |
231 | Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``:: |
232 | ||
233 | $ qemu-storage-daemon \ | |
234 | --blockdev driver=file,node-name=disk,filename=disk.img \ | |
235 | --nbd-server addr.type=unix,addr.path=nbd.sock \ | |
236 | --export type=nbd,id=export,node-name=disk,writable=on | |
237 | ||
9bd11f96 | 238 | Export a qcow2 image file ``disk.qcow2`` as a vhost-user-blk device over UNIX |
1982e160 SH |
239 | domain socket ``vhost-user-blk.sock``:: |
240 | ||
241 | $ qemu-storage-daemon \ | |
242 | --blockdev driver=file,node-name=file,filename=disk.qcow2 \ | |
243 | --blockdev driver=qcow2,node-name=qcow2,file=file \ | |
244 | --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2 | |
245 | ||
220222a0 HR |
246 | Export a qcow2 image file ``disk.qcow2`` via FUSE on itself, so the disk image |
247 | file will then appear as a raw image:: | |
248 | ||
249 | $ qemu-storage-daemon \ | |
250 | --blockdev driver=file,node-name=file,filename=disk.qcow2 \ | |
251 | --blockdev driver=qcow2,node-name=qcow2,file=file \ | |
252 | --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on | |
253 | ||
1982e160 SH |
254 | See also |
255 | -------- | |
256 | ||
257 | :manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)` |