"-machine [type=]name[,prop[=value][,...]]\n"
" selects emulated machine (-machine ? for list)\n"
" property accel=accel1[:accel2[:...]] selects accelerator\n"
- " supported accelerators are kvm, xen, tcg (default: tcg)\n",
+ " supported accelerators are kvm, xen, tcg (default: tcg)\n"
+ " kernel_irqchip=on|off controls accelerated irqchip support\n"
+ " kvm_shadow_mem=size of KVM shadow MMU\n",
QEMU_ARCH_ALL)
STEXI
@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
kvm, xen, or tcg can be available. By default, tcg is used. If there is more
than one accelerator specified, the next one is used if the previous one fails
to initialize.
+@item kernel_irqchip=on|off
+Enables in-kernel irqchip support for the chosen accelerator when available.
+@item kvm_shadow_mem=size
+Defines the size of the KVM shadow MMU.
@end table
ETEXI
" [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
" [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
" [,serial=s][,addr=A][,id=name][,aio=threads|native]\n"
- " [,readonly=on|off]\n"
+ " [,readonly=on|off][,copy-on-read=on|off]\n"
+ " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]][[,iops=i]|[[,iops_rd=r][,iops_wr=w]]\n"
" use 'file' as a drive image\n", QEMU_ARCH_ALL)
STEXI
@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
This option defines which disk image (@pxref{disk_images}) to use with
this drive. If the filename contains comma, you must double it
(for instance, "file=my,,file" to use file "my,file").
+
+Special files such as iSCSI devices can be specified using protocol
+specific URLs. See the section for "Device URL Syntax" for more information.
@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, virtio.
The default setting is @option{werror=enospc} and @option{rerror=report}.
@item readonly
Open drive @option{file} as read-only. Guest write attempts will fail.
+@item copy-on-read=@var{copy-on-read}
+@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
+file sectors into the image file.
@end table
By default, writethrough caching is used for all block device. This means that
@option{cache=writeback} should be used with qcow2.
In case you don't care about data integrity over host failures, use
-cache=unsafe. This option tells qemu that it never needs to write any data
+cache=unsafe. This option tells QEMU that it never needs to write any data
to the disk but can instead keeps things in cache. If anything goes wrong,
-like your host losing power, the disk storage getting disconnected accidently,
+like your host losing power, the disk storage getting disconnected accidentally,
etc. you're image will most probably be rendered unusable. When using
the @option{-snapshot} option, unsafe caching is always used.
+Copy-on-read avoids accessing the same backing file sectors repeatedly and is
+useful when the backing file is over a slow network. By default copy-on-read
+is off.
+
Instead of @option{-cdrom} you can use:
@example
-qemu -drive file=file,index=2,media=cdrom
+qemu-system-i386 -drive file=file,index=2,media=cdrom
@end example
Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
use:
@example
-qemu -drive file=file,index=0,media=disk
-qemu -drive file=file,index=1,media=disk
-qemu -drive file=file,index=2,media=disk
-qemu -drive file=file,index=3,media=disk
+qemu-system-i386 -drive file=file,index=0,media=disk
+qemu-system-i386 -drive file=file,index=1,media=disk
+qemu-system-i386 -drive file=file,index=2,media=disk
+qemu-system-i386 -drive file=file,index=3,media=disk
@end example
You can connect a CDROM to the slave of ide0:
@example
-qemu -drive file=file,if=ide,index=1,media=cdrom
+qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
@end example
If you don't specify the "file=" argument, you define an empty drive:
@example
-qemu -drive if=ide,index=1,media=cdrom
+qemu-system-i386 -drive if=ide,index=1,media=cdrom
@end example
You can connect a SCSI disk with unit ID 6 on the bus #0:
@example
-qemu -drive file=file,if=scsi,bus=0,unit=6
+qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6
@end example
Instead of @option{-fda}, @option{-fdb}, you can use:
@example
-qemu -drive file=file,index=0,if=floppy
-qemu -drive file=file,index=1,if=floppy
+qemu-system-i386 -drive file=file,index=0,if=floppy
+qemu-system-i386 -drive file=file,index=1,if=floppy
@end example
By default, @var{interface} is "ide" and @var{index} is automatically
incremented:
@example
-qemu -drive file=a -drive file=b"
+qemu-system-i386 -drive file=a -drive file=b"
@end example
is interpreted like:
@example
-qemu -hda a -hdb b
+qemu-system-i386 -hda a -hdb b
@end example
ETEXI
ETEXI
DEF("global", HAS_ARG, QEMU_OPTION_global,
- "-global driver.property=value\n"
+ "-global driver.prop=value\n"
" set a global default for a driver property\n",
QEMU_ARCH_ALL)
STEXI
-@item -global
+@item -global @var{driver}.@var{prop}=@var{value}
@findex -global
-TODO
+Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
+
+@example
+qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
+@end example
+
+In particular, you can use this to set driver properties for devices which are
+created automatically by the machine model. To create a device which is not
+created automatically and set properties on it, use -@option{device}.
ETEXI
DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
@example
# try to boot from network first, then from hard disk
-qemu -boot order=nc
+qemu-system-i386 -boot order=nc
# boot from CD-ROM first, switch back to default order after reboot
-qemu -boot once=d
+qemu-system-i386 -boot once=d
# boot with a splash picture for 5 seconds.
-qemu -boot menu=on,splash=/root/boot.bmp,splash-time=5000
+qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
@end example
Note: The legacy format '-boot @var{drives}' is still supported but its
available sound hardware.
@example
-qemu -soundhw sb16,adlib disk.img
-qemu -soundhw es1370 disk.img
-qemu -soundhw ac97 disk.img
-qemu -soundhw hda disk.img
-qemu -soundhw all disk.img
-qemu -soundhw ?
+qemu-system-i386 -soundhw sb16,adlib disk.img
+qemu-system-i386 -soundhw es1370 disk.img
+qemu-system-i386 -soundhw ac97 disk.img
+qemu-system-i386 -soundhw hda disk.img
+qemu-system-i386 -soundhw all disk.img
+qemu-system-i386 -soundhw ?
@end example
Note that Linux's i810_audio OSS kernel (for AC97) module might
@end example
ETEXI
+DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
+ "-balloon none disable balloon device\n"
+ "-balloon virtio[,addr=str]\n"
+ " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
+STEXI
+@item -balloon none
+@findex -balloon
+Disable balloon device.
+@item -balloon virtio[,addr=@var{addr}]
+Enable virtio balloon device (default), optionally with PCI address
+@var{addr}.
+ETEXI
+
STEXI
@end table
ETEXI
@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
+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}]:@var{file}
@code{-device @var{driver},?}.
ETEXI
+DEFHEADING()
+
DEFHEADING(File system options:)
DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
- "-fsdev local,id=id,path=path,security_model=[mapped|passthrough|none]\n",
+ "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
+ " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
QEMU_ARCH_ALL)
STEXI
-The general form of a File system device option is:
-@table @option
-
-@item -fsdev @var{fstype} ,id=@var{id} [,@var{options}]
+@item -fsdev @var{fsdriver},id=@var{id},path=@var{path},[security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}]
@findex -fsdev
-Fstype is one of:
-@option{local},
-The specific Fstype will determine the applicable options.
-
-Options to each backend are described below.
-
-@item -fsdev local ,id=@var{id} ,path=@var{path} ,security_model=@var{security_model}
-
-Create a file-system-"device" for local-filesystem.
-
-@option{local} is only available on Linux.
-
-@option{path} specifies the path to be exported. @option{path} is required.
-
-@option{security_model} specifies the security model to be followed.
-@option{security_model} is required.
+Define a new file system device. Valid options are:
+@table @option
+@item @var{fsdriver}
+This option specifies the fs driver backend to use.
+Currently "local", "handle" and "proxy" file system drivers are supported.
+@item id=@var{id}
+Specifies identifier for this device
+@item path=@var{path}
+Specifies the export path for the file system device. Files under
+this path will be available to the 9p client on the guest.
+@item security_model=@var{security_model}
+Specifies the security model to be used for this export path.
+Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
+In "passthrough" security model, files are stored using the same
+credentials as they are created on the guest. This requires QEMU
+to run as root. In "mapped-xattr" security model, some of the file
+attributes like uid, gid, mode bits and link target are stored as
+file attributes. For "mapped-file" these attributes are stored in the
+hidden .virtfs_metadata directory. Directories exported by this security model cannot
+interact with other unix tools. "none" security model is same as
+passthrough except the sever won't report failures if it fails to
+set file attributes like ownership. Security model is mandatory
+only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
+security model as a parameter.
+@item writeout=@var{writeout}
+This is an optional argument. The only supported value is "immediate".
+This means that host page cache will be used to read and write data but
+write notification will be sent to the guest only when the data has been
+reported as written by the storage subsystem.
+@item readonly
+Enables exporting 9p share as a readonly mount for guests. By default
+read-write access is given.
+@item socket=@var{socket}
+Enables proxy filesystem driver to use passed socket file for communicating
+with virtfs-proxy-helper
+@item sock_fd=@var{sock_fd}
+Enables proxy filesystem driver to use passed socket descriptor for
+communicating with virtfs-proxy-helper. Usually a helper like libvirt
+will create socketpair and pass one of the fds as sock_fd
+@end table
+-fsdev option is used along with -device driver "virtio-9p-pci".
+@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
+Options for virtio-9p-pci driver are:
+@table @option
+@item fsdev=@var{id}
+Specifies the id value specified along with -fsdev option
+@item mount_tag=@var{mount_tag}
+Specifies the tag name to be used by the guest to mount this export point
@end table
+
ETEXI
+DEFHEADING()
+
DEFHEADING(Virtual File system pass-through options:)
DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
- "-virtfs local,path=path,mount_tag=tag,security_model=[mapped|passthrough|none]\n",
+ "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
+ " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
QEMU_ARCH_ALL)
STEXI
-The general form of a Virtual File system pass-through option is:
-@table @option
-
-@item -virtfs @var{fstype} [,@var{options}]
+@item -virtfs @var{fsdriver}[,path=@var{path}],mount_tag=@var{mount_tag}[,security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}]
@findex -virtfs
-Fstype is one of:
-@option{local},
-The specific Fstype will determine the applicable options.
-
-Options to each backend are described below.
-
-@item -virtfs local ,path=@var{path} ,mount_tag=@var{mount_tag} ,security_model=@var{security_model}
-
-Create a Virtual file-system-pass through for local-filesystem.
-
-@option{local} is only available on Linux.
-
-@option{path} specifies the path to be exported. @option{path} is required.
-
-@option{security_model} specifies the security model to be followed.
-@option{security_model} is required.
-
-
-@option{mount_tag} specifies the tag with which the exported file is mounted.
-@option{mount_tag} is required.
+The general form of a Virtual File system pass-through options are:
+@table @option
+@item @var{fsdriver}
+This option specifies the fs driver backend to use.
+Currently "local", "handle" and "proxy" file system drivers are supported.
+@item id=@var{id}
+Specifies identifier for this device
+@item path=@var{path}
+Specifies the export path for the file system device. Files under
+this path will be available to the 9p client on the guest.
+@item security_model=@var{security_model}
+Specifies the security model to be used for this export path.
+Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
+In "passthrough" security model, files are stored using the same
+credentials as they are created on the guest. This requires QEMU
+to run as root. In "mapped-xattr" security model, some of the file
+attributes like uid, gid, mode bits and link target are stored as
+file attributes. For "mapped-file" these attributes are stored in the
+hidden .virtfs_metadata directory. Directories exported by this security model cannot
+interact with other unix tools. "none" security model is same as
+passthrough except the sever won't report failures if it fails to
+set file attributes like ownership. Security model is mandatory only
+for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
+model as a parameter.
+@item writeout=@var{writeout}
+This is an optional argument. The only supported value is "immediate".
+This means that host page cache will be used to read and write data but
+write notification will be sent to the guest only when the data has been
+reported as written by the storage subsystem.
+@item readonly
+Enables exporting 9p share as a readonly mount for guests. By default
+read-write access is given.
+@item socket=@var{socket}
+Enables proxy filesystem driver to use passed socket file for
+communicating with virtfs-proxy-helper. Usually a helper like libvirt
+will create socketpair and pass one of the fds as sock_fd
+@item sock_fd
+Enables proxy filesystem driver to use passed 'sock_fd' as the socket
+descriptor for interfacing with virtfs-proxy-helper
@end table
ETEXI
+DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
+ "-virtfs_synth Create synthetic file system image\n",
+ QEMU_ARCH_ALL)
+STEXI
+@item -virtfs_synth
+@findex -virtfs_synth
+Create synthetic file system image
+ETEXI
+
DEFHEADING()
DEF("name", HAS_ARG, QEMU_OPTION_name,
@item tls-ciphers=<list>
Specify which ciphers to use.
-@item tls-channel=[main|display|inputs|record|playback|tunnel]
-@item plaintext-channel=[main|display|inputs|record|playback|tunnel]
+@item tls-channel=[main|display|cursor|inputs|record|playback]
+@item plaintext-channel=[main|display|cursor|inputs|record|playback]
Force specific channel to be used with or without TLS encryption. The
options can be specified multiple times to configure multiple
channels. The special name "default" can be used to set the default
adaptive encodings allows to restore the original static behavior of encodings
like Tight.
+@item share=[allow-exclusive|force-shared|ignore]
+
+Set display sharing policy. 'allow-exclusive' allows clients to ask
+for exclusive access. As suggested by the rfb spec this is
+implemented by dropping other connections. Connecting multiple
+clients in parallel requires all clients asking for a shared session
+(vncviewer: -shared switch). This is the default. 'force-shared'
+disables exclusive client access. Useful for shared desktop sessions,
+where you don't want someone forgetting specify -shared disconnect
+everybody else. 'ignore' completely ignores the shared flag and
+allows everybody connect unconditionally. Doesn't conform to the rfb
+spec but is traditional QEMU behavior.
+
@end table
ETEXI
@end table
ETEXI
-DEFHEADING()
+ARCHHEADING(, QEMU_ARCH_I386)
-DEFHEADING(i386 target only:)
+ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
STEXI
@table @option
ETEXI
Disable HPET support.
ETEXI
-DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
- "-balloon none disable balloon device\n"
- "-balloon virtio[,addr=str]\n"
- " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
-STEXI
-@item -balloon none
-@findex -balloon
-Disable balloon device.
-@item -balloon virtio[,addr=@var{addr}]
-Enable virtio balloon device (default), optionally with PCI address
-@var{addr}.
-ETEXI
-
DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
"-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,{data|file}=file1[:file2]...]\n"
" ACPI table description\n", QEMU_ARCH_I386)
"-net tap[,vlan=n][,name=str],ifname=name\n"
" connect the host TAP network interface to VLAN 'n'\n"
#else
- "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostforce=on|off]\n"
- " connect the host TAP network interface to VLAN 'n' and use the\n"
- " network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
- " and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
+ "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostforce=on|off]\n"
+ " connect the host TAP network interface to VLAN 'n' \n"
+ " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
+ " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
+ " to deconfigure it\n"
" use '[down]script=no' to disable script execution\n"
+ " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
+ " configure it\n"
" use 'fd=h' to connect to an already opened TAP interface\n"
" use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
" default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
" (only has effect for virtio guests which use MSIX)\n"
" use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
" use 'vhostfd=h' to connect to an already opened vhost net device\n"
+ "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n"
+ " connects a host TAP network interface to a host bridge device 'br'\n"
+ " (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n"
+ " (default=" DEFAULT_BRIDGE_HELPER ")\n"
#endif
"-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
" connect the vlan 'n' to another VLAN using a socket connection\n"
"-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
" connect the vlan 'n' to multicast maddr and port\n"
" use 'localaddr=addr' to specify the host address to send packets from\n"
+ "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
+ " connect the vlan 'n' to another VLAN using an UDP tunnel\n"
#ifdef CONFIG_VDE
"-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
" connect the vlan 'n' to port 'n' of a vde switch running\n"
"user|"
#endif
"tap|"
+ "bridge|"
#ifdef CONFIG_VDE
"vde|"
#endif
Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
that the card should have; this option currently only affects virtio cards; set
@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
-NIC is created. Qemu can emulate several different models of network card.
+NIC is created. QEMU can emulate several different models of network card.
Valid values for @var{type} are
@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
Example (using pxelinux):
@example
-qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
+qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
@end example
@item smb=@var{dir}[,smbserver=@var{addr}]
@example
# on the host
-qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
+qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
# this host xterm should open in the guest X11 server
xterm -display :1
@end example
@example
# on the host
-qemu -net user,hostfwd=tcp::5555-:23 [...]
+qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
telnet localhost 5555
@end example
syntax gives undefined results. Their use for new applications is discouraged
as they will be removed from future versions.
-@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
+@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
+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:
+automatically provides one. 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.
+
+If running QEMU as an unprivileged user, use the network helper
+@var{helper} to configure the TAP interface. The default network
+helper executable is @file{/usr/local/libexec/qemu-bridge-helper}.
+
+@option{fd}=@var{h} can be used to specify the handle of an already
+opened host TAP interface.
+
+Examples:
+
+@example
+#launch a QEMU instance with the default network script
+qemu-system-i386 linux.img -net nic -net tap
+@end example
+
+@example
+#launch a QEMU instance with two NICs, each one connected
+#to a TAP device
+qemu-system-i386 linux.img \
+ -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
+ -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
+@end example
+
+@example
+#launch a QEMU instance with the default network helper to
+#connect a TAP device to bridge br0
+qemu-system-i386 linux.img \
+ -net nic -net tap,"helper=/usr/local/libexec/qemu-bridge-helper"
+@end example
+
+@item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
+Connect a host TAP network interface to a host bridge device.
+
+Use the network helper @var{helper} to configure the TAP interface and
+attach it to the bridge. The default network helper executable is
+@file{/usr/local/libexec/qemu-bridge-helper} and the default bridge
+device is @file{br0}.
+
+Examples:
@example
-qemu linux.img -net nic -net tap
+#launch a QEMU instance with the default network helper to
+#connect a TAP device to bridge br0
+qemu-system-i386 linux.img -net bridge -net nic,model=virtio
@end example
-More complicated example (two NICs, each one connected to a TAP device)
@example
-qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
- -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
+#launch a QEMU instance with the default network helper to
+#connect a TAP device to bridge qemubr0
+qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
@end example
@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
Example:
@example
# launch a first QEMU instance
-qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
- -net socket,listen=:1234
+qemu-system-i386 linux.img \
+ -net nic,macaddr=52:54:00:12:34:56 \
+ -net socket,listen=:1234
# connect the VLAN 0 of this instance to the VLAN 0
# of the first instance
-qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
- -net socket,connect=127.0.0.1:1234
+qemu-system-i386 linux.img \
+ -net nic,macaddr=52:54:00:12:34:57 \
+ -net socket,connect=127.0.0.1:1234
@end example
@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
Example:
@example
# launch one QEMU instance
-qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
- -net socket,mcast=230.0.0.1:1234
+qemu-system-i386 linux.img \
+ -net nic,macaddr=52:54:00:12:34:56 \
+ -net socket,mcast=230.0.0.1:1234
# launch another QEMU instance on same "bus"
-qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
- -net socket,mcast=230.0.0.1:1234
+qemu-system-i386 linux.img \
+ -net nic,macaddr=52:54:00:12:34:57 \
+ -net socket,mcast=230.0.0.1:1234
# launch yet another QEMU instance on same "bus"
-qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
- -net socket,mcast=230.0.0.1:1234
+qemu-system-i386 linux.img \
+ -net nic,macaddr=52:54:00:12:34:58 \
+ -net socket,mcast=230.0.0.1:1234
@end example
Example (User Mode Linux compat.):
@example
# launch QEMU instance (note mcast address selected
# is UML's default)
-qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
- -net socket,mcast=239.192.168.1:1102
+qemu-system-i386 linux.img \
+ -net nic,macaddr=52:54:00:12:34:56 \
+ -net socket,mcast=239.192.168.1:1102
# launch UML
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
@end example
Example (send packets from host's 1.2.3.4):
@example
-qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
- -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
+qemu-system-i386 linux.img \
+ -net nic,macaddr=52:54:00:12:34:56 \
+ -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
@end example
@item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
# launch vde switch
vde_switch -F -sock /tmp/myswitch
# launch QEMU instance
-qemu linux.img -net nic -net vde,sock=/tmp/myswitch
+qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
@end example
@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
@option{pty} is not available on Windows hosts.
@item -chardev stdio ,id=@var{id} [,signal=on|off]
-Connect to standard input and standard output of the qemu process.
+Connect to standard input and standard output of the QEMU process.
@option{signal} controls if signals are enabled on the terminal, that includes
exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
DEFHEADING()
+STEXI
+DEFHEADING(Device URL Syntax:)
+
+In addition to using normal file images for the emulated storage devices,
+QEMU can also use networked resources such as iSCSI devices. These are
+specified using a special URL syntax.
+
+@table @option
+@item iSCSI
+iSCSI support allows QEMU to access iSCSI resources directly and use as
+images for the guest storage. Both disk and cdrom images are supported.
+
+Syntax for specifying iSCSI LUNs is
+``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
+
+Example (without authentication):
+@example
+qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
+ -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
+ -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+@end example
+
+Example (CHAP username/password via URL):
+@example
+qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
+@end example
+
+Example (CHAP username/password via environment variables):
+@example
+LIBISCSI_CHAP_USERNAME="user" \
+LIBISCSI_CHAP_PASSWORD="password" \
+qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+@end example
+
+iSCSI support is an optional feature of QEMU and only available when
+compiled and linked against libiscsi.
+ETEXI
+DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
+ "-iscsi [user=user][,password=password]\n"
+ " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
+ " [,initiator-name=iqn]\n"
+ " iSCSI session parameters\n", QEMU_ARCH_ALL)
+STEXI
+
+@item NBD
+QEMU supports NBD (Network Block Devices) both using TCP protocol as well
+as Unix Domain Sockets.
+
+Syntax for specifying a NBD device using TCP
+``nbd:<server-ip>:<port>[:exportname=<export>]''
+
+Syntax for specifying a NBD device using Unix Domain Sockets
+``nbd:unix:<domain-socket>[:exportname=<export>]''
+
+
+Example for TCP
+@example
+qemu-system-i386 --drive file=nbd:192.0.2.1:30000
+@end example
+
+Example for Unix Domain Sockets
+@example
+qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
+@end example
+
+@item Sheepdog
+Sheepdog is a distributed storage system for QEMU.
+QEMU supports using either local sheepdog devices or remote networked
+devices.
+
+Syntax for specifying a sheepdog device
+@table @list
+``sheepdog:<vdiname>''
+
+``sheepdog:<vdiname>:<snapid>''
+
+``sheepdog:<vdiname>:<tag>''
+
+``sheepdog:<host>:<port>:<vdiname>''
+
+``sheepdog:<host>:<port>:<vdiname>:<snapid>''
+
+``sheepdog:<host>:<port>:<vdiname>:<tag>''
+@end table
+
+Example
+@example
+qemu-system-i386 --drive file=sheepdog:192.0.2.1:30000:MyVirtualMachine
+@end example
+
+See also @url{http://http://www.osrg.net/sheepdog/}.
+
+@end table
+ETEXI
+
DEFHEADING(Bluetooth(R) options:)
DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
be used as following:
@example
-qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
+qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
@end example
@item -bt device:@var{dev}[,vlan=@var{n}]
first module.
ETEXI
+DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
+ "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
+STEXI
+@item -dtb @var{file}
+@findex -dtb
+Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
+on boot.
+ETEXI
+
STEXI
@end table
ETEXI
When not using a specified @var{src_port} a random port is automatically chosen.
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:
-@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
+@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
+@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
will appear in the netconsole session.
If you plan to send characters back via netconsole or you want to stop
-and start qemu a lot of times, you should have qemu use the same
+and start QEMU a lot of times, you should have QEMU use the same
source port each time by using something like @code{-serial
-udp::4555@@:4556} to qemu. Another approach is to use a patched
+udp::4555@@:4556} to QEMU. Another approach is to use a patched
version of netcat which can listen to a TCP port and send and receive
characters via udp. If you have a patched version of netcat which
activates telnet remote echo and single char transfer, then you can
use the following options to step up a netcat redirector to allow
-telnet on port 5555 to access the qemu port.
+telnet on port 5555 to access the QEMU port.
@table @code
-@item Qemu Options:
+@item QEMU Options:
-serial udp::4555@@:4556
@item netcat options:
-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
@findex -gdb
Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
connections will likely be TCP-based, but also UDP, pseudo TTY, or even
-stdio are reasonable use case. The latter is allowing to start qemu from
+stdio are reasonable use case. The latter is allowing to start QEMU from
within gdb and establish the connection via a pipe:
@example
-(gdb) target remote | exec qemu -gdb stdio ...
+(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
@end example
ETEXI
"-D logfile output log to logfile (instead of the default /tmp/qemu.log)\n",
QEMU_ARCH_ALL)
STEXI
-@item -D
+@item -D @var{logfile}
@findex -D
-Output log in logfile instead of /tmp/qemu.log
+Output log in @var{logfile} instead of /tmp/qemu.log
ETEXI
DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
"-hdachs c,h,s[,t]\n" \
" force hard disk 0 physical geometry and the optional BIOS\n" \
- " translation (t=none or lba) (usually qemu can guess them)\n",
+ " translation (t=none or lba) (usually QEMU can guess them)\n",
QEMU_ARCH_ALL)
STEXI
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
QEMU_ARCH_ALL)
DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
"-xen-attach attach to existing xen domain\n"
- " xend will use this when starting qemu\n",
+ " xend will use this when starting QEMU\n",
QEMU_ARCH_ALL)
STEXI
@item -xen-domid @var{id}
@item -xen-attach
@findex -xen-attach
Attach to existing xen domain.
-xend will use this when starting qemu (XEN only).
+xend will use this when starting QEMU (XEN only).
ETEXI
DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
- "-rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]\n" \
+ "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
" set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
QEMU_ARCH_ALL)
By default the RTC is driven by the host system time. This allows to use the
RTC as accurate reference clock inside the guest, specifically if the host
time is smoothly following an accurate external reference clock, e.g. via NTP.
-If you want to isolate the guest time from the host, even prevent it from
-progressing during suspension, you can set @option{clock} to @code{vm} instead.
+If you want to isolate the guest time from the host, you can set @option{clock}
+to @code{rt} instead. To even prevent it from progressing during suspension,
+you can set it to @code{vm}.
Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
specifically with Windows' ACPI HAL. This option will try to figure out how
STEXI
@item -nodefconfig
@findex -nodefconfig
-Normally QEMU loads a configuration file from @var{sysconfdir}/qemu.conf and
-@var{sysconfdir}/target-@var{ARCH}.conf on startup. The @code{-nodefconfig}
-option will prevent QEMU from loading these configuration files at startup.
+Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
+The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
+ETEXI
+DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
+ "-no-user-config\n"
+ " do not load user-provided config files at startup\n",
+ QEMU_ARCH_ALL)
+STEXI
+@item -no-user-config
+@findex -no-user-config
+The @code{-no-user-config} option makes QEMU not load any of the user-provided
+config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
+files from @var{datadir}.
ETEXI
DEF("trace", HAS_ARG, QEMU_OPTION_trace,
"-trace [events=<file>][,file=<file>]\n"
@end table
ETEXI
+DEF("qtest", HAS_ARG, QEMU_OPTION_qtest,
+ "-qtest CHR specify tracing options\n",
+ QEMU_ARCH_ALL)
+
+DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log,
+ "-qtest-log LOG specify tracing options\n",
+ QEMU_ARCH_ALL)
+
HXCOMM This is the last statement. Insert new options before this line!
STEXI
@end table
projects / qemu.git / blobdiff