| blob | a71aaf8ea895ab26d6935a478141e410bf76ad19 |
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
6 HXCOMM architectures.
10 STEXI
11 @table @option
12 ETEXI
16 STEXI
17 @item -h
18 @findex -h
19 Display help and exit
20 ETEXI
24 STEXI
25 @item -version
26 @findex -version
27 Display version information and exit
28 ETEXI
47 QEMU_ARCH_ALL)
48 STEXI
50 @findex -machine
53 @table @option
58 to initialize.
59 @item kernel_irqchip=on|off
61 @item gfx_passthru=on|off
63 @item vmport=on|off|auto
66 is on.
67 @item kvm_shadow_mem=size
68 Defines the size of the KVM shadow MMU.
77 controls whether AES wrapping keys will be created to allow
81 controls whether DEA wrapping keys will be created to allow
83 @item nvdimm=on|off
85 @end table
86 ETEXI
88 HXCOMM Deprecated by -machine
93 STEXI
95 @findex -cpu
97 ETEXI
107 QEMU_ARCH_ALL)
108 STEXI
109 @item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
110 @findex -smp
118 specifies the maximum number of hotpluggable CPUs.
119 ETEXI
124 STEXI
127 @findex -numa
131 resources. That is, it just assigns existing resources to NUMA nodes. This
132 means that one still has to use the @option{-m}, @option{-smp} options
133 to allocate RAM and VCPUs respectively, and possibly @option{-object}
134 to specify the memory backend for the @samp{memdev} suboption.
136 @samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, if one
137 node uses @samp{memdev}, all of them have to use it.
138 ETEXI
140 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
143 STEXI
144 @item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
145 @findex -add-fd
147 Add a file descriptor to an fd set. Valid options are:
149 @table @option
150 @item fd=@var{fd}
151 This option defines the file descriptor of which a duplicate is added to fd set.
152 The file descriptor cannot be stdin, stdout, or stderr.
153 @item set=@var{set}
154 This option defines the ID of the fd set to add the file descriptor to.
155 @item opaque=@var{opaque}
156 This option defines a free-form string that can be used to describe @var{fd}.
157 @end table
159 You can open an image using pre-opened file descriptors from an fd set:
160 @example
161 qemu-system-i386
162 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
163 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
164 -drive file=/dev/fdset/2,index=0,media=disk
165 @end example
166 ETEXI
168 DEF("set", HAS_ARG, QEMU_OPTION_set,
172 STEXI
173 @item -set @var{group}.@var{id}.@var{arg}=@var{value}
174 @findex -set
176 ETEXI
178 DEF("global", HAS_ARG, QEMU_OPTION_global,
182 QEMU_ARCH_ALL)
183 STEXI
184 @item -global @var{driver}.@var{prop}=@var{value}
185 @itemx -global driver=@var{driver},property=@var{property},value=@var{value}
186 @findex -global
189 @example
190 qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
191 @end example
194 created automatically by the machine model. To create a device which is not
200 ETEXI
209 QEMU_ARCH_ALL)
210 STEXI
211 @item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}][,reboot-timeout=@var{rb_timeout}][,strict=on|off]
212 @findex -boot
217 particular boot order only on the first startup, specify it via
233 system support it.
236 supports it. This only effects when boot priority is changed by
239 @example
246 @end example
249 use is discouraged as it may be removed from future versions.
250 ETEXI
259 QEMU_ARCH_ALL)
260 STEXI
262 @findex -m
266 could be used to set amount of hotpluggable memory slots and maximum amount of
273 @example
275 @end example
278 be enabled and the guest startup RAM will never increase.
279 ETEXI
281 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
283 STEXI
284 @item -mem-path @var{path}
285 @findex -mem-path
286 Allocate guest RAM from a temporarily created file in @var{path}.
287 ETEXI
289 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
291 QEMU_ARCH_ALL)
292 STEXI
293 @item -mem-prealloc
294 @findex -mem-prealloc
295 Preallocate memory when using -mem-path.
296 ETEXI
298 DEF("k", HAS_ARG, QEMU_OPTION_k,
300 QEMU_ARCH_ALL)
301 STEXI
302 @item -k @var{language}
303 @findex -k
304 Use keyboard layout @var{language} (for example @code{fr} for
305 French). This option is only needed where it is not easy to get raw PC
306 keycodes (e.g. on Macs, with some X11 servers or with a VNC
308 hosts.
310 The available layouts are:
311 @example
315 @end example
318 ETEXI
323 QEMU_ARCH_ALL)
324 STEXI
328 parameters.
329 ETEXI
336 STEXI
338 @findex -soundhw
340 available sound hardware.
342 @example
349 @end example
351 Note that Linux's i810_audio OSS kernel (for AC97) module might
352 require manually specifying clocking.
354 @example
355 modprobe i810_audio clocking=48000
356 @end example
357 ETEXI
359 DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
363 STEXI
364 @item -balloon none
365 @findex -balloon
366 Disable balloon device.
367 @item -balloon virtio[,addr=@var{addr}]
368 Enable virtio balloon device (default), optionally with PCI address
369 @var{addr}.
370 ETEXI
372 DEF("device", HAS_ARG, QEMU_OPTION_device,
378 QEMU_ARCH_ALL)
379 STEXI
380 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
381 @findex -device
382 Add device @var{driver}. @var{prop}=@var{value} sets driver
383 properties. Valid properties depend on the driver. To get help on
384 possible drivers and properties, use @code{-device help} and
385 @code{-device @var{driver},help}.
387 Some drivers are:
388 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}]
390 Add an IPMI BMC. This is a simulation of a hardware management
391 interface processor that normally sits on a system. It provides
392 a watchdog and the ability to reset and power control the system.
393 You need to connect this to an IPMI interface to make it useful
395 The IPMI slave address to use for the BMC. The default is 0x20.
396 This address is the BMC's address on the I2C network of management
398 it.
400 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
402 Add a connection to an external IPMI BMC simulator. Instead of
403 locally emulating the BMC like the above item, instead connect
404 to an external entity that provides the IPMI services.
406 A connection is made to an external BMC simulator. If you do this, it
407 is strongly recommended that you use the "reconnect=" chardev option
408 to reconnect to the simulator if the connection is lost. Note that if
409 this is not used carefully, it can be a security issue, as the
410 interface has the ability to send resets, NMIs, and power off the VM.
412 on a secure port on localhost, so neither the simulator nor QEMU is
413 exposed to any outside network.
420 Add a KCS IPMI interafce on the ISA bus. This also adds a
423 @table @option
431 @end table
438 ETEXI
446 QEMU_ARCH_ALL)
447 STEXI
449 @findex -name
454 Naming of individual threads can also be enabled on Linux to aid debugging.
455 ETEXI
460 STEXI
462 @findex -uuid
463 Set system UUID.
464 ETEXI
466 STEXI
467 @end table
468 ETEXI
472 STEXI
473 @table @option
474 ETEXI
479 STEXI
482 @findex -fda
483 @findex -fdb
485 ETEXI
493 STEXI
498 @findex -hda
499 @findex -hdb
500 @findex -hdc
501 @findex -hdd
503 ETEXI
507 QEMU_ARCH_ALL)
508 STEXI
510 @findex -cdrom
514 ETEXI
531 STEXI
533 @findex -drive
537 @table @option
543 Special files such as iSCSI devices can be specified using protocol
549 These options define where is connected the drive by defining the bus number and
550 the unit id.
562 @var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data.
564 @var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
566 @var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) requests are ignored or passed to the filesystem. Some machine types may not support discard requests.
570 an untrusted format header.
572 This option specifies the serial number to assign to the device.
574 Specify the controller's PCI address (if=virtio only).
575 @item werror=@var{action},rerror=@var{action}
576 Specify which @var{action} to take on write and read errors. Valid actions are:
577 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
578 "report" (report the error to the guest), "enospc" (pause QEMU only if the
579 host disk is full; report the error to the guest otherwise).
580 The default setting is @option{werror=enospc} and @option{rerror=report}.
581 @item readonly
582 Open drive @option{file} as read-only. Guest write attempts will fail.
583 @item copy-on-read=@var{copy-on-read}
584 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
585 file sectors into the image file.
586 @item detect-zeroes=@var{detect-zeroes}
587 @var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
588 conversion of plain zero writes by the OS to driver specific optimized
589 zero write commands. You may even choose "unmap" if @var{discard} is set
590 to "unmap" to allow a zero write to be converted to an UNMAP operation.
591 @end table
593 By default, the @option{cache=writeback} mode is used. It will report data
594 writes as completed as soon as the data is present in the host page cache.
595 This is safe as long as your guest OS makes sure to correctly flush disk caches
596 where needed. If your guest OS does not handle volatile disk write caches
597 correctly and your host crashes or loses power, then the guest may experience
598 data corruption.
600 For such guests, you should consider using @option{cache=writethrough}. This
601 means that the host page cache will be used to read and write data, but write
602 notification will be sent to the guest only after QEMU has made sure to flush
603 each write to the disk. Be aware that this has a major impact on performance.
605 The host page cache can be avoided entirely with @option{cache=none}. This will
608 the guest OS must handle the disk write cache correctly in order to avoid data
609 corruption on host crashes.
611 The host page cache can be avoided while only sending write notifications to
612 the guest when the data has been flushed to the disk using
616 @option{cache=unsafe}. This option tells QEMU that it never needs to write any
617 data to the disk but can instead keep things in cache. If anything goes wrong,
618 like your host losing power, the disk storage getting disconnected accidentally,
619 etc. your image will most probably be rendered unusable. When using
620 the @option{-snapshot} option, unsafe caching is always used.
622 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
623 useful when the backing file is over a slow network. By default copy-on-read
624 is off.
626 Instead of @option{-cdrom} you can use:
627 @example
628 qemu-system-i386 -drive file=file,index=2,media=cdrom
629 @end example
631 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
632 use:
633 @example
634 qemu-system-i386 -drive file=file,index=0,media=disk
635 qemu-system-i386 -drive file=file,index=1,media=disk
636 qemu-system-i386 -drive file=file,index=2,media=disk
637 qemu-system-i386 -drive file=file,index=3,media=disk
638 @end example
640 You can open an image using pre-opened file descriptors from an fd set:
641 @example
642 qemu-system-i386
643 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
644 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
645 -drive file=/dev/fdset/2,index=0,media=disk
646 @end example
648 You can connect a CDROM to the slave of ide0:
649 @example
650 qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
651 @end example
654 @example
656 @end example
659 @example
661 @end example
664 @example
667 @end example
670 incremented:
671 @example
673 @end example
674 is interpreted like:
675 @example
676 qemu-system-i386 -hda a -hdb b
677 @end example
678 ETEXI
682 QEMU_ARCH_ALL)
683 STEXI
684 @item -mtdblock @var{file}
685 @findex -mtdblock
686 Use @var{file} as on-board Flash memory image.
687 ETEXI
691 STEXI
692 @item -sd @var{file}
693 @findex -sd
694 Use @var{file} as SecureDigital card image.
695 ETEXI
699 STEXI
700 @item -pflash @var{file}
701 @findex -pflash
702 Use @var{file} as a parallel flash image.
703 ETEXI
707 QEMU_ARCH_ALL)
708 STEXI
709 @item -snapshot
710 @findex -snapshot
711 Write to temporary files instead of disk image files. In this case,
712 the raw disk image you use is not written back. You can however force
713 the write back by pressing @key{C-a s} (@pxref{disk_images}).
714 ETEXI
720 QEMU_ARCH_ALL)
721 STEXI
722 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
723 @findex -hdachs
724 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
725 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
726 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
727 all those parameters. This option is useful for old MS-DOS disk
728 images.
729 ETEXI
732 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
734 QEMU_ARCH_ALL)
736 STEXI
738 @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}]
739 @findex -fsdev
740 Define a new file system device. Valid options are:
741 @table @option
742 @item @var{fsdriver}
743 This option specifies the fs driver backend to use.
745 @item id=@var{id}
746 Specifies identifier for this device
747 @item path=@var{path}
748 Specifies the export path for the file system device. Files under
749 this path will be available to the 9p client on the guest.
750 @item security_model=@var{security_model}
751 Specifies the security model to be used for this export path.
754 credentials as they are created on the guest. This requires QEMU
756 attributes like uid, gid, mode bits and link target are stored as
758 hidden .virtfs_metadata directory. Directories exported by this security model cannot
760 passthrough except the sever won't report failures if it fails to
761 set file attributes like ownership. Security model is mandatory
762 only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
763 security model as a parameter.
764 @item writeout=@var{writeout}
766 This means that host page cache will be used to read and write data but
767 write notification will be sent to the guest only when the data has been
768 reported as written by the storage subsystem.
769 @item readonly
770 Enables exporting 9p share as a readonly mount for guests. By default
771 read-write access is given.
772 @item socket=@var{socket}
773 Enables proxy filesystem driver to use passed socket file for communicating
774 with virtfs-proxy-helper
775 @item sock_fd=@var{sock_fd}
776 Enables proxy filesystem driver to use passed socket descriptor for
777 communicating with virtfs-proxy-helper. Usually a helper like libvirt
778 will create socketpair and pass one of the fds as sock_fd
779 @end table
782 @item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
783 Options for virtio-9p-pci driver are:
784 @table @option
785 @item fsdev=@var{id}
786 Specifies the id value specified along with -fsdev option
787 @item mount_tag=@var{mount_tag}
788 Specifies the tag name to be used by the guest to mount this export point
789 @end table
791 ETEXI
794 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
796 QEMU_ARCH_ALL)
798 STEXI
800 @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}]
801 @findex -virtfs
803 The general form of a Virtual File system pass-through options are:
804 @table @option
805 @item @var{fsdriver}
806 This option specifies the fs driver backend to use.
808 @item id=@var{id}
809 Specifies identifier for this device
810 @item path=@var{path}
811 Specifies the export path for the file system device. Files under
812 this path will be available to the 9p client on the guest.
813 @item security_model=@var{security_model}
814 Specifies the security model to be used for this export path.
817 credentials as they are created on the guest. This requires QEMU
819 attributes like uid, gid, mode bits and link target are stored as
821 hidden .virtfs_metadata directory. Directories exported by this security model cannot
823 passthrough except the sever won't report failures if it fails to
824 set file attributes like ownership. Security model is mandatory only
825 for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
826 model as a parameter.
827 @item writeout=@var{writeout}
829 This means that host page cache will be used to read and write data but
830 write notification will be sent to the guest only when the data has been
831 reported as written by the storage subsystem.
832 @item readonly
833 Enables exporting 9p share as a readonly mount for guests. By default
834 read-write access is given.
835 @item socket=@var{socket}
836 Enables proxy filesystem driver to use passed socket file for
837 communicating with virtfs-proxy-helper. Usually a helper like libvirt
838 will create socketpair and pass one of the fds as sock_fd
839 @item sock_fd
840 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
841 descriptor for interfacing with virtfs-proxy-helper
842 @end table
843 ETEXI
847 QEMU_ARCH_ALL)
848 STEXI
849 @item -virtfs_synth
850 @findex -virtfs_synth
851 Create synthetic file system image
852 ETEXI
854 STEXI
855 @end table
856 ETEXI
857 DEFHEADING()
859 DEFHEADING(USB options:)
860 STEXI
861 @table @option
862 ETEXI
866 QEMU_ARCH_ALL)
867 STEXI
868 @item -usb
869 @findex -usb
870 Enable the USB driver (will be the default soon)
871 ETEXI
875 QEMU_ARCH_ALL)
876 STEXI
878 @item -usbdevice @var{devname}
879 @findex -usbdevice
880 Add the USB device @var{devname}. @xref{usb_devices}.
882 @table @option
884 @item mouse
885 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
887 @item tablet
888 Pointer device that uses absolute coordinates (like a touchscreen). This
889 means QEMU is able to report the mouse position without having to grab the
890 mouse. Also overrides the PS/2 mouse emulation when activated.
892 @item disk:[format=@var{format}]:@var{file}
893 Mass storage device based on file. The optional @var{format} argument
894 will be used rather than detecting the format. Can be used to specify
895 @code{format=raw} to avoid interpreting an untrusted format header.
897 @item host:@var{bus}.@var{addr}
898 Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
900 @item host:@var{vendor_id}:@var{product_id}
901 Pass through the host device identified by @var{vendor_id}:@var{product_id}
902 (Linux only).
904 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
905 Serial converter to host character device @var{dev}, see @code{-serial} for the
906 available devices.
908 @item braille
909 Braille device. This will use BrlAPI to display the braille output on a real
910 or fake device.
912 @item net:@var{options}
913 Network adapter that supports CDC ethernet and RNDIS protocols.
915 @end table
916 ETEXI
918 STEXI
919 @end table
920 ETEXI
921 DEFHEADING()
923 DEFHEADING(Display options:)
924 STEXI
925 @table @option
926 ETEXI
937 #if defined(CONFIG_GTK)
939 #elif defined(CONFIG_SDL)
941 #elif defined(CONFIG_COCOA)
943 #elif defined(CONFIG_VNC)
945 #else
947 #endif
948 , QEMU_ARCH_ALL)
949 STEXI
950 @item -display @var{type}
951 @findex -display
952 Select type of display to use. This option is a replacement for the
953 old style -sdl/-curses/... options. Valid values for @var{type} are
954 @table @option
955 @item sdl
956 Display video output via SDL (usually in a separate graphics
957 window; see the SDL documentation for other possibilities).
958 @item curses
959 Display video output via curses. For graphics device models which
960 support a text mode, QEMU can display this output using a
961 curses/ncurses interface. Nothing is displayed when the graphics
962 device is in graphical mode or if the graphics device does not support
963 a text mode. Generally only the VGA device models support text mode.
964 @item none
965 Do not display video output. The guest will still see an emulated
966 graphics card, but its output will not be displayed to the QEMU
967 user. This option differs from the -nographic option in that it
968 only affects what is done with video output; -nographic also changes
969 the destination of the serial and parallel port data.
970 @item gtk
971 Display video output in a GTK window. This interface provides drop-down
972 menus and other UI elements to configure and control the VM during
973 runtime.
974 @item vnc
975 Start a VNC server on display <arg>
976 @end table
977 ETEXI
981 QEMU_ARCH_ALL)
982 STEXI
983 @item -nographic
984 @findex -nographic
985 Normally, QEMU uses SDL to display the VGA output. With this option,
986 you can totally disable graphical output so that QEMU is a simple
987 command line application. The emulated serial port is redirected on
988 the console and muxed with the monitor (unless redirected elsewhere
989 explicitly). Therefore, you can still use QEMU to debug a Linux kernel
990 with a serial console. Use @key{C-a h} for help on switching between
991 the console and monitor.
992 ETEXI
996 QEMU_ARCH_ALL)
997 STEXI
998 @item -curses
999 @findex -curses
1000 Normally, QEMU uses SDL to display the VGA output. With this option,
1001 QEMU can display the VGA output when in text mode using a
1002 curses/ncurses interface. Nothing is displayed in graphical mode.
1003 ETEXI
1007 QEMU_ARCH_ALL)
1008 STEXI
1009 @item -no-frame
1010 @findex -no-frame
1011 Do not use decorations for SDL windows and start them using the whole
1012 available screen space. This makes the using QEMU in a dedicated desktop
1013 workspace more convenient.
1014 ETEXI
1018 QEMU_ARCH_ALL)
1019 STEXI
1020 @item -alt-grab
1021 @findex -alt-grab
1022 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1023 affects the special keys (for fullscreen, monitor-mode switching, etc).
1024 ETEXI
1028 QEMU_ARCH_ALL)
1029 STEXI
1030 @item -ctrl-grab
1031 @findex -ctrl-grab
1032 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1033 affects the special keys (for fullscreen, monitor-mode switching, etc).
1034 ETEXI
1038 STEXI
1039 @item -no-quit
1040 @findex -no-quit
1041 Disable SDL window close capability.
1042 ETEXI
1046 STEXI
1047 @item -sdl
1048 @findex -sdl
1049 Enable SDL.
1050 ETEXI
1070 QEMU_ARCH_ALL)
1071 STEXI
1072 @item -spice @var{option}[,@var{option}[,...]]
1073 @findex -spice
1074 Enable the spice remote desktop protocol. Valid options are
1076 @table @option
1078 @item port=<nr>
1079 Set the TCP port spice is listening on for plaintext channels.
1081 @item addr=<addr>
1082 Set the IP address spice is listening on. Default is any address.
1084 @item ipv4
1085 @itemx ipv6
1086 @itemx unix
1087 Force using the specified IP version.
1089 @item password=<secret>
1090 Set the password you need to authenticate.
1092 @item sasl
1093 Require that the client use SASL to authenticate with the spice.
1094 The exact choice of authentication method used is controlled from the
1095 system / user's SASL configuration file for the 'qemu' service. This
1096 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1097 unprivileged user, an environment variable SASL_CONF_PATH can be used
1098 to make it search alternate locations for the service config.
1099 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1100 it is recommended that SASL always be combined with the 'tls' and
1101 'x509' settings to enable use of SSL and server certificates. This
1102 ensures a data encryption preventing compromise of authentication
1103 credentials.
1105 @item disable-ticketing
1106 Allow client connects without authentication.
1108 @item disable-copy-paste
1109 Disable copy paste between the client and the guest.
1111 @item disable-agent-file-xfer
1112 Disable spice-vdagent based file-xfer between the client and the guest.
1114 @item tls-port=<nr>
1115 Set the TCP port spice is listening on for encrypted channels.
1117 @item x509-dir=<dir>
1118 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1120 @item x509-key-file=<file>
1121 @itemx x509-key-password=<file>
1122 @itemx x509-cert-file=<file>
1123 @itemx x509-cacert-file=<file>
1124 @itemx x509-dh-key-file=<file>
1125 The x509 file names can also be configured individually.
1127 @item tls-ciphers=<list>
1128 Specify which ciphers to use.
1130 @item tls-channel=[main|display|cursor|inputs|record|playback]
1131 @itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
1132 Force specific channel to be used with or without TLS encryption. The
1133 options can be specified multiple times to configure multiple
1135 mode. For channels which are not explicitly forced into one mode the
1136 spice client is allowed to pick tls/plaintext as he pleases.
1138 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1139 Configure image compression (lossless).
1140 Default is auto_glz.
1142 @item jpeg-wan-compression=[auto|never|always]
1143 @itemx zlib-glz-wan-compression=[auto|never|always]
1144 Configure wan image compression (lossy for slow links).
1145 Default is auto.
1147 @item streaming-video=[off|all|filter]
1148 Configure video stream detection. Default is filter.
1150 @item agent-mouse=[on|off]
1151 Enable/disable passing mouse events via vdagent. Default is on.
1153 @item playback-compression=[on|off]
1154 Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1156 @item seamless-migration=[on|off]
1157 Enable/disable spice seamless migration. Default is off.
1159 @item gl=[on|off]
1160 Enable/disable OpenGL context. Default is off.
1162 @end table
1163 ETEXI
1167 QEMU_ARCH_ALL)
1168 STEXI
1169 @item -portrait
1170 @findex -portrait
1171 Rotate graphical output 90 deg left (only PXA LCD).
1172 ETEXI
1176 QEMU_ARCH_ALL)
1177 STEXI
1178 @item -rotate @var{deg}
1179 @findex -rotate
1180 Rotate graphical output some deg left (only PXA LCD).
1181 ETEXI
1186 STEXI
1187 @item -vga @var{type}
1188 @findex -vga
1189 Select type of VGA card to emulate. Valid values for @var{type} are
1190 @table @option
1191 @item cirrus
1192 Cirrus Logic GD5446 Video card. All Windows versions starting from
1193 Windows 95 should recognize and use this graphic card. For optimal
1194 performances, use 16 bit color depth in the guest and the host OS.
1195 (This one is the default)
1196 @item std
1197 Standard VGA card with Bochs VBE extensions. If your guest OS
1198 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1199 to use high resolution modes (>= 1280x1024x16) then you should use
1200 this option.
1201 @item vmware
1202 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1203 recent XFree86/XOrg server or Windows guest with a driver for this
1204 card.
1205 @item qxl
1206 QXL paravirtual graphic card. It is VGA compatible (including VESA
1207 2.0 VBE support). Works best with qxl guest drivers installed though.
1208 Recommended choice when using the spice protocol.
1209 @item tcx
1210 (sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1211 sun4m machines and offers both 8-bit and 24-bit colour depths at a
1212 fixed resolution of 1024x768.
1213 @item cg3
1214 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1215 for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1216 resolutions aimed at people wishing to run older Solaris versions.
1217 @item virtio
1218 Virtio VGA card.
1219 @item none
1220 Disable VGA card.
1221 @end table
1222 ETEXI
1226 STEXI
1227 @item -full-screen
1228 @findex -full-screen
1229 Start in full screen.
1230 ETEXI
1234 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
1235 STEXI
1236 @item -g @var{width}x@var{height}[x@var{depth}]
1237 @findex -g
1238 Set the initial graphical resolution and depth (PPC, SPARC only).
1239 ETEXI
1243 STEXI
1244 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1245 @findex -vnc
1246 Normally, QEMU uses SDL to display the VGA output. With this option,
1247 you can have QEMU listen on VNC display @var{display} and redirect the VGA
1248 display over the VNC session. It is very useful to enable the usb
1249 tablet device when using this option (option @option{-usbdevice
1250 tablet}). When using the VNC display, you must use the @option{-k}
1251 parameter to set the keyboard layout if you are not using en-us. Valid
1252 syntax for the @var{display} is
1254 @table @option
1256 @item to=@var{L}
1258 With this option, QEMU will try next available VNC @var{display}s, until the
1260 available, e.g. port 5900+@var{display} is already used by another
1261 application. By default, to=0.
1263 @item @var{host}:@var{d}
1265 TCP connections will only be allowed from @var{host} on display @var{d}.
1266 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1267 be omitted in which case the server will accept connections from any host.
1269 @item unix:@var{path}
1271 Connections will be allowed over UNIX domain sockets where @var{path} is the
1272 location of a unix socket to listen for connections on.
1274 @item none
1276 VNC is initialized but not started. The monitor @code{change} command
1277 can be used to later start the VNC server.
1279 @end table
1281 Following the @var{display} value there may be one or more @var{option} flags
1282 separated by commas. Valid options are
1284 @table @option
1286 @item reverse
1288 Connect to a listening VNC client via a ``reverse'' connection. The
1289 client is specified by the @var{display}. For reverse network
1290 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1291 is a TCP port number, not a display number.
1293 @item websocket
1295 Opens an additional TCP listening port dedicated to VNC Websocket connections.
1296 By definition the Websocket port is 5700+@var{display}. If @var{host} is
1297 specified connections will only be allowed from this host.
1298 As an alternative the Websocket port could be specified by using
1299 @code{websocket}=@var{port}.
1300 If no TLS credentials are provided, the websocket connection runs in
1301 unencrypted mode. If TLS credentials are provided, the websocket connection
1302 requires encrypted client connections.
1304 @item password
1306 Require that password based authentication is used for client connections.
1308 The password must be set separately using the @code{set_password} command in
1309 the @ref{pcsys_monitor}. The syntax to change your password is:
1310 @code{set_password <protocol> <password>} where <protocol> could be either
1313 If you would like to change <protocol> password expiration, you should use
1314 @code{expire_password <protocol> <expiration-time>} where expiration time could
1315 be one of the following options: now, never, +seconds or UNIX time of
1316 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1318 date and time).
1321 allow <protocol> password to expire immediately or never expire.
1323 @item tls-creds=@var{ID}
1325 Provides the ID of a set of TLS credentials to use to secure the
1326 VNC server. They will apply to both the normal VNC server socket
1327 and the websocket socket (if enabled). Setting TLS credentials
1328 will cause the VNC server socket to enable the VeNCrypt auth
1329 mechanism. The credentials should have been previously created
1330 using the @option{-object tls-creds} argument.
1332 The @option{tls-creds} parameter obsoletes the @option{tls},
1333 @option{x509}, and @option{x509verify} options, and as such
1334 it is not permitted to set both new and old type options at
1335 the same time.
1337 @item tls
1339 Require that client use TLS when communicating with the VNC server. This
1340 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1341 attack. It is recommended that this option be combined with either the
1342 @option{x509} or @option{x509verify} options.
1344 This option is now deprecated in favor of using the @option{tls-creds}
1345 argument.
1347 @item x509=@var{/path/to/certificate/dir}
1349 Valid if @option{tls} is specified. Require that x509 credentials are used
1350 for negotiating the TLS session. The server will send its x509 certificate
1351 to the client. It is recommended that a password be set on the VNC server
1352 to provide authentication of the client when this is used. The path following
1353 this option specifies where the x509 certificates are to be loaded from.
1354 See the @ref{vnc_security} section for details on generating certificates.
1356 This option is now deprecated in favour of using the @option{tls-creds}
1357 argument.
1359 @item x509verify=@var{/path/to/certificate/dir}
1361 Valid if @option{tls} is specified. Require that x509 credentials are used
1362 for negotiating the TLS session. The server will send its x509 certificate
1363 to the client, and request that the client send its own x509 certificate.
1364 The server will validate the client's certificate against the CA certificate,
1365 and reject clients when validation fails. If the certificate authority is
1366 trusted, this is a sufficient authentication mechanism. You may still wish
1367 to set a password on the VNC server as a second authentication layer. The
1368 path following this option specifies where the x509 certificates are to
1369 be loaded from. See the @ref{vnc_security} section for details on generating
1370 certificates.
1372 This option is now deprecated in favour of using the @option{tls-creds}
1373 argument.
1375 @item sasl
1377 Require that the client use SASL to authenticate with the VNC server.
1378 The exact choice of authentication method used is controlled from the
1379 system / user's SASL configuration file for the 'qemu' service. This
1380 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1381 unprivileged user, an environment variable SASL_CONF_PATH can be used
1382 to make it search alternate locations for the service config.
1383 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1384 it is recommended that SASL always be combined with the 'tls' and
1385 'x509' settings to enable use of SSL and server certificates. This
1386 ensures a data encryption preventing compromise of authentication
1387 credentials. See the @ref{vnc_security} section for details on using
1388 SASL authentication.
1390 @item acl
1392 Turn on access control lists for checking of the x509 client certificate
1393 and SASL party. For x509 certs, the ACL check is made against the
1394 certificate's distinguished name. This is something that looks like
1395 @code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1396 made against the username, which depending on the SASL plugin, may
1397 include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1398 When the @option{acl} flag is set, the initial access list will be
1399 empty, with a @code{deny} policy. Thus no one will be allowed to
1400 use the VNC server until the ACLs have been loaded. This can be
1401 achieved using the @code{acl} monitor command.
1403 @item lossy
1405 Enable lossy compression methods (gradient, JPEG, ...). If this
1406 option is set, VNC client may receive lossy framebuffer updates
1407 depending on its encoding settings. Enabling this option can save
1408 a lot of bandwidth at the expense of quality.
1410 @item non-adaptive
1412 Disable adaptive encodings. Adaptive encodings are enabled by default.
1413 An adaptive encoding will try to detect frequently updated screen regions,
1414 and send updates in these regions using a lossy encoding (like JPEG).
1415 This can be really helpful to save bandwidth when playing videos. Disabling
1416 adaptive encodings restores the original static behavior of encodings
1417 like Tight.
1419 @item share=[allow-exclusive|force-shared|ignore]
1421 Set display sharing policy. 'allow-exclusive' allows clients to ask
1422 for exclusive access. As suggested by the rfb spec this is
1423 implemented by dropping other connections. Connecting multiple
1424 clients in parallel requires all clients asking for a shared session
1425 (vncviewer: -shared switch). This is the default. 'force-shared'
1426 disables exclusive client access. Useful for shared desktop sessions,
1427 where you don't want someone forgetting specify -shared disconnect
1428 everybody else. 'ignore' completely ignores the shared flag and
1429 allows everybody connect unconditionally. Doesn't conform to the rfb
1430 spec but is traditional QEMU behavior.
1432 @item key-delay-ms
1434 Set keyboard delay, for key down and key up events, in milliseconds.
1435 Default is 1. Keyboards are low-bandwidth devices, so this slowdown
1436 can help the device and guest to keep up and not lose events in case
1437 events are arriving in bulk. Possible causes for the latter are flaky
1438 network connections, or scripts for automated testing.
1440 @end table
1441 ETEXI
1443 STEXI
1444 @end table
1445 ETEXI
1446 ARCHHEADING(, QEMU_ARCH_I386)
1448 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
1449 STEXI
1450 @table @option
1451 ETEXI
1455 QEMU_ARCH_I386)
1456 STEXI
1457 @item -win2k-hack
1458 @findex -win2k-hack
1459 Use it when installing Windows 2000 to avoid a disk full bug. After
1460 Windows 2000 is installed, you no longer need this option (this option
1461 slows down the IDE transfers).
1462 ETEXI
1464 HXCOMM Deprecated by -rtc
1469 QEMU_ARCH_I386)
1470 STEXI
1471 @item -no-fd-bootchk
1472 @findex -no-fd-bootchk
1473 Disable boot signature checking for floppy disks in BIOS. May
1474 be needed to boot from old floppy disks.
1475 ETEXI
1479 STEXI
1480 @item -no-acpi
1481 @findex -no-acpi
1482 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1483 it if your guest OS complains about ACPI problems (PC target machine
1484 only).
1485 ETEXI
1489 STEXI
1490 @item -no-hpet
1491 @findex -no-hpet
1492 Disable HPET support.
1493 ETEXI
1496 "-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"
1498 STEXI
1499 @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}]...]
1500 @findex -acpitable
1501 Add ACPI table with specified header fields and context from specified files.
1502 For file=, take whole ACPI table from the specified files, including all
1503 ACPI headers (possible overridden by other options).
1504 For data=, only data
1505 portion of the table is used, all header information is specified in the
1506 command line.
1507 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1508 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1509 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1510 spec.
1511 ETEXI
1534 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1535 STEXI
1536 @item -smbios file=@var{binary}
1537 @findex -smbios
1538 Load SMBIOS entry from binary file.
1540 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
1541 Specify SMBIOS type 0 fields
1543 @item -smbios type=1[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,uuid=@var{uuid}][,sku=@var{str}][,family=@var{str}]
1544 Specify SMBIOS type 1 fields
1546 @item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}]
1547 Specify SMBIOS type 2 fields
1549 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1550 Specify SMBIOS type 3 fields
1552 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1553 Specify SMBIOS type 4 fields
1555 @item -smbios type=17[,loc_pfx=@var{str}][,bank=@var{str}][,manufacturer=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}][,speed=@var{%d}]
1556 Specify SMBIOS type 17 fields
1557 ETEXI
1559 STEXI
1560 @end table
1561 ETEXI
1562 DEFHEADING()
1564 DEFHEADING(Network options:)
1565 STEXI
1566 @table @option
1567 ETEXI
1569 HXCOMM Legacy slirp options (now moved to -net user):
1570 #ifdef CONFIG_SLIRP
1574 #ifndef _WIN32
1576 #endif
1577 #endif
1580 #ifdef CONFIG_SLIRP
1586 #ifndef _WIN32
1588 #endif
1591 #endif
1592 #ifdef _WIN32
1595 #else
1625 #endif
1626 #ifdef __linux__
1652 #endif
1662 #ifdef CONFIG_VDE
1668 #endif
1669 #ifdef CONFIG_NETMAP
1674 #endif
1688 #ifdef CONFIG_SLIRP
1690 #endif
1693 #ifdef CONFIG_VDE
1695 #endif
1696 #ifdef CONFIG_NETMAP
1698 #endif
1702 STEXI
1703 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1704 @findex -net
1705 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1706 = 0 is the default). The NIC is an e1000 by default on the PC
1707 target. Optionally, the MAC address can be changed to @var{mac}, the
1708 device address set to @var{addr} (PCI cards only),
1709 and a @var{name} can be assigned for use in monitor commands.
1710 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1711 that the card should have; this option currently only affects virtio cards; set
1712 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1713 NIC is created. QEMU can emulate several different models of network card.
1714 Valid values for @var{type} are
1715 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1716 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1717 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1718 Not all devices are supported on all targets. Use @code{-net nic,model=help}
1719 for a list of available devices for your target.
1721 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
1722 @findex -netdev
1723 @item -net user[,@var{option}][,@var{option}][,...]
1724 Use the user mode network stack which requires no administrator
1725 privilege to run. Valid options are:
1727 @table @option
1728 @item vlan=@var{n}
1729 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1731 @item id=@var{id}
1732 @itemx name=@var{name}
1733 Assign symbolic name for use in monitor commands.
1735 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
1736 be enabled. If neither is specified both protocols are enabled.
1738 @item net=@var{addr}[/@var{mask}]
1739 Set IP network address the guest will see. Optionally specify the netmask,
1740 either in the form a.b.c.d or as number of valid top-most bits. Default is
1741 10.0.2.0/24.
1743 @item host=@var{addr}
1744 Specify the guest-visible address of the host. Default is the 2nd IP in the
1745 guest network, i.e. x.x.x.2.
1747 @item ipv6-net=@var{addr}[/@var{int}]
1748 Set IPv6 network address the guest will see (default is fec0::/64). The
1749 network prefix is given in the usual hexadecimal IPv6 address
1750 notation. The prefix size is optional, and is given as the number of
1751 valid top-most bits (default is 64).
1753 @item ipv6-host=@var{addr}
1754 Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
1755 the guest network, i.e. xxxx::2.
1757 @item restrict=on|off
1758 If this option is enabled, the guest will be isolated, i.e. it will not be
1759 able to contact the host and no guest IP packets will be routed over the host
1760 to the outside. This option does not affect any explicitly set forwarding rules.
1762 @item hostname=@var{name}
1763 Specifies the client hostname reported by the built-in DHCP server.
1765 @item dhcpstart=@var{addr}
1766 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1767 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1769 @item dns=@var{addr}
1770 Specify the guest-visible address of the virtual nameserver. The address must
1771 be different from the host address. Default is the 3rd IP in the guest network,
1772 i.e. x.x.x.3.
1774 @item ipv6-dns=@var{addr}
1775 Specify the guest-visible address of the IPv6 virtual nameserver. The address
1776 must be different from the host address. Default is the 3rd IP in the guest
1777 network, i.e. xxxx::3.
1779 @item dnssearch=@var{domain}
1780 Provides an entry for the domain-search list sent by the built-in
1781 DHCP server. More than one domain suffix can be transmitted by specifying
1782 this option multiple times. If supported, this will cause the guest to
1783 automatically try to append the given domain suffix(es) in case a domain name
1784 can not be resolved.
1786 Example:
1787 @example
1788 qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1789 @end example
1791 @item tftp=@var{dir}
1792 When using the user mode network stack, activate a built-in TFTP
1793 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1794 The TFTP client on the guest must be configured in binary mode (use the command
1795 @code{bin} of the Unix TFTP client).
1797 @item bootfile=@var{file}
1798 When using the user mode network stack, broadcast @var{file} as the BOOTP
1799 filename. In conjunction with @option{tftp}, this can be used to network boot
1800 a guest from a local directory.
1802 Example (using pxelinux):
1803 @example
1804 qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1805 @end example
1807 @item smb=@var{dir}[,smbserver=@var{addr}]
1808 When using the user mode network stack, activate a built-in SMB
1809 server so that Windows OSes can access to the host files in @file{@var{dir}}
1810 transparently. The IP address of the SMB server can be set to @var{addr}. By
1811 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1813 In the guest Windows OS, the line:
1814 @example
1815 10.0.2.4 smbserver
1816 @end example
1817 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1818 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1822 Note that a SAMBA server must be installed on the host OS.
1823 QEMU was tested successfully with smbd versions from Red Hat 9,
1824 Fedora Core 3 and OpenSUSE 11.x.
1826 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1827 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1828 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1829 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1830 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1831 be bound to a specific host interface. If no connection type is set, TCP is
1832 used. This option can be given multiple times.
1834 For example, to redirect host X11 connection from screen 1 to guest
1835 screen 0, use the following:
1837 @example
1838 # on the host
1839 qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1840 # this host xterm should open in the guest X11 server
1841 xterm -display :1
1842 @end example
1844 To redirect telnet connections from host port 5555 to telnet port on
1845 the guest, use the following:
1847 @example
1848 # on the host
1849 qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
1850 telnet localhost 5555
1851 @end example
1853 Then when you use on the host @code{telnet localhost 5555}, you
1854 connect to the guest telnet server.
1856 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1857 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
1858 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1859 to the character device @var{dev} or to a program executed by @var{cmd:command}
1860 which gets spawned for each connection. This option can be given multiple times.
1862 You can either use a chardev directly and have that one used throughout QEMU's
1863 lifetime, like in the following example:
1865 @example
1866 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1867 # the guest accesses it
1868 qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
1869 @end example
1871 Or you can execute a command on every TCP connection established by the guest,
1872 so that QEMU behaves similar to an inetd process for that virtual server:
1874 @example
1876 # and connect the TCP stream to its stdin/stdout
1877 qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1878 @end example
1880 @end table
1882 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1883 processed and applied to -net user. Mixing them with the new configuration
1884 syntax gives undefined results. Their use for new applications is discouraged
1885 as they will be removed from future versions.
1887 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1888 @itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1889 Connect the host TAP network interface @var{name} to VLAN @var{n}.
1891 Use the network script @var{file} to configure it and the network script
1892 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1893 automatically provides one. The default network configure script is
1894 @file{/etc/qemu-ifup} and the default network deconfigure script is
1895 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1896 to disable script execution.
1898 If running QEMU as an unprivileged user, use the network helper
1899 @var{helper} to configure the TAP interface. The default network
1900 helper executable is @file{/path/to/qemu-bridge-helper}.
1902 @option{fd}=@var{h} can be used to specify the handle of an already
1903 opened host TAP interface.
1905 Examples:
1907 @example
1908 #launch a QEMU instance with the default network script
1909 qemu-system-i386 linux.img -net nic -net tap
1910 @end example
1912 @example
1913 #launch a QEMU instance with two NICs, each one connected
1914 #to a TAP device
1915 qemu-system-i386 linux.img \
1916 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1917 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1918 @end example
1920 @example
1921 #launch a QEMU instance with the default network helper to
1922 #connect a TAP device to bridge br0
1923 qemu-system-i386 linux.img \
1925 @end example
1927 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
1928 @itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
1929 Connect a host TAP network interface to a host bridge device.
1931 Use the network helper @var{helper} to configure the TAP interface and
1932 attach it to the bridge. The default network helper executable is
1933 @file{/path/to/qemu-bridge-helper} and the default bridge
1934 device is @file{br0}.
1936 Examples:
1938 @example
1939 #launch a QEMU instance with the default network helper to
1940 #connect a TAP device to bridge br0
1941 qemu-system-i386 linux.img -net bridge -net nic,model=virtio
1942 @end example
1944 @example
1945 #launch a QEMU instance with the default network helper to
1946 #connect a TAP device to bridge qemubr0
1947 qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
1948 @end example
1950 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1951 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1953 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1954 machine using a TCP socket connection. If @option{listen} is
1955 specified, QEMU waits for incoming connections on @var{port}
1956 (@var{host} is optional). @option{connect} is used to connect to
1957 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1958 specifies an already opened TCP socket.
1960 Example:
1961 @example
1962 # launch a first QEMU instance
1963 qemu-system-i386 linux.img \
1964 -net nic,macaddr=52:54:00:12:34:56 \
1965 -net socket,listen=:1234
1966 # connect the VLAN 0 of this instance to the VLAN 0
1967 # of the first instance
1968 qemu-system-i386 linux.img \
1969 -net nic,macaddr=52:54:00:12:34:57 \
1970 -net socket,connect=127.0.0.1:1234
1971 @end example
1973 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1974 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1976 Create a VLAN @var{n} shared with another QEMU virtual
1977 machines using a UDP multicast socket, effectively making a bus for
1978 every QEMU with same multicast address @var{maddr} and @var{port}.
1979 NOTES:
1980 @enumerate
1981 @item
1982 Several QEMU can be running on different hosts and share same bus (assuming
1983 correct multicast setup for these hosts).
1984 @item
1985 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1986 @url{http://user-mode-linux.sf.net}.
1987 @item
1988 Use @option{fd=h} to specify an already opened UDP multicast socket.
1989 @end enumerate
1991 Example:
1992 @example
1993 # launch one QEMU instance
1994 qemu-system-i386 linux.img \
1995 -net nic,macaddr=52:54:00:12:34:56 \
1996 -net socket,mcast=230.0.0.1:1234
1998 qemu-system-i386 linux.img \
1999 -net nic,macaddr=52:54:00:12:34:57 \
2000 -net socket,mcast=230.0.0.1:1234
2002 qemu-system-i386 linux.img \
2003 -net nic,macaddr=52:54:00:12:34:58 \
2004 -net socket,mcast=230.0.0.1:1234
2005 @end example
2007 Example (User Mode Linux compat.):
2008 @example
2009 # launch QEMU instance (note mcast address selected
2010 # is UML's default)
2011 qemu-system-i386 linux.img \
2012 -net nic,macaddr=52:54:00:12:34:56 \
2013 -net socket,mcast=239.192.168.1:1102
2014 # launch UML
2015 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2016 @end example
2018 Example (send packets from host's 1.2.3.4):
2019 @example
2020 qemu-system-i386 linux.img \
2021 -net nic,macaddr=52:54:00:12:34:56 \
2022 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2023 @end example
2025 @item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
2026 @itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
2027 Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
2028 protocol to transport Ethernet (and other Layer 2) data frames between
2029 two systems. It is present in routers, firewalls and the Linux kernel
2030 (from version 3.3 onwards).
2032 This transport allows a VM to communicate to another VM, router or firewall directly.
2034 @item src=@var{srcaddr}
2035 source address (mandatory)
2036 @item dst=@var{dstaddr}
2037 destination address (mandatory)
2038 @item udp
2039 select udp encapsulation (default is ip).
2040 @item srcport=@var{srcport}
2041 source udp port.
2042 @item dstport=@var{dstport}
2043 destination udp port.
2044 @item ipv6
2045 force v6, otherwise defaults to v4.
2046 @item rxcookie=@var{rxcookie}
2047 @itemx txcookie=@var{txcookie}
2048 Cookies are a weak form of security in the l2tpv3 specification.
2049 Their function is mostly to prevent misconfiguration. By default they are 32
2050 bit.
2051 @item cookie64
2052 Set cookie size to 64 bit instead of the default 32
2053 @item counter=off
2054 Force a 'cut-down' L2TPv3 with no counter as in
2055 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2056 @item pincounter=on
2057 Work around broken counter handling in peer. This may also help on
2058 networks which have packet reorder.
2059 @item offset=@var{offset}
2060 Add an extra offset between header and data
2062 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2063 on the remote Linux host 1.2.3.4:
2064 @example
2065 # Setup tunnel on linux host using raw ip as encapsulation
2066 # on 1.2.3.4
2067 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2068 encap udp udp_sport 16384 udp_dport 16384
2069 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2070 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2071 ifconfig vmtunnel0 mtu 1500
2072 ifconfig vmtunnel0 up
2073 brctl addif br-lan vmtunnel0
2076 # on 4.3.2.1
2077 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2079 qemu-system-i386 linux.img -net nic -net l2tpv3,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2082 @end example
2084 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2085 @itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2086 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
2087 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2088 and MODE @var{octalmode} to change default ownership and permissions for
2089 communication port. This option is only available if QEMU has been compiled
2090 with vde support enabled.
2092 Example:
2093 @example
2094 # launch vde switch
2095 vde_switch -F -sock /tmp/myswitch
2096 # launch QEMU instance
2097 qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
2098 @end example
2100 @item -netdev hubport,id=@var{id},hubid=@var{hubid}
2105 netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
2106 required hub automatically.
2108 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
2110 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2111 be a unix domain socket backed one. The vhost-user uses a specifically defined
2112 protocol to pass vhost ioctl replacement messages to an application on the other
2113 end of the socket. On non-MSIX guests, the feature can be forced with
2114 @var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2115 be created for multiqueue vhost-user.
2117 Example:
2118 @example
2119 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2120 -numa node,memdev=mem \
2121 -chardev socket,path=/path/to/socket \
2122 -netdev type=vhost-user,id=net0,chardev=chr0 \
2123 -device virtio-net-pci,netdev=net0
2124 @end example
2126 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
2127 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
2128 At most @var{len} bytes (64k by default) per packet are stored. The file format is
2129 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
2130 Note: For devices created with '-netdev', use '-object filter-dump,...' instead.
2132 @item -net none
2133 Indicate that no network devices should be configured. It is used to
2134 override the default configuration (@option{-net nic -net user}) which
2135 is activated if no @option{-net} options are provided.
2136 ETEXI
2138 STEXI
2139 @end table
2140 ETEXI
2141 DEFHEADING()
2143 DEFHEADING(Character device options:)
2144 STEXI
2146 The general form of a character device option is:
2147 @table @option
2148 ETEXI
2152 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
2166 #ifdef _WIN32
2169 #else
2172 #endif
2173 #ifdef CONFIG_BRLAPI
2175 #endif
2176 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2177 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2180 #endif
2181 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2184 #endif
2185 #if defined(CONFIG_SPICE)
2188 #endif
2189 , QEMU_ARCH_ALL
2190 )
2192 STEXI
2193 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
2194 @findex -chardev
2195 Backend is one of:
2196 @option{null},
2197 @option{socket},
2198 @option{udp},
2199 @option{msmouse},
2200 @option{vc},
2201 @option{ringbuf},
2202 @option{file},
2203 @option{pipe},
2204 @option{console},
2205 @option{serial},
2206 @option{pty},
2207 @option{stdio},
2208 @option{braille},
2209 @option{tty},
2210 @option{parallel},
2211 @option{parport},
2212 @option{spicevmc}.
2213 @option{spiceport}.
2214 The specific backend will determine the applicable options.
2216 All devices must have an id, which can be any string up to 127 characters long.
2217 It is used to uniquely identify this device in other command line directives.
2219 A character device may be used in multiplexing mode by multiple front-ends.
2220 Specify @option{mux=on} to enable this mode.
2223 If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2224 create a multiplexer with your specified ID, and you can then configure multiple
2225 front ends to use that chardev ID for their input/output. Up to four different
2226 front ends can be connected to a single multiplexed chardev. (Without
2227 multiplexing enabled, a chardev can only be used by a single front end.)
2228 For instance you could use this to allow a single stdio chardev to be used by
2229 two serial ports and the QEMU monitor:
2231 @example
2232 -chardev stdio,mux=on,id=char0 \
2233 -mon chardev=char0,mode=readline,default \
2234 -serial chardev:char0 \
2235 -serial chardev:char0
2236 @end example
2238 You can have more than one multiplexer in a system configuration; for instance
2239 you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2240 multiplexed between the QEMU monitor and a parallel port:
2242 @example
2243 -chardev stdio,mux=on,id=char0 \
2244 -mon chardev=char0,mode=readline,default \
2245 -parallel chardev:char0 \
2246 -chardev tcp,...,mux=on,id=char1 \
2247 -serial chardev:char1 \
2248 -serial chardev:char1
2249 @end example
2251 When you're using a multiplexed character device, some escape sequences are
2252 interpreted in the input. @xref{mux_keys, Keys in the character backend
2253 multiplexer}.
2255 Note that some other command line options may implicitly create multiplexed
2256 character backends; for instance @option{-serial mon:stdio} creates a
2257 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2258 and @option{-nographic} also multiplexes the console and the monitor to
2259 stdio.
2261 There is currently no support for multiplexing in the other direction
2262 (where a single QEMU front end takes input and output from multiple chardevs).
2264 Every backend supports the @option{logfile} option, which supplies the path
2265 to a file to record all data transmitted via the backend. The @option{logappend}
2266 option controls whether the log file will be truncated or appended to when
2267 opened.
2269 Further options to each backend are described below.
2271 @item -chardev null ,id=@var{id}
2272 A void device. This device will not emit any data, and will drop any data it
2273 receives. The null backend does not take any options.
2275 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}]
2277 Create a two-way stream socket, which can be either a TCP or a unix socket. A
2278 unix socket will be created if @option{path} is specified. Behaviour is
2279 undefined if TCP options are specified for a unix socket.
2281 @option{server} specifies that the socket shall be a listening socket.
2283 @option{nowait} specifies that QEMU should not block waiting for a client to
2284 connect to a listening socket.
2286 @option{telnet} specifies that traffic on the socket should interpret telnet
2287 escape sequences.
2289 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
2290 the remote end goes away. qemu will delay this many seconds and then attempt
2291 to reconnect. Zero disables reconnecting, and is the default.
2293 @option{tls-creds} requests enablement of the TLS protocol for encryption,
2294 and specifies the id of the TLS credentials to use for the handshake. The
2295 credentials must be previously created with the @option{-object tls-creds}
2296 argument.
2298 TCP and unix socket options are given below:
2300 @table @option
2302 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
2304 @option{host} for a listening socket specifies the local address to be bound.
2305 For a connecting socket species the remote host to connect to. @option{host} is
2306 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2308 @option{port} for a listening socket specifies the local port to be bound. For a
2309 connecting socket specifies the port on the remote host to connect to.
2310 @option{port} can be given as either a port number or a service name.
2311 @option{port} is required.
2313 @option{to} is only relevant to listening sockets. If it is specified, and
2314 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2315 to and including @option{to} until it succeeds. @option{to} must be specified
2316 as a port number.
2318 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2319 If neither is specified the socket may use either protocol.
2321 @option{nodelay} disables the Nagle algorithm.
2323 @item unix options: path=@var{path}
2325 @option{path} specifies the local path of the unix socket. @option{path} is
2326 required.
2328 @end table
2330 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2332 Sends all traffic from the guest to a remote host over UDP.
2334 @option{host} specifies the remote host to connect to. If not specified it
2335 defaults to @code{localhost}.
2337 @option{port} specifies the port on the remote host to connect to. @option{port}
2338 is required.
2340 @option{localaddr} specifies the local address to bind to. If not specified it
2341 defaults to @code{0.0.0.0}.
2343 @option{localport} specifies the local port to bind to. If not specified any
2344 available local port will be used.
2346 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2347 If neither is specified the device may use either protocol.
2349 @item -chardev msmouse ,id=@var{id}
2351 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2352 take any options.
2354 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2356 Connect to a QEMU text console. @option{vc} may optionally be given a specific
2357 size.
2359 @option{width} and @option{height} specify the width and height respectively of
2360 the console, in pixels.
2362 @option{cols} and @option{rows} specify that the console be sized to fit a text
2363 console with the given dimensions.
2365 @item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
2367 Create a ring buffer with fixed size @option{size}.
2368 @var{size} must be a power of two, and defaults to @code{64K}).
2370 @item -chardev file ,id=@var{id} ,path=@var{path}
2372 Log all traffic received from the guest to a file.
2374 @option{path} specifies the path of the file to be opened. This file will be
2375 created if it does not already exist, and overwritten if it does. @option{path}
2376 is required.
2378 @item -chardev pipe ,id=@var{id} ,path=@var{path}
2380 Create a two-way connection to the guest. The behaviour differs slightly between
2381 Windows hosts and other hosts:
2383 On Windows, a single duplex pipe will be created at
2386 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2387 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2388 received by the guest. Data written by the guest can be read from
2389 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2390 be present.
2392 @option{path} forms part of the pipe path as described above. @option{path} is
2393 required.
2395 @item -chardev console ,id=@var{id}
2397 Send traffic from the guest to QEMU's standard output. @option{console} does not
2398 take any options.
2400 @option{console} is only available on Windows hosts.
2402 @item -chardev serial ,id=@var{id} ,path=@option{path}
2404 Send traffic from the guest to a serial device on the host.
2406 On Unix hosts serial will actually accept any tty device,
2407 not only serial lines.
2409 @option{path} specifies the name of the serial device to open.
2411 @item -chardev pty ,id=@var{id}
2413 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2414 not take any options.
2416 @option{pty} is not available on Windows hosts.
2418 @item -chardev stdio ,id=@var{id} [,signal=on|off]
2419 Connect to standard input and standard output of the QEMU process.
2421 @option{signal} controls if signals are enabled on the terminal, that includes
2422 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2423 default, use @option{signal=off} to disable it.
2425 @option{stdio} is not available on Windows hosts.
2427 @item -chardev braille ,id=@var{id}
2429 Connect to a local BrlAPI server. @option{braille} does not take any options.
2431 @item -chardev tty ,id=@var{id} ,path=@var{path}
2433 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2434 DragonFlyBSD hosts. It is an alias for @option{serial}.
2436 @option{path} specifies the path to the tty. @option{path} is required.
2438 @item -chardev parallel ,id=@var{id} ,path=@var{path}
2439 @itemx -chardev parport ,id=@var{id} ,path=@var{path}
2441 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
2443 Connect to a local parallel port.
2445 @option{path} specifies the path to the parallel port device. @option{path} is
2446 required.
2448 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2450 @option{spicevmc} is only available when spice support is built in.
2452 @option{debug} debug level for spicevmc
2454 @option{name} name of spice channel to connect to
2456 Connect to a spice virtual machine channel, such as vdiport.
2458 @item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2460 @option{spiceport} is only available when spice support is built in.
2462 @option{debug} debug level for spicevmc
2464 @option{name} name of spice port to connect to
2466 Connect to a spice port, allowing a Spice client to handle the traffic
2467 identified by a name (preferably a fqdn).
2468 ETEXI
2470 STEXI
2471 @end table
2472 ETEXI
2473 DEFHEADING()
2475 DEFHEADING(Device URL Syntax:)
2476 STEXI
2478 In addition to using normal file images for the emulated storage devices,
2479 QEMU can also use networked resources such as iSCSI devices. These are
2480 specified using a special URL syntax.
2482 @table @option
2483 @item iSCSI
2484 iSCSI support allows QEMU to access iSCSI resources directly and use as
2485 images for the guest storage. Both disk and cdrom images are supported.
2487 Syntax for specifying iSCSI LUNs is
2488 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2490 By default qemu will use the iSCSI initiator-name
2491 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2492 line or a configuration file.
2494 Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
2495 stalled requests and force a reestablishment of the session. The timeout
2496 is specified in seconds. The default is 0 which means no timeout. Libiscsi
2497 1.15.0 or greater is required for this feature.
2499 Example (without authentication):
2500 @example
2501 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2502 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2503 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2504 @end example
2506 Example (CHAP username/password via URL):
2507 @example
2508 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
2509 @end example
2511 Example (CHAP username/password via environment variables):
2512 @example
2515 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2516 @end example
2518 iSCSI support is an optional feature of QEMU and only available when
2519 compiled and linked against libiscsi.
2520 ETEXI
2527 STEXI
2529 iSCSI parameters such as username and password can also be specified via
2530 a configuration file. See qemu-doc for more information and examples.
2532 @item NBD
2533 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2534 as Unix Domain Sockets.
2536 Syntax for specifying a NBD device using TCP
2537 ``nbd:<server-ip>:<port>[:exportname=<export>]''
2539 Syntax for specifying a NBD device using Unix Domain Sockets
2540 ``nbd:unix:<domain-socket>[:exportname=<export>]''
2543 Example for TCP
2544 @example
2545 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
2546 @end example
2548 Example for Unix Domain Sockets
2549 @example
2550 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
2551 @end example
2553 @item SSH
2554 QEMU supports SSH (Secure Shell) access to remote disks.
2556 Examples:
2557 @example
2558 qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2559 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2560 @end example
2562 Currently authentication must be done using ssh-agent. Other
2563 authentication methods may be supported in future.
2565 @item Sheepdog
2566 Sheepdog is a distributed storage system for QEMU.
2567 QEMU supports using either local sheepdog devices or remote networked
2568 devices.
2570 Syntax for specifying a sheepdog device
2571 @example
2572 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
2573 @end example
2575 Example
2576 @example
2577 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
2578 @end example
2580 See also @url{http://http://www.osrg.net/sheepdog/}.
2582 @item GlusterFS
2583 GlusterFS is an user space distributed file system.
2584 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2585 TCP, Unix Domain Sockets and RDMA transport protocols.
2587 Syntax for specifying a VM disk image on GlusterFS volume is
2588 @example
2589 gluster[+transport]://[server[:port]]/volname/image[?socket=...]
2590 @end example
2593 Example
2594 @example
2595 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img
2596 @end example
2598 See also @url{http://www.gluster.org}.
2600 @item HTTP/HTTPS/FTP/FTPS/TFTP
2601 QEMU supports read-only access to files accessed over http(s), ftp(s) and tftp.
2603 Syntax using a single filename:
2604 @example
2605 <protocol>://[<username>[:<password>]@@]<host>/<path>
2606 @end example
2608 where:
2609 @table @option
2610 @item protocol
2611 'http', 'https', 'ftp', 'ftps', or 'tftp'.
2613 @item username
2614 Optional username for authentication to the remote server.
2616 @item password
2617 Optional password for authentication to the remote server.
2619 @item host
2620 Address of the remote server.
2622 @item path
2623 Path on the remote server, including any query string.
2624 @end table
2626 The following options are also supported:
2627 @table @option
2628 @item url
2629 The full URL when passing options to the driver explicitly.
2631 @item readahead
2632 The amount of data to read ahead with each range request to the remote server.
2633 This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2634 does not have a suffix, it will be assumed to be in bytes. The value must be a
2635 multiple of 512 bytes. It defaults to 256k.
2637 @item sslverify
2638 Whether to verify the remote server's certificate when connecting over SSL. It
2639 can have the value 'on' or 'off'. It defaults to 'on'.
2641 @item cookie
2642 Send this cookie (it can also be a list of cookies separated by ';') with
2643 each outgoing request. Only supported when using protocols such as HTTP
2644 which support cookies, otherwise ignored.
2646 @item timeout
2647 Set the timeout in seconds of the CURL connection. This timeout is the time
2648 that CURL waits for a response from the remote server to get the size of the
2649 image to be downloaded. If not set, the default timeout of 5 seconds is used.
2650 @end table
2652 Note that when passing options to qemu explicitly, @option{driver} is the value
2653 of <protocol>.
2655 Example: boot from a remote Fedora 20 live ISO image
2656 @example
2657 qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
2659 qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
2660 @end example
2662 Example: boot from a remote Fedora 20 cloud image using a local overlay for
2663 writes, copy-on-read, and a readahead of 64k
2664 @example
2665 qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
2668 @end example
2673 @example
2674 qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
2677 @end example
2678 ETEXI
2680 STEXI
2681 @end table
2682 ETEXI
2685 STEXI
2686 @table @option
2687 ETEXI
2699 QEMU_ARCH_ALL)
2700 STEXI
2702 @findex -bt
2705 example when emulating a machine with only one HCI built into it, only
2707 logic. The Transport Layer is decided by the machine type. Currently
2708 the machines @code{n800} and @code{n810} have one HCI and all other
2709 machines have none.
2711 @anchor{bt-hcis}
2712 The following three types are recognized:
2714 @table @option
2715 @item -bt hci,null
2716 (default) The corresponding Bluetooth HCI assumes no internal logic
2717 and will not respond to any HCI commands or emit events.
2719 @item -bt hci,host[:@var{id}]
2720 (@code{bluez} only) The corresponding HCI passes commands / events
2721 to / from the physical HCI identified by the name @var{id} (default:
2722 @code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2723 capable systems like Linux.
2725 @item -bt hci[,vlan=@var{n}]
2726 Add a virtual, standard HCI that will participate in the Bluetooth
2727 scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2728 VLANs, devices inside a bluetooth network @var{n} can only communicate
2729 with other devices in the same network (scatternet).
2730 @end table
2732 @item -bt vhci[,vlan=@var{n}]
2733 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2734 to the host bluetooth stack instead of to the emulated target. This
2735 allows the host and target machines to participate in a common scatternet
2736 and communicate. Requires the Linux @code{vhci} driver installed. Can
2737 be used as following:
2739 @example
2740 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2741 @end example
2743 @item -bt device:@var{dev}[,vlan=@var{n}]
2744 Emulate a bluetooth device @var{dev} and place it in network @var{n}
2745 (default @code{0}). QEMU can only emulate one type of bluetooth devices
2746 currently:
2748 @table @option
2749 @item keyboard
2750 Virtual wireless keyboard implementing the HIDP bluetooth profile.
2751 @end table
2752 ETEXI
2754 STEXI
2755 @end table
2756 ETEXI
2757 DEFHEADING()
2759 #ifdef CONFIG_TPM
2760 DEFHEADING(TPM device options:)
2762 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
2767 QEMU_ARCH_ALL)
2768 STEXI
2770 The general form of a TPM device option is:
2771 @table @option
2773 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2774 @findex -tpmdev
2775 Backend type must be:
2776 @option{passthrough}.
2778 The specific backend type will determine the applicable options.
2779 The @code{-tpmdev} option creates the TPM backend and requires a
2780 @code{-device} option that specifies the TPM frontend interface model.
2782 Options to each backend are described below.
2784 Use 'help' to print all available TPM backend types.
2785 @example
2786 qemu -tpmdev help
2787 @end example
2789 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
2791 (Linux-host only) Enable access to the host's TPM using the passthrough
2792 driver.
2794 @option{path} specifies the path to the host's TPM device, i.e., on
2795 a Linux host this would be @code{/dev/tpm0}.
2796 @option{path} is optional and by default @code{/dev/tpm0} is used.
2798 @option{cancel-path} specifies the path to the host TPM device's sysfs
2799 entry allowing for cancellation of an ongoing TPM command.
2800 @option{cancel-path} is optional and by default QEMU will search for the
2801 sysfs entry to use.
2803 Some notes about using the host's TPM with the passthrough driver:
2805 The TPM device accessed by the passthrough driver must not be
2806 used by any other application on the host.
2808 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2809 the VM's firmware (BIOS/UEFI) will not be able to initialize the
2810 TPM again and may therefore not show a TPM-specific menu that would
2811 otherwise allow the user to configure the TPM, e.g., allow the user to
2812 enable/disable or activate/deactivate the TPM.
2813 Further, if TPM ownership is released from within a VM then the host's TPM
2814 will get disabled and deactivated. To enable and activate the
2815 TPM again afterwards, the host has to be rebooted and the user is
2816 required to enter the firmware's menu to enable and activate the TPM.
2817 If the TPM is left disabled and/or deactivated most TPM commands will fail.
2819 To create a passthrough TPM use the following two options:
2820 @example
2821 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2822 @end example
2823 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2824 @code{tpmdev=tpm0} in the device option.
2826 @end table
2828 ETEXI
2830 DEFHEADING()
2832 #endif
2834 DEFHEADING(Linux/Multiboot boot specific:)
2835 STEXI
2837 When using these options, you can use a given Linux or Multiboot
2838 kernel without installing it in the disk image. It can be useful
2839 for easier testing of various kernels.
2841 @table @option
2842 ETEXI
2846 STEXI
2847 @item -kernel @var{bzImage}
2848 @findex -kernel
2849 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2850 or in multiboot format.
2851 ETEXI
2855 STEXI
2856 @item -append @var{cmdline}
2857 @findex -append
2858 Use @var{cmdline} as kernel command line
2859 ETEXI
2863 STEXI
2864 @item -initrd @var{file}
2865 @findex -initrd
2866 Use @var{file} as initial ram disk.
2870 This syntax is only available with multiboot.
2872 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2873 first module.
2874 ETEXI
2878 STEXI
2879 @item -dtb @var{file}
2880 @findex -dtb
2881 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
2882 on boot.
2883 ETEXI
2885 STEXI
2886 @end table
2887 ETEXI
2888 DEFHEADING()
2890 DEFHEADING(Debug/Expert options:)
2891 STEXI
2892 @table @option
2893 ETEXI
2900 QEMU_ARCH_ALL)
2901 STEXI
2903 @item -fw_cfg [name=]@var{name},file=@var{file}
2904 @findex -fw_cfg
2905 Add named fw_cfg entry with contents from file @var{file}.
2907 @item -fw_cfg [name=]@var{name},string=@var{str}
2908 Add named fw_cfg entry with contents from string @var{str}.
2910 The terminating NUL character of the contents of @var{str} will not be
2911 included as part of the fw_cfg item data. To insert contents with
2912 embedded NUL characters, you have to use the @var{file} parameter.
2914 The fw_cfg entries are passed by QEMU through to the guest.
2916 Example:
2917 @example
2918 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
2919 @end example
2920 creates an fw_cfg entry named opt/com.mycompany/blob with contents
2921 from ./my_blob.bin.
2923 ETEXI
2927 QEMU_ARCH_ALL)
2928 STEXI
2929 @item -serial @var{dev}
2930 @findex -serial
2931 Redirect the virtual serial port to host character device
2932 @var{dev}. The default device is @code{vc} in graphical mode and
2933 @code{stdio} in non graphical mode.
2935 This option can be used several times to simulate up to 4 serial
2936 ports.
2938 Use @code{-serial none} to disable all serial ports.
2940 Available character devices are:
2941 @table @option
2942 @item vc[:@var{W}x@var{H}]
2943 Virtual console. Optionally, a width and height can be given in pixel with
2944 @example
2945 vc:800x600
2946 @end example
2947 It is also possible to specify width or height in characters:
2948 @example
2949 vc:80Cx24C
2950 @end example
2951 @item pty
2952 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2953 @item none
2954 No device is allocated.
2955 @item null
2956 void device
2957 @item chardev:@var{id}
2958 Use a named character device defined with the @code{-chardev} option.
2959 @item /dev/XXX
2960 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2961 parameters are set according to the emulated ones.
2962 @item /dev/parport@var{N}
2963 [Linux only, parallel port only] Use host parallel port
2964 @var{N}. Currently SPP and EPP parallel port features can be used.
2965 @item file:@var{filename}
2966 Write output to @var{filename}. No character can be read.
2967 @item stdio
2968 [Unix only] standard input/output
2969 @item pipe:@var{filename}
2970 name pipe @var{filename}
2971 @item COM@var{n}
2972 [Windows only] Use host serial port @var{n}
2973 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2974 This implements UDP Net Console.
2975 When @var{remote_host} or @var{src_ip} are not specified
2976 they default to @code{0.0.0.0}.
2977 When not using a specified @var{src_port} a random port is automatically chosen.
2979 If you just want a simple readonly console you can use @code{netcat} or
2980 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
2981 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
2982 will appear in the netconsole session.
2984 If you plan to send characters back via netconsole or you want to stop
2985 and start QEMU a lot of times, you should have QEMU use the same
2986 source port each time by using something like @code{-serial
2987 udp::4555@@:4556} to QEMU. Another approach is to use a patched
2988 version of netcat which can listen to a TCP port and send and receive
2989 characters via udp. If you have a patched version of netcat which
2990 activates telnet remote echo and single char transfer, then you can
2991 use the following options to step up a netcat redirector to allow
2992 telnet on port 5555 to access the QEMU port.
2993 @table @code
2994 @item QEMU Options:
2995 -serial udp::4555@@:4556
2996 @item netcat options:
2997 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2998 @item telnet options:
2999 localhost 5555
3000 @end table
3002 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
3003 The TCP Net Console has two modes of operation. It can send the serial
3004 I/O to a location or wait for a connection from a location. By default
3005 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3006 the @var{server} option QEMU will wait for a client socket application
3007 to connect to the port before continuing, unless the @code{nowait}
3008 option was specified. The @code{nodelay} option disables the Nagle buffering
3009 algorithm. The @code{reconnect} option only applies if @var{noserver} is
3010 set, if the connection goes down it will attempt to reconnect at the
3011 given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
3012 one TCP connection at a time is accepted. You can use @code{telnet} to
3013 connect to the corresponding character device.
3014 @table @code
3015 @item Example to send tcp console to 192.168.0.2 port 4444
3016 -serial tcp:192.168.0.2:4444
3017 @item Example to listen and wait on port 4444 for connection
3018 -serial tcp::4444,server
3019 @item Example to not wait and listen on ip 192.168.0.100 port 4444
3020 -serial tcp:192.168.0.100:4444,server,nowait
3021 @end table
3023 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3024 The telnet protocol is used instead of raw tcp sockets. The options
3025 work the same as if you had specified @code{-serial tcp}. The
3026 difference is that the port acts like a telnet server or client using
3027 telnet option negotiation. This will also allow you to send the
3028 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3029 sequence. Typically in unix telnet you do it with Control-] and then
3032 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3033 A unix domain socket is used instead of a tcp socket. The option works the
3034 same as if you had specified @code{-serial tcp} except the unix domain socket
3035 @var{path} is used for connections.
3037 @item mon:@var{dev_string}
3038 This is a special option to allow the monitor to be multiplexed onto
3039 another serial port. The monitor is accessed with key sequence of
3040 @key{Control-a} and then pressing @key{c}.
3041 @var{dev_string} should be any one of the serial devices specified
3042 above. An example to multiplex the monitor onto a telnet server
3043 listening on port 4444 would be:
3044 @table @code
3045 @item -serial mon:telnet::4444,server,nowait
3046 @end table
3047 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3048 QEMU any more but will be passed to the guest instead.
3050 @item braille
3051 Braille device. This will use BrlAPI to display the braille output on a real
3052 or fake device.
3054 @item msmouse
3055 Three button serial mouse. Configure the guest to use Microsoft protocol.
3056 @end table
3057 ETEXI
3061 QEMU_ARCH_ALL)
3062 STEXI
3063 @item -parallel @var{dev}
3064 @findex -parallel
3065 Redirect the virtual parallel port to host device @var{dev} (same
3066 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3067 be used to use hardware devices connected on the corresponding host
3068 parallel port.
3070 This option can be used several times to simulate up to 3 parallel
3071 ports.
3073 Use @code{-parallel none} to disable all parallel ports.
3074 ETEXI
3078 QEMU_ARCH_ALL)
3079 STEXI
3080 @item -monitor @var{dev}
3081 @findex -monitor
3082 Redirect the monitor to host device @var{dev} (same devices as the
3083 serial port).
3084 The default device is @code{vc} in graphical mode and @code{stdio} in
3085 non graphical mode.
3086 Use @code{-monitor none} to disable the default monitor.
3087 ETEXI
3090 QEMU_ARCH_ALL)
3091 STEXI
3092 @item -qmp @var{dev}
3093 @findex -qmp
3094 Like -monitor but opens in 'control' mode.
3095 ETEXI
3098 QEMU_ARCH_ALL)
3099 STEXI
3100 @item -qmp-pretty @var{dev}
3101 @findex -qmp-pretty
3102 Like -qmp but uses pretty JSON formatting.
3103 ETEXI
3107 STEXI
3108 @item -mon [chardev=]name[,mode=readline|control][,default]
3109 @findex -mon
3110 Setup monitor on chardev @var{name}.
3111 ETEXI
3115 QEMU_ARCH_ALL)
3116 STEXI
3117 @item -debugcon @var{dev}
3118 @findex -debugcon
3119 Redirect the debug console to host device @var{dev} (same devices as the
3120 serial port). The debug console is an I/O port which is typically port
3121 0xe9; writing to that I/O port sends output to this device.
3122 The default device is @code{vc} in graphical mode and @code{stdio} in
3123 non graphical mode.
3124 ETEXI
3128 STEXI
3129 @item -pidfile @var{file}
3130 @findex -pidfile
3131 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3132 from a script.
3133 ETEXI
3137 STEXI
3138 @item -singlestep
3139 @findex -singlestep
3140 Run the emulation in single step mode.
3141 ETEXI
3145 QEMU_ARCH_ALL)
3146 STEXI
3147 @item -S
3148 @findex -S
3149 Do not start CPU at startup (you must type 'c' in the monitor).
3150 ETEXI
3156 QEMU_ARCH_ALL)
3157 STEXI
3158 @item -realtime mlock=on|off
3159 @findex -realtime
3160 Run qemu with realtime features.
3161 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3162 (enabled by default).
3163 ETEXI
3167 STEXI
3168 @item -gdb @var{dev}
3169 @findex -gdb
3170 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3171 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3172 stdio are reasonable use case. The latter is allowing to start QEMU from
3173 within gdb and establish the connection via a pipe:
3174 @example
3175 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
3176 @end example
3177 ETEXI
3181 QEMU_ARCH_ALL)
3182 STEXI
3183 @item -s
3184 @findex -s
3185 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3186 (@pxref{gdb_usage}).
3187 ETEXI
3191 QEMU_ARCH_ALL)
3192 STEXI
3193 @item -d @var{item1}[,...]
3194 @findex -d
3195 Enable logging of specified items. Use '-d help' for a list of log items.
3196 ETEXI
3200 QEMU_ARCH_ALL)
3201 STEXI
3202 @item -D @var{logfile}
3203 @findex -D
3204 Output log in @var{logfile} instead of to stderr
3205 ETEXI
3208 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3209 QEMU_ARCH_ALL)
3210 STEXI
3211 @item -dfilter @var{range1}[,...]
3212 @findex -dfilter
3213 Filter debug output to that relevant to a range of target addresses. The filter
3214 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3215 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3216 addresses and sizes required. For example:
3217 @example
3218 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3219 @end example
3220 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3221 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3222 block starting at 0xffffffc00005f000.
3223 ETEXI
3227 QEMU_ARCH_ALL)
3228 STEXI
3229 @item -L @var{path}
3230 @findex -L
3231 Set the directory for the BIOS, VGA BIOS and keymaps.
3233 To list all the data directories, use @code{-L help}.
3234 ETEXI
3238 STEXI
3239 @item -bios @var{file}
3240 @findex -bios
3241 Set the filename for the BIOS.
3242 ETEXI
3246 STEXI
3247 @item -enable-kvm
3248 @findex -enable-kvm
3249 Enable KVM full virtualization support. This option is only available
3250 if KVM support is enabled when compiling.
3251 ETEXI
3258 QEMU_ARCH_ALL)
3262 QEMU_ARCH_ALL)
3263 STEXI
3264 @item -xen-domid @var{id}
3265 @findex -xen-domid
3266 Specify xen guest domain @var{id} (XEN only).
3267 @item -xen-create
3268 @findex -xen-create
3269 Create domain using xen hypercalls, bypassing xend.
3270 Warning: should not be used when xend is in use (XEN only).
3271 @item -xen-attach
3272 @findex -xen-attach
3273 Attach to existing xen domain.
3274 xend will use this when starting QEMU (XEN only).
3275 ETEXI
3279 STEXI
3280 @item -no-reboot
3281 @findex -no-reboot
3282 Exit instead of rebooting.
3283 ETEXI
3287 STEXI
3288 @item -no-shutdown
3289 @findex -no-shutdown
3290 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3291 This allows for instance switching to monitor to commit changes to the
3292 disk image.
3293 ETEXI
3298 QEMU_ARCH_ALL)
3299 STEXI
3300 @item -loadvm @var{file}
3301 @findex -loadvm
3302 Start right away with a saved state (@code{loadvm} in monitor)
3303 ETEXI
3305 #ifndef _WIN32
3308 #endif
3309 STEXI
3310 @item -daemonize
3311 @findex -daemonize
3312 Daemonize the QEMU process after initialization. QEMU will not detach from
3313 standard IO until it is ready to receive connections on any of its devices.
3314 This option is a useful way for external programs to launch QEMU without having
3315 to cope with initialization race conditions.
3316 ETEXI
3320 QEMU_ARCH_ALL)
3321 STEXI
3322 @item -option-rom @var{file}
3323 @findex -option-rom
3324 Load the contents of @var{file} as an option ROM.
3325 This option is useful to load things like EtherBoot.
3326 ETEXI
3328 HXCOMM Silently ignored for compatibility
3331 HXCOMM Options deprecated by -rtc
3338 QEMU_ARCH_ALL)
3340 STEXI
3342 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
3343 @findex -rtc
3344 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3345 UTC or local time, respectively. @code{localtime} is required for correct date in
3346 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3347 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3349 By default the RTC is driven by the host system time. This allows using of the
3350 RTC as accurate reference clock inside the guest, specifically if the host
3351 time is smoothly following an accurate external reference clock, e.g. via NTP.
3352 If you want to isolate the guest time from the host, you can set @option{clock}
3353 to @code{rt} instead. To even prevent it from progressing during suspension,
3354 you can set it to @code{vm}.
3356 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3357 specifically with Windows' ACPI HAL. This option will try to figure out how
3358 many timer interrupts were not processed by the Windows guest and will
3359 re-inject them.
3360 ETEXI
3367 STEXI
3368 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename}]
3369 @findex -icount
3370 Enable virtual instruction counter. The virtual cpu will execute one
3371 instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
3372 then the virtual cpu speed will be automatically adjusted to keep virtual
3373 time within a few seconds of real time.
3375 When the virtual cpu is sleeping, the virtual time will advance at default
3376 speed unless @option{sleep=on|off} is specified.
3377 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3378 instantly whenever the virtual cpu goes to sleep mode and will not advance
3379 if no timer is enabled. This behavior give deterministic execution times from
3380 the guest point of view.
3382 Note that while this option can give deterministic behavior, it does not
3383 provide cycle accurate emulation. Modern CPUs contain superscalar out of
3384 order cores with complex cache hierarchies. The number of instructions
3385 executed often has little or no correlation with actual performance.
3387 @option{align=on} will activate the delay algorithm which will try
3388 to synchronise the host clock and the virtual clock. The goal is to
3389 have a guest running at the real frequency imposed by the shift option.
3390 Whenever the guest clock is behind the host clock and if
3391 @option{align=on} is specified then we print a message to the user
3392 to inform about the delay.
3393 Currently this option does not work when @option{shift} is @code{auto}.
3394 Note: The sync algorithm will work for those shift values for which
3395 the guest clock runs ahead of the host clock. Typically this happens
3396 when the shift value is high (how high depends on the host machine).
3398 When @option{rr} option is specified deterministic record/replay is enabled.
3399 Replay log is written into @var{filename} file in record mode and
3400 read from this file in replay mode.
3401 ETEXI
3406 QEMU_ARCH_ALL)
3407 STEXI
3408 @item -watchdog @var{model}
3409 @findex -watchdog
3410 Create a virtual hardware watchdog device. Once enabled (by a guest
3411 action), the watchdog must be periodically polled by an agent inside
3412 the guest or else the guest will be restarted. Choose a model for
3413 which your guest has drivers.
3415 The @var{model} is the model of hardware watchdog to emulate. Use
3416 @code{-watchdog help} to list available hardware models. Only one
3417 watchdog can be enabled for a guest.
3419 The following models may be available:
3420 @table @option
3421 @item ib700
3422 iBASE 700 is a very simple ISA watchdog with a single timer.
3423 @item i6300esb
3424 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3425 dual-timer watchdog.
3426 @item diag288
3427 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3428 (currently KVM only).
3429 @end table
3430 ETEXI
3435 QEMU_ARCH_ALL)
3436 STEXI
3437 @item -watchdog-action @var{action}
3438 @findex -watchdog-action
3440 The @var{action} controls what QEMU will do when the watchdog timer
3441 expires.
3442 The default is
3443 @code{reset} (forcefully reset the guest).
3444 Other possible actions are:
3445 @code{shutdown} (attempt to gracefully shutdown the guest),
3446 @code{poweroff} (forcefully poweroff the guest),
3447 @code{pause} (pause the guest),
3448 @code{debug} (print a debug message and continue), or
3449 @code{none} (do nothing).
3451 Note that the @code{shutdown} action requires that the guest responds
3452 to ACPI signals, which it may not be able to do in the sort of
3453 situations where the watchdog would have expired, and thus
3454 @code{-watchdog-action shutdown} is not recommended for production use.
3456 Examples:
3458 @table @code
3459 @item -watchdog i6300esb -watchdog-action pause
3460 @itemx -watchdog ib700
3461 @end table
3462 ETEXI
3466 QEMU_ARCH_ALL)
3467 STEXI
3469 @item -echr @var{numeric_ascii_value}
3470 @findex -echr
3471 Change the escape character used for switching to the monitor when using
3472 monitor and serial sharing. The default is @code{0x01} when using the
3473 @code{-nographic} option. @code{0x01} is equal to pressing
3474 @code{Control-a}. You can select a different character from the ascii
3475 control keys where 1 through 26 map to Control-a through Control-z. For
3476 instance you could use the either of the following to change the escape
3477 character to Control-t.
3478 @table @code
3479 @item -echr 0x14
3480 @itemx -echr 20
3481 @end table
3482 ETEXI
3487 STEXI
3488 @item -virtioconsole @var{c}
3489 @findex -virtioconsole
3490 Set virtio console.
3492 This option is maintained for backward compatibility.
3494 Please use @code{-device virtconsole} for the new way of invocation.
3495 ETEXI
3499 STEXI
3500 @item -show-cursor
3501 @findex -show-cursor
3502 Show cursor.
3503 ETEXI
3507 STEXI
3508 @item -tb-size @var{n}
3509 @findex -tb-size
3510 Set TB size.
3511 ETEXI
3525 QEMU_ARCH_ALL)
3526 STEXI
3527 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
3528 @itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
3529 @findex -incoming
3530 Prepare for incoming migration, listen on a given tcp port.
3532 @item -incoming unix:@var{socketpath}
3533 Prepare for incoming migration, listen on a given unix socket.
3535 @item -incoming fd:@var{fd}
3536 Accept incoming migration from a given filedescriptor.
3538 @item -incoming exec:@var{cmdline}
3539 Accept incoming migration as an output from specified external command.
3541 @item -incoming defer
3542 Wait for the URI to be specified via migrate_incoming. The monitor can
3543 be used to change settings (such as migration parameters) prior to issuing
3544 the migrate_incoming to allow the migration to begin.
3545 ETEXI
3549 STEXI
3550 @item -nodefaults
3551 @findex -nodefaults
3556 ETEXI
3558 #ifndef _WIN32
3561 QEMU_ARCH_ALL)
3562 #endif
3563 STEXI
3565 @findex -chroot
3566 Immediately before starting guest execution, chroot to the specified
3568 ETEXI
3570 #ifndef _WIN32
3573 QEMU_ARCH_ALL)
3574 #endif
3575 STEXI
3577 @findex -runas
3579 to the specified user.
3580 ETEXI
3585 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
3586 STEXI
3590 ETEXI
3593 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3594 QEMU_ARCH_MIPS)
3595 STEXI
3596 @item -semihosting
3597 @findex -semihosting
3599 ETEXI
3603 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3604 QEMU_ARCH_MIPS)
3605 STEXI
3609 @table @option
3615 Allows the user to pass input arguments, and can be used multiple times to build
3620 @end table
3621 ETEXI
3624 STEXI
3628 ETEXI
3632 QEMU_ARCH_ALL)
3633 STEXI
3635 @findex -sandbox
3638 ETEXI
3642 STEXI
3644 @findex -readconfig
3646 QEMU process with many command line options but you don't want to exceed the command line
3647 character limit.
3648 ETEXI
3649 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3652 STEXI
3653 @item -writeconfig @var{file}
3654 @findex -writeconfig
3655 Write device configuration to @var{file}. The @var{file} can be either filename to save
3656 command line and device configuration into file or dash @code{-}) character to print the
3657 output to stdout. This can be later used as input file for @code{-readconfig} option.
3658 ETEXI
3659 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3662 QEMU_ARCH_ALL)
3663 STEXI
3664 @item -nodefconfig
3665 @findex -nodefconfig
3666 Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3667 The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3668 ETEXI
3669 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3672 QEMU_ARCH_ALL)
3673 STEXI
3674 @item -no-user-config
3675 @findex -no-user-config
3676 The @code{-no-user-config} option makes QEMU not load any of the user-provided
3679 ETEXI
3683 QEMU_ARCH_ALL)
3684 STEXI
3686 HXCOMM HX does not support conditional compilation of text.
3690 ETEXI
3692 HXCOMM Internal use
3696 #ifdef __linux__
3699 QEMU_ARCH_ALL)
3700 #endif
3701 STEXI
3705 ETEXI
3710 HXCOMM Deprecated by kvm-pit driver properties
3727 QEMU_ARCH_ALL)
3728 STEXI
3730 @findex -msg
3732 ETEXI
3740 QEMU_ARCH_ALL)
3741 STEXI
3746 ETEXI
3756 QEMU_ARCH_ALL)
3757 STEXI
3759 @findex -object
3765 @table @option
3767 @item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off}
3769 Creates a memory file backend object, which can be used to back
3771 unique ID that will be used to reference this memory region
3773 option provides the size of the memory region, and accepts
3775 the path to either a shared memory or huge page filesystem mount.
3782 Creates a random number generator backend which obtains entropy from
3790 Creates a random number generator backend which obtains entropy from
3792 a unique ID that will be used to reference this entropy backend from
3794 the unique ID of a character device backend that provides the connection
3795 to the RNG daemon.
3797 @item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
3799 Creates a TLS anonymous credentials object, which can be used to provide
3801 ID which network backends will use to access the credentials. The
3803 on whether the QEMU network backend that uses the credentials will be
3812 a set of DH parameters at startup. This is a computationally
3813 expensive operation that consumes random pool entropy, so it is
3814 recommended that a persistent set of parameters be generated
3815 upfront and saved.
3817 @item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off},passwordid=@var{id}
3819 Creates a TLS anonymous credentials object, which can be used to provide
3821 ID which network backends will use to access the credentials. The
3823 on whether the QEMU network backend that uses the credentials will be
3827 must be provided with valid client certificates too.
3833 a set of DH parameters at startup. This is a computationally
3834 expensive operation that consumes random pool entropy, so it is
3835 recommended that a persistent set of parameters be generated
3836 upfront and saved.
3838 For x509 certificate credentials the directory will contain further files
3839 providing the x509 certificates. The certificates must be stored
3850 @item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
3853 packets arriving in a given interval on netdev @var{netdevid} are delayed
3854 until the end of the interval. Interval is in microseconds.
3855 @option{status} is optional that indicate whether the netfilter is
3858 queue @var{all|rx|tx} is an option that can be applied to any netfilter.
3860 @option{all}: the filter is attached both to the receive and the transmit
3861 queue of the netdev (default).
3863 @option{rx}: the filter is attached to the receive queue of the netdev,
3864 where it will receive packets sent to the netdev.
3866 @option{tx}: the filter is attached to the transmit queue of the netdev,
3867 where it will receive packets sent by the netdev.
3869 @item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
3871 filter-mirror on netdev @var{netdevid},mirror net packet to chardev
3872 @var{chardevid}
3874 @item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},
3875 outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
3877 filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
3879 Create a filter-redirector we need to differ outdev id from indev id, id can not
3880 be the same. we can just use indev or outdev, but at least one of indev or outdev
3881 need to be specified.
3883 @item -object filter-dump,id=@var{id},netdev=@var{dev},file=@var{filename}][,maxlen=@var{len}]
3885 Dump the network traffic on netdev @var{dev} to the file specified by
3886 @var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
3887 The file format is libpcap, so it can be analyzed with tools such as tcpdump
3888 or Wireshark.
3890 @item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
3891 @item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
3893 Defines a secret to store a password, encryption key, or some other sensitive
3894 data. The sensitive data can either be passed directly via the @var{data}
3895 parameter, or indirectly via the @var{file} parameter. Using the @var{data}
3896 parameter is insecure unless the sensitive data is encrypted.
3898 The sensitive data can be provided in raw format (the default), or base64.
3899 When encoded as JSON, the raw format only supports valid UTF-8 characters,
3900 so base64 is recommended for sending binary data. QEMU will convert from
3901 which ever format is provided to the format it needs internally. eg, an
3902 RBD password can be provided in raw format, even though it will be base64
3903 encoded when passed onto the RBD sever.
3905 For added protection, it is possible to encrypt the data associated with
3906 a secret using the AES-256-CBC cipher. Use of encryption is indicated
3907 by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
3908 parameter provides the ID of a previously defined secret that contains
3909 the AES-256 decryption key. This key should be 32-bytes long and be
3910 base64 encoded. The @var{iv} parameter provides the random initialization
3911 vector used for encryption of this particular secret and should be a
3912 base64 encrypted string of the 16-byte IV.
3914 The simplest (insecure) usage is to provide the secret inline
3916 @example
3918 # $QEMU -object secret,id=sec0,data=letmein,format=raw
3920 @end example
3922 The simplest secure usage is to provide the secret via a file
3924 # echo -n "letmein" > mypasswd.txt
3925 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
3927 For greater security, AES-256-CBC should be used. To illustrate usage,
3928 consider the openssl command line tool which can encrypt the data. Note
3929 that when encrypting, the plaintext must be padded to the cipher block
3930 size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
3932 First a master key needs to be created in base64 encoding:
3934 @example
3935 # openssl rand -base64 32 > key.b64
3937 @end example
3939 Each secret to be encrypted needs to have a random initialization vector
3940 generated. These do not need to be kept secret
3942 @example
3943 # openssl rand -base64 16 > iv.b64
3945 @end example
3947 The secret to be defined can now be encrypted, in this case we're
3948 telling openssl to base64 encode the result, but it could be left
3951 @example
3954 @end example
3957 and specify that to be used to decrypt the user password. Pass the
3960 @example
3961 # $QEMU \
3965 @end example
3967 @end table
3969 ETEXI
3973 STEXI
3974 @end table
3975 ETEXI