QEMU(1) | QEMU | QEMU(1) |
qemu - QEMU User Documentation
qemu-system-x86_64 [options] [disk_image]
The QEMU PC System emulator simulates the following peripherals:
SMP is supported with up to 255 CPUs.
QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL VGA BIOS.
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
QEMU uses GUS emulation (GUSEMU32 http://www.deinmeister.de/gusemu/) by Tibor "TS" Schütz.
Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU must be told to not have parallel ports to have working GUS.
qemu_system-x86_64 dos.img -device gus -parallel none
Alternatively:
qemu_system-x86_64 dos.img -device gus,irq=5
Or some other unclaimed IRQ.
CS4231A is the chip used in Windows Sound System and GUSMAX products
The PC speaker audio device can be configured using the pcspk-audiodev machine property, i.e.
qemu_system-x86_64 some.img -audiodev <backend>,id=<name> -machine pcspk-audiodev=<name>
disk_image is a raw hard disk image for IDE hard disk 0. Some targets do not need a disk image.
For architectures which aim to support live migration compatibility across releases, each release will introduce a new versioned machine type. For example, the 2.8.0 release introduced machine types "pc-i440fx-2.8" and "pc-q35-2.8" for the x86_64/i686 architectures.
To allow live migration of guests from QEMU version 2.8.0, to QEMU version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8" and "pc-q35-2.8" machines too. To allow users live migrating VMs to skip multiple intermediate releases when upgrading, new releases of QEMU will support machine types from many previous versions.
Supported machine properties are:
Legacy VCPU assignment uses 'cpus' option where firstcpu and lastcpu are CPU indexes. Each 'cpus' option represent a contiguous range of CPU indexes (or a single VCPU if lastcpu is omitted). A non-contiguous set of VCPUs can be represented by providing multiple 'cpus' options. If 'cpus' is omitted on all nodes, VCPUs are automatically split between them.
For example, the following option assigns VCPUs 0, 1, 2 and 5 to a NUMA node:
-numa node,cpus=0-2,cpus=5
'cpu' option is a new alternative to 'cpus' option which uses 'socket-id|core-id|thread-id' properties to assign CPU objects to a node using topology layout properties of CPU. The set of properties is machine specific, and depends on used machine type/'smp' options. It could be queried with 'hotpluggable-cpus' monitor command. 'node-id' property specifies node to which CPU object will be assigned, it's required for node to be declared with 'node' option before it's used with 'cpu' option.
For example:
-M pc \ -smp 1,sockets=2,maxcpus=2 \ -numa node,nodeid=0 -numa node,nodeid=1 \ -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
Legacy 'mem' assigns a given RAM amount to a node (not supported for 5.1 and newer machine types). 'memdev' assigns RAM from a given memory backend device to a node. If 'mem' and 'memdev' are omitted in all nodes, RAM is split equally between them.
'mem' and 'memdev' are mutually exclusive. Furthermore, if one node uses 'memdev', all of them have to use it.
'initiator' is an additional option that points to an initiator NUMA node that has best performance (the lowest latency or largest bandwidth) to this NUMA node. Note that this option can be set only when the machine property 'hmat' is set to 'on'.
Following example creates a machine with 2 NUMA nodes, node 0 has CPU. node 1 has only memory, and its initiator is node 0. Note that because node 0 has CPU, by default the initiator of node 0 is itself and must be itself.
-machine hmat=on \ -m 2G,slots=2,maxmem=4G \ -object memory-backend-ram,size=1G,id=m0 \ -object memory-backend-ram,size=1G,id=m1 \ -numa node,nodeid=0,memdev=m0 \ -numa node,nodeid=1,memdev=m1,initiator=0 \ -smp 2,sockets=2,maxcpus=2 \ -numa cpu,node-id=0,socket-id=0 \ -numa cpu,node-id=0,socket-id=1
source and destination are NUMA node IDs. distance is the NUMA distance from source to destination. The distance from a node to itself is always 10. If any pair of nodes is given a distance, then all pairs must be given distances. Although, when distances are only given in one direction for each pair of nodes, then the distances in the opposite directions are assumed to be the same. If, however, an asymmetrical pair of distances is given for even one node pair, then all node pairs must be provided distance values for both directions, even when they are symmetrical. When a node is unreachable from another node, set the pair's distance to 255.
Note that the -numa option doesn't allocate any of the specified resources, it just assigns existing resources to NUMA nodes. This means that one still has to use the -m, -smp options to allocate RAM and VCPUs respectively.
Use 'hmat-lb' to set System Locality Latency and Bandwidth Information between initiator and target NUMA nodes in ACPI Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node can create memory requests, usually it has one or more processors. Target NUMA node contains addressable memory.
In 'hmat-lb' option, node are NUMA node IDs. hierarchy is the memory hierarchy of the target NUMA node: if hierarchy is 'memory', the structure represents the memory performance; if hierarchy is 'first-level|second-level|third-level', this structure represents aggregated performance of memory side caches for each domain. type of 'data-type' is type of data represented by this structure instance: if 'hierarchy' is 'memory', 'data-type' is 'access|read|write' latency or 'access|read|write' bandwidth of the target memory; if 'hierarchy' is 'first-level|second-level|third-level', 'data-type' is 'access|read|write' hit latency or 'access|read|write' hit bandwidth of the target memory side cache.
lat is latency value in nanoseconds. bw is bandwidth value, the possible value and units are NUM[M|G|T], mean that the bandwidth value are NUM byte per second (or MB/s, GB/s or TB/s depending on used suffix). Note that if latency or bandwidth value is 0, means the corresponding latency or bandwidth information is not provided.
In 'hmat-cache' option, node-id is the NUMA-id of the memory belongs. size is the size of memory side cache in bytes. level is the cache level described in this structure, note that the cache level 0 should not be used with 'hmat-cache' option. associativity is the cache associativity, the possible value is 'none/direct(direct-mapped)/complex(complex cache indexing)'. policy is the write policy. line is the cache Line size in bytes.
For example, the following options describe 2 NUMA nodes. Node 0 has 2 cpus and a ram, node 1 has only a ram. The processors in node 0 access memory in node 0 with access-latency 5 nanoseconds, access-bandwidth is 200 MB/s; The processors in NUMA node 0 access memory in NUMA node 1 with access-latency 10 nanoseconds, access-bandwidth is 100 MB/s. And for memory side cache information, NUMA node 0 and 1 both have 1 level memory cache, size is 10KB, policy is write-back, the cache Line size is 8 bytes:
-machine hmat=on \ -m 2G \ -object memory-backend-ram,size=1G,id=m0 \ -object memory-backend-ram,size=1G,id=m1 \ -smp 2 \ -numa node,nodeid=0,memdev=m0 \ -numa node,nodeid=1,memdev=m1,initiator=0 \ -numa cpu,node-id=0,socket-id=0 \ -numa cpu,node-id=0,socket-id=1 \ -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \ -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \ -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \ -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \ -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \ -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
You can open an image using pre-opened file descriptors from an fd set:
qemu-system-x86_64 \
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
-drive file=/dev/fdset/2,index=0,media=disk
qemu_system-x86_64 -global ide-hd.physical_block_size=4096 disk-image.img
In particular, you can use this to set driver properties for devices which are created automatically by the machine model. To create a device which is not created automatically and set properties on it, use -device.
-global driver.prop=value is shorthand for -global driver=driver,property=prop,value=value. The longhand syntax works even when driver contains a dot.
Interactive boot menus/prompts can be enabled via menu=on as far as firmware/BIOS supports them. The default is non-interactive boot.
A splash picture could be passed to bios, enabling user to show it as logo, when option splash=sp_name is given and menu=on, If firmware/BIOS supports them. Currently Seabios for X86 system support it. limitation: The splash file could be a jpeg file or a BMP file in 24 BPP format(true color). The resolution should be supported by the SVGA mode, so the recommended is 320x240, 640x480, 800x640.
A timeout could be passed to bios, guest will pause for rb_timeout ms when boot failed, then reboot. If rb_timeout is '-1', guest will not reboot, qemu passes '-1' to bios by default. Currently Seabios for X86 system support it.
Do strict boot via strict=on as far as firmware/BIOS supports it. This only effects when boot priority is changed by bootindex options. The default is non-strict boot.
# try to boot from network first, then from hard disk qemu_system-x86_64 -boot order=nc # boot from CD-ROM first, switch back to default order after reboot qemu_system-x86_64 -boot once=d # boot with a splash picture for 5 seconds. qemu_system-x86_64 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
Note: The legacy format '-boot drives' is still supported but its use is discouraged as it may be removed from future versions.
For example, the following command-line sets the guest startup RAM size to 1GB, creates 3 slots to hotplug additional memory and sets the maximum memory the guest can reach to 4GB:
qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
If slots and maxmem are not specified, memory hotplug won't be enabled and the guest startup RAM will never increase.
The available layouts are:
ar de-ch es fo fr-ca hu ja mk no pt-br sv da en-gb et fr fr-ch is lt nl pl ru th de en-us fi fr-be hr it lv nl-be pt sl tr
The default is en-us.
-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
NOTE: parameter validation is known to be incomplete, in many cases specifying an invalid option causes QEMU to print an error message and continue emulation without sound.
Valid global options are:
ALSA specific options are:
Core Audio specific options are:
DirectSound specific options are:
OSS specific options are:
PulseAudio specific options are:
Backend specific options are:
qemu_system-x86_64 -soundhw sb16,adlib disk.img qemu_system-x86_64 -soundhw es1370 disk.img qemu_system-x86_64 -soundhw ac97 disk.img qemu_system-x86_64 -soundhw hda disk.img qemu_system-x86_64 -soundhw all disk.img qemu_system-x86_64 -soundhw help
Note that Linux's i810_audio OSS kernel (for AC97) module might require manually specifying clocking.
modprobe i810_audio clocking=48000
Some drivers are:
The IPMI slave address to use for the BMC. The default is 0x20. This address is the BMC's address on the I2C network of management controllers. If you don't know what this means, it is safe to ignore it.
A connection is made to an external BMC simulator. If you do this, it is strongly recommended that you use the "reconnect=" chardev option to reconnect to the simulator if the connection is lost. Note that if this is not used carefully, it can be a security issue, as the interface has the ability to send resets, NMIs, and power off the VM. It's best if QEMU makes a connection to an external simulator running on a secure port on localhost, so neither the simulator nor QEMU is exposed to any outside network.
See the "lanserv/README.vm" file in the OpenIPMI library for more details on the external interface.
Options that expect a reference to another node (e.g. file) can be given in two ways. Either you specify the node name of an already existing node (file=node-name), or you define a new node inline, adding options for the referenced node after a dot (file.filename=path,file.aio=native).
A block driver node created with -blockdev can be used for a guest device by specifying its node name for the drive property in a -device argument that defines a block device.
If no node name is specified, it is automatically generated. The generated node name is not intended to be predictable and changes between QEMU invocations. For the top level, an explicit node name must be specified.
Note that some block drivers support only read-only access, either generally or in certain configurations. In this case, the default value read-only=off does not work and the option must be specified explicitly.
Enabling force-share=on requires read-only=on.
Example:
-blockdev driver=file,node-name=disk,filename=disk.img
Example 1:
-blockdev driver=file,node-name=disk_file,filename=disk.img -blockdev driver=raw,node-name=disk,file=disk_file
Example 2:
-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
Example 1:
-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
Example 2:
-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
-drive accepts all options that are accepted by -blockdev. In addition, it knows the following options:
Special files such as iSCSI devices can be specified using protocol specific URLs. See the section for "Device URL Syntax" for more information.
cache.writeback | cache.direct | cache.no-flush | |
writeback | on | off | off |
none | on | on | off |
writethrough | off | off | off |
directsync | off | on | off |
unsafe | on | off | on |
The default mode is cache=writeback.
By default, the cache.writeback=on mode is used. It will report data writes as completed as soon as the data is present in the host page cache. This is safe as long as your guest OS makes sure to correctly flush disk caches where needed. If your guest OS does not handle volatile disk write caches correctly and your host crashes or loses power, then the guest may experience data corruption.
For such guests, you should consider using cache.writeback=off. This means that the host page cache will be used to read and write data, but write notification will be sent to the guest only after QEMU has made sure to flush each write to the disk. Be aware that this has a major impact on performance.
When using the -snapshot option, unsafe caching is always used.
Copy-on-read avoids accessing the same backing file sectors repeatedly and is useful when the backing file is over a slow network. By default copy-on-read is off.
Instead of -cdrom you can use:
qemu-system-x86_64 -drive file=file,index=2,media=cdrom
Instead of -hda, -hdb, -hdc, -hdd, you can use:
qemu-system-x86_64 -drive file=file,index=0,media=disk qemu-system-x86_64 -drive file=file,index=1,media=disk qemu-system-x86_64 -drive file=file,index=2,media=disk qemu-system-x86_64 -drive file=file,index=3,media=disk
You can open an image using pre-opened file descriptors from an fd set:
qemu-system-x86_64 \
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
-drive file=/dev/fdset/2,index=0,media=disk
You can connect a CDROM to the slave of ide0:
qemu_system-x86_64 -drive file=file,if=ide,index=1,media=cdrom
If you don't specify the "file=" argument, you define an empty drive:
qemu_system-x86_64 -drive if=ide,index=1,media=cdrom
Instead of -fda, -fdb, you can use:
qemu_system-x86_64 -drive file=file,index=0,if=floppy qemu_system-x86_64 -drive file=file,index=1,if=floppy
By default, interface is "ide" and index is automatically incremented:
qemu_system-x86_64 -drive file=a -drive file=b"
is interpreted like:
qemu_system-x86_64 -hda a -hdb b
-fsdev option is used along with -device driver "virtio-9p-...".
Note that -virtfs is actually just a convenience shortcut for its generalized form -fsdev -device virtio-9p-pci.
The general form of pass-through file system options are:
For PPC the default is 800x600x32.
For SPARC with the TCX graphics device, the default is 1024x768x8 with the option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option of 1152x900x8 for people who wish to use OBP.
Following the display value there may be one or more option flags separated by commas. Valid options are
If host is specified connections will only be allowed from this host. It is possible to control the websocket listen address independently, using the syntax websocket=host:port.
If no TLS credentials are provided, the websocket connection runs in unencrypted mode. If TLS credentials are provided, the websocket connection requires encrypted client connections.
The password must be set separately using the set_password command in the QEMU monitor. The syntax to change your password is: set_password <protocol> <password> where <protocol> could be either "vnc" or "spice".
If you would like to change <protocol> password expiration, you should use expire_password <protocol> <expiration-time> where expiration time could be one of the following options: now, never, +seconds or UNIX time of expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this date and time).
You can also use keywords "now" or "never" for the expiration time to allow <protocol> password to expire immediately or never expire.
This option is deprecated and should no longer be used. The new sasl-authz and tls-authz options are a replacement.
This argument can be repeated multiple times, and values are added in the order they are parsed. Applications intending to use OEM strings data are encouraged to use their application name as a prefix for the value string. This facilitates passing information for multiple applications concurrently.
The value=str syntax provides the string data inline, while the path=filename syntax loads data from a file on disk. Note that the file is not permitted to contain any NUL bytes.
Both the value and path options can be repeated multiple times and will be added to the SMBIOS table in the order in which they appear.
Note that on the x86 architecture, the total size of all SMBIOS tables is limited to 65535 bytes. Thus the OEM strings data is not suitable for passing large amounts of data into the guest. Instead it should be used as a indicator to inform the guest where to locate the real data set, for example, by specifying the serial ID of a block device.
An example passing three strings is
-smbios type=11,value=cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/,\
value=anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os,\
path=/some/file/with/oemstringsdata.txt
In the guest OS this is visible with the dmidecode command
$ dmidecode -t 11 Handle 0x0E00, DMI type 11, 5 bytes OEM Strings
String 1: cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/
String 2: anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os
String 3: myapp:some extra data
The following two example do exactly the same, to show how -nic can be used to shorten the command line length:
qemu-system-x86_64 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 qemu-system-x86_64 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
Example:
qemu-system-x86_64 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
Example (using pxelinux):
qemu-system-x86_64 -hda linux.img -boot n -device e1000,netdev=n1 \
-netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
In the guest Windows OS, the line:
10.0.2.4 smbserver
must be added in the file C:\WINDOWS\LMHOSTS (for windows 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows NT/2000).
Then dir can be accessed in \\smbserver\qemu.
Note that a SAMBA server must be installed on the host OS.
For example, to redirect host X11 connection from screen 1 to guest screen 0, use the following:
# on the host qemu-system-x86_64 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 # this host xterm should open in the guest X11 server xterm -display :1
To redirect telnet connections from host port 5555 to telnet port on the guest, use the following:
# on the host qemu-system-x86_64 -nic user,hostfwd=tcp::5555-:23 telnet localhost 5555
Then when you use on the host telnet localhost 5555, you connect to the guest telnet server.
You can either use a chardev directly and have that one used throughout QEMU's lifetime, like in the following example:
# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever # the guest accesses it qemu-system-x86_64 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
Or you can execute a command on every TCP connection established by the guest, so that QEMU behaves similar to an inetd process for that virtual server:
# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 # and connect the TCP stream to its stdin/stdout qemu-system-x86_64 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
Use the network script file to configure it and the network script dfile to deconfigure it. If name is not provided, the OS automatically provides one. The default network configure script is /etc/qemu-ifup and the default network deconfigure script is /etc/qemu-ifdown. Use script=no or downscript=no to disable script execution.
If running QEMU as an unprivileged user, use the network helper to configure the TAP interface and attach it to the bridge. The default network helper executable is /path/to/qemu-bridge-helper and the default bridge device is br0.
fd=h can be used to specify the handle of an already opened host TAP interface.
Examples:
#launch a QEMU instance with the default network script qemu-system-x86_64 linux.img -nic tap
#launch a QEMU instance with two NICs, each one connected #to a TAP device qemu-system-x86_64 linux.img \
-netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
-netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
#launch a QEMU instance with the default network helper to #connect a TAP device to bridge br0 qemu-system-x86_64 linux.img -device virtio-net-pci,netdev=n1 \
-netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
Use the network helper helper to configure the TAP interface and attach it to the bridge. The default network helper executable is /path/to/qemu-bridge-helper and the default bridge device is br0.
Examples:
#launch a QEMU instance with the default network helper to #connect a TAP device to bridge br0 qemu-system-x86_64 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
#launch a QEMU instance with the default network helper to #connect a TAP device to bridge qemubr0 qemu-system-x86_64 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
Example:
# launch a first QEMU instance qemu-system-x86_64 linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,listen=:1234 # connect the network of this instance to the network of the first instance qemu-system-x86_64 linux.img \
-device e1000,netdev=n2,mac=52:54:00:12:34:57 \
-netdev socket,id=n2,connect=127.0.0.1:1234
Example:
# launch one QEMU instance qemu-system-x86_64 linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=230.0.0.1:1234 # launch another QEMU instance on same "bus" qemu-system-x86_64 linux.img \
-device e1000,netdev=n2,mac=52:54:00:12:34:57 \
-netdev socket,id=n2,mcast=230.0.0.1:1234 # launch yet another QEMU instance on same "bus" qemu-system-x86_64 linux.img \
-device e1000,netdev=n3,mac=52:54:00:12:34:58 \
-netdev socket,id=n3,mcast=230.0.0.1:1234
Example (User Mode Linux compat.):
# launch QEMU instance (note mcast address selected is UML's default) qemu-system-x86_64 linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=239.192.168.1:1102 # launch UML /path/to/linux ubd0=/path/to/root_fs eth0=mcast
Example (send packets from host's 1.2.3.4):
qemu-system-x86_64 linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
This transport allows a VM to communicate to another VM, router or firewall directly.
For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan on the remote Linux host 1.2.3.4:
# Setup tunnel on linux host using raw ip as encapsulation # on 1.2.3.4 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
encap udp udp_sport 16384 udp_dport 16384 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
0xFFFFFFFF peer_session_id 0xFFFFFFFF ifconfig vmtunnel0 mtu 1500 ifconfig vmtunnel0 up brctl addif br-lan vmtunnel0 # on 4.3.2.1 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter qemu-system-x86_64 linux.img -device e1000,netdev=n1 \
-netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
Example:
# launch vde switch vde_switch -F -sock /tmp/myswitch # launch QEMU instance qemu-system-x86_64 linux.img -nic vde,sock=/tmp/myswitch
Example:
qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
-numa node,memdev=mem \
-chardev socket,id=chr0,path=/path/to/socket \
-netdev type=vhost-user,id=net0,chardev=chr0 \
-device virtio-net-pci,netdev=net0
vDPA device is a device that uses a datapath which complies with the virtio specifications with a vendor specific control path. vDPA devices can be both physically located on the hardware or emulated by software.
The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a single netdev. Alternatively, you can also connect the hubport to another netdev with ID nd by using the netdev=nd option.
The general form of a character device option is:
Use -chardev help to print all available chardev backend types.
All devices must have an id, which can be any string up to 127 characters long. It is used to uniquely identify this device in other command line directives.
A character device may be used in multiplexing mode by multiple front-ends. Specify mux=on to enable this mode. A multiplexer is a "1:N" device, and here the "1" end is your specified chardev backend, and the "N" end is the various parts of QEMU that can talk to a chardev. If you create a chardev with id=myid and mux=on, QEMU will create a multiplexer with your specified ID, and you can then configure multiple front ends to use that chardev ID for their input/output. Up to four different front ends can be connected to a single multiplexed chardev. (Without multiplexing enabled, a chardev can only be used by a single front end.) For instance you could use this to allow a single stdio chardev to be used by two serial ports and the QEMU monitor:
-chardev stdio,mux=on,id=char0 \ -mon chardev=char0,mode=readline \ -serial chardev:char0 \ -serial chardev:char0
You can have more than one multiplexer in a system configuration; for instance you could have a TCP port multiplexed between UART 0 and UART 1, and stdio multiplexed between the QEMU monitor and a parallel port:
-chardev stdio,mux=on,id=char0 \ -mon chardev=char0,mode=readline \ -parallel chardev:char0 \ -chardev tcp,...,mux=on,id=char1 \ -serial chardev:char1 \ -serial chardev:char1
When you're using a multiplexed character device, some escape sequences are interpreted in the input. See the chapter about keys in the character backend multiplexer in the System Emulation Users Guide for more details.
Note that some other command line options may implicitly create multiplexed character backends; for instance -serial mon:stdio creates a multiplexed stdio backend connected to the serial port and the QEMU monitor, and -nographic also multiplexes the console and the monitor to stdio.
There is currently no support for multiplexing in the other direction (where a single QEMU front end takes input and output from multiple chardevs).
Every backend supports the logfile option, which supplies the path to a file to record all data transmitted via the backend. The logappend option controls whether the log file will be truncated or appended to when opened.
The available backends are:
server specifies that the socket shall be a listening socket.
nowait specifies that QEMU should not block waiting for a client to connect to a listening socket.
telnet specifies that traffic on the socket should interpret telnet escape sequences.
websocket specifies that the socket uses WebSocket protocol for communication.
reconnect sets the timeout for reconnecting on non-server sockets when the remote end goes away. qemu will delay this many seconds and then attempt to reconnect. Zero disables reconnecting, and is the default.
tls-creds requests enablement of the TLS protocol for encryption, and specifies the id of the TLS credentials to use for the handshake. The credentials must be previously created with the -object tls-creds argument.
tls-auth provides the ID of the QAuthZ authorization object against which the client's x509 distinguished name will be validated. This object is only resolved at time of use, so can be deleted and recreated on the fly while the chardev server is active. If missing, it will default to denying access.
TCP and unix socket options are given below:
port for a listening socket specifies the local port to be bound. For a connecting socket specifies the port on the remote host to connect to. port can be given as either a port number or a service name. port is required.
to is only relevant to listening sockets. If it is specified, and port cannot be bound, QEMU will attempt to bind to subsequent ports up to and including to until it succeeds. to must be specified as a port number.
ipv4 and ipv6 specify that either IPv4 or IPv6 must be used. If neither is specified the socket may use either protocol.
nodelay disables the Nagle algorithm.
host specifies the remote host to connect to. If not specified it defaults to localhost.
port specifies the port on the remote host to connect to. port is required.
localaddr specifies the local address to bind to. If not specified it defaults to 0.0.0.0.
localport specifies the local port to bind to. If not specified any available local port will be used.
ipv4 and ipv6 specify that either IPv4 or IPv6 must be used. If neither is specified the device may use either protocol.
width and height specify the width and height respectively of the console, in pixels.
cols and rows specify that the console be sized to fit a text console with the given dimensions.
path specifies the path of the file to be opened. This file will be created if it does not already exist, and overwritten if it does. path is required.
On Windows, a single duplex pipe will be created at \\.pipe\path.
On other hosts, 2 pipes will be created called path.in and path.out. Data written to path.in will be received by the guest. Data written by the guest can be read from path.out. QEMU will not create these fifos, and requires them to be present.
path forms part of the pipe path as described above. path is required.
console is only available on Windows hosts.
On Unix hosts serial will actually accept any tty device, not only serial lines.
path specifies the name of the serial device to open.
pty is not available on Windows hosts.
signal controls if signals are enabled on the terminal, that includes exiting QEMU with the key sequence Control-c. This option is enabled by default, use signal=off to disable it.
path specifies the path to the tty. path is required.
Connect to a local parallel port.
path specifies the path to the parallel port device. path is required.
debug debug level for spicevmc
name name of spice channel to connect to
Connect to a spice virtual machine channel, such as vdiport.
debug debug level for spicevmc
name name of spice port to connect to
Connect to a spice port, allowing a Spice client to handle the traffic identified by a name (preferably a fqdn).
The general form of a TPM device option is:
Use -tpmdev help to print all available TPM backend types.
The available backends are:
path specifies the path to the host's TPM device, i.e., on a Linux host this would be /dev/tpm0. path is optional and by default /dev/tpm0 is used.
cancel-path specifies the path to the host TPM device's sysfs entry allowing for cancellation of an ongoing TPM command. cancel-path is optional and by default QEMU will search for the sysfs entry to use.
Some notes about using the host's TPM with the passthrough driver:
The TPM device accessed by the passthrough driver must not be used by any other application on the host.
Since the host's firmware (BIOS/UEFI) has already initialized the TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize the TPM again and may therefore not show a TPM-specific menu that would otherwise allow the user to configure the TPM, e.g., allow the user to enable/disable or activate/deactivate the TPM. Further, if TPM ownership is released from within a VM then the host's TPM will get disabled and deactivated. To enable and activate the TPM again afterwards, the host has to be rebooted and the user is required to enter the firmware's menu to enable and activate the TPM. If the TPM is left disabled and/or deactivated most TPM commands will fail.
To create a passthrough TPM use the following two options:
-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
Note that the -tpmdev id is tpm0 and is referenced by tpmdev=tpm0 in the device option.
chardev specifies the unique ID of a character device backend that provides connection to the software TPM server.
To create a TPM emulator backend device with chardev socket backend:
-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
When using these options, you can use a given Linux or Multiboot kernel without installing it in the disk image. It can be useful for easier testing of various kernels.
Use file1 and file2 as modules and pass arg=foo as parameter to the first module.
The terminating NUL character of the contents of str will not be included as part of the fw_cfg item data. To insert contents with embedded NUL characters, you have to use the file parameter.
The fw_cfg entries are passed by QEMU through to the guest.
Example:
-fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
creates an fw_cfg entry named opt/com.mycompany/blob with contents from ./my_blob.bin.
This option can be used several times to simulate up to 4 serial ports.
Use -serial none to disable all serial ports.
Available character devices are:
vc:800x600
It is also possible to specify width or height in characters:
vc:80Cx24C
If you just want a simple readonly console you can use netcat or nc, by starting QEMU with: -serial udp::4555 and nc as: nc -u -l -p 4555. Any time QEMU writes something to that port it will appear in the netconsole session.
If you plan to send characters back via netconsole or you want to stop and start QEMU a lot of times, you should have QEMU use the same source port each time by using something like -serial udp::4555@:4556 to QEMU. Another approach is to use a patched version of netcat which can listen to a TCP port and send and receive characters via udp. If you have a patched version of netcat which activates telnet remote echo and single char transfer, then you can use the following options to set up a netcat redirector to allow telnet on port 5555 to access the QEMU port.
-serial mon:telnet::4444,server,nowait
When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate QEMU any more but will be passed to the guest instead.
This option can be used several times to simulate up to 3 parallel ports.
Use -parallel none to disable all parallel ports.
Locking qemu and guest memory can be enabled via mem-lock=on (disabled by default). This works when host memory is not overcommitted and reduces the worst-case latency for guest. This is equivalent to realtime.
Guest ability to manage power state of host cpus (increasing latency for other processes on the same host cpu, but decreasing latency for guest) can be enabled via cpu-pm=on (disabled by default). This works best when host CPU is not overcommitted. When used, host estimates of CPU cycle and power utilization will be incorrect, not taking into account guest idle time.
The most usual configuration is to listen on a local TCP socket:
-gdb tcp::3117
but you can specify other backends; UDP, pseudo TTY, or even stdio are all reasonable use cases. For example, a stdio connection allows you to start QEMU from within gdb and establish the connection via a pipe:
(gdb) target remote | exec qemu-system-x86_64 -gdb stdio ...
-dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
Will dump output for any code in the 0x1000 sized block starting at 0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized block starting at 0xffffffc00005f000.
To list all the data directories, use -L help.
By default the RTC is driven by the host system time. This allows using of the RTC as accurate reference clock inside the guest, specifically if the host time is smoothly following an accurate external reference clock, e.g. via NTP. If you want to isolate the guest time from the host, you can set clock to rt instead, which provides a host monotonic clock if host support it. To even prevent the RTC from progressing during suspension, you can set clock to vm (virtual clock). 'clock=vm' is recommended especially in icount mode in order to preserve determinism; however, note that in icount mode the speed of the virtual clock is variable and can in general differ from the host clock.
Enable driftfix (i386 targets only) if you experience time drift problems, specifically with Windows' ACPI HAL. This option will try to figure out how many timer interrupts were not processed by the Windows guest and will re-inject them.
When the virtual cpu is sleeping, the virtual time will advance at default speed unless sleep=on|off is specified. With sleep=on|off, the virtual time will jump to the next timer deadline instantly whenever the virtual cpu goes to sleep mode and will not advance if no timer is enabled. This behavior give deterministic execution times from the guest point of view.
Note that while this option can give deterministic behavior, it does not provide cycle accurate emulation. Modern CPUs contain superscalar out of order cores with complex cache hierarchies. The number of instructions executed often has little or no correlation with actual performance.
align=on will activate the delay algorithm which will try to synchronise the host clock and the virtual clock. The goal is to have a guest running at the real frequency imposed by the shift option. Whenever the guest clock is behind the host clock and if align=on is specified then we print a message to the user to inform about the delay. Currently this option does not work when shift is auto. Note: The sync algorithm will work for those shift values for which the guest clock runs ahead of the host clock. Typically this happens when the shift value is high (how high depends on the host machine).
When rr option is specified deterministic record/replay is enabled. Replay log is written into filename file in record mode and read from this file in replay mode.
Option rrsnapshot is used to create new vm snapshot named snapshot at the start of execution recording. In replay mode this option is used to load the initial VM state.
The model is the model of hardware watchdog to emulate. Use -watchdog help to list available hardware models. Only one watchdog can be enabled for a guest.
The following models may be available:
Note that the shutdown action requires that the guest responds to ACPI signals, which it may not be able to do in the sort of situations where the watchdog would have expired, and thus -watchdog-action shutdown is not recommended for production use.
Examples:
-watchdog i6300esb -watchdog-action pause; -watchdog ib700
-echr 0x14; -echr 20
qemu-system-sparc -prom-env 'auto-boot?=false' \
-prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
qemu-system-ppc -prom-env 'auto-boot?=false' \
-prom-env 'boot-device=hd:2,\yaboot' \
-prom-env 'boot-args=conf=hd:2,\yaboot.conf'
Note that this allows guest direct access to the host filesystem, so should only be used with a trusted guest OS.
See the -semihosting-config option documentation for further information about the facilities this enables.
Note that this allows guest direct access to the host filesystem, so should only be used with a trusted guest OS.
On Arm this implements the standard semihosting API, version 2.0.
On M68K this implements the "ColdFire GDB" interface used by libgloss.
Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select. Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
[enable=]PATTERN
Use -trace help to print a list of names of trace points.
events=FILE
file=FILE
The id parameter is a unique ID that will be used to reference this memory region when configuring the -numa argument.
The size option provides the size of the memory region, and accepts common suffixes, eg 500M.
The mem-path provides the path to either a shared memory or huge page filesystem mount.
The share boolean option determines whether the memory region is marked as private to QEMU, or shared. The latter allows a co-operating external process to access the QEMU memory region.
The share is also required for pvrdma devices due to limitations in the RDMA API provided by Linux.
Setting share=on might affect the ability to configure NUMA bindings for the memory backend under some circumstances, see Documentation/vm/numa_memory_policy.txt on the Linux kernel source tree for additional details.
Setting the discard-data boolean option to on indicates that file contents can be destroyed when QEMU exits, to avoid unnecessarily flushing data to the backing file. Note that discard-data is only an optimization, and QEMU might not discard file contents if it aborts unexpectedly or is terminated using SIGKILL.
The merge boolean option enables memory merge, also known as MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for memory deduplication.
Setting the dump boolean option to off excludes the memory from core dumps. This feature is also known as MADV_DONTDUMP.
The prealloc boolean option enables memory preallocation.
The host-nodes option binds the memory range to a list of NUMA host nodes.
The policy option sets the NUMA policy to one of the following values:
The align option specifies the base address alignment when QEMU mmap(2) mem-path, and accepts common suffixes, eg 2M. Some backend store specified by mem-path requires an alignment different than the default one used by QEMU, eg the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In such cases, users can specify the required alignment via this option.
The pmem option specifies whether the backing file specified by mem-path is in host persistent memory that can be accessed using the SNIA NVM programming model (e.g. Intel NVDIMM). If pmem is set to 'on', QEMU will take necessary operations to guarantee the persistence of its own writes to mem-path (e.g. in vNVDIMM label emulation and live migration). Also, we will map the backend-file with MAP_SYNC flag, which ensures the file metadata is in sync for mem-path in case of host crash or a power failure. MAP_SYNC requires support from both the host kernel (since Linux kernel 4.15) and the filesystem of mem-path mounted with DAX option.
The seal option creates a sealed-file, that will block further resizing the memory ('on' by default).
The hugetlb option specify the file to be created resides in the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with the hugetlb option, the hugetlbsize option specify the hugetlb page size on systems that support multiple hugetlb page sizes (it must be a power of 2 value supported by the system).
In some versions of Linux, the hugetlb option is incompatible with the seal option (requires at least Linux 4.16).
Please refer to memory-backend-file for a description of the other options.
The share boolean option is on by default with memfd.
The dir parameter tells QEMU where to find the credential files. For server endpoints, this directory may contain a file dh-params.pem providing diffie-hellman parameters to use for the TLS server. If the file is missing, QEMU will generate a set of DH parameters at startup. This is a computationally expensive operation that consumes random pool entropy, so it is recommended that a persistent set of parameters be generated upfront and saved.
The dir parameter tells QEMU where to find the keys file. It is called "dir/keys.psk" and contains "username:key" pairs. This file can most easily be created using the GnuTLS psktool program.
For server endpoints, dir may also contain a file dh-params.pem providing diffie-hellman parameters to use for the TLS server. If the file is missing, QEMU will generate a set of DH parameters at startup. This is a computationally expensive operation that consumes random pool entropy, so it is recommended that a persistent set of parameters be generated up front and saved.
The dir parameter tells QEMU where to find the credential files. For server endpoints, this directory may contain a file dh-params.pem providing diffie-hellman parameters to use for the TLS server. If the file is missing, QEMU will generate a set of DH parameters at startup. This is a computationally expensive operation that consumes random pool entropy, so it is recommended that a persistent set of parameters be generated upfront and saved.
For x509 certificate credentials the directory will contain further files providing the x509 certificates. The certificates must be stored in PEM format, in filenames ca-cert.pem, ca-crl.pem (optional), server-cert.pem (only servers), server-key.pem (only servers), client-cert.pem (only clients), and client-key.pem (only clients).
For the server-key.pem and client-key.pem files which contain sensitive private keys, it is possible to use an encrypted version by providing the passwordid parameter. This provides the ID of a previously created secret object containing the password for decryption.
The priority parameter allows to override the global default priority used by gnutls. This can be useful if the system administrator needs to use a weaker set of crypto priorities for QEMU without potentially forcing the weakness onto all applications. Or conversely if one wants wants a stronger default for QEMU than for all other applications, they can do this through this parameter. Its format is a gnutls priority string as described at https://gnutls.org/manual/html_node/Priority-Strings.html.
The id parameter is a unique ID which frontends will use to access the ordered list of permitted TLS cipher suites from the host.
The priority parameter allows to override the global default priority used by gnutls. This can be useful if the system administrator needs to use a weaker set of crypto priorities for QEMU without potentially forcing the weakness onto all applications. Or conversely if one wants wants a stronger default for QEMU than for all other applications, they can do this through this parameter. Its format is a gnutls priority string as described at https://gnutls.org/manual/html_node/Priority-Strings.html.
An example of use of this object is to control UEFI HTTPS Boot. The tls-cipher-suites object exposes the ordered list of permitted TLS cipher suites from the host side to the guest firmware, via fw_cfg. The list is represented as an array of IANA_TLS_CIPHER objects. The firmware uses the IANA_TLS_CIPHER array for configuring guest-side TLS.
In the following example, the priority at which the host-side policy is retrieved is given by the priority property. Given that QEMU uses GNUTLS, priority=@SYSTEM may be used to refer to /etc/crypto-policies/back-ends/gnutls.config.
# qemu-system-x86_64 \
-object tls-cipher-suites,id=mysuite0,priority=@SYSTEM \
-fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0
queue all|rx|tx is an option that can be applied to any netfilter.
all: the filter is attached both to the receive and the transmit queue of the netdev (default).
rx: the filter is attached to the receive queue of the netdev, where it will receive packets sent to the netdev.
tx: the filter is attached to the transmit queue of the netdev, where it will receive packets sent by the netdev.
position head|tail|id=<id> is an option to specify where the filter should be inserted in the filter list. It can be applied to any netfilter.
head: the filter is inserted at the head of the filter list, before any existing filters.
tail: the filter is inserted at the tail of the filter list, behind any existing filters (default).
id=<id>: the filter is inserted before or behind the filter specified by <id>, see the insert option below.
insert behind|before is an option to specify where to insert the new filter relative to the one specified with position=id=<id>. It can be applied to any netfilter.
before: insert before the specified filter.
behind: insert behind the specified filter (default).
usage: colo secondary: -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object filter-rewriter,id=rew0,netdev=hn0,queue=all
COLO-compare must be used with the help of filter-mirror, filter-redirector and filter-rewriter.
KVM COLO primary: -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait -chardev socket,id=compare0-0,host=3.3.3.3,port=9001 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait -chardev socket,id=compare_out0,host=3.3.3.3,port=9005 -object iothread,id=iothread1 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 secondary: -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown -device e1000,netdev=hn0,mac=52:a4:00:12:78:66 -chardev socket,id=red0,host=3.3.3.3,port=9003 -chardev socket,id=red1,host=3.3.3.3,port=9004 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 Xen COLO primary: -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait -chardev socket,id=compare0-0,host=3.3.3.3,port=9001 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait -chardev socket,id=compare_out0,host=3.3.3.3,port=9005 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 -object iothread,id=iothread1 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1 secondary: -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown -device e1000,netdev=hn0,mac=52:a4:00:12:78:66 -chardev socket,id=red0,host=3.3.3.3,port=9003 -chardev socket,id=red1,host=3.3.3.3,port=9004 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
If you want to know the detail of above command line, you can read the colo-compare git log.
# qemu-system-x86_64 \
[...] \
-object cryptodev-backend-builtin,id=cryptodev0 \
-device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
[...]
# qemu-system-x86_64 \
[...] \
-chardev socket,id=chardev0,path=/path/to/socket \
-object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
-device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
[...]
The sensitive data can be provided in raw format (the default), or base64. When encoded as JSON, the raw format only supports valid UTF-8 characters, so base64 is recommended for sending binary data. QEMU will convert from which ever format is provided to the format it needs internally. eg, an RBD password can be provided in raw format, even though it will be base64 encoded when passed onto the RBD sever.
For added protection, it is possible to encrypt the data associated with a secret using the AES-256-CBC cipher. Use of encryption is indicated by providing the keyid and iv parameters. The keyid parameter provides the ID of a previously defined secret that contains the AES-256 decryption key. This key should be 32-bytes long and be base64 encoded. The iv parameter provides the random initialization vector used for encryption of this particular secret and should be a base64 encrypted string of the 16-byte IV.
The simplest (insecure) usage is to provide the secret inline
# qemu-system-x86_64 -object secret,id=sec0,data=letmein,format=raw
The simplest secure usage is to provide the secret via a file
# printf "letmein" > mypasswd.txt # QEMU_SYSTEM_MACRO -object secret,id=sec0,file=mypasswd.txt,format=raw
For greater security, AES-256-CBC should be used. To illustrate usage, consider the openssl command line tool which can encrypt the data. Note that when encrypting, the plaintext must be padded to the cipher block size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
First a master key needs to be created in base64 encoding:
# openssl rand -base64 32 > key.b64 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
Each secret to be encrypted needs to have a random initialization vector generated. These do not need to be kept secret
# openssl rand -base64 16 > iv.b64 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
The secret to be defined can now be encrypted, in this case we're telling openssl to base64 encode the result, but it could be left as raw bytes if desired.
# SECRET=$(printf "letmein" |
openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
When launching QEMU, create a master secret pointing to key.b64 and specify that to be used to decrypt the user password. Pass the contents of iv.b64 to the second secret
# qemu-system-x86_64 \
-object secret,id=secmaster0,format=base64,file=key.b64 \
-object secret,id=sec0,keyid=secmaster0,format=base64,\
data=$SECRET,iv=$(<iv.b64)
When memory encryption is enabled, one of the physical address bit (aka the C-bit) is utilized to mark if a memory page is protected. The cbitpos is used to provide the C-bit position. The C-bit position is Host family dependent hence user must provide this value. On EPYC, the value should be 47.
When memory encryption is enabled, we loose certain bits in physical address space. The reduced-phys-bits is used to provide the number of bits we loose in physical address space. Similar to C-bit, the value is Host family dependent. On EPYC, the value should be 5.
The sev-device provides the device file to use for communicating with the SEV firmware running inside AMD Secure Processor. The default device is '/dev/sev'. If hardware supports memory encryption then /dev/sev devices are created by CCP driver.
The policy provides the guest policy to be enforced by the SEV firmware and restrict what configuration and operational commands can be performed on this guest by the hypervisor. The policy should be provided by the guest owner and is bound to the guest and cannot be changed throughout the lifetime of the guest. The default is 0.
If guest policy allows sharing the key with another SEV guest then handle can be use to provide handle of the guest from which to share the key.
The dh-cert-file and session-file provides the guest owner's Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters are used for establishing a cryptographic session with the guest owner to negotiate keys used for attestation. The file must be encoded in base64.
e.g to launch a SEV guest
# qemu_system-x86_64 \
...... \
-object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
-machine ...,memory-encryption=sev0 \
.....
The identity parameter is identifies the user and its format depends on the network service that authorization object is associated with. For authorizing based on TLS x509 certificates, the identity must be the x509 distinguished name. Note that care must be taken to escape any commas in the distinguished name.
An example authorization object to validate a x509 distinguished name would look like:
# qemu-system-x86_64 \
... \
-object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
...
Note the use of quotes due to the x509 distinguished name containing whitespace, and escaping of ','.
The filename parameter is the fully qualified path to a file containing the access control list rules in JSON format.
An example set of rules that match against SASL usernames might look like:
{
"rules": [
{ "match": "fred", "policy": "allow", "format": "exact" },
{ "match": "bob", "policy": "allow", "format": "exact" },
{ "match": "danb", "policy": "deny", "format": "glob" },
{ "match": "dan*", "policy": "allow", "format": "exact" },
],
"policy": "deny" }
When checking access the object will iterate over all the rules and the first rule to match will have its policy value returned as the result. If no rules match, then the default policy value is returned.
The rules can either be an exact string match, or they can use the simple UNIX glob pattern matching to allow wildcards to be used.
If refresh is set to true the file will be monitored and automatically reloaded whenever its content changes.
As with the authz-simple object, the format of the identity strings being matched depends on the network service, but is usually a TLS x509 distinguished name, or a SASL username.
An example authorization object to validate a SASL username would look like:
# qemu-system-x86_64 \
... \
-object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes \
...
The service parameter provides the name of a PAM service to use for authorization. It requires that a file /etc/pam.d/service exist to provide the configuration for the account subsystem.
An example authorization object to validate a TLS x509 distinguished name would look like:
# qemu-system-x86_64 \
... \
-object authz-pam,id=auth0,service=qemu-vnc \
...
There would then be a corresponding config file for PAM at /etc/pam.d/qemu-vnc that contains:
account requisite pam_listfile.so item=user sense=allow \
file=/etc/qemu/vnc.allow
Finally the /etc/qemu/vnc.allow file would contain the list of x509 distingished names that are permitted access
CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
The id parameter is a unique ID that will be used to reference this IOThread from -device ...,iothread=id. Multiple devices can be assigned to an IOThread. Note that not all devices support an iothread parameter.
The query-iothreads QMP command lists IOThreads and reports their thread IDs so that the user can configure host CPU pinning/affinity.
IOThreads use an adaptive polling algorithm to reduce event loop latency. Instead of entering a blocking system call to monitor file descriptors and then pay the cost of being woken up when an event occurs, the polling algorithm spins waiting for events for a short time. The algorithm's default parameters are suitable for many cases but can be adjusted based on knowledge of the workload and/or host device latency.
The poll-max-ns parameter is the maximum number of nanoseconds to busy wait for events. Polling can be disabled by setting this value to 0.
The poll-grow parameter is the multiplier used to increase the polling time when the algorithm detects it is missing events due to not polling long enough.
The poll-shrink parameter is the divisor used to decrease the polling time when the algorithm detects it is spending too long polling without encountering events.
The polling parameters can be modified at run-time using the qom-set command (where iothread1 is the IOThread's id):
(qemu) qom-set /objects/iothread1 poll-max-ns 100000
During the graphical emulation, you can use special key combinations to change modes. The default key mappings are shown below, but if you use -alt-grab then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use -ctrl-grab then the modifier is the right Ctrl key (instead of Ctrl-Alt):
In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp and Ctrl-PageDown to move in the back log.
During emulation, if you are using a character backend multiplexer (which is the default if you are using -nographic) then several commands are available via an escape sequence. These key sequences all start with an escape character, which is Ctrl-a by default, but can be changed with -echr. The list below assumes you're using the default.
In addition to using normal file images for the emulated storage devices, QEMU can also use networked resources such as iSCSI devices. These are specified using a special URL syntax.
Syntax for specifying iSCSI LUNs is "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
By default qemu will use the iSCSI initiator-name 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command line or a configuration file.
Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect stalled requests and force a reestablishment of the session. The timeout is specified in seconds. The default is 0 which means no timeout. Libiscsi 1.15.0 or greater is required for this feature.
Example (without authentication):
qemu-system-x86_64 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
-cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
-drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Example (CHAP username/password via URL):
qemu-system-x86_64 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
Example (CHAP username/password via environment variables):
LIBISCSI_CHAP_USERNAME="user" \ LIBISCSI_CHAP_PASSWORD="password" \ qemu-system-x86_64 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Syntax for specifying a NBD device using TCP, in preferred URI form: "nbd://<server-ip>[:<port>]/[<export>]"
Syntax for specifying a NBD device using Unix Domain Sockets; remember that '?' is a shell glob character and may need quoting: "nbd+unix:///[<export>]?socket=<domain-socket>"
Older syntax that is also recognized: "nbd:<server-ip>:<port>[:exportname=<export>]"
Syntax for specifying a NBD device using Unix Domain Sockets "nbd:unix:<domain-socket>[:exportname=<export>]"
Example for TCP
qemu-system-x86_64 --drive file=nbd:192.0.2.1:30000
Example for Unix Domain Sockets
qemu-system-x86_64 --drive file=nbd:unix:/tmp/nbd-socket
Examples:
qemu-system-x86_64 -drive file=ssh://user@host/path/to/disk.img qemu-system-x86_64 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
Currently authentication must be done using ssh-agent. Other authentication methods may be supported in future.
Syntax for specifying a sheepdog device
sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
Example
qemu-system-x86_64 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
See also https://sheepdog.github.io/sheepdog/.
Syntax for specifying a VM disk image on GlusterFS volume is
URI: gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...] JSON: 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...", "server":[{"type":"tcp","host":"...","port":"..."}, {"type":"unix","socket":"..."}]}}'
Example
URI: qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img, file.debug=9,file.logfile=/var/log/qemu-gluster.log JSON: qemu-system-x86_64 'json:{"driver":"qcow2", "file":{"driver":"gluster", "volume":"testvol","path":"a.img", "debug":9,"logfile":"/var/log/qemu-gluster.log", "server":[{"type":"tcp","host":"1.2.3.4","port":24007}, {"type":"unix","socket":"/var/run/glusterd.socket"}]}}' qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, file.debug=9,file.logfile=/var/log/qemu-gluster.log, file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
See also http://www.gluster.org.
Syntax using a single filename:
<protocol>://[<username>[:<password>]@]<host>/<path>
where:
The following options are also supported:
Note that when passing options to qemu explicitly, driver is the value of <protocol>.
Example: boot from a remote Fedora 20 live ISO image
qemu_system-x86_64 --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly qemu_system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
Example: boot from a remote Fedora 20 cloud image using a local overlay for writes, copy-on-read, and a readahead of 64k
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 qemu_system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
Example: boot from an image stored on a VMware vSphere server with a self-signed certificate using a local overlay for writes, a readahead of 64k and a timeout of 10 seconds.
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:password@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2 qemu_system-x86_64 -drive file=/tmp/test.qcow2
The HTML documentation of QEMU for more precise information and Linux user mode emulator invocation.
Fabrice Bellard
2023, The QEMU Project Developers
September 4, 2023 | 5.2.0 |