1@node Deprecated features 2@appendix Deprecated features 3 4In general features are intended to be supported indefinitely once 5introduced into QEMU. In the event that a feature needs to be removed, 6it will be listed in this appendix. The feature will remain functional 7for 2 releases prior to actual removal. Deprecated features may also 8generate warnings on the console when QEMU starts up, or if activated 9via a monitor command, however, this is not a mandatory requirement. 10 11Prior to the 2.10.0 release there was no official policy on how 12long features would be deprecated prior to their removal, nor 13any documented list of which features were deprecated. Thus 14any features deprecated prior to 2.10.0 will be treated as if 15they were first deprecated in the 2.10.0 release. 16 17What follows is a list of all features currently marked as 18deprecated. 19 20@section System emulator command line arguments 21 22@subsection -machine enforce-config-section=on|off (since 3.1) 23 24The @option{enforce-config-section} parameter is replaced by the 25@option{-global migration.send-configuration=@var{on|off}} option. 26 27@subsection -no-kvm (since 1.3.0) 28 29The ``-no-kvm'' argument is now a synonym for setting 30``-machine accel=tcg''. 31 32@subsection -usbdevice (since 2.10.0) 33 34The ``-usbdevice DEV'' argument is now a synonym for setting 35the ``-device usb-DEV'' argument instead. The deprecated syntax 36would automatically enable USB support on the machine type. 37If using the new syntax, USB support must be explicitly 38enabled via the ``-machine usb=on'' argument. 39 40@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0) 41 42The 'file' driver for drives is no longer appropriate for character or host 43devices and will only accept regular files (S_IFREG). The correct driver 44for these file types is 'host_cdrom' or 'host_device' as appropriate. 45 46@subsection -net ...,name=@var{name} (since 3.1) 47 48The @option{name} parameter of the @option{-net} option is a synonym 49for the @option{id} parameter, which should now be used instead. 50 51@subsection -smp (invalid topologies) (since 3.1) 52 53CPU topology properties should describe whole machine topology including 54possible CPUs. 55 56However, historically it was possible to start QEMU with an incorrect topology 57where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}}, 58which could lead to an incorrect topology enumeration by the guest. 59Support for invalid topologies will be removed, the user must ensure 60topologies described with -smp include all possible cpus, i.e. 61 @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}. 62 63@subsection -vnc acl (since 4.0.0) 64 65The @code{acl} option to the @code{-vnc} argument has been replaced 66by the @code{tls-authz} and @code{sasl-authz} options. 67 68@subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0) 69 70The ``-audiodev'' argument is now the preferred way to specify audio 71backend settings instead of environment variables. To ease migration to 72the new format, the ``-audiodev-help'' option can be used to convert 73the current values of the environment variables to ``-audiodev'' options. 74 75@section QEMU Machine Protocol (QMP) commands 76 77@subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0) 78 79"autoload" parameter is now ignored. All bitmaps are automatically loaded 80from qcow2 images. 81 82@subsection query-block result field dirty-bitmaps[i].status (since 4.0) 83 84The ``status'' field of the ``BlockDirtyInfo'' structure, returned by 85the query-block command is deprecated. Two new boolean fields, 86``recording'' and ``busy'' effectively replace it. 87 88@subsection query-cpus (since 2.12.0) 89 90The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command. 91 92@subsection query-cpus-fast "arch" output member (since 3.0.0) 93 94The ``arch'' output member of the ``query-cpus-fast'' command is 95replaced by the ``target'' output member. 96 97@subsection cpu-add (since 4.0) 98 99Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See 100documentation of ``query-hotpluggable-cpus'' for additional 101details. 102 103@subsection query-events (since 4.0) 104 105The ``query-events'' command has been superseded by the more powerful 106and accurate ``query-qmp-schema'' command. 107 108@subsection chardev client socket with 'wait' option (since 4.0) 109 110Character devices creating sockets in client mode should not specify 111the 'wait' field, which is only applicable to sockets in server mode 112 113@section Human Monitor Protocol (HMP) commands 114 115@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1) 116 117The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and 118'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}. 119 120@subsection cpu-add (since 4.0) 121 122Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See 123documentation of ``query-hotpluggable-cpus'' for additional details. 124 125@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0) 126 127The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and 128``acl_remove'' commands are deprecated with no replacement. Authorization 129for VNC should be performed using the pluggable QAuthZ objects. 130 131@section System emulator devices 132 133@subsection bluetooth (since 3.1) 134 135The bluetooth subsystem is unmaintained since many years and likely bitrotten 136quite a bit. It will be removed without replacement unless some users speaks 137up at the @email{qemu-devel@@nongnu.org} mailing list with information about 138their usecases. 139 140@section System emulator machines 141 142@subsection pc-0.12, pc-0.13, pc-0.14 and pc-0.15 (since 4.0) 143 144These machine types are very old and likely can not be used for live migration 145from old QEMU versions anymore. A newer machine type should be used instead. 146 147@subsection prep (PowerPC) (since 3.1) 148 149This machine type uses an unmaintained firmware, broken in lots of ways, 150and unable to start post-2004 operating systems. 40p machine type should be 151used instead. 152 153@section Device options 154 155@subsection Block device options 156 157@subsubsection "backing": "" (since 2.12.0) 158 159In order to prevent QEMU from automatically opening an image's backing 160chain, use ``"backing": null'' instead. 161 162@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0) 163 164Options for ``rbd'' should be specified according to its runtime options, 165like other block drivers. Legacy parsing of keyvalue pair encoded 166filenames is useful to open images with the old format for backing files; 167These image files should be updated to use the current format. 168 169Example of legacy encoding: 170 171@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}} 172 173The above, converted to the current supported format: 174 175@code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}} 176 177@section Related binaries 178 179@subsection qemu-nbd --partition (since 4.0.0) 180 181The ``qemu-nbd --partition $digit'' code (also spelled @option{-P}) 182can only handle MBR partitions, and has never correctly handled 183logical partitions beyond partition 5. If you know the offset and 184length of the partition (perhaps by using @code{sfdisk} within the 185guest), you can achieve the effect of exporting just that subset of 186the disk by use of the @option{--image-opts} option with a raw 187blockdev using the @code{offset} and @code{size} parameters layered on 188top of any other existing blockdev. For example, if partition 1 is 189100MiB long starting at 1MiB, the old command: 190 191@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2} 192 193can be rewritten as: 194 195@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.backing.driver=file,file.backing.filename=file.qcow2} 196 197Alternatively, the @code{nbdkit} project provides a more powerful 198partition filter on top of its nbd plugin, which can be used to select 199an arbitrary MBR or GPT partition on top of any other full-image NBD 200export. Using this to rewrite the above example results in: 201 202@code{qemu-nbd -t -k /tmp/sock -f qcow2 file.qcow2 &} 203@code{nbdkit -f --filter=partition nbd socket=/tmp/sock partition=1} 204 205Note that if you are exposing the export via /dev/nbd0, it is easier 206to just export the entire image and then mount only /dev/nbd0p1 than 207it is to reinvoke @command{qemu-nbd -c /dev/nbd0} limited to just a 208subset of the image. 209