QEMU interface introspection: From hacks to solutions
Markus Armbruster
QEMU evolves rapidly Many interface versions Our command line is big
In v2.4: 139 total options -14 deprecated -2 internal use 123 supported options 0.57kg If I had a coin for each of them. . . It’s big: output of -help
QEMU emulator version 2.3.93, Copyright (c) 2003-2008 Fabrice Bellard -alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt) configure a network backend to connect to another network -incoming rdma:host:port[,ipv4][,ipv6] usage: upstream-qemu [options] [disk_image] -ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt) using an UDP tunnel -incoming unix:socketpath -no-quit disable SDL window close capability -netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off] prepare for incoming migration, listen on ’disk_image’ is a raw hard disk image for IDE hard disk 0 -sdl enable SDL configure a vhost-user network, backed by a chardev ’dev’ specified protocol and socket address -spice [port=port][,tls-port=secured-port][,x509-dir=
- ] (use the ’-device devtype,netdev=str’ option if possible instead) -incoming defer selects emulated machine (’-machine help’ for list) [,tls-channel=[main|display|cursor|inputs|record|playback]] -net dump[,vlan=n][,file=f][,len=n] wait for the URI to be specified via migrate_incoming property accel=accel1[:accel2[:...]] selects accelerator [,plaintext-channel=[main|display|cursor|inputs|record|playback]] dump traffic on vlan ’n’ to file ’f’ (max n bytes per packet) -nodefaults don’t create default devices supported accelerators are kvm, xen, tcg (default: tcg) [,sasl][,password=
Chapter 3: QEMU PC System emulator 5 Chapter 3: QEMU PC System emulator 6 Chapter 3: QEMU PC System emulator 7 Chapter 3: QEMU PC System emulator 8 Chapter 3: QEMU PC System emulator 9 Chapter 3: QEMU PC System emulator 10 Chapter 3: QEMU PC System emulator 11 Chapter 3: QEMU PC System emulator 12 Chapter 3: QEMU PC System emulator 13
3.3 Invocation to allow execution of DEA cryptographic functions. The default is qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk qemu-system-x86_64 -m 1G,slots=3,maxmem=4G the top visible process name in Linux. Naming of individual threads can also cache=cache cation will be sent to the guest only after QEMU has made sure to flush each qemu-system-i386 -hda a -hdb b write data but write notification will be sent to the guest only when on. be enabled on Linux to aid debugging. cache is "none", "writeback", "unsafe", "directsync" or write to the disk. Be aware that this has a major impact on performance. the data has been reported as written by the storage subsystem. usage: qemu-system-i386 [options] [disk_image] In particular, you can use this to set driver properties for devices which are If slots and maxmem are not specified, memory hotplug won’t be enabled and -mtdblock file "writethrough" and controls how the host cache is used to access -cpu model created automatically by the machine model. To create a device which is not the guest startup RAM will never increase. -uuid uuid The host page cache can be avoided entirely with cache=none. This will at- Use file as on-board Flash memory image. readonly Enables exporting 9p share as a readonly mount for guests. By disk image is a raw hard disk image for IDE hard disk 0. Some targets do not need a disk block data. created automatically and set properties on it, use -device. tempt to do disk IO directly to the guest’s memory. QEMU may still perform default read-write access is given. image. Select CPU model (-cpu help for list and additional feature selection) -mem-path path Set system UUID. -sd file Use file as SecureDigital card image. -global driver.prop=value is shorthand for -global driver=driver,property=prop,value=value. aio=aio " " " " an internal copy of the data. Note that this is considered a writeback mode Standard options: Allocate guest RAM from a temporarily created file in path. aio is threads , or native and selects between pthread based socket=socket -smp Block device options: and the guest OS must handle the disk write cache correctly in order to avoid -pflash file The longhand syntax works even when driver contains a dot. disk I/O and native Linux AIO. Enables proxy filesystem driver to use passed socket file for com- -h Display help and exit [cpus=]n[,cores=cores][,threads=threads][,sockets=sockets][,maxcpus=maxcpus] -mem-prealloc data corruption on host crashes. Use file as a parallel flash image. -boot [order=drives][,once=drives][,menu=on|off][,splash=sp_ Preallocate memory when using -mem-path. -fda file discard=discard municating with virtfs-proxy-helper Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs are The host page cache can be avoided while only sending write notifications to -version Display version information and exit name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off] -fdb file Use file as floppy disk 0/1 image (see Section 3.6 [disk images], page 57). discard is one of "ignore" (or "off") or "unmap" (or "on") and -snapshot supported. On Sparc32 target, Linux limits the number of usable CPUs to 4. -k language the guest when the data has been flushed to the disk using cache=directsync. sock_fd=sock_fd Specify boot order drives as a string of drive letters. Valid drive letters depend controls whether discard (also known as trim or unmap) requests Write to temporary files instead of disk image files. In this case, the rawdisk -machine [type=]name[,prop=value[,...]] For the PC target, the number of cores per socket, the number of threads per Use keyboard layout language (for example fr for French). This option is only -hda file Enables proxy filesystem driver to use passed socket descriptor for on the target architecture. The x86 PC uses: a, b (floppy 1 and 2), c (first hard are ignored or passed to the filesystem. Some machine types may In case you don’t care about data integrity over host failures, use cache=unsafe. image you use is not written back. You can however force the write back by Select the emulated machine by name. Use -machine help to list available cores and the total number of sockets can be specified. Missing values will be needed where it is not easy to get raw PC keycodes (e.g. on Macs, with some -hdb file communicating with virtfs-proxy-helper. Usually a helper like lib- This option tells QEMU that it never needs to write any data to the disk but pressing C-a s (see Section 3.6 [disk images], page 57). machines. Supported machine properties are: computed. If any on the three values is given, the total number of CPUs n can disk), d (first CD-ROM), n-p (Etherboot from network adapter 1-4), hard disk -hdc file not support discard requests. virt will create socketpair and pass one of the fds as sock fd X11 servers or with a VNC display). You don’t normally need to use it on can instead keep things in cache. If anything goes wrong, like your host losing be omitted. maxcpus specifies the maximum number of hotpluggable CPUs. boot is the default. To apply a particular boot order only on the first startup, -hdd file Use file as hard disk 0, 1, 2 or 3 image (see Section 3.6 [disk images], page 57). -hdachs c,h,s,[,t] accel=accels1[:accels2[:...]] PC/Linux or PC/Windows hosts. format=format power, the disk storage getting disconnected accidentally, etc. your image will -fsdev option is used along with -device driver "virtio-9p-pci". specify it via once. Force hard disk 0 physical geometry (1 <= c <= 16383, 1 <= h <= 16, 1 <= s This is used to enable an accelerator. Depending on the target -numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node] The available layouts are: -cdrom file Specify which disk format will be used rather than detecting the most probably be rendered unusable. When using the -snapshot option, unsafe Interactive boot menus/prompts can be enabled via menu=on as far as <= 63) and optionally force the BIOS translation mode (t=none, lba or auto). -device virtio-9p-pci,fsdev=id,mount_tag=mount_tag architecture, kvm, xen, or tcg can be available. By default, tcg is -numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node] ar de-ch es fo fr-ca hu ja mk no pt-br sv Use file as CD-ROM image (you cannot use -hdc and -cdrom at the same format. Can be used to specifiy format=raw to avoid interpreting caching is always used. firmware/BIOS supports them. The default is non-interactive boot. an untrusted format header. Usually QEMU can guess all those parameters. This option is useful for old Options for virtio-9p-pci driver are: used. If there is more than one accelerator specified, the next one Simulate a multi node NUMA system. If ‘mem’, ‘memdev’ and ‘cpus’ are omitted, da en-gb et fr fr-ch is lt nl pl ru th time). You can use the host CD-ROM by using /dev/cdrom as filename (see Copy-on-read avoids accessing the same backing file sectors repeatedly and is A splash picture could be passed to bios, enabling user to show it as logo, MS-DOS disk images. fsdev=id Specifies the id value specified along with -fsdev option is used if the previous one fails to initialize. resources are split equally. Also, note that the -numa option doesn’t allocate any de en-us fi fr-be hr it lv nl-be pt sl tr Section 3.6.7 [host drives], page 69). serial=serial useful when the backing file is over a slow network. By default copy-on-read is when option splash=sp name is given and menu=on, If firmware/BIOS sup- of the specified resources. That is, it just assigns existing resources toNUMA This option specifies the serial number to assign to the device. off. -fsdev fsdriver,id=id,path=path,[security_model=security_ mount_tag=mount_tag kernel_irqchip=on|off ports them. Currently Seabios for X86 system support it. limitation: The The default is en-us. -drive option[,option[,option[,...]]] nodes. This means that one still has to use the -m, -smp options to allocate model][,writeout=writeout][,readonly][,socket=socket|sock_fd=sock_fd] Specifies the tag name to be used by the guest to mount this export Enables in-kernel irqchip support for the chosen accelerator when splash file could be a jpeg file or a BMP file in 24 BPP format(true color). -audio-help Define a new drive. Valid options are: addr=addr Instead of -cdrom you can use: available. RAM and VCPUs respectively, and possibly -object to specify the memory Define a new file system device. Valid options are: point backend for the ‘memdev’ suboption. The resolution should be supported by the SVGA mode, so the recommended Will show the audio subsystem help: list of drivers, tunable parameters. file=file Specify the controller’s PCI address (if=virtio only). qemu-system-i386 -drive file=file,index=2,media=cdrom vmport=on|off|auto is 320x240, 640x480, 800x640. fsdriver This option specifies the fs driver backend to use. Currently "local", -virtfs fsdriver[,path=path],mount_tag=mount_tag[,security_model=security_ ‘mem’ and ‘memdev’ are mutually exclusive. Furthermore, if one node uses -soundhw card1[,card2,...] or -soundhw all This option defines which disk image (see Section 3.6 [disk images], werror=action,rerror=action Instead of -hda, -hdb, -hdc, -hdd, you can use: Enables emulation of VMWare IO port, for vmmouse etc. auto says "handle" and "proxy" file system drivers are supported. model][,writeout=writeout][,readonly][,socket=socket|sock_fd=sock_fd] ‘memdev’, all of them have to use it. A timeout could be passed to bios, guest will pause for rb timeout ms when Enable audio and selected sound hardware. Use ’help’ to print all available page 57) to use with this drive. If the filename contains comma, you Specify which action to take on write and read errors. Valid actions qemu-system-i386 -drive file=file,index=0,media=disk to select the value based on accel. For accel=xen the default is off The general form of a Virtual File system pass-through options are: boot failed, then reboot. If rb timeout is ’-1’, guest will not reboot, qemu passes sound hardware. must double it (for instance, "file=my,,file" to use file "my,file"). are: "ignore" (ignore the error and try to continue), "stop" (pause qemu-system-i386 -drive file=file,index=1,media=disk id=id Specifies identifier for this device otherwise the default is on. -add-fd fd=fd,set=set[,opaque=opaque] ’-1’ to bios by default. Currently Seabios for X86 system support it. qemu-system-i386 -soundhw sb16,adlib disk.img Special files such as iSCSI devices can be specified using protocol QEMU), "report" (report the error to the guest), "enospc" (pause qemu-system-i386 -drive file=file,index=2,media=disk fsdriver This option specifies the fs driver backend to use. Currently "local", Add a file descriptor to an fd set. Valid options are: path=path kvm_shadow_mem=size Do strict boot via strict=on as far as firmware/BIOS supports it. This only qemu-system-i386 -soundhw es1370 disk.img specific URLs. See the section for "Device URL Syntax" for more QEMU only if the host disk is full; report the error to the guest oth- qemu-system-i386 -drive file=file,index=3,media=disk Specifies the export path for the file system device. Files underthis "handle" and "proxy" file system drivers are supported. Defines the size of the KVM shadow MMU. fd=fd This option defines the file descriptor of which a duplicate isadded effects when boot priority is changed by bootindex options. The default is qemu-system-i386 -soundhw ac97 disk.img information. erwise). The default setting is werror=enospc and rerror=report. You can open an image using pre-opened file descriptors from an fd set: path will be available to the 9p client on the guest. id=id Specifies identifier for this device to fd set. The file descriptor cannot be stdin, stdout, or stderr. non-strict boot. qemu-system-i386 -soundhw hda disk.img dump-guest-core=on|off if=interface readonly Open drive file as read-only. Guest write attempts will fail. qemu-system-i386 security_model=security_model path=path # try to boot from network first, then from hard disk qemu-system-i386 -soundhw all disk.img Include guest memory in a core dump. The default is on. set=set This option defines the ID of the fd set to add the file descriptor This option defines on which type on interface the drive iscon- -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" Specifies the security model to be used for this export path. Specifies the export path for the file system device. Files underthis qemu-system-i386 -boot order=nc qemu-system-i386 -soundhw help copy-on-read=copy-on-read mem-merge=on|off to. nected. Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" Supported security models are "passthrough", "mapped-xattr", path will be available to the 9p client on the guest. # boot from CD-ROM first, switch back to default order after reboot Note that Linux’s i810 audio OSS kernel (for AC97) module might require copy-on-read is "on" or "off" and enables whether to copy read Enables or disables memory merge support. This feature, when -drive file=/dev/fdset/2,index=0,media=disk "mapped-file" and "none". In "passthrough" security model, files opaque=opaque qemu-system-i386 -boot once=d manually specifying clocking. bus=bus,unit=unit backing file sectors into the image file. security_model=security_model You can connect a CDROM to the slave of ide0: are stored using the same credentials as they are created on the supported by the host, de-duplicates identical memory pages among This option defines a free-form string that can be used to describe # boot with a splash picture for 5 seconds. These options define where is connected the drive by defining the Specifies the security model to be used for this export path. modprobe i810_audio clocking=48000 detect-zeroes=detect-zeroes guest. This requires QEMU to run as root. In "mapped-xattr" VMs instances (enabled by default). fd. qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 bus number and the unit id. qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom Supported security models are "passthrough", "mapped-xattr", detect-zeroes is "off", "on" or "unmap" and enables the automatic security model, some of the file attributes like uid, gid, mode bits -balloon none If you don’t specify the "file=" argument, you define an empty drive: "mapped-file" and "none". In "passthrough" security model, files iommu=on|off Note: The legacy format ’-boot drives’ is still supported but its use is discour- index=index conversion of plain zero writes by the OS to driver specific optimized and link target are stored as file attributes. For "mapped-file" You can open an image using pre-opened file descriptors from an fd set: Disable balloon device. are stored using the same credentials as they are created on the Enables or disables emulated Intel IOMMU (VT-d) support. The aged as it may be removed from future versions. This option defines where is connected the drive by using an index zero write commands. You may even choose "unmap" if discard is qemu-system-i386 -drive if=ide,index=1,media=cdrom these attributes are stored in the hidden .virtfs metadata default is off. qemu-system-i386 guest. This requires QEMU to run as root. In "mapped-xattr" -balloon virtio[,addr=addr] in the list of available connectors of a given interface type. set to "unmap" to allow a zero write to be converted to an UNMAP You can connect a SCSI disk with unit ID 6 on the bus #0: directory. Directories exported by this security model cannot -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" -m [size=]megs[,slots=n,maxmem=size] security model, some of the file attributes like uid, gid, mode bits aes-key-wrap=on|off Enable virtio balloon device (default), optionally with PCI address addr. operation. interact with other unix tools. "none" security model is same as -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" Sets guest startup RAM size to megs megabytes. Default is 128 MiB. Op- media=media qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6 and link target are stored as file attributes. For "mapped-file" Enables or disables AES key wrapping support on s390-ccw hosts. -device driver[,prop[=value][,...]] passthrough except the sever won’t report failures if it fails to set -drive file=/dev/fdset/2,index=0,media=disk tionally, a suffix of “M” or “G” can be used to signify a value in megabytes This option defines the type of the media: disk or cdrom. By default, the cache=writeback mode is used. It will report data writes as Instead of -fda, -fdb, you can use: these attributes are stored in the hidden .virtfs metadata This feature controls whether AES wrapping keys will be created file attributes like ownership. Security model is mandatory only or gigabytes respectively. Optional pair slots, maxmem could be used to set Add device driver. prop=value sets driver properties. Valid properties depend completed as soon as the data is present in the host page cache. This is safe as directory. Directories exported by this security model cannot to allow execution of AES cryptographic functions. The default is -set group.id.arg=value cyls=c,heads=h,secs=s[,trans=t] qemu-system-i386 -drive file=file,index=0,if=floppy for local fsdriver. Other fsdrivers (like handle, proxy) don’t take amount of hotpluggable memory slots and maximum amount of memory. Note on the driver. To get help on possible drivers and properties, use -device help long as your guest OS makes sure to correctly flush disk caches where needed. interact with other unix tools. "none" security model is same as on. Set parameter arg for item id of type group\n" These options have the same definition as they have in -hdachs. qemu-system-i386 -drive file=file,index=1,if=floppy security model as a parameter. that maxmem must be aligned to the page size. and -device driver,help. If your guest OS does not handle volatile disk write caches correctly and your passthrough except the sever won’t report failures if it fails to set By default, interface is "ide" and index is automatically incremented: dea-key-wrap=on|off -global driver.prop=value For example, the following command-line sets the guest startup RAM size to -name name snapshot=snapshot host crashes or loses power, then the guest may experience data corruption. writeout=writeout file attributes like ownership. Security model is mandatory only Enables or disables DEA key wrapping support on s390-ccw hosts. -global driver=driver,property=property,value=value 1GB, creates 3 slots to hotplug additional memory and sets the maximum Sets the name of the guest. This name will be displayed in the SDL window snapshot is "on" or "off" and controls snapshot mode for the given For such guests, you should consider using cache=writethrough. This means qemu-system-i386 -drive file=a -drive file=b" This is an optional argument. The only supported value is "imme- for local fsdriver. Other fsdrivers (like handle, proxy) don’t take This feature controls whether DEA wrapping keys will be created Set default value of driver’s property prop to value, e.g.: memory the guest can reach to 4GB: caption. The name will also be used for the VNC server. Also optionally set drive (see -snapshot). that the host page cache will be used to read and write data, but write notifi- is interpreted like: diate". This means that host page cache will be used to read and security model as a parameter.
Chapter 3: QEMU PC System emulator 14 Chapter 3: QEMU PC System emulator 15 Chapter 3: QEMU PC System emulator 16 Chapter 3: QEMU PC System emulator 17 Chapter 3: QEMU PC System emulator 18 Chapter 3: QEMU PC System emulator 19 Chapter 3: QEMU PC System emulator 20
writeout=writeout net:options -ctrl-grab x509-key-file= -spice option[,option[,...]] VESA 2.0 VBE support). Works best with qxl guest drivers in- Opens an additional TCP listening port dedicated to VNC mechanism. You may still wish to set a password on the VNC -sdl/-curses/... options. Valid values for type are Specify which ciphers to use. socket=socket Enable the spice remote desktop protocol. Valid options are stalled though. Recommended choice when using the spice proto- Websocket connections. By definition the Websocket port is server as a second authentication layer. The path following this sdl Display video output via SDL (usually in a separate graphics win- Enables proxy filesystem driver to use passed socket file for com- tls-channel=[main|display|cursor|inputs|record|playback] col. 5700+display. If host is specified connections will only be allowed option specifies where the x509 certificates are to be loaded from. dow; see the SDL documentation for other possibilities). port=
Chapter 3: QEMU PC System emulator 21 Chapter 3: QEMU PC System emulator 22 Chapter 3: QEMU PC System emulator 23 Chapter 3: QEMU PC System emulator 24 Chapter 3: QEMU PC System emulator 25 Chapter 3: QEMU PC System emulator 26 Chapter 3: QEMU PC System emulator 27
screen regions, and send updates in these regions using a lossy -smbios hostname=name hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport -netdev connections on port (host is optional). connect is used to connect to another Example (send packets from host’s 1.2.3.4): encoding (like JPEG). This can be really helpful to save bandwidth type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str] Specifies the client hostname reported by the built-in DHCP server. Redirect incoming TCP or UDP connections to the host port host- tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,helper=helper] QEMU instance using the listen option. fd=h specifies an already opened qemu-system-i386 linux.img \ when playing videos. Disabling adaptive encodings restores the Specify SMBIOS type 3 fields port to the guest IP address guestaddr on guest port guestport. If -net TCP socket. dhcpstart=addr -net nic,macaddr=52:54:00:12:34:56 \ original static behavior of encodings like Tight. guestaddr is not specified, its value is x.x.x.15 (default first address tap[,vlan=n][,name=name][,fd=h][,ifname=name][,script=file][,downscript=dfile][,helper=helper] -smbios type=4[,sock_ Specify the first of the 16 IPs the built-in DHCP server can assign. Example: -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 given by the built-in DHCP server). By specifying hostaddr, the Connect the host TAP network interface name to VLAN n. share=[allow-exclusive|force-shared|ignore] pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str] Default is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to # launch a first QEMU instance -netdev rule can be bound to a specific host interface. If no connection type Use the network script file to configure it and the network script dfile to de- Set display sharing policy. ’allow-exclusive’ allows clients to ask for Specify SMBIOS type 4 fields x.x.x.31. qemu-system-i386 linux.img \ l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset] exclusive access. As suggested by the rfb spec this is implemented is set, TCP is used. This option can be given multiple times. configure it. If name is not provided, the OS automatically provides one. The -smbios type=17[,loc_ -net nic,macaddr=52:54:00:12:34:56 \ -net by dropping other connections. Connecting multiple clients in par- dns=addr Specify the guest-visible address of the virtual nameserver. The default network configure script is /etc/qemu-ifup and the default network pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d] For example, to redirect host X11 connection from screen 1 to guest -net socket,listen=:1234 l2tpv3[,vlan=n][,name=name],src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset] allel requires all clients asking for a shared session (vncviewer: - address must be different from the host address. Default is the 3rd deconfigure script is /etc/qemu-ifdown. Use script=no or downscript=no to Specify SMBIOS type 17 fields screen 0, use the following: # connect the VLAN 0 of this instance to the VLAN 0 Connect VLAN n to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular shared switch). This is the default. ’force-shared’ disables exclusive IP in the guest network, i.e. x.x.x.3. disable script execution. # of the first instance # on the host protocol to transport Ethernet (and other Layer 2) data frames between two client access. Useful for shared desktop sessions, where you don’t Network options: If running QEMU as an unprivileged user, use the network helper helper qemu-system-i386 linux.img \ dnssearch=domain qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] systems. It is present in routers, firewalls and the Linux kernel (from version want someone forgetting specify -shared disconnect everybody else. to configure the TAP interface. The default network helper executable is -net nic,macaddr=52:54:00:12:34:57 \ -net nic[,vlan=n][,macaddr=mac][,model=type] Provides an entry for the domain-search list sent by the built-in # this host xterm should open in the guest X11 server 3.3 onwards). ’ignore’ completely ignores the shared flag and allows everybody /path/to/qemu-bridge-helper. -net socket,connect=127.0.0.1:1234 [,name=name][,addr=addr][,vectors=v] DHCP server. More than one domain suffix can be transmitted xterm -display :1 This transport allows a VM to communicate to another VM, router or firewall connect unconditionally. Doesn’t conform to the rfb spec but is Create a new Network Interface Card and connect it to VLAN n (n = 0 is the by specifying this option multiple times. If supported, this will fd=h can be used to specify the handle of an already opened host TAP interface. directly. traditional QEMU behavior. To redirect telnet connections from host port 5555 to telnet port -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]] default). The NIC is an e1000 by default on the PC target. Optionally, the cause the guest to automatically try to append the given domain Examples: on the guest, use the following: -net socket[,vlan=n][,name=name][,fd=h][,mcast=maddr:port[,localaddr=addr]] src=srcaddr i386 target only: MAC address can be changed to mac, the device address set to addr (PCI cards suffix(es) in case a domain name can not be resolved. #launch a QEMU instance with the default network script Create a VLAN n shared with another QEMU virtual machines using a UDP only), and a name can be assigned for use in monitor commands. Optionally, source address (mandatory) -win2k-hack Example: # on the host qemu-system-i386 linux.img -net nic -net tap multicast socket, effectively making a bus for every QEMU with same multicast for PCI cards, you can specify the number v of MSI-X vectors that the card qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] dst=dstaddr Use it when installing Windows 2000 to avoid a disk full bug. After Windows qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] #launch a QEMU instance with two NICs, each one connected address maddr and port. NOTES: should have; this option currently only affects virtio cards; set v = 0 to disable telnet localhost 5555 destination address (mandatory) 2000 is installed, you no longer need this option (this option slows down the #to a TAP device 1. Several QEMU can be running on different hosts and share same bus (as- MSI-X. If no -net option is specified, a single NIC is created. QEMU can tftp=dir When using the user mode network stack, activate a built-in TFTP IDE transfers). Then when you use on the host telnet localhost 5555, you con- qemu-system-i386 linux.img \ suming correct multicast setup for these hosts). udp select udp encapsulation (default is ip). emulate several different models of network card. Valid values for type are server. The files in dir will be exposed as the root of a TFTP server. -no-fd-bootchk virtio, i82551, i82557b, i82559er, ne2k_pci, ne2k_isa, pcnet, rtl8139, nect to the guest telnet server. -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 2. mcast support is compatible with User Mode Linux (argument srcport=srcport The TFTP client on the guest must be configured in binary mode -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 Disable boot signature checking for floppy disks in BIOS. May be needed to e1000, smc91c111, lance and mcf_fec. Not all devices are supported on all (use the command bin of the Unix TFTP client). ethN=mcast), see http://user-mode-linux.sf.net. source udp port. boot from old floppy disks. guestfwd=[tcp]:server:port-dev #launch a QEMU instance with the default network helper to targets. Use -net nic,model=help for a list of available devices for your target. 3. Use fd=h to specify an already opened UDP multicast socket. dstport=dstport bootfile=file guestfwd=[tcp]:server:port-cmd:command #connect a TAP device to bridge br0 -no-acpi Disable ACPI (Advanced Configuration and Power Interface) support. Use it -netdev user,id=id[,option][,option][,...] destination udp port. When using the user mode network stack, broadcast file as the Forward guest TCP connections to the IP address server on port qemu-system-i386 linux.img \ Example: if your guest OS complains about ACPI problems (PC target machine only). -net user[,option][,option][,...] BOOTP filename. In conjunction with tftp, this can be used to port to the character device dev or to a program executed by -net nic -net tap,"helper=/path/to/qemu-bridge-helper" # launch one QEMU instance ipv6 force v6, otherwise defaults to v4. -no-hpet Disable HPET support. Use the user mode network stack which requires no administrator privilege to cmd:command which gets spawned for each connection. This op- network boot a guest from a local directory. -netdev bridge,id=id[,br=bridge][,helper=helper] qemu-system-i386 linux.img \ run. Valid options are: tion can be given multiple times. rxcookie=rxcookie -acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n] Example (using pxelinux): -net bridge[,vlan=n][,name=name][,br=bridge][,helper=helper] -net nic,macaddr=52:54:00:12:34:56 \ txcookie=txcookie [,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...] vlan=n Connect user mode stack to VLAN n (n = 0 is the default). -net socket,mcast=230.0.0.1:1234 qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 You can either use a chardev directly and have that one used Connect a host TAP network interface to a host bridge device. Cookies are a weak form of security in the l2tpv3 specification. Their function Add ACPI table with specified header fields and context from specified files. # launch another QEMU instance on same "bus" id=id throughout QEMU’s lifetime, like in the following example: Use the network helper helper to configure the TAP interface and attach itto is mostly to prevent misconfiguration. By default they are 32 bit. For file=, take whole ACPI table from the specified files, including allACPI smb=dir[,smbserver=addr] qemu-system-i386 linux.img \ name=name # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever the bridge. The default network helper executable is /path/to/qemu-bridge- headers (possible overridden by other options). For data=, only data portion When using the user mode network stack, activate a built-in SMB -net nic,macaddr=52:54:00:12:34:57 \ cookie64 Set cookie size to 64 bit instead of the default 32 Assign symbolic name for use in monitor commands. # the guest accesses it helper and the default bridge device is br0. of the table is used, all header information is specified in the command line. server so that Windows OSes can access to the host files in dir -net socket,mcast=230.0.0.1:1234 counter=off net=addr[/mask] qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] Examples: transparently. The IP address of the SMB server can be set to addr. # launch yet another QEMU instance on same "bus" Force a ’cut-down’ L2TPv3 with no counter as in draft-mkonstan-l2tpext-keyed- -smbios file=binary Set IP network address the guest will see. Optionally specify the By default the 4th IP in the guest network is used, i.e. x.x.x.4. Or you can execute a command on every TCP connection estab- #launch a QEMU instance with the default network helper to qemu-system-i386 linux.img \ ipv6-tunnel-00 Load SMBIOS entry from binary file. netmask, either in the form a.b.c.d or as number of valid top-most lished by the guest, so that QEMU behaves similar to an inetd #connect a TAP device to bridge br0 -net nic,macaddr=52:54:00:12:34:58 \ bits. Default is 10.0.2.0/24. In the guest Windows OS, the line: pincounter=on -smbios process for that virtual server: qemu-system-i386 linux.img -net bridge -net nic,model=virtio -net socket,mcast=230.0.0.1:1234 10.0.2.4 smbserver Work around broken counter handling in peer. This may also help on networks type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off] host=addr #launch a QEMU instance with the default network helper to # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 Example (User Mode Linux compat.): which have packet reorder. Specify SMBIOS type 0 fields Specify the guest-visible address of the host. Default is the 2nd IP must be added in the file C:\WINDOWS\LMHOSTS (for windows #connect a TAP device to bridge qemubr0 # and connect the TCP stream to its stdin/stdout # launch QEMU instance (note mcast address selected 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows offset=offset -smbios in the guest network, i.e. x.x.x.2. qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio # is UML’s default) NT/2000). qemu -net ’user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321’ type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str] restrict=on|off -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port] qemu-system-i386 linux.img \ Add an extra offset between header and data Specify SMBIOS type 1 fields If this option is enabled, the guest will be isolated, i.e. it will not be Then dir can be accessed in \\smbserver\qemu. Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still pro- -net socket[,vlan=n][,name=name][,fd=h] -net nic,macaddr=52:54:00:12:34:56 \ For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge -smbios able to contact the host and no guest IP packets will be routed over Note that a SAMBA server must be installed on the host OS. cessed and applied to -net user. Mixing them with the new configuration syntax [,listen=[host]:port][,connect=host:port] -net socket,mcast=239.192.168.1:1102 br-lan on the remote Linux host 1.2.3.4: type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str][,family=str] the host to the outside. This option does not affect any explicitly QEMU was tested successfully with smbd versions from Red Hat gives undefined results. Their use for new applications is discouraged asthey Connect the VLAN n to a remote VLAN in another QEMU virtual machine us- # launch UML # Setup tunnel on linux host using raw ip as encapsulation Specify SMBIOS type 2 fields set forwarding rules. 9, Fedora Core 3 and OpenSUSE 11.x. will be removed from future versions. ing a TCP socket connection. If listen is specified, QEMU waits for incoming /path/to/linux ubd0=/path/to/root_fs eth0=mcast # on 1.2.3.4
Chapter 3: QEMU PC System emulator 28 Chapter 3: QEMU PC System emulator 29 Chapter 3: QEMU PC System emulator 30 Chapter 3: QEMU PC System emulator 31 Chapter 3: QEMU PC System emulator 32 Chapter 3: QEMU PC System emulator 33 Chapter 3: QEMU PC System emulator 34 Chapter 3: QEMU PC System emulator 35 Chapter 3: QEMU PC System emulator 36
ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ -device virtio-net-pci,netdev=net0 host is optional for listening sockets. If not specified it defaults path specifies the path of the file to be opened. This file will be created ifit -chardev spicevmc ,id=id ,debug=debug, name=name NBD QEMU supports NBD (Network Block Devices) both using TCP protocol as password Optional password for authentication to the remote server. when emulating a machine with only one HCI built into it, only the first -bt path specifies the path to the host’s TPM device, i.e., on a Linux hostthis encap udp udp_sport 16384 udp_dport 16384 to 0.0.0.0. does not already exist, and overwritten if it does. path is required. spicevmc is only available when spice support is built in. well as Unix Domain Sockets. hci[...] option is valid and defines the HCI’s logic. The Transport Layer is would be /dev/tpm0. path is optional and by default /dev/tpm0 is used. -net dump[,vlan=n][,file=file][,len=len] host Address of the remote server. ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ decided by the machine type. Currently the machines n800 and n810 have one Dump network traffic on VLAN n to file file (qemu-vlan0.pcap by default). port for a listening socket specifies the local port to be bound. For -chardev pipe ,id=id ,path=path debug debug level for spicevmc Syntax for specifying a NBD device using TCP “nbd:
Chapter 3: QEMU PC System emulator 37 Chapter 3: QEMU PC System emulator 38 Chapter 3: QEMU PC System emulator 39 Chapter 3: QEMU PC System emulator 40 Chapter 3: QEMU PC System emulator 41 Chapter 3: QEMU PC System emulator 42 Chapter 3: QEMU PC System emulator 43 Chapter 3: QEMU PC System emulator 44 Chapter 3: QEMU PC System emulator 45
This option can be used several times to simulate up to 4 serial ports. QEMU Options: -serial mon:telnet::4444,server,nowait (gdb) target remote | exec qemu-system-i386 -gdb stdio ... or Windows. To start at a specific point in time, provide date in the format diag288 A virtual watchdog for s390x backed by the diagnose 288 hypercall -incoming defer -writeconfig file filesystem mount. The share boolean option determines whether -serial udp::4555@:4556 2006-06-17T16:01:21 or 2006-06-17. The default base is UTC. (currently KVM only). Wait for the URI to be specified via migrate incoming. The monitor can be Write device configuration to file. The file can be either filename to save com- the memory region is marked as private to QEMU, or shared. The Use -serial none to disable all serial ports. When the monitor is multiplexed to stdio in this way, Ctrl+C will -s Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 (see used to change settings (such as migration parameters) prior to issuing the mand line and device configuration into file or dash -) character to print the latter allows a co-operating external process to access the QEMU Available character devices are: netcat options: not terminate QEMU any more but will be passed to the guest Section 3.12 [gdb usage], page 83). By default the RTC is driven by the host system time. This allows using of the -watchdog-action action migrate incoming to allow the migration to begin. output to stdout. This can be later used as input file for -readconfig option. memory region. -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T instead. RTC as accurate reference clock inside the guest, specifically if the host time is The action controls what QEMU will do when the watchdog timer expires. vc[:WxH] Virtual console. Optionally, a width and height can be given in -d item1[,...] smoothly following an accurate external reference clock, e.g. via NTP. If you The default is reset (forcefully reset the guest). Other possible actions are: -nodefaults -nodefconfig -object rng-random,id=id,filename=/dev/random pixel with telnet options: braille Braille device. This will use BrlAPI to display the braille output Enable logging of specified items. Use ’-d help’ for a list of log items. want to isolate the guest time from the host, you can set clock to rt instead. shutdown (attempt to gracefully shutdown the guest), poweroff (forcefully Don’t create default devices. Normally, QEMU sets the default devices like Normally QEMU loads configuration files from sysconfdir and datadir at Creates a random number generator backend which obtains entropy vc:800x600 localhost 5555 on a real or fake device. -D logfile To even prevent it from progressing during suspension, you can set it to vm. poweroff the guest), pause (pause the guest), debug (print a debug message serial port, parallel port, virtual console, monitor device, VGA adapter, floppy startup. The -nodefconfig option will prevent QEMU from loading any of from a device on the host. The id parameter is a unique ID that msmouse Three button serial mouse. Configure the guest to use Microsoft It is also possible to specify width or height in characters: tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds] Output log in logfile instead of to stderr Enable driftfix (i386 targets only) if you experience time drift problems, and continue), or none (do nothing). and CD-ROM drive and others. The -nodefaults option will disable all those those config files. will be used to reference this entropy backend from the virtio-rng protocol. vc:80Cx24C The TCP Net Console has two modes of operation. It can send the specifically with Windows’ ACPI HAL. This option will try to figure outhow default devices. device. The filename parameter specifies which file to obtain en- -L path Set the directory for the BIOS, VGA BIOS and keymaps. Note that the shutdown action requires that the guest responds to ACPI sig- -no-user-config serial I/O to a location or wait for a connection from a location. By -parallel dev many timer interrupts were not processed by the Windows guest and will re- tropy from and if omitted defaults to /dev/random. pty [Linux only] Pseudo TTY (a new PTY is automatically allocated) nals, which it may not be able to do in the sort of situations where the watch- -chroot dir The -no-user-config option makes QEMU not load any of the user-provided default the TCP Net Console is sent to host at the port. If you use Redirect the virtual parallel port to host device dev (same devices as the serial -bios file inject them. dog would have expired, and thus -watchdog-action shutdown is not recom- Immediately before starting guest execution, chroot to the specified directory. config files on sysconfdir, but won’t make it skip the QEMU-provided config -object rng-egd,id=id,chardev=chardevid none No device is allocated. the server option QEMU will wait for a client socket application port). On Linux hosts, /dev/parportN can be used to use hardware devices Set the filename for the BIOS. -icount [shift=N|auto] mended for production use. Especially useful in combination with -runas. files from datadir. Creates a random number generator backend which obtains entropy null void device to connect to the port before continuing, unless the nowait option connected on the corresponding host parallel port. -enable-kvm Enable virtual instruction counter. The virtual cpu will execute one instruction Examples: from an external daemon running on the host. The id parameter was specified. The nodelay option disables the Nagle buffering -runas user -trace [events=file][,file=file] chardev:id This option can be used several times to simulate up to 3 parallel ports. Enable KVM full virtualization support. This option is only available if KVM every 2^N ns of virtual time. If auto is specified then the virtual cpu speed is a unique ID that will be used to reference this entropy backend algorithm. The reconnect option only applies if noserver is set, if -watchdog i6300esb -watchdog-action pause Immediately before starting guest execution, drop root privileges, switching to Specify tracing options. Use a named character device defined with the -chardev option. Use -parallel none to disable all parallel ports. support is enabled when compiling. will be automatically adjusted to keep virtual time within a few seconds of real from the virtio-rng device. The chardev parameter is the unique the connection goes down it will attempt to reconnect at the given -watchdog ib700 the specified user. time. events=file ID of a character device backend that provides the connection to /dev/XXX [Linux only] Use host tty, e.g. /dev/ttyS0. The host serial port interval. If host is omitted, 0.0.0.0 is assumed. Only one TCP -monitor dev -xen-domid id -echr numeric_ascii_value -prom-env variable=value Immediately enable events listed in file. The file must contain one the RNG daemon. parameters are set according to the emulated ones. connection at a time is accepted. You can use telnet to connect Redirect the monitor to host device dev (same devices as the serial port). The Specify xen guest domain id (XEN only). When the virtual cpu is sleeping, the virtual time will advance at default speed Change the escape character used for switching to the monitor when using mon- Set OpenBIOS nvram variable to given value (PPC, SPARC only). default device is vc in graphical mode and stdio in non graphical mode. Use unless sleep=no is specified. With sleep=no, the virtual time will jump to event name (as listed in the trace-events file) per line. This option /dev/parportN to the corresponding character device. -xen-create itor and serial sharing. The default is 0x01 when using the -nographic option. -monitor none to disable the default monitor. the next timer deadline instantly whenever the virtual cpu goes to sleep mode -semihosting is only available if QEMU has been compiled with either simple or [Linux only, parallel port only] Use host parallel port N. Currently Example to send tcp console to 192.168.0.2 port 4444 Create domain using xen hypercalls, bypassing xend. Warning: should not be 0x01 is equal to pressing Control-a. You can select a different character from and will not advance if no timer is enabled. This behavior give deterministic Enable semihosting mode (ARM, M68K, Xtensa, MIPS only). stderr tracing backend. SPP and EPP parallel port features can be used. -serial tcp:192.168.0.2:4444 -qmp dev Like -monitor but opens in ’control’ mode. used when xend is in use (XEN only). execution times from the guest point of view. the ascii control keys where 1 through 26 map to Control-a through Control- z. For instance you could use the either of the following to change the escape -semihosting-config file=file file:filename Example to listen and wait on port 4444 for connection -qmp-pretty dev -xen-attach Note that while this option can give deterministic behavior, it does not provide character to Control-t. [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] Log output traces to file. Write output to filename. No character can be read. -serial tcp::4444,server Like -qmp but uses pretty JSON formatting. Attach to existing xen domain. xend will use this when starting QEMU (XEN cycle accurate emulation. Modern CPUs contain superscalar out of order cores Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only). This option is only available if QEMU has been compiled with the only). with complex cache hierarchies. The number of instructions executed often has -echr 0x14 stdio [Unix only] standard input/output Example to not wait and listen on ip 192.168.0.100 port -mon [chardev=]name[,mode=readline|control][,default] simple tracing backend. little or no correlation with actual performance. -echr 20 target=native|gdb|auto 4444 Setup monitor on chardev name. -no-reboot pipe:filename Defines where the semihosting calls will be addressed, toQEMU -enable-fips -serial tcp:192.168.0.100:4444,server,nowait Exit instead of rebooting. align=on will activate the delay algorithm which will try to to synchronise the -virtioconsole c name pipe filename -debugcon dev (native) or to GDB (gdb). The default is auto, which means gdb Enable FIPS 140-2 compliance mode. host clock and the virtual clock. The goal is to have a guest running at the Set virtio console. telnet:host:port[,server][,nowait][,nodelay] Redirect the debug console to host device dev (same devices as the serial port). -no-shutdown COMn [Windows only] Use host serial port n real frequency imposed by the shift option. Whenever the guest clock is behind during debug sessions and native otherwise. -msg timestamp[=on|off] The telnet protocol is used instead of raw tcp sockets. The options The debug console is an I/O port which is typically port 0xe9; writing to that Don’t exit QEMU on guest shutdown, but instead only stop the emulation. This option is maintained for backward compatibility. udp:[remote_host]:remote_port[@[src_ip]:src_port] the host clock and if align=on is specified then we print a message to the user arg=str1,arg=str2,... prepend a timestamp to each log message.(default:on) work the same as if you had specified -serial tcp. The difference I/O port sends output to this device. The default device is vc in graphical This allows for instance switching to monitor to commit changes to the disk Please use -device virtconsole for the new way of invocation. This implements UDP Net Console. When remote host or src ip to inform about the delay. Currently this option does not work when shift is Allows the user to pass input arguments, and can be used mul- is that the port acts like a telnet server or client using telnet option mode and stdio in non graphical mode. image. -dump-vmstate file are not specified they default to 0.0.0.0. When not using a spec- auto. Note: The sync algorithm will work for those shift values for which the -show-cursor tiple times to build up a list. The old-style -kernel/-append negotiation. This will also allow you to send the MAGIC SYSRQ Dump json-encoded vmstate information for current machine type to file in file ified src port a random port is automatically chosen. -pidfile file -loadvm file guest clock runs ahead of the host clock. Typically this happens when the shift Show cursor. method of passing a command line is still supported for back- sequence if you use a telnet that supports sending the break se- Generic object creation Store the QEMU process PID in file. It is useful if you launch QEMU from a Start right away with a saved state (loadvm in monitor) value is high (how high depends on the host machine). ward compatibility. If both the --semihosting-config arg and If you just want a simple readonly console you can use netcat or quence. Typically in unix telnet you do it with Control-] and then -tb-size n script. the -kernel/-append are specified, the former is passed to semi- -object typename[,prop1=value1,...] nc, by starting QEMU with: -serial udp::4555 and nc as: nc -u type "send break" followed by pressing the enter key. -daemonize -watchdog model Set TB size. hosting as it always takes precedence. Create a new object of type typename setting properties in the order they are -l -p 4555. Any time QEMU writes something to that port it will -singlestep Daemonize the QEMU process after initialization. QEMU will not detach from Create a virtual hardware watchdog device. Once enabled (by a guest action), unix:path[,server][,nowait][,reconnect=seconds] -incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6] specified. Note that the ’id’ property must be set. These objects are placed in appear in the netconsole session. Run the emulation in single step mode. standard IO until it is ready to receive connections on any of its devices. This the watchdog must be periodically polled by an agent inside the guest or else -old-param A unix domain socket is used instead of a tcp socket. The option -incoming rdma:host:port[,ipv4][,ipv6] the ’/objects’ path. If you plan to send characters back via netconsole or you want to option is a useful way for external programs to launch QEMU without having the guest will be restarted. Choose a model for which your guest has drivers. Old param mode (ARM only). works the same as if you had specified -serial tcp except the unix -S Do not start CPU at startup (you must type ’c’ in the monitor). Prepare for incoming migration, listen on a given tcp port. stop and start QEMU a lot of times, you should have QEMU use to cope with initialization race conditions. The model is the model of hardware watchdog to emulate. Use -watchdog -object domain socket path is used for connections. -realtime mlock=on|off -sandbox arg the same source port each time by using something like -serial help to list available hardware models. Only one watchdog can be enabled for -incoming unix:socketpath memory-backend-file,id=id,size=size,mem-path=dir,share=on|off Run qemu with realtime features. mlocking qemu and guest memory can be -option-rom file Enable Seccomp mode 2 system call filter. ’on’ will enable syscall filtering and udp::4555@:4556 to QEMU. Another approach is to use a patched mon:dev_string a guest. Prepare for incoming migration, listen on a given unix socket. Creates a memory file backend object, which can be used to back mlock=on Load the contents of file as an option ROM. This option is useful to load things ’off’ will disable it. The default is ’off’. version of netcat which can listen to a TCP port and send and This is a special option to allow the monitor to be multiplexed onto enabled via (enabled by default). the guest RAM with huge pages. The id parameter is a unique like EtherBoot. The following models may be available: -incoming fd:fd receive characters via udp. If you have a patched version of netcat another serial port. The monitor is accessed with key sequence of -gdb dev Wait for gdb connection on device dev (see Section 3.12 [gdb usage], page 83). -readconfig file ID that will be used to reference this memory region when con- Accept incoming migration from a given filedescriptor. which activates telnet remote echo and single char transfer, then Control-a and then pressing c. dev string should be any one of Typical connections will likely be TCP-based, but also UDP, pseudo TTY, or -rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew] ib700 iBASE 700 is a very simple ISA watchdog with a single timer. Read device configuration from file. This approach is useful when you want to figuring the -numa argument. The size option provides the size you can use the following options to step up a netcat redirector to the serial devices specified above. An example to multiplex the even stdio are reasonable use case. The latter is allowing to start QEMU from Specify base as utc or localtime to let the RTC start at the current UTC i6300esb Intel 6300ESB I/O controller hub is a much more featureful PCI- -incoming exec:cmdline spawn QEMU process with many command line options but you don’t want to of the memory region, and accepts common suffixes, eg 500M. The allow telnet on port 5555 to access the QEMU port. monitor onto a telnet server listening on port 4444 would be: within gdb and establish the connection via a pipe: or local time, respectively. localtime is required for correct date in MS-DOS based dual-timer watchdog. Accept incoming migration as an output from specified external command. exceed the command line character limit. mem-path provides the path to either a shared memory or huge page This is how it’s used in anger
$ /usr/bin/qemu-system-x86_64 -machine accel=kvm -name boxes-unknown -S -machine pc-i440fx-1.6,accel=kvm,usb=off -cpu \ Penryn -m 3115 -realtime mlock=off -smp 4,sockets=1,cores=4,threads=1 -uuid 8bd53789-adab-484f-8c53-a6df9d5f1dbf -no-u\ ser-config -nodefaults -chardev socket,id=charmonitor,path=/home/guillaume/.config/libvirt/qemu/lib/boxes-unknown.moni\ tor,server,nowait -mon chardev=charmonitor,id=monitor,mode=control -rtc base=utc,driftfix=slew -global kvm-pit.lost_ti\ ck_policy=discard -no-shutdown -global PIIX4_PM.disable_s3=1 -global PIIX4_PM.disable_s4=1 -boot strict=on -device ich\ 9-usb-ehci1,id=usb,bus=pci.0,addr=0x5.0x7 -device ich9-usb-uhci1,masterbus=usb.0,firstport=0,bus=pci.0,multifunction=o\ n,addr=0x5 -device ich9-usb-uhci2,masterbus=usb.0,firstport=2,bus=pci.0,addr=0x5.0x1-device ich9-usb-uhci3,masterbus=u\ sb.0,firstport=4,bus=pci.0,addr=0x5.0x2 -device virtio-serial-pci,id=virtio-serial0,bus=pci.0,addr=0x6 -device usb-cci\ d,id=ccid0 -drive file=/home/guillaume/.local/share/gnome-boxes/images/boxes-unknown,if=none,id=drive-ide0-0-0,format=\ qcow2,cache=none -device ide-hd,bus=ide.0,unit=0,drive=drive-ide0-0-0,id=ide0-0-0,bootindex=1 -drive if=none,id=drive-\ ide0-1-0,readonly=on,format=raw -device ide-cd,bus=ide.1,unit=0,drive=drive-ide0-1-0,id=ide0-1-0 -netdev tap,fd=23,id=\ hostnet0 -device rtl8139,netdev=hostnet0,id=net0,mac=52:54:00:db:56:54,bus=pci.0,addr=0x3 -chardev spicevmc,id=charsma\ rtcard0,name=smartcard -device ccid-card-passthru,chardev=charsmartcard0,id=smartcard0,bus=ccid0.0 -chardev pty,id=cha\ rserial0 -device isa-serial,chardev=charserial0,id=serial0 -chardev spicevmc,id=charchannel0,name=vdagent -device virt\ serialport,bus=virtio-serial0.0,nr=1,chardev=charchannel0,id=channel0,name=com.redhat.spice.0 -device usb-tablet,id=in\ put0 -spice port=5901,addr=127.0.0.1,disable-ticketing,image-compression=off,seamless-migration=on -device qxl-vga,id=\ video0,ram_size=67108864,vram_size=67108864,vgamem_mb=16,bus=pci.0,addr=0x2 -device AC97,id=sound0,bus=pci.0,addr=0x4 \ -chardev spicevmc,id=charredir0,name=usbredir -device usb-redir,chardev=charredir0,id=redir0 -chardev spicevmc,id=char\ redir1,name=usbredir -device usb-redir,chardev=charredir1,id=redir1 -chardev spicevmc,id=charredir2,name=usbredir -dev\ ice usb-redir,chardev=charredir2,id=redir2 -chardev spicevmc,id=charredir3,name=usbredir -device usb-redir,chardev=cha\ rredir3,id=redir3 -incoming fd:20 -device virtio-balloon-pci,id=balloon0,bus=pci.0,addr=0x7 -msg timestamp=on QMP is even bigger 126 commands + 33 events More than 700 named arguments and results Defined in the (book-sized) QAPI/QMP schema
qemu-doc.texi Gospel of Luke QMP schema Genesis 0 5 10 15 20 25 30 #words [thousands] Command line evolves fast
45 450
40 400 -help
35 350 Lines in
Pages in manual +20% p.a. 30 300
1.6 1.7 2.0 2.1 2.2 2.3 2.4 2013-08 2015-08 QMP evolves faster
22,000 20,000 18,000 +25% p.a.! 160 16,000 140 14,000 Words in Schema
Commands + Events 120 12,000
1.6 1.7 2.0 2.1 2.2 2.3 2.4 2013-08 2015-08 Why interface introspection?
QEMU provides big, rapidly evolving interfaces A program can Tie to a specific build of QEMU Wrong talk, you can break for coffee now Figure out what the QEMU it got can do Easiest when interfaces support introspection Trouble is our interfaces don’t fully support it, yet Part II Prior work Version numbers? QEMU says 0.12.1, but. . .
Upstream 800 150 RHEL-6
+250% 600 -help 100 400
50 Lines in
Commands + Events +35% 200
base 6.0 6.1 6.2 6.3 6.4 6.5 6.6 6.7 2009-12 2015-06 Backports make the upstream version meaningless Downstream version?
We provide for downstreams adding their version But: not always stepped Downstream version often meaningless, too Even if it wasn’t: #downstreams × #releases = heaps of versions Upstream wise guy shrugs “downstream problem” Version numbers insufficient!
Upstream 2.4 development cycle:
$ git-diff --shortstat v2.3.0..v2.4.0 1414 files changed, 72635 insertions(+), 25875 deletions(-) $ git-log --oneline v2.3.0..v2.4.0 | wc -l 2147 Version for 1901 out of 2147 commits: 2.3.50 Development can’t wait for the version to change! Upstream wise guy gets enlightened Just try to use it
Workable in simple cases Example: libvirt tries QMP inject-nmi, falls back to old HMP nmi Complex, slow, fragile in not so simple cases Recovery may need to recognize exact error Probe by trying may need complex scaffolding Probe must avoid unwanted effects A real-world failure of “just try” block-commit new in v1.3, and libvirt just tried it: Run block-commit, and if it succeeds wait for event BLOCK_JOB_COMPLETED Before v2.0, block-commit fails for active layer Since then, it succeeds, but requires manual block-job-complete to complete
Old libvirt hangs on BLOCK_JOB_COMPLETED Relying on behaviour in error cases is fragile Pretend to be human: read help
Examples: -help -device help -device virtio-net,help -drive format=help Drawbacks: Parsing help is painful and fragile Help text becomes de facto ABI Help is incomplete (e.g. no -drive if=help) Everyone did this until QEMU grew real interfaces QMP query-commands
Example:
QMP> { "execute":"query-commands" } { "return":[ ... { "name":"eject" }, ... ]}
This is very limited QMP interface introspection: can check presence of commands silent on arguments & results Plenty useful, but we need arguments & results now QMP query-command-line-options
Example:
QMP> { "execute":"query-command-line-options" } { "return":[ ... { "option":"memory", "parameters":[ { "name":"slots", "type":"number" }, { "name":"size", "type":"size" } ], ... }]}
This tries to be command line introspection What’s wrong with it? Dear God, where to begin! query-c-l-options is incomplete
missing, inessential complete
name wrong some parameters
no parameters
missing, no excuse
Probably better than nothing Certainly less than needed query-c-l-options is inexpressive
Things we’d like to know, but it can’t tell: Formats supported by -drive? It only tells us parameter format is “string” Parameters supported with -chardev socket? It tells us parameters supported by any backend Structural weaknesses Worse than merely incomplete Look for a witness
Example: how libvirt probes for -spice New in v0.14 No query-command-line-options back then With -spice, we added QMP query-spice Can probe that one with query-commands Use query-spice as a witness for -spice Useful when direct probe is impractical and a suitable witness exists Add an ad hoc query command
9 ♣ 8 ♣ ♥ 7 DeckDeckDeckDeckDeck of of of of of chardev- ♠ 6 7 backends♥ 8 6 definitions 9 ♠ dump-guest- ♣ ♠♠ 5 ♦ ♣ ♥ 4 cpu- 5 ♥ ♦ ♣ capability memory-♦ ♦♣♥ 3 ♣♣
♥♠ 2 4
kvm
♥machines ♥
♣ ♦
♣ ♠
capabilities 3
♥ ♥
9
migrate-
backends ♠
kvm
chardev- ♦ ♣ capability tpm-models 8 memory- ♥
♠ 2
♠ QueriesQueriesQueries
♣ ♥ ♠
dump-guest- ♦
cpu-definitions machines
7 ♦ ♦ ♦
♠ migrate-
♦
9
tpm-types
8
capabilities♣ ♣ 6 7
♣
♥ ♥ ♣
6 tpm-models
tpm-types
5
♥ ♠
5
4 ♥ ♦
3
♠
2
4 ♦
♠ Got several already
3
♦ How many more? 2 Add an ad hoc query command
9 ♣ 8 JOKER ♣ ♥ 7 chardev- ♠ 6 7 backends♥ 8 6 definitions 9 ♠ dump-guest- ♣ ♠♠ 5 ♦ ♣ ♥ 4 cpu- 5 ♥ ♦ ♣ capability memory-♦ ♦♣♥ 3 ♣♣
♥♠ 2 4
kvm
♥machines ♥
♣ ♦
♣ ♠
capabilities 3
♥ ♥
9
migrate-
backends ♠
kvm
chardev- ♦ ♣ capability tpm-models 8 memory- ♥
♠ 2 ♠
JOKER
♣ ♥ ♠
dump-guest- ♦
cpu-definitions machines
7 ♦ ♦ ♦
♠ migrate-
♦
9
tpm-types
8
capabilities♣ ♣ 6 7
♣
♥ ♥ ♣
6 tpm-models
tpm-types
5
♥ ♠
5
4 ♥ ♦
3
♠
2
4 ♦
♠ Got several already
3 ♦ How many more?
2 Can we get a joker instead? Where do we stand now?
Current introspection solutions work, but won’t cut it much longer: query-command-line-options too incomplete and inexpressive query-commands too limited we need arguments & results Adding a query-FOO for every FOO will result in a mess Time to crack QMP introspection for real! Part III QMP Introspection The basic idea
Interface introspection turns interface into data QMP is defined by QAPI schema Schema is data, so let clients query for it! However: Geared towards humans, not machines Mixes up ABI aspects and internal detail Instead of simply dumping QAPI schema: Expose only its QMP wire ABI aspects Design query output for machines Cooking: query-schema Coming in v2.5:
QMP> { "execute":"query-schema" } {"return":[ ... {"name": "eject", ... ]}
Exposes QMP wire ABI as defined in the schema: Commands, events with arguments & results Arguments & results fully typed Enumerations (find supported values) Variants records ... By yours truly, with heaps of help from Eric Blake Let’s introspect a command
QAPI Schema for query-block:
{ ’command’: ’query-block’, ’returns’: [’BlockInfo’] } Relevant part of query-schema’s return:
{ "name":"query-block", "meta-type":"command", "arg-type":"15", "ret-type":"101" }, { "name":"15", "meta-type":"object", "members":[] }, { "name":"101", "meta-type":"array", "element-type":"183" } Let’s introspect a command
QAPI Schema for query-block:
{ ’command’: ’query-block’’query-block’, ’returns’: [’BlockInfo’] } Relevant part of query-schema’s return: { "name":"query-block""name":"query-block", “query-block” "meta-type":"command""meta-type":"command", is a command "arg-type":"15", "ret-type":"101" }, { "name":"15", "meta-type":"object", "members":[] }, { "name":"101", "meta-type":"array", "element-type":"183" } Let’s introspect a command
QAPI Schema for query-block:
{ ’command’: ’query-block’, # no arguments ’returns’: [’BlockInfo’] } Relevant part of query-schema’s return: { "name":"query-block",It has an empty argument type "meta-type":"command",(normalized from no arguments) "arg-type":"15""arg-type":"15", "ret-type":"101" }, { "name":"15", "meta-type":"object", "members":[] }, { "name":"101", "meta-type":"array", "element-type":"183" } Let’s introspect a command
QAPI Schema for query-block:
{ ’command’: ’query-block’, ’returns’: [’BlockInfo’] } Relevant part of query-schema’s return:
{ "name":"query-block", "meta-type":"command", "arg-type":"15", "ret-type":"101" }, { "name":"15", "meta-type":"object", "members":[] }, Return type is array of BlockInfo { "name":"101", "meta-type":"array", "element-type":"183" } Let’s introspect a command
QAPI Schema for query-block:
{ ’command’: ’query-block’, ’returns’: [’BlockInfo’] } Relevant part of query-schema’s return:
{ "name":"query-block", "meta-type":"command", "arg-type":"15", "ret-type":"101" }, { "name":"15", "meta-type":"object", "members":[] }, Type name { "name":"101", "meta-type":"array",’BlockInfo’ masked "element-type":"183" } (not ABI) Let’s introspect a command
QAPI Schema for query-block:
{ ’command’: ’query-block’, ’returns’: [’BlockInfo’] } Relevant part of query-schema’s return:
{ "name":"query-block", "meta-type":"command",Tediously explicit "arg-type":"15", "ret-type":"101" }, { "name":"15", "meta-type":"object", "members":[] }, { "name":"101", "meta-type":"array", "element-type":"183" } Let’s introspect introspection! Like query-block, QAPI Schema for query-schema: with SchemaInfo { ’command’: ’query-schema’, instead of ’returns’: [’SchemaInfo’’SchemaInfo’] } BlockInfo Relevant part of query-schema’s return:
{ "name":"query-schema", "meta-type":"command", "arg-type":"15", "ret-type":"129" }, { "name":"15", "meta-type":"object", "members":[] }, { "name":"129", "meta-type":"array", "element-type":"203" } Drill down into SchemaInfo
{ ’union’: ’SchemaInfo’, ’base’: ’SchemaInfoBase’, ’discriminator’: ’meta-type’, ’data’: { ’command’: ’SchemaInfoCommand’, ’enum’: ’SchemaInfoEnum’, ’object’: ’SchemaInfoObject’, ... }} { ’struct’: ’SchemaInfoBase’, ’data’: { ’name’: ’str’, ’meta-type’: ’SchemaMetaType’ } } { ’enum’: ’SchemaMetaType’, ’data’: [’builtin’, ’enum’, ’array’, ’object’, ’alternate’, ’command’, ’event’] } Drill down into SchemaInfo
{ ’union’: ’SchemaInfo’, ’base’:QAPI ’SchemaInfoBase’, schema gobbledygook decoded: ’discriminator’: ’meta-type’, ’data’: {SchemaInfo is a variant record ’command’:Common ’SchemaInfoCommand’, members: name, meta-type ’enum’: ’SchemaInfoEnum’, ’object’:Variant ’SchemaInfoObject’, members depend on meta-type: ... }}meta-type variant members { ’struct’:command ’SchemaInfoBase’,arg-type, ret-type ’data’: { ’name’: ’str’, ’meta-type’:array ’SchemaMetaType’element-type } } { ’enum’: ’SchemaMetaType’,object members, tag, variants ’data’: [’builtin’,... ’enum’, ’array’, ’object’, ’alternate’, ’command’, ’event’] } Introspect SchemaInfo
{ "name":"203", "meta-type":"object", "members": [{ "name":"name", "type":"str" }, { "name":"meta-type", "type":"271" }], "tag":"meta-type", "variants": [{ "case":"builtin", "type":"272" }, { "case":"enum", "type":"273" }, { "case":"array", "type":"274" }, { "case":"object", "type":"275" }, { "case":"alternate", "type":"276" }, { "case":"command", "type":"277" }, { "case":"event", "type":"278" }] } Introspect SchemaInfo
{ "name":"203", "meta-type":"object", "members": [{ "name":"name", "type":"str"It’s an object }, type { "name":"meta-type", "type":"271" }], "tag":"meta-type", "variants": [{ "case":"builtin", "type":"272" }, { "case":"enum", "type":"273" }, { "case":"array", "type":"274" }, { "case":"object", "type":"275" }, { "case":"alternate", "type":"276" }, { "case":"command", "type":"277" }, { "case":"event", "type":"278" }] } Introspect SchemaInfo
{ "name":"203", "meta-type":"object", "members""members": [{ "name":"name""name", "type":"str" }, { "name":"meta-type""meta-type", "type":"271" }], "tag":"meta-type", "variants": It has a name and a meta-type (always) [{ "case":"builtin", "type":"272" }, { "case":"enum", "type":"273" }, { "case":"array", "type":"274" }, { "case":"object", "type":"275" }, { "case":"alternate", "type":"276" }, { "case":"command", "type":"277" }, { "case":"event", "type":"278" }] } Introspect SchemaInfo
{ "name":"203", "meta-type":"object", "members": [{ "name":"name", "type":"str" }, { "name":"meta-type""meta-type", "type":"271" }], "tag":"meta-type""tag":"meta-type", "variants""variants": It has variants, [{ "case":"builtin",and"type":"272" this is their tag }, { "case":"enum", "type":"273" }, { "case":"array", "type":"274" }, { "case":"object", "type":"275" }, { "case":"alternate", "type":"276" }, { "case":"command", "type":"277" }, { "case":"event", "type":"278" }] } Introspect SchemaInfo
{ "name":"203", "meta-type":"object", "members": [{ "name":"name", "type":"str" }, { "name":"meta-type", "type":"271" }], "tag":"meta-type", "variants": Each case applies to a [{ "case":"builtin""builtin", "type":"272" }, { "case":"enum""enum", "type":"273"value of the tag’s }, type { "case":"array""array", "type":"274" }, { "case":"object""object", "type":"275" }, { "case":"alternate""alternate", "type":"276" }, { "case":"command""command", "type":"277" }, { "case":"event""event", "type":"278" }] } Introspect SchemaInfo
{ "name":"203", "meta-type":"object", "members": [{ "name":"name", "type":"str" }, { "name":"meta-type", "type":"271" }], "tag":"meta-type", "variants": [{ "case":"builtin", "type":"272" }, { "case":"enum", "type":"273" }, Variant{ members "case":"array", are "type":"274" }, { "case":"object", "type":"275" }, just another{ "case": object"alternate", type "type":"276" }, { "case":"command", "type":"277" }, { "case":"event", "type":"278" }] } The types of its name & tag The name’s type is “str” { "name":"str""str", "meta-type":"builtin""builtin", It’s a built-in type "json-type":"string" } and on the wire it’s JSON string
{ "name":"271", "meta-type":"enum", "values": ["builtin", "enum", "array", "object", "alternate", "command", "event"] } The types of its name & tag
{ "name":"str", "meta-type":"builtin", "json-type":"string" }
Tag’s type is an enumeration { "name":"271", "meta-type":"enum""enum", "values": ["builtin", "enum", "array", "object", "alternate", "command", "event""event"] } with these members SchemaInfo’s enum variant
The case’s type is an object type { "name":"273", "meta-type":"object""object", "members": [{ "name":"values""values", "type":"270" }] }, It has just one member “values”
{ "name":"270", "meta-type":"array", "element-type":"str" } SchemaInfo’s enum variant
{ "name":"273", "meta-type":"object", "members": [{ "name":"values", "type":"270" }] },
The type of “values” is array of str
{ "name":"270""270", "meta-type":"array""array", "element-type":"str" } Quick peek under the hood
QAPI schema is compile time static so far SchemaInfo is generated from it Generator is 160 SLOC of Python The necessary refactoring of core, however. . . Complete info is a bit over 70KiB Should probably support caching it (put hash in QMP greeting) Still work in progress http://repo.or.cz/qemu/armbru.git qapi-introspect Part IV Future work QMP introspection limitations
Known issues: Can see only qapified commands Can’t see device_add Can see only qapified arguments & results We cheat for netdev_add... Can’t see most of netdev_add’s arguments Only as good as the qapification add_client takes arguments protocol, tls tls accepted only when protocol supports it Can’t see which protocols support TLS Clean up qapification of netdev_add
Need to qapify its type-specific arguments. . . without upsetting the QMP wire format Wire format matches QAPI/QMP’s flat union type Possible solution: Support unions as command arguments Code up the matching flat union type Qapify device_add
Wire format like netdev_add: common + driver-specific arguments But: drivers collected only at run time! QAPI schema fixed at compile time. . . Choices: Collect drivers at compile time? Hard. . . Make QAPI schema dynamic? Hard. . . Forgo driver-specific arguments in schema? Defeats introspection. . . No conclusion, yet QAPI follow-up work On the way to introspection, we got ourselves real test coverage replaced our internal schema representation fixed many bugs, and marked more as FIXME plugged many documentation holes Left to do: Fix the FIXMEs Finish transition to new internal representation Clean up schema language and generated code Review schema for imprecise qapifications What about command line?
Introspection needs the interface as data Good: our command line definition is data Bad: not QAPI, less expressive, leaves more to code Choices: Build non-QAPI command line introspection? Only as good as the data. . . Rebase command line onto QAPI? Hard. . . Use QMP introspection as witness instead? Assumes suitable witness exists. . . No conclusion, yet Questions?