@item PC (x86 or x86_64 processor)
@item ISA PC (old style PC without PCI bus)
@item PREP (PowerPC processor)
-@item G3 BW PowerMac (PowerPC processor)
+@item G3 Beige PowerMac (PowerPC processor)
@item Mac99 PowerMac (PowerPC processor, in progress)
@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
@item ARM Integrator/CP (ARM)
@item ARM Versatile baseboard (ARM)
@item ARM RealView Emulation baseboard (ARM)
-@item Spitz, Akita, Borzoi and Terrier PDAs (PXA270 processor)
+@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
@item Freescale MCF5208EVB (ColdFire V2).
@item Palm Tungsten|E PDA (OMAP310 processor)
@item N800 and N810 tablets (OMAP2420 processor)
@item MusicPal (MV88W8618 ARM processor)
+@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
+@item Siemens SX1 smartphone (OMAP310 processor)
@end itemize
For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
SMP is supported with up to 255 CPUs.
-Note that adlib, ac97, gus and cs4231a are only available when QEMU
-was configured with --audio-card-list option containing the name(s) of
+Note that adlib, gus and cs4231a are only available when QEMU was
+configured with --audio-card-list option containing the name(s) of
required card(s).
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
@end example
@c man begin OPTIONS
-@var{disk_image} is a raw hard disk image for IDE hard disk 0.
+@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
+targets do not need a disk image.
General options:
@table @option
+@item -h
+Display help and exit
+
@item -M @var{machine}
Select the emulated @var{machine} (@code{-M ?} for list)
+@item -cpu @var{model}
+Select CPU model (-cpu ? for list and additional feature selection)
+
+@item -smp @var{n}
+Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
+CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
+to 4.
+
@item -fda @var{file}
@item -fdb @var{file}
Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
(for instance, "file=my,,file" to use file "my,file").
@item if=@var{interface}
This option defines on which type on interface the drive is connected.
-Available types are: ide, scsi, sd, mtd, floppy, pflash.
+Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
@item bus=@var{bus},unit=@var{unit}
These options define where is connected the drive by defining the bus number and
the unit id.
Specify which disk @var{format} will be used rather than detecting
the format. Can be used to specifiy format=raw to avoid interpreting
an untrusted format header.
+@item serial=@var{serial}
+This option specifies the serial number to assign to the device.
@end table
By default, writethrough caching is used for all block device. This means that
attempt to do disk IO directly to the guests memory. QEMU may still perform
an internal copy of the data.
+Some block drivers perform badly with @option{cache=writethrough}, most notably,
+qcow2. If performance is more important than correctness,
+@option{cache=writeback} should be used with qcow2. By default, if no explicit
+caching is specified for a qcow2 disk image, @option{cache=writeback} will be
+used. For all other disk types, @option{cache=writethrough} is the default.
+
Instead of @option{-cdrom} you can use:
@example
qemu -drive file=file,index=2,media=cdrom
qemu -hda a -hdb b
@end example
+@item -mtdblock file
+Use 'file' as on-board Flash memory image.
+
+@item -sd file
+Use 'file' as SecureDigital card image.
+
+@item -pflash file
+Use 'file' as a parallel flash image.
+
@item -boot [a|c|d|n]
Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
is the default.
the raw disk image you use is not written back. You can however force
the write back by pressing @key{C-a s} (@pxref{disk_images}).
-@item -no-fd-bootchk
-Disable boot signature checking for floppy disks in Bochs BIOS. It may
-be needed to boot from old floppy disks.
-
@item -m @var{megs}
Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
gigabytes respectively.
-@item -cpu @var{model}
-Select CPU model (-cpu ? for list and additional feature selection)
+@item -k @var{language}
-@item -smp @var{n}
-Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
-CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
-to 4.
+Use keyboard layout @var{language} (for example @code{fr} for
+French). This option is only needed where it is not easy to get raw PC
+keycodes (e.g. on Macs, with some X11 servers or with a VNC
+display). You don't normally need to use it on PC/Linux or PC/Windows
+hosts.
+
+The available layouts are:
+@example
+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
+@end example
+
+The default is @code{en-us}.
@item -audio-help
available sound hardware.
@example
-qemu -soundhw sb16,adlib hda
-qemu -soundhw es1370 hda
-qemu -soundhw ac97 hda
-qemu -soundhw all hda
+qemu -soundhw sb16,adlib disk.img
+qemu -soundhw es1370 disk.img
+qemu -soundhw ac97 disk.img
+qemu -soundhw all disk.img
qemu -soundhw ?
@end example
modprobe i810_audio clocking=48000
@end example
-@item -localtime
-Set the real time clock to local time (the default is to UTC
-time). This option is needed to have correct date in MS-DOS or
-Windows.
+@end table
-@item -startdate @var{date}
-Set the initial date of the real time clock. Valid format for
-@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
-@code{2006-06-17}. The default value is @code{now}.
+USB options:
+@table @option
-@item -pidfile @var{file}
-Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
-from a script.
+@item -usb
+Enable the USB driver (will be the default soon)
-@item -daemonize
-Daemonize the QEMU process after initialization. QEMU will not detach from
-standard IO until it is ready to receive connections on any of its devices.
-This option is a useful way for external programs to launch QEMU without having
-to cope with initialization race conditions.
+@item -usbdevice @var{devname}
+Add the USB device @var{devname}. @xref{usb_devices}.
-@item -win2k-hack
-Use it when installing Windows 2000 to avoid a disk full bug. After
-Windows 2000 is installed, you no longer need this option (this option
-slows down the IDE transfers).
+@table @code
-@item -option-rom @var{file}
-Load the contents of @var{file} as an option ROM.
-This option is useful to load things like EtherBoot.
+@item mouse
+Virtual Mouse. This will override the PS/2 mouse emulation when activated.
+
+@item tablet
+Pointer device that uses absolute coordinates (like a touchscreen). This
+means qemu is able to report the mouse position without having to grab the
+mouse. Also overrides the PS/2 mouse emulation when activated.
+
+@item disk:[format=@var{format}]:file
+Mass storage device based on file. The optional @var{format} argument
+will be used rather than detecting the format. Can be used to specifiy
+format=raw to avoid interpreting an untrusted format header.
+
+@item host:bus.addr
+Pass through the host device identified by bus.addr (Linux only).
+
+@item host:vendor_id:product_id
+Pass through the host device identified by vendor_id:product_id (Linux only).
+
+@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
+Serial converter to host character device @var{dev}, see @code{-serial} for the
+available devices.
+
+@item braille
+Braille device. This will use BrlAPI to display the braille output on a real
+or fake device.
+
+@item net:options
+Network adapter that supports CDC ethernet and RNDIS protocols.
+
+@end table
@item -name @var{name}
Sets the @var{name} of the guest.
-This name will be display in the SDL window caption.
+This name will be displayed in the SDL window caption.
The @var{name} will also be used for the VNC server.
+@item -uuid @var{uuid}
+Set system UUID.
+
@end table
Display options:
available screen space. This makes the using QEMU in a dedicated desktop
workspace more convenient.
+@item -alt-grab
+
+Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt).
+
@item -no-quit
Disable SDL window close capability.
+@item -sdl
+
+Enable SDL.
+
+@item -portrait
+
+Rotate graphical output 90 deg left (only PXA LCD).
+
+@item -vga @var{type}
+Select type of VGA card to emulate. Valid values for @var{type} are
+@table @code
+@item cirrus
+Cirrus Logic GD5446 Video card. All Windows versions starting from
+Windows 95 should recognize and use this graphic card. For optimal
+performances, use 16 bit color depth in the guest and the host OS.
+(This one is the default)
+@item std
+Standard VGA card with Bochs VBE extensions. If your guest OS
+supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
+to use high resolution modes (>= 1280x1024x16) then you should use
+this option.
+@item vmware
+VMWare SVGA-II compatible adapter. Use it if you have sufficiently
+recent XFree86/XOrg server or Windows guest with a driver for this
+card.
+@item none
+Disable VGA card.
+@end table
+
@item -full-screen
Start in full screen.
be loaded from. See the @ref{vnc_security} section for details on generating
certificates.
-@end table
-
-@item -k @var{language}
-
-Use keyboard layout @var{language} (for example @code{fr} for
-French). This option is only needed where it is not easy to get raw PC
-keycodes (e.g. on Macs, with some X11 servers or with a VNC
-display). You don't normally need to use it on PC/Linux or PC/Windows
-hosts.
-
-The available layouts are:
-@example
-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
-@end example
-
-The default is @code{en-us}.
-
-@end table
-
-USB options:
-@table @option
-
-@item -usb
-Enable the USB driver (will be the default soon)
-
-@item -usbdevice @var{devname}
-Add the USB device @var{devname}. @xref{usb_devices}.
-
-@table @code
-
-@item mouse
-Virtual Mouse. This will override the PS/2 mouse emulation when activated.
-
-@item tablet
-Pointer device that uses absolute coordinates (like a touchscreen). This
-means qemu is able to report the mouse position without having to grab the
-mouse. Also overrides the PS/2 mouse emulation when activated.
-
-@item disk:[format=@var{format}]:file
-Mass storage device based on file. The optional @var{format} argument
-will be used rather than detecting the format. Can be used to specifiy
-format=raw to avoid interpreting an untrusted format header.
-
-@item host:bus.addr
-Pass through the host device identified by bus.addr (Linux only).
-
-@item host:vendor_id:product_id
-Pass through the host device identified by vendor_id:product_id (Linux only).
-
-@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
-Serial converter to host character device @var{dev}, see @code{-serial} for the
-available devices.
-
-@item braille
-Braille device. This will use BrlAPI to display the braille output on a real
-or fake device.
-
-@item net:options
-Network adapter that supports CDC ethernet and RNDIS protocols.
+@item sasl
+
+Require that the client use SASL to authenticate with the VNC server.
+The exact choice of authentication method used is controlled from the
+system / user's SASL configuration file for the 'qemu' service. This
+is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
+unprivileged user, an environment variable SASL_CONF_PATH can be used
+to make it search alternate locations for the service config.
+While some SASL auth methods can also provide data encryption (eg GSSAPI),
+it is recommended that SASL always be combined with the 'tls' and
+'x509' settings to enable use of SSL and server certificates. This
+ensures a data encryption preventing compromise of authentication
+credentials. See the @ref{vnc_security} section for details on using
+SASL authentication.
+
+@item acl
+
+Turn on access control lists for checking of the x509 client certificate
+and SASL party. For x509 certs, the ACL check is made against the
+certificate's distinguished name. This is something that looks like
+@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
+made against the username, which depending on the SASL plugin, may
+include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
+When the @option{acl} flag is set, the initial access list will be
+empty, with a @code{deny} policy. Thus no one will be allowed to
+use the VNC server until the ACLs have been loaded. This can be
+achieved using the @code{acl} monitor command.
@end table
@table @option
-@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
+@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}][,name=@var{name}]
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
= 0 is the default). The NIC is an ne2k_pci by default on the PC
-target. Optionally, the MAC address can be changed. If no
+target. Optionally, the MAC address can be changed to @var{addr}
+and a @var{name} can be assigned for use in monitor commands. If no
@option{-net} option is specified, a single NIC is created.
Qemu can emulate several different models of network card.
Valid values for @var{type} are
Not all devices are supported on all targets. Use -net nic,model=?
for a list of available devices for your target.
-@item -net user[,vlan=@var{n}][,hostname=@var{name}]
+@item -net user[,vlan=@var{n}][,hostname=@var{name}][,name=@var{name}]
Use the user mode network stack which requires no administrator
privilege to run. @option{hostname=name} can be used to specify the client
hostname reported by the builtin DHCP server.
-@item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}]
-Connect the host TAP network interface @var{name} to VLAN @var{n} and
-use the network script @var{file} to configure it. The default
-network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
-disable script execution. If @var{name} is not
-provided, the OS automatically provides one. @option{fd}=@var{h} can be
-used to specify the handle of an already opened host TAP interface. Example:
+@item -net channel,@var{port}:@var{dev}
+Forward @option{user} TCP connection to port @var{port} to character device @var{dev}
+
+@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
+Connect the host TAP network interface @var{name} to VLAN @var{n}, use
+the network script @var{file} to configure it and the network script
+@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
+automatically provides one. @option{fd}=@var{h} can be used to specify
+the handle of an already opened host TAP interface. The default network
+configure script is @file{/etc/qemu-ifup} and the default network
+deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
+or @option{downscript=no} to disable script execution. Example:
@example
qemu linux.img -net nic -net tap
@end example
-@item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
+@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
machine using a TCP socket connection. If @option{listen} is
-net socket,connect=127.0.0.1:1234
@end example
-@item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
+@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
Create a VLAN @var{n} shared with another QEMU virtual
machines using a UDP multicast socket, effectively making a bus for
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
@end example
-@item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
+@item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
and MODE @var{octalmode} to change default ownership and permissions for
@end table
+Bluetooth(R) options:
+@table @option
+
+@item -bt hci[...]
+Defines the function of the corresponding Bluetooth HCI. -bt options
+are matched with the HCIs present in the chosen machine type. For
+example when emulating a machine with only one HCI built into it, only
+the first @code{-bt hci[...]} option is valid and defines the HCI's
+logic. The Transport Layer is decided by the machine type. Currently
+the machines @code{n800} and @code{n810} have one HCI and all other
+machines have none.
+
+@anchor{bt-hcis}
+The following three types are recognized:
+
+@table @code
+@item -bt hci,null
+(default) The corresponding Bluetooth HCI assumes no internal logic
+and will not respond to any HCI commands or emit events.
+
+@item -bt hci,host[:@var{id}]
+(@code{bluez} only) The corresponding HCI passes commands / events
+to / from the physical HCI identified by the name @var{id} (default:
+@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
+capable systems like Linux.
+
+@item -bt hci[,vlan=@var{n}]
+Add a virtual, standard HCI that will participate in the Bluetooth
+scatternet @var{n} (default @code{0}). Similarly to @option{-net}
+VLANs, devices inside a bluetooth network @var{n} can only communicate
+with other devices in the same network (scatternet).
+@end table
+
+@item -bt vhci[,vlan=@var{n}]
+(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
+to the host bluetooth stack instead of to the emulated target. This
+allows the host and target machines to participate in a common scatternet
+and communicate. Requires the Linux @code{vhci} driver installed. Can
+be used as following:
+
+@example
+qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
+@end example
+
+@item -bt device:@var{dev}[,vlan=@var{n}]
+Emulate a bluetooth device @var{dev} and place it in network @var{n}
+(default @code{0}). QEMU can only emulate one type of bluetooth devices
+currently:
+
+@table @code
+@item keyboard
+Virtual wireless keyboard implementing the HIDP bluetooth profile.
+@end table
+
+@end table
+
+i386 target only:
+
+@table @option
+
+@item -win2k-hack
+Use it when installing Windows 2000 to avoid a disk full bug. After
+Windows 2000 is installed, you no longer need this option (this option
+slows down the IDE transfers).
+
+@item -rtc-td-hack
+Use it if you experience time drift problem in Windows with 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.
+
+@item -no-fd-bootchk
+Disable boot signature checking for floppy disks in Bochs BIOS. It may
+be needed to boot from old floppy disks.
+
+@item -no-acpi
+Disable ACPI (Advanced Configuration and Power Interface) support. Use
+it if your guest OS complains about ACPI problems (PC target machine
+only).
+
+@item -no-hpet
+Disable HPET support.
+
+@item -acpitable [sig=@var{str}][,rev=@var{n}][,oem_id=@var{str}][,oem_table_id=@var{str}][,oem_rev=@var{n}] [,asl_compiler_id=@var{str}][,asl_compiler_rev=@var{n}][,data=@var{file1}[:@var{file2}]...]
+Add ACPI table with specified header fields and context from specified files.
+
+@end table
+
Linux boot specific: When using these options, you can use a given
Linux kernel without installing it in the disk image. It can be useful
for easier testing of various kernels.
@var{dev}. The default device is @code{vc} in graphical mode and
@code{stdio} in non graphical mode.
-This option can be used several times to simulate up to 4 serials
+This option can be used several times to simulate up to 4 serial
ports.
Use @code{-serial none} to disable all serial ports.
When @var{remote_host} or @var{src_ip} are not specified
they default to @code{0.0.0.0}.
When not using a specified @var{src_port} a random port is automatically chosen.
+@item msmouse
+Three button serial mouse. Configure the guest to use Microsoft protocol.
If you just want a simple readonly console you can use @code{netcat} or
@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
The default device is @code{vc} in graphical mode and @code{stdio} in
non graphical mode.
-@item -echr numeric_ascii_value
-Change the escape character used for switching to the monitor when using
-monitor and serial sharing. The default is @code{0x01} when using the
-@code{-nographic} option. @code{0x01} is equal to pressing
-@code{Control-a}. You can select a different character from 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
-character to Control-t.
-@table @code
-@item -echr 0x14
-@item -echr 20
-@end table
+@item -pidfile @var{file}
+Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
+from a script.
+
+@item -S
+Do not start CPU at startup (you must type 'c' in the monitor).
@item -s
Wait gdb connection to port 1234 (@pxref{gdb_usage}).
+
@item -p @var{port}
Change gdb connection port. @var{port} can be either a decimal number
to specify a TCP port, or a host device (same devices as the serial port).
-@item -S
-Do not start CPU at startup (you must type 'c' in the monitor).
+
@item -d
Output log in /tmp/qemu.log
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
all those parameters. This option is useful for old MS-DOS disk
images.
-@item -L path
+@item -L @var{path}
Set the directory for the BIOS, VGA BIOS and keymaps.
-@item -vga @var{type}
-Select type of VGA card to emulate. Valid values for @var{type} are
-@table @code
-@item cirrus
-Cirrus Logic GD5446 Video card. All Windows versions starting from
-Windows 95 should recognize and use this graphic card. For optimal
-performances, use 16 bit color depth in the guest and the host OS.
-(This one is the default)
-@item std
-Standard VGA card with Bochs VBE extensions. If your guest OS
-supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
-to use high resolution modes (>= 1280x1024x16) then you should use
-this option.
-@item vmware
-VMWare SVGA-II compatible adapter. Use it if you have sufficiently
-recent XFree86/XOrg server or Windows guest with a driver for this
-card.
-@end table
+@item -bios @var{file}
+Set the filename for the BIOS.
-@item -no-acpi
-Disable ACPI (Advanced Configuration and Power Interface) support. Use
-it if your guest OS complains about ACPI problems (PC target machine
-only).
+@item -kernel-kqemu
+Enable KQEMU full virtualization (default is user mode only).
+
+@item -no-kqemu
+Disable KQEMU kernel module usage. KQEMU options are only available if
+KQEMU support is enabled when compiling.
+
+@item -enable-kvm
+Enable KVM full virtualization support. This option is only available
+if KVM support is enabled when compiling.
@item -no-reboot
Exit instead of rebooting.
This allows for instance switching to monitor to commit changes to the
disk image.
-@item -loadvm file
+@item -loadvm @var{file}
Start right away with a saved state (@code{loadvm} in monitor)
-@item -semihosting
-Enable semihosting syscall emulation (ARM and M68K target machines only).
+@item -daemonize
+Daemonize the QEMU process after initialization. QEMU will not detach from
+standard IO until it is ready to receive connections on any of its devices.
+This option is a useful way for external programs to launch QEMU without having
+to cope with initialization race conditions.
-On ARM this implements the "Angel" interface.
-On M68K this implements the "ColdFire GDB" interface used by libgloss.
+@item -option-rom @var{file}
+Load the contents of @var{file} as an option ROM.
+This option is useful to load things like EtherBoot.
-Note that this allows guest direct access to the host filesystem,
-so should only be used with trusted guest OS.
+@item -clock @var{method}
+Force the use of the given methods for timer alarm. To see what timers
+are available use -clock ?.
+
+@item -localtime
+Set the real time clock to local time (the default is to UTC
+time). This option is needed to have correct date in MS-DOS or
+Windows.
+
+@item -startdate @var{date}
+Set the initial date of the real time clock. Valid formats for
+@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
+@code{2006-06-17}. The default value is @code{now}.
@item -icount [N|auto]
Enable virtual instruction counter. The virtual cpu will execute one
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.
+
+@item -echr numeric_ascii_value
+Change the escape character used for switching to the monitor when using
+monitor and serial sharing. The default is @code{0x01} when using the
+@code{-nographic} option. @code{0x01} is equal to pressing
+@code{Control-a}. You can select a different character from 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
+character to Control-t.
+@table @code
+@item -echr 0x14
+@item -echr 20
+@end table
+
+@item -chroot dir
+Immediately before starting guest execution, chroot to the specified
+directory. Especially useful in combination with -runas.
+
+@item -runas user
+Immediately before starting guest execution, drop root privileges, switching
+to the specified user.
+
@end table
@c man end
@table @key
@item Ctrl-a h
+@item Ctrl-a ?
Print this help
@item Ctrl-a x
Exit emulator
@item Ctrl-a s
Save disk data back to file (if -snapshot)
@item Ctrl-a t
-toggle console timestamps
+Toggle console timestamps
@item Ctrl-a b
Send break (magic sysrq in Linux)
@item Ctrl-a c
Show various information about the system state.
@table @option
+@item info version
+show the version of QEMU
@item info network
show the various VLANs and the associated devices
+@item info chardev
+show the character devices
@item info block
show the block devices
+@item info block
+show block device statistics
@item info registers
show the cpu registers
+@item info cpus
+show infos for each CPU
@item info history
show the command line history
+@item info irq
+show the interrupts statistics (if available)
+@item info pic
+show i8259 (PIC) state
@item info pci
-show emulated PCI device
+show emulated PCI device info
+@item info tlb
+show virtual to physical memory mappings (i386 only)
+@item info mem
+show the active virtual memory mappings (i386 only)
+@item info hpet
+show state of HPET (i386 only)
+@item info kqemu
+show KQEMU information
+@item info kvm
+show KVM information
@item info usb
show USB devices plugged on the virtual USB hub
@item info usbhost
show all USB host devices
+@item info profile
+show profiling information
@item info capture
show information about active capturing
@item info snapshots
show list of VM snapshots
+@item info status
+show the current VM status (running|paused)
+@item info pcmcia
+show guest PCMCIA status
@item info mice
show which guest mouse is receiving events
+@item info vnc
+show the vnc server status
+@item info name
+show the current VM name
+@item info uuid
+show the current VM UUID
+@item info cpustats
+show CPU statistics
+@item info slirp
+show SLIRP statistics (if available)
+@item info migrate
+show migration status
+@item info balloon
+show balloon information
@end table
@item q or quit
Change the configuration of a device.
@table @option
-@item change @var{diskdevice} @var{filename}
+@item change @var{diskdevice} @var{filename} [@var{format}]
Change the medium for a removable disk device to point to @var{filename}. eg
@example
(qemu) change ide1-cd0 /path/to/some.iso
@end example
+@var{format} is optional.
+
@item change vnc @var{display},@var{options}
Change the configuration of the VNC server. The valid syntax for @var{display}
and @var{options} are described at @ref{sec_invocation}. eg
(qemu) change vnc localhost:1
@end example
-@item change vnc password
+@item change vnc password [@var{password}]
-Change the password associated with the VNC server. The monitor will prompt for
-the new password to be entered. VNC passwords are only significant upto 8 letters.
-eg.
+Change the password associated with the VNC server. If the new password is not
+supplied, the monitor will prompt for it to be entered. VNC passwords are only
+significant up to 8 letters. eg
@example
(qemu) change vnc password
@end table
-@item screendump @var{filename}
-Save screen into PPM image @var{filename}.
-
-@item mouse_move @var{dx} @var{dy} [@var{dz}]
-Move the active mouse to the specified coordinates @var{dx} @var{dy}
-with optional scroll axis @var{dz}.
+@item acl @var{subcommand} @var{aclname} @var{match} @var{index}
-@item mouse_button @var{val}
-Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
+Manage access control lists for network services. There are currently
+two named access control lists, @var{vnc.x509dname} and @var{vnc.username}
+matching on the x509 client certificate distinguished name, and SASL
+username respectively.
-@item mouse_set @var{index}
-Set which mouse device receives events at given @var{index}, index
-can be obtained with
-@example
-info mice
-@end example
-
-@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
-Capture audio into @var{filename}. Using sample rate @var{frequency}
-bits per sample @var{bits} and number of channels @var{channels}.
+@table @option
+@item acl show <aclname>
+list all the match rules in the access control list, and the default
+policy
+@item acl policy <aclname> @code{allow|deny}
+set the default access control list policy, used in the event that
+none of the explicit rules match. The default policy at startup is
+always @code{deny}
+@item acl allow <aclname> <match> [<index>]
+add a match to the access control list, allowing access. The match will
+normally be an exact username or x509 distinguished name, but can
+optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to allow
+all users in the @code{EXAMPLE.COM} kerberos realm. The match will
+normally be appended to the end of the ACL, but can be inserted
+earlier in the list if the optional @code{index} parameter is supplied.
+@item acl deny <aclname> <match> [<index>]
+add a match to the access control list, denying access. The match will
+normally be an exact username or x509 distinguished name, but can
+optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to allow
+all users in the @code{EXAMPLE.COM} kerberos realm. The match will
+normally be appended to the end of the ACL, but can be inserted
+earlier in the list if the optional @code{index} parameter is supplied.
+@item acl remove <aclname> <match>
+remove the specified match rule from the access control list.
+@item acl reset <aclname>
+remove all matches from the access control list, and set the default
+policy back to @code{deny}.
+@end table
-Defaults:
-@itemize @minus
-@item Sample rate = 44100 Hz - CD quality
-@item Bits = 16
-@item Number of channels = 2 - Stereo
-@end itemize
+@item screendump @var{filename}
+Save screen into PPM image @var{filename}.
-@item stopcapture @var{index}
-Stop capture with a given @var{index}, index can be obtained with
-@example
-info capture
-@end example
+@item logfile @var{filename}
+Output logs to @var{filename}.
@item log @var{item1}[,...]
Activate logging of the specified items to @file{/tmp/qemu.log}.
Reset the system.
-@item boot_set @var{bootdevicelist}
+@item system_powerdown
-Define new values for the boot device list. Those values will override
-the values specified on the command line through the @code{-boot} option.
+Power down the system (if supported).
-The values that can be specified here depend on the machine type, but are
-the same that can be specified in the @code{-boot} command line option.
+@item sum @var{addr} @var{size}
+
+Compute the checksum of a memory region.
@item usb_add @var{devname}
hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
command @code{info usb} to see the devices you can remove.
+@item mouse_move @var{dx} @var{dy} [@var{dz}]
+Move the active mouse to the specified coordinates @var{dx} @var{dy}
+with optional scroll axis @var{dz}.
+
+@item mouse_button @var{val}
+Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
+
+@item mouse_set @var{index}
+Set which mouse device receives events at given @var{index}, index
+can be obtained with
+@example
+info mice
+@end example
+
+@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
+Capture audio into @var{filename}. Using sample rate @var{frequency}
+bits per sample @var{bits} and number of channels @var{channels}.
+
+Defaults:
+@itemize @minus
+@item Sample rate = 44100 Hz - CD quality
+@item Bits = 16
+@item Number of channels = 2 - Stereo
+@end itemize
+
+@item stopcapture @var{index}
+Stop capture with a given @var{index}, index can be obtained with
+@example
+info capture
+@end example
+
+@item memsave @var{addr} @var{size} @var{file}
+save to disk virtual memory dump starting at @var{addr} of size @var{size}.
+
+@item pmemsave @var{addr} @var{size} @var{file}
+save to disk physical memory dump starting at @var{addr} of size @var{size}.
+
+@item boot_set @var{bootdevicelist}
+
+Define new values for the boot device list. Those values will override
+the values specified on the command line through the @code{-boot} option.
+
+The values that can be specified here depend on the machine type, but are
+the same that can be specified in the @code{-boot} command line option.
+
+@item nmi @var{cpu}
+Inject an NMI on the given CPU.
+
+@item migrate [-d] @var{uri}
+Migrate to @var{uri} (using -d to not wait for completion).
+
+@item migrate_cancel
+Cancel the current VM migration.
+
+@item migrate_set_speed @var{value}
+Set maximum speed to @var{value} (in bytes) for migrations.
+
+@item balloon @var{value}
+Request VM to change its memory allocation to @var{value} (in MB).
+
+@item set_link @var{name} [up|down]
+Set link @var{name} up or down.
+
@end table
@subsection Integer expressions
qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
@end example
Currently this cannot be used in machines that support PCI NICs.
+@item bt[:@var{hci-type}]
+Bluetooth dongle whose type is specified in the same format as with
+the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
+no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
+This USB device implements the USB Transport Layer of HCI. Example
+usage:
+@example
+qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
+@end example
@end table
@node host_usb_devices
* vnc_sec_certificate::
* vnc_sec_certificate_verify::
* vnc_sec_certificate_pw::
+* vnc_sec_sasl::
+* vnc_sec_certificate_sasl::
* vnc_generate_cert::
+* vnc_setup_sasl::
@end menu
@node vnc_sec_none
@subsection Without passwords
(qemu)
@end example
+
+@node vnc_sec_sasl
+@subsection With SASL authentication
+
+The SASL authentication method is a VNC extension, that provides an
+easily extendable, pluggable authentication method. This allows for
+integration with a wide range of authentication mechanisms, such as
+PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
+The strength of the authentication depends on the exact mechanism
+configured. If the chosen mechanism also provides a SSF layer, then
+it will encrypt the datastream as well.
+
+Refer to the later docs on how to choose the exact SASL mechanism
+used for authentication, but assuming use of one supporting SSF,
+then QEMU can be launched with:
+
+@example
+qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
+@end example
+
+@node vnc_sec_certificate_sasl
+@subsection With x509 certificates and SASL authentication
+
+If the desired SASL authentication mechanism does not supported
+SSF layers, then it is strongly advised to run it in combination
+with TLS and x509 certificates. This provides securely encrypted
+data stream, avoiding risk of compromising of the security
+credentials. This can be enabled, by combining the 'sasl' option
+with the aforementioned TLS + x509 options:
+
+@example
+qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
+@end example
+
+
@node vnc_generate_cert
@subsection Generating certificates for VNC
The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
copied to the client for which they were generated.
+
+@node vnc_setup_sasl
+
+@subsection Configuring SASL mechanisms
+
+The following documentation assumes use of the Cyrus SASL implementation on a
+Linux host, but the principals should apply to any other SASL impl. When SASL
+is enabled, the mechanism configuration will be loaded from system default
+SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
+unprivileged user, an environment variable SASL_CONF_PATH can be used
+to make it search alternate locations for the service config.
+
+The default configuration might contain
+
+@example
+mech_list: digest-md5
+sasldb_path: /etc/qemu/passwd.db
+@end example
+
+This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
+Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
+in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
+command. While this mechanism is easy to configure and use, it is not
+considered secure by modern standards, so only suitable for developers /
+ad-hoc testing.
+
+A more serious deployment might use Kerberos, which is done with the 'gssapi'
+mechanism
+
+@example
+mech_list: gssapi
+keytab: /etc/qemu/krb5.tab
+@end example
+
+For this to work the administrator of your KDC must generate a Kerberos
+principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
+replacing 'somehost.example.com' with the fully qualified host name of the
+machine running QEMU, and 'EXAMPLE.COM' with the Keberos Realm.
+
+Other configurations will be left as an exercise for the reader. It should
+be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
+encryption. For all other mechanisms, VNC should always be configured to
+use TLS and x509 certificates to protect security credentials from snooping.
+
@node gdb_usage
@section GDB usage
@itemize @minus
@item
-UniNorth PCI Bridge
+UniNorth or Grackle PCI Bridge
@item
PCI VGA compatible card with VESA Bochs Extensions
@item
QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
+Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
+for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
+v2) portable firmware implementation. The goal is to implement a 100%
+IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
+
@c man begin OPTIONS
The following options are specific to the PowerPC emulation:
Set the initial VGA graphic mode. The default is 800x600x15.
+@item -prom-env string
+
+Set OpenBIOS variables in NVRAM, for example:
+
+@example
+qemu-system-ppc -prom-env 'auto-boot?=false' \
+ -prom-env 'boot-device=hd:2,\yaboot' \
+ -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
+@end example
+
+These variables are not used by Open Hack'Ware.
+
@end table
@c man end
@item
Malta FPGA serial device
@item
-Cirrus VGA graphics card
+Cirrus (default) or any other PCI VGA graphics card
@end itemize
The ACER Pica emulation supports:
@item
Three OMAP on-chip UARTs and on-chip STI debugging console
@item
+A Bluetooth(R) transciever and HCI connected to an UART
+@item
Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
TUSB6010 chip - only USB host mode is supported
@item
2 buttons, 2 navigation wheels with button function
@end itemize
+The Siemens SX1 models v1 and v2 (default) basic emulation.
+The emulaton includes the following elements:
+
+@itemize @minus
+@item
+Texas Instruments OMAP310 System-on-chip (ARM 925T core)
+@item
+ROM and RAM memories (ROM firmware image can be loaded with -pflash)
+V1
+1 Flash of 16MB and 1 Flash of 8MB
+V2
+1 Flash of 32MB
+@item
+On-chip LCD controller
+@item
+On-chip Real Time Clock
+@item
+Secure Digital card connected to OMAP MMC/SD host
+@item
+Three on-chip UARTs
+@end itemize
+
A Linux 2.6 test image is available on the QEMU web site. More
information is available in the QEMU mailing-list archive.
+@c man begin OPTIONS
+
+The following options are specific to the ARM emulation:
+
+@table @option
+
+@item -semihosting
+Enable semihosting syscall emulation.
+
+On ARM this implements the "Angel" interface.
+
+Note that this allows guest direct access to the host filesystem,
+so should only be used with trusted guest OS.
+
+@end table
+
@node ColdFire System emulator
@section ColdFire System emulator
Two on-chip UARTs.
@end itemize
+@c man begin OPTIONS
+
+The following options are specific to the ARM emulation:
+
+@table @option
+
+@item -semihosting
+Enable semihosting syscall emulation.
+
+On M68K this implements the "ColdFire GDB" interface used by libgloss.
+
+Note that this allows guest direct access to the host filesystem,
+so should only be used with trusted guest OS.
+
+@end table
+
@node QEMU User space emulator
@chapter QEMU User space emulator
projects / qemu / blobdiff