15824d651Sblueswir1HXCOMM Use DEFHEADING() to define headings in both help text and texi 25824d651Sblueswir1HXCOMM Text between STEXI and ETEXI are copied to texi version and 35824d651Sblueswir1HXCOMM discarded from C version 4ad96090aSBlue SwirlHXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to 5ad96090aSBlue SwirlHXCOMM construct option structures, enums and help message for specified 6ad96090aSBlue SwirlHXCOMM architectures. 75824d651Sblueswir1HXCOMM HXCOMM can be used for comments, discarded from both texi and C 85824d651Sblueswir1 95824d651Sblueswir1DEFHEADING(Standard options:) 105824d651Sblueswir1STEXI 115824d651Sblueswir1@table @option 125824d651Sblueswir1ETEXI 135824d651Sblueswir1 145824d651Sblueswir1DEF("help", 0, QEMU_OPTION_h, 15ad96090aSBlue Swirl "-h or -help display this help and exit\n", QEMU_ARCH_ALL) 165824d651Sblueswir1STEXI 175824d651Sblueswir1@item -h 186616b2adSStefan Weil@findex -h 195824d651Sblueswir1Display help and exit 205824d651Sblueswir1ETEXI 215824d651Sblueswir1 229bd7e6d9SpbrookDEF("version", 0, QEMU_OPTION_version, 23ad96090aSBlue Swirl "-version display version information and exit\n", QEMU_ARCH_ALL) 249bd7e6d9SpbrookSTEXI 259bd7e6d9Spbrook@item -version 266616b2adSStefan Weil@findex -version 279bd7e6d9SpbrookDisplay version information and exit 289bd7e6d9SpbrookETEXI 299bd7e6d9Spbrook 3080f52a66SJan KiszkaDEF("machine", HAS_ARG, QEMU_OPTION_machine, \ 3180f52a66SJan Kiszka "-machine [type=]name[,prop[=value][,...]]\n" 32585f6036SPeter Maydell " selects emulated machine ('-machine help' for list)\n" 3380f52a66SJan Kiszka " property accel=accel1[:accel2[:...]] selects accelerator\n" 346a48ffaaSJan Kiszka " supported accelerators are kvm, xen, tcg (default: tcg)\n" 3539d6960aSJan Kiszka " kernel_irqchip=on|off controls accelerated irqchip support\n" 3632c18a2dSMatt Gingell " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n" 37d1048befSDon Slutz " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 3896404013SPeter Maydell " kvm_shadow_mem=size of KVM shadow MMU in bytes\n" 398490fc78SLuiz Capitulino " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 40a52a7fdfSLe Tan " mem-merge=on|off controls memory merge support (default: on)\n" 4179814179STiejun Chen " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n" 422eb1cd07STony Krowiak " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 439850c604SAlexander Graf " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 4487252e1bSXiao Guangrong " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 45902c053dSGreg Kurz " nvdimm=on|off controls NVDIMM support (default=off)\n" 46902c053dSGreg Kurz " enforce-config-section=on|off enforce configuration section migration (default=off)\n", 4780f52a66SJan Kiszka QEMU_ARCH_ALL) 485824d651Sblueswir1STEXI 4980f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 5080f52a66SJan Kiszka@findex -machine 51585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 5280f52a66SJan Kiszkaavailable machines. Supported machine properties are: 5380f52a66SJan Kiszka@table @option 5480f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 5580f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 5680f52a66SJan Kiszkakvm, xen, or tcg can be available. By default, tcg is used. If there is more 5780f52a66SJan Kiszkathan one accelerator specified, the next one is used if the previous one fails 5880f52a66SJan Kiszkato initialize. 596a48ffaaSJan Kiszka@item kernel_irqchip=on|off 6032c18a2dSMatt GingellControls in-kernel irqchip support for the chosen accelerator when available. 6179814179STiejun Chen@item gfx_passthru=on|off 6279814179STiejun ChenEnables IGD GFX passthrough support for the chosen machine when available. 63d1048befSDon Slutz@item vmport=on|off|auto 64d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 65d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 66d1048befSDon Slutzis on. 6739d6960aSJan Kiszka@item kvm_shadow_mem=size 6839d6960aSJan KiszkaDefines the size of the KVM shadow MMU. 69ddb97f1dSJason Baron@item dump-guest-core=on|off 70ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 718490fc78SLuiz Capitulino@item mem-merge=on|off 728490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 738490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 748490fc78SLuiz Capitulino(enabled by default). 752eb1cd07STony Krowiak@item aes-key-wrap=on|off 762eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 772eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 782eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 792eb1cd07STony Krowiak@item dea-key-wrap=on|off 802eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 812eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 822eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 8387252e1bSXiao Guangrong@item nvdimm=on|off 8487252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 8580f52a66SJan Kiszka@end table 865824d651Sblueswir1ETEXI 875824d651Sblueswir1 8880f52a66SJan KiszkaHXCOMM Deprecated by -machine 8980f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 9080f52a66SJan Kiszka 915824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 92585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 935824d651Sblueswir1STEXI 945824d651Sblueswir1@item -cpu @var{model} 956616b2adSStefan Weil@findex -cpu 96585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 975824d651Sblueswir1ETEXI 985824d651Sblueswir1 995824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 10012b7f57eSMichael Tokarev "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 1016be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1026be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 103ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 10458a04db1SAndre Przywara " cores= number of CPU cores on one socket\n" 10558a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 106ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 107ad96090aSBlue Swirl QEMU_ARCH_ALL) 1085824d651Sblueswir1STEXI 10912b7f57eSMichael Tokarev@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1106616b2adSStefan Weil@findex -smp 1115824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1125824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1135824d651Sblueswir1to 4. 11458a04db1SAndre PrzywaraFor the PC target, the number of @var{cores} per socket, the number 11558a04db1SAndre Przywaraof @var{threads} per cores and the total number of @var{sockets} can be 11658a04db1SAndre Przywaraspecified. Missing values will be computed. If any on the three values is 11758a04db1SAndre Przywaragiven, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 11858a04db1SAndre Przywaraspecifies the maximum number of hotpluggable CPUs. 1195824d651Sblueswir1ETEXI 1205824d651Sblueswir1 121268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 1227febe36fSPaolo Bonzini "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n" 1237febe36fSPaolo Bonzini "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL) 124268a362cSaliguoriSTEXI 1254932b897SLuiz Capitulino@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}] 126f9cfd655SMarkus Armbruster@itemx -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}] 1276616b2adSStefan Weil@findex -numa 1287febe36fSPaolo BonziniSimulate a multi node NUMA system. If @samp{mem}, @samp{memdev} 1294932b897SLuiz Capitulinoand @samp{cpus} are omitted, resources are split equally. Also, note 1304932b897SLuiz Capitulinothat the -@option{numa} option doesn't allocate any of the specified 1314932b897SLuiz Capitulinoresources. That is, it just assigns existing resources to NUMA nodes. This 1324932b897SLuiz Capitulinomeans that one still has to use the @option{-m}, @option{-smp} options 1337febe36fSPaolo Bonzinito allocate RAM and VCPUs respectively, and possibly @option{-object} 1347febe36fSPaolo Bonzinito specify the memory backend for the @samp{memdev} suboption. 1357febe36fSPaolo Bonzini 1367febe36fSPaolo Bonzini@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, if one 1377febe36fSPaolo Bonzininode uses @samp{memdev}, all of them have to use it. 138268a362cSaliguoriETEXI 139268a362cSaliguori 14010adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 14110adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 14210adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 14310adb8beSMarkus ArmbrusterSTEXI 14410adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 14510adb8beSMarkus Armbruster@findex -add-fd 14610adb8beSMarkus Armbruster 14710adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 14810adb8beSMarkus Armbruster 14910adb8beSMarkus Armbruster@table @option 15010adb8beSMarkus Armbruster@item fd=@var{fd} 15110adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 15210adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 15310adb8beSMarkus Armbruster@item set=@var{set} 15410adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 15510adb8beSMarkus Armbruster@item opaque=@var{opaque} 15610adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 15710adb8beSMarkus Armbruster@end table 15810adb8beSMarkus Armbruster 15910adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 16010adb8beSMarkus Armbruster@example 16110adb8beSMarkus Armbrusterqemu-system-i386 16210adb8beSMarkus Armbruster-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 16310adb8beSMarkus Armbruster-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 16410adb8beSMarkus Armbruster-drive file=/dev/fdset/2,index=0,media=disk 16510adb8beSMarkus Armbruster@end example 16610adb8beSMarkus ArmbrusterETEXI 16710adb8beSMarkus Armbruster 16810adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 16910adb8beSMarkus Armbruster "-set group.id.arg=value\n" 17010adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 17110adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 17210adb8beSMarkus ArmbrusterSTEXI 17310adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 17410adb8beSMarkus Armbruster@findex -set 17510adb8beSMarkus ArmbrusterSet parameter @var{arg} for item @var{id} of type @var{group}\n" 17610adb8beSMarkus ArmbrusterETEXI 17710adb8beSMarkus Armbruster 17810adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 1793751d7c4SPaolo Bonzini "-global driver.property=value\n" 1803751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 18110adb8beSMarkus Armbruster " set a global default for a driver property\n", 18210adb8beSMarkus Armbruster QEMU_ARCH_ALL) 18310adb8beSMarkus ArmbrusterSTEXI 18410adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 1853751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 18610adb8beSMarkus Armbruster@findex -global 18710adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 18810adb8beSMarkus Armbruster 18910adb8beSMarkus Armbruster@example 19010adb8beSMarkus Armbrusterqemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk 19110adb8beSMarkus Armbruster@end example 19210adb8beSMarkus Armbruster 19310adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 19410adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 19510adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 1963751d7c4SPaolo Bonzini 197ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 198ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 199ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 20010adb8beSMarkus ArmbrusterETEXI 20110adb8beSMarkus Armbruster 20210adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 20310adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 204c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 20510adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 20610adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 20710adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 20810adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 20910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 21010adb8beSMarkus ArmbrusterSTEXI 211c8a6ae8bSAmos Kong@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] 21210adb8beSMarkus Armbruster@findex -boot 21310adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 214d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 21510adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 21610adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 21710adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 21810adb8beSMarkus Armbruster@option{once}. 21910adb8beSMarkus Armbruster 22010adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 22110adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 22210adb8beSMarkus Armbruster 22310adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 22410adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 22510adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 22610adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 22710adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 22810adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 22910adb8beSMarkus Armbruster 23010adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 23110adb8beSMarkus Armbrusterwhen boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 23210adb8beSMarkus Armbrusterreboot, qemu passes '-1' to bios by default. Currently Seabios for X86 23310adb8beSMarkus Armbrustersystem support it. 23410adb8beSMarkus Armbruster 235c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 236c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 237c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 238c8a6ae8bSAmos Kong 23910adb8beSMarkus Armbruster@example 24010adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 24110adb8beSMarkus Armbrusterqemu-system-i386 -boot order=nc 24210adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 24310adb8beSMarkus Armbrusterqemu-system-i386 -boot once=d 24410adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 24510adb8beSMarkus Armbrusterqemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 24610adb8beSMarkus Armbruster@end example 24710adb8beSMarkus Armbruster 24810adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 24910adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 25010adb8beSMarkus ArmbrusterETEXI 25110adb8beSMarkus Armbruster 25210adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 253c270fb9eSIgor Mammedov "-m[emory] [size=]megs[,slots=n,maxmem=size]\n" 2546e1d3c1cSIgor Mammedov " configure guest RAM\n" 2550daba1f0SAlexander Graf " size: initial amount of guest memory\n" 256c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 257b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 258b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 2596e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 26010adb8beSMarkus ArmbrusterSTEXI 2619fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 26210adb8beSMarkus Armbruster@findex -m 2639fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 2649fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 2659fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 2669fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 2679fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 2689fcc0794SLuiz Capitulino 2699fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 2709fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 2719fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 2729fcc0794SLuiz Capitulino 2739fcc0794SLuiz Capitulino@example 2749fcc0794SLuiz Capitulinoqemu-system-x86_64 -m 1G,slots=3,maxmem=4G 2759fcc0794SLuiz Capitulino@end example 2769fcc0794SLuiz Capitulino 2779fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 2789fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 27910adb8beSMarkus ArmbrusterETEXI 28010adb8beSMarkus Armbruster 28110adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 28210adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 28310adb8beSMarkus ArmbrusterSTEXI 28410adb8beSMarkus Armbruster@item -mem-path @var{path} 28510adb8beSMarkus Armbruster@findex -mem-path 28610adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 28710adb8beSMarkus ArmbrusterETEXI 28810adb8beSMarkus Armbruster 28910adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 29010adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 29110adb8beSMarkus Armbruster QEMU_ARCH_ALL) 29210adb8beSMarkus ArmbrusterSTEXI 29310adb8beSMarkus Armbruster@item -mem-prealloc 29410adb8beSMarkus Armbruster@findex -mem-prealloc 29510adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 29610adb8beSMarkus ArmbrusterETEXI 29710adb8beSMarkus Armbruster 29810adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 29910adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 30010adb8beSMarkus Armbruster QEMU_ARCH_ALL) 30110adb8beSMarkus ArmbrusterSTEXI 30210adb8beSMarkus Armbruster@item -k @var{language} 30310adb8beSMarkus Armbruster@findex -k 30410adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 30510adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 30610adb8beSMarkus Armbrusterkeycodes (e.g. on Macs, with some X11 servers or with a VNC 30710adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 30810adb8beSMarkus Armbrusterhosts. 30910adb8beSMarkus Armbruster 31010adb8beSMarkus ArmbrusterThe available layouts are: 31110adb8beSMarkus Armbruster@example 31210adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 31310adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 31410adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 31510adb8beSMarkus Armbruster@end example 31610adb8beSMarkus Armbruster 31710adb8beSMarkus ArmbrusterThe default is @code{en-us}. 31810adb8beSMarkus ArmbrusterETEXI 31910adb8beSMarkus Armbruster 32010adb8beSMarkus Armbruster 32110adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 32210adb8beSMarkus Armbruster "-audio-help print list of audio drivers and their options\n", 32310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 32410adb8beSMarkus ArmbrusterSTEXI 32510adb8beSMarkus Armbruster@item -audio-help 32610adb8beSMarkus Armbruster@findex -audio-help 32710adb8beSMarkus ArmbrusterWill show the audio subsystem help: list of drivers, tunable 32810adb8beSMarkus Armbrusterparameters. 32910adb8beSMarkus ArmbrusterETEXI 33010adb8beSMarkus Armbruster 33110adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 33210adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 33310adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 33410adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 33510adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 33610adb8beSMarkus ArmbrusterSTEXI 33710adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 33810adb8beSMarkus Armbruster@findex -soundhw 33910adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 34010adb8beSMarkus Armbrusteravailable sound hardware. 34110adb8beSMarkus Armbruster 34210adb8beSMarkus Armbruster@example 34310adb8beSMarkus Armbrusterqemu-system-i386 -soundhw sb16,adlib disk.img 34410adb8beSMarkus Armbrusterqemu-system-i386 -soundhw es1370 disk.img 34510adb8beSMarkus Armbrusterqemu-system-i386 -soundhw ac97 disk.img 34610adb8beSMarkus Armbrusterqemu-system-i386 -soundhw hda disk.img 34710adb8beSMarkus Armbrusterqemu-system-i386 -soundhw all disk.img 34810adb8beSMarkus Armbrusterqemu-system-i386 -soundhw help 34910adb8beSMarkus Armbruster@end example 35010adb8beSMarkus Armbruster 35110adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 35210adb8beSMarkus Armbrusterrequire manually specifying clocking. 35310adb8beSMarkus Armbruster 35410adb8beSMarkus Armbruster@example 35510adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 35610adb8beSMarkus Armbruster@end example 35710adb8beSMarkus ArmbrusterETEXI 35810adb8beSMarkus Armbruster 35910adb8beSMarkus ArmbrusterDEF("balloon", HAS_ARG, QEMU_OPTION_balloon, 36010adb8beSMarkus Armbruster "-balloon none disable balloon device\n" 36110adb8beSMarkus Armbruster "-balloon virtio[,addr=str]\n" 36210adb8beSMarkus Armbruster " enable virtio balloon device (default)\n", QEMU_ARCH_ALL) 36310adb8beSMarkus ArmbrusterSTEXI 36410adb8beSMarkus Armbruster@item -balloon none 36510adb8beSMarkus Armbruster@findex -balloon 36610adb8beSMarkus ArmbrusterDisable balloon device. 36710adb8beSMarkus Armbruster@item -balloon virtio[,addr=@var{addr}] 36810adb8beSMarkus ArmbrusterEnable virtio balloon device (default), optionally with PCI address 36910adb8beSMarkus Armbruster@var{addr}. 37010adb8beSMarkus ArmbrusterETEXI 37110adb8beSMarkus Armbruster 37210adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 37310adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 37410adb8beSMarkus Armbruster " add device (based on driver)\n" 37510adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 37610adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 37710adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 37810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 37910adb8beSMarkus ArmbrusterSTEXI 38010adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 38110adb8beSMarkus Armbruster@findex -device 38210adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 38310adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 38410adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 38510adb8beSMarkus Armbruster@code{-device @var{driver},help}. 386f8490451SCorey Minyard 387f8490451SCorey MinyardSome drivers are: 388f8490451SCorey Minyard@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}] 389f8490451SCorey Minyard 390f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 391f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 392f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 393f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 394f8490451SCorey Minyard 395f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 396f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 397f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 398f8490451SCorey Minyardit. 399f8490451SCorey Minyard 400f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 401f8490451SCorey Minyard 402f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 403f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 404f8490451SCorey Minyardto an external entity that provides the IPMI services. 405f8490451SCorey Minyard 406f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 407f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 408f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 409f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 410f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 411f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 412f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 413f8490451SCorey Minyardexposed to any outside network. 414f8490451SCorey Minyard 415f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 416f8490451SCorey Minyarddetails on the external interface. 417f8490451SCorey Minyard 418f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 419f8490451SCorey Minyard 420f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 421f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 422f8490451SCorey Minyard 423f8490451SCorey Minyard@table @option 424f8490451SCorey Minyard@item bmc=@var{id} 425f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 426f8490451SCorey Minyard@item ioport=@var{val} 427f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 428f8490451SCorey Minyard@item irq=@var{val} 429f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 430f8490451SCorey Minyardset this to 0. 431f8490451SCorey Minyard@end table 432f8490451SCorey Minyard 433f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 434f8490451SCorey Minyard 435f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 436f8490451SCorey Minyard0xe4 and the default interrupt is 5. 437f8490451SCorey Minyard 43810adb8beSMarkus ArmbrusterETEXI 43910adb8beSMarkus Armbruster 44010adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 4418f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 44210adb8beSMarkus Armbruster " set the name of the guest\n" 4438f480de0SDr. David Alan Gilbert " string1 sets the window title and string2 the process name (on Linux)\n" 4448f480de0SDr. David Alan Gilbert " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n" 4458f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 44610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 44710adb8beSMarkus ArmbrusterSTEXI 44810adb8beSMarkus Armbruster@item -name @var{name} 44910adb8beSMarkus Armbruster@findex -name 45010adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 45110adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 45210adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 45310adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 4548f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 45510adb8beSMarkus ArmbrusterETEXI 45610adb8beSMarkus Armbruster 45710adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 45810adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 45910adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 46010adb8beSMarkus ArmbrusterSTEXI 46110adb8beSMarkus Armbruster@item -uuid @var{uuid} 46210adb8beSMarkus Armbruster@findex -uuid 46310adb8beSMarkus ArmbrusterSet system UUID. 46410adb8beSMarkus ArmbrusterETEXI 46510adb8beSMarkus Armbruster 46610adb8beSMarkus ArmbrusterSTEXI 46710adb8beSMarkus Armbruster@end table 46810adb8beSMarkus ArmbrusterETEXI 46910adb8beSMarkus ArmbrusterDEFHEADING() 47010adb8beSMarkus Armbruster 47110adb8beSMarkus ArmbrusterDEFHEADING(Block device options:) 47210adb8beSMarkus ArmbrusterSTEXI 47310adb8beSMarkus Armbruster@table @option 47410adb8beSMarkus ArmbrusterETEXI 47510adb8beSMarkus Armbruster 4765824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 477ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 478ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 4795824d651Sblueswir1STEXI 4805824d651Sblueswir1@item -fda @var{file} 481f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 4826616b2adSStefan Weil@findex -fda 4836616b2adSStefan Weil@findex -fdb 48492a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 4855824d651Sblueswir1ETEXI 4865824d651Sblueswir1 4875824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 488ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 489ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 4905824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 491ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 492ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 4935824d651Sblueswir1STEXI 4945824d651Sblueswir1@item -hda @var{file} 495f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 496f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 497f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 4986616b2adSStefan Weil@findex -hda 4996616b2adSStefan Weil@findex -hdb 5006616b2adSStefan Weil@findex -hdc 5016616b2adSStefan Weil@findex -hdd 5025824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 5035824d651Sblueswir1ETEXI 5045824d651Sblueswir1 5055824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 506ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 507ad96090aSBlue Swirl QEMU_ARCH_ALL) 5085824d651Sblueswir1STEXI 5095824d651Sblueswir1@item -cdrom @var{file} 5106616b2adSStefan Weil@findex -cdrom 5115824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 5125824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 5135824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 5145824d651Sblueswir1ETEXI 5155824d651Sblueswir1 5165824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 5175824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 5185824d651Sblueswir1 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" 51992196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 520d1db760dSStefan Hajnoczi " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n" 521d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 522fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 5232f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 5243e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 5253e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 5263e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 5273e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 5282024c1dfSBenoît Canet " [[,iops_size=is]]\n" 52976f4afb4SAlberto Garcia " [[,group=g]]\n" 530ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 5315824d651Sblueswir1STEXI 5325824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 5336616b2adSStefan Weil@findex -drive 5345824d651Sblueswir1 5355824d651Sblueswir1Define a new drive. Valid options are: 5365824d651Sblueswir1 537b3f046c2SKevin Wolf@table @option 5385824d651Sblueswir1@item file=@var{file} 5395824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 5405824d651Sblueswir1this drive. If the filename contains comma, you must double it 5415824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 5420f5314a2SRonnie Sahlberg 5430f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 5440f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 5455824d651Sblueswir1@item if=@var{interface} 5465824d651Sblueswir1This option defines on which type on interface the drive is connected. 5475824d651Sblueswir1Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. 5485824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 5495824d651Sblueswir1These options define where is connected the drive by defining the bus number and 5505824d651Sblueswir1the unit id. 5515824d651Sblueswir1@item index=@var{index} 5525824d651Sblueswir1This option defines where is connected the drive by using an index in the list 5535824d651Sblueswir1of available connectors of a given interface type. 5545824d651Sblueswir1@item media=@var{media} 5555824d651Sblueswir1This option defines the type of the media: disk or cdrom. 5565824d651Sblueswir1@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] 5575824d651Sblueswir1These options have the same definition as they have in @option{-hdachs}. 5585824d651Sblueswir1@item snapshot=@var{snapshot} 5599d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 5609d85d557SMichael Tokarev(see @option{-snapshot}). 5615824d651Sblueswir1@item cache=@var{cache} 56292196b2fSStefan Hajnoczi@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data. 5635c6c3a6cSChristoph Hellwig@item aio=@var{aio} 5645c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 565a9384affSPaolo Bonzini@item discard=@var{discard} 566a9384affSPaolo Bonzini@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. 5675824d651Sblueswir1@item format=@var{format} 5685824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 569d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 5705824d651Sblueswir1an untrusted format header. 5715824d651Sblueswir1@item serial=@var{serial} 5725824d651Sblueswir1This option specifies the serial number to assign to the device. 573c2cc47a4SMarkus Armbruster@item addr=@var{addr} 574c2cc47a4SMarkus ArmbrusterSpecify the controller's PCI address (if=virtio only). 575ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 576ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 577ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 578ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 579ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 580ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 581ae73e591SLuiz Capitulino@item readonly 582ae73e591SLuiz CapitulinoOpen drive @option{file} as read-only. Guest write attempts will fail. 583fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 584fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 585fb0490f6SStefan Hajnoczifile sectors into the image file. 586465bee1dSPeter Lieven@item detect-zeroes=@var{detect-zeroes} 587465bee1dSPeter Lieven@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 588465bee1dSPeter Lievenconversion of plain zero writes by the OS to driver specific optimized 589465bee1dSPeter Lievenzero write commands. You may even choose "unmap" if @var{discard} is set 590465bee1dSPeter Lievento "unmap" to allow a zero write to be converted to an UNMAP operation. 5915824d651Sblueswir1@end table 5925824d651Sblueswir1 593a13e5e05SKevin WolfBy default, the @option{cache=writeback} mode is used. It will report data 594a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 595a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 596a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 597a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 598a13e5e05SKevin Wolfdata corruption. 5995824d651Sblueswir1 600a13e5e05SKevin WolfFor such guests, you should consider using @option{cache=writethrough}. This 601a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 602a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 603a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 6045824d651Sblueswir1 605c304d317SAurelien JarnoThe host page cache can be avoided entirely with @option{cache=none}. This will 606a13e5e05SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform 607a13e5e05SKevin Wolfan internal copy of the data. Note that this is considered a writeback mode and 608a13e5e05SKevin Wolfthe guest OS must handle the disk write cache correctly in order to avoid data 609a13e5e05SKevin Wolfcorruption on host crashes. 6105824d651Sblueswir1 61192196b2fSStefan HajnocziThe host page cache can be avoided while only sending write notifications to 612a13e5e05SKevin Wolfthe guest when the data has been flushed to the disk using 613a13e5e05SKevin Wolf@option{cache=directsync}. 6145824d651Sblueswir1 615016f5cf6SAlexander GrafIn case you don't care about data integrity over host failures, use 616a13e5e05SKevin Wolf@option{cache=unsafe}. This option tells QEMU that it never needs to write any 617a13e5e05SKevin Wolfdata to the disk but can instead keep things in cache. If anything goes wrong, 618e7d81004SStefan Weillike your host losing power, the disk storage getting disconnected accidentally, 619a13e5e05SKevin Wolfetc. your image will most probably be rendered unusable. When using 620c3177288SAlexander Grafthe @option{-snapshot} option, unsafe caching is always used. 621016f5cf6SAlexander Graf 622fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 623fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 624fb0490f6SStefan Hajnocziis off. 625fb0490f6SStefan Hajnoczi 6265824d651Sblueswir1Instead of @option{-cdrom} you can use: 6275824d651Sblueswir1@example 6283804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=cdrom 6295824d651Sblueswir1@end example 6305824d651Sblueswir1 6315824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 6325824d651Sblueswir1use: 6335824d651Sblueswir1@example 6343804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,media=disk 6353804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,media=disk 6363804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=disk 6373804da9dSStefan Weilqemu-system-i386 -drive file=file,index=3,media=disk 6385824d651Sblueswir1@end example 6395824d651Sblueswir1 640587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 641587ed6beSCorey Bryant@example 642587ed6beSCorey Bryantqemu-system-i386 643587ed6beSCorey Bryant-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 644587ed6beSCorey Bryant-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 645587ed6beSCorey Bryant-drive file=/dev/fdset/2,index=0,media=disk 646587ed6beSCorey Bryant@end example 647587ed6beSCorey Bryant 6485824d651Sblueswir1You can connect a CDROM to the slave of ide0: 6495824d651Sblueswir1@example 6503804da9dSStefan Weilqemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 6515824d651Sblueswir1@end example 6525824d651Sblueswir1 6535824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 6545824d651Sblueswir1@example 6553804da9dSStefan Weilqemu-system-i386 -drive if=ide,index=1,media=cdrom 6565824d651Sblueswir1@end example 6575824d651Sblueswir1 6585824d651Sblueswir1You can connect a SCSI disk with unit ID 6 on the bus #0: 6595824d651Sblueswir1@example 6603804da9dSStefan Weilqemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6 6615824d651Sblueswir1@end example 6625824d651Sblueswir1 6635824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 6645824d651Sblueswir1@example 6653804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,if=floppy 6663804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,if=floppy 6675824d651Sblueswir1@end example 6685824d651Sblueswir1 6695824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 6705824d651Sblueswir1incremented: 6715824d651Sblueswir1@example 6723804da9dSStefan Weilqemu-system-i386 -drive file=a -drive file=b" 6735824d651Sblueswir1@end example 6745824d651Sblueswir1is interpreted like: 6755824d651Sblueswir1@example 6763804da9dSStefan Weilqemu-system-i386 -hda a -hdb b 6775824d651Sblueswir1@end example 6785824d651Sblueswir1ETEXI 6795824d651Sblueswir1 6805824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 681ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 682ad96090aSBlue Swirl QEMU_ARCH_ALL) 6835824d651Sblueswir1STEXI 6844e257e5eSKevin Wolf@item -mtdblock @var{file} 6856616b2adSStefan Weil@findex -mtdblock 6864e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 6875824d651Sblueswir1ETEXI 6885824d651Sblueswir1 6895824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 690ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 6915824d651Sblueswir1STEXI 6924e257e5eSKevin Wolf@item -sd @var{file} 6936616b2adSStefan Weil@findex -sd 6944e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 6955824d651Sblueswir1ETEXI 6965824d651Sblueswir1 6975824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 698ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 6995824d651Sblueswir1STEXI 7004e257e5eSKevin Wolf@item -pflash @var{file} 7016616b2adSStefan Weil@findex -pflash 7024e257e5eSKevin WolfUse @var{file} as a parallel flash image. 7035824d651Sblueswir1ETEXI 7045824d651Sblueswir1 7055824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 706ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 707ad96090aSBlue Swirl QEMU_ARCH_ALL) 7085824d651Sblueswir1STEXI 7095824d651Sblueswir1@item -snapshot 7106616b2adSStefan Weil@findex -snapshot 7115824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 7125824d651Sblueswir1the raw disk image you use is not written back. You can however force 7135824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 7145824d651Sblueswir1ETEXI 7155824d651Sblueswir1 71610adb8beSMarkus ArmbrusterDEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ 71710adb8beSMarkus Armbruster "-hdachs c,h,s[,t]\n" \ 71810adb8beSMarkus Armbruster " force hard disk 0 physical geometry and the optional BIOS\n" \ 71910adb8beSMarkus Armbruster " translation (t=none or lba) (usually QEMU can guess them)\n", 720ad96090aSBlue Swirl QEMU_ARCH_ALL) 721c902760fSMarcelo TosattiSTEXI 72210adb8beSMarkus Armbruster@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] 72310adb8beSMarkus Armbruster@findex -hdachs 72410adb8beSMarkus ArmbrusterForce hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= 72510adb8beSMarkus Armbruster@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS 72610adb8beSMarkus Armbrustertranslation mode (@var{t}=none, lba or auto). Usually QEMU can guess 72710adb8beSMarkus Armbrusterall those parameters. This option is useful for old MS-DOS disk 72810adb8beSMarkus Armbrusterimages. 729c70a01e4SMarkus ArmbrusterETEXI 73074db920cSGautham R Shenoy 73174db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 7322c30dd74SAneesh Kumar K.V "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 73384a87cc4SM. Mohan Kumar " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 73474db920cSGautham R Shenoy QEMU_ARCH_ALL) 73574db920cSGautham R Shenoy 73674db920cSGautham R ShenoySTEXI 73774db920cSGautham R Shenoy 73884a87cc4SM. Mohan Kumar@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}] 73974db920cSGautham R Shenoy@findex -fsdev 7407c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 7417c92a3d2SAneesh Kumar K.V@table @option 7427c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 7437c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 744f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 7457c92a3d2SAneesh Kumar K.V@item id=@var{id} 7467c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 7477c92a3d2SAneesh Kumar K.V@item path=@var{path} 7487c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 7497c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 7507c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 7517c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 7522c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 7537c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 754b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 7552c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 7567c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 7572c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 7582c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 7597c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 7607c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 761d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 762f67e3ffdSM. Mohan Kumaronly for local fsdriver. Other fsdrivers (like handle, proxy) don't take 763d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 7647c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 7657c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 7667c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 7677c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 7687c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 7692c74c2cbSM. Mohan Kumar@item readonly 7702c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 7712c74c2cbSM. Mohan Kumarread-write access is given. 77284a87cc4SM. Mohan Kumar@item socket=@var{socket} 77384a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 77484a87cc4SM. Mohan Kumarwith virtfs-proxy-helper 775f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 776f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 777f67e3ffdSM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 778f67e3ffdSM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 77974db920cSGautham R Shenoy@end table 7807c92a3d2SAneesh Kumar K.V 7817c92a3d2SAneesh Kumar K.V-fsdev option is used along with -device driver "virtio-9p-pci". 7827c92a3d2SAneesh Kumar K.V@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 7837c92a3d2SAneesh Kumar K.VOptions for virtio-9p-pci driver are: 7847c92a3d2SAneesh Kumar K.V@table @option 7857c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 7867c92a3d2SAneesh Kumar K.VSpecifies the id value specified along with -fsdev option 7877c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 7887c92a3d2SAneesh Kumar K.VSpecifies the tag name to be used by the guest to mount this export point 7897c92a3d2SAneesh Kumar K.V@end table 7907c92a3d2SAneesh Kumar K.V 79174db920cSGautham R ShenoyETEXI 79274db920cSGautham R Shenoy 7933d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 7942c30dd74SAneesh Kumar K.V "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 79584a87cc4SM. Mohan Kumar " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 7963d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 7973d54abc7SGautham R Shenoy 7983d54abc7SGautham R ShenoySTEXI 7993d54abc7SGautham R Shenoy 80084a87cc4SM. Mohan Kumar@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}] 8013d54abc7SGautham R Shenoy@findex -virtfs 8023d54abc7SGautham R Shenoy 8037c92a3d2SAneesh Kumar K.VThe general form of a Virtual File system pass-through options are: 8047c92a3d2SAneesh Kumar K.V@table @option 8057c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 8067c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 807f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 8087c92a3d2SAneesh Kumar K.V@item id=@var{id} 8097c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 8107c92a3d2SAneesh Kumar K.V@item path=@var{path} 8117c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 8127c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 8137c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 8147c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 8152c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 8167c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 817b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 8182c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 8197c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 8202c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 8212c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 8227c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 8237c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 824d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 825f67e3ffdSM. Mohan Kumarfor local fsdriver. Other fsdrivers (like handle, proxy) don't take security 826d9b36a6eSM. Mohan Kumarmodel as a parameter. 8277c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 8287c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 8297c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 8307c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 8317c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 8322c74c2cbSM. Mohan Kumar@item readonly 8332c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 8342c74c2cbSM. Mohan Kumarread-write access is given. 83584a87cc4SM. Mohan Kumar@item socket=@var{socket} 83684a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 83784a87cc4SM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 83884a87cc4SM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 839f67e3ffdSM. Mohan Kumar@item sock_fd 840f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 841f67e3ffdSM. Mohan Kumardescriptor for interfacing with virtfs-proxy-helper 8423d54abc7SGautham R Shenoy@end table 8433d54abc7SGautham R ShenoyETEXI 8443d54abc7SGautham R Shenoy 8459db221aeSAneesh Kumar K.VDEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 8469db221aeSAneesh Kumar K.V "-virtfs_synth Create synthetic file system image\n", 8479db221aeSAneesh Kumar K.V QEMU_ARCH_ALL) 8489db221aeSAneesh Kumar K.VSTEXI 8499db221aeSAneesh Kumar K.V@item -virtfs_synth 8509db221aeSAneesh Kumar K.V@findex -virtfs_synth 8519db221aeSAneesh Kumar K.VCreate synthetic file system image 8529db221aeSAneesh Kumar K.VETEXI 8539db221aeSAneesh Kumar K.V 8545824d651Sblueswir1STEXI 8555824d651Sblueswir1@end table 8565824d651Sblueswir1ETEXI 8575824d651Sblueswir1DEFHEADING() 8585824d651Sblueswir1 85910adb8beSMarkus ArmbrusterDEFHEADING(USB options:) 86010adb8beSMarkus ArmbrusterSTEXI 86110adb8beSMarkus Armbruster@table @option 86210adb8beSMarkus ArmbrusterETEXI 86310adb8beSMarkus Armbruster 86410adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 86510adb8beSMarkus Armbruster "-usb enable the USB driver (will be the default soon)\n", 86610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 86710adb8beSMarkus ArmbrusterSTEXI 86810adb8beSMarkus Armbruster@item -usb 86910adb8beSMarkus Armbruster@findex -usb 87010adb8beSMarkus ArmbrusterEnable the USB driver (will be the default soon) 87110adb8beSMarkus ArmbrusterETEXI 87210adb8beSMarkus Armbruster 87310adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 87410adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 87510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 87610adb8beSMarkus ArmbrusterSTEXI 87710adb8beSMarkus Armbruster 87810adb8beSMarkus Armbruster@item -usbdevice @var{devname} 87910adb8beSMarkus Armbruster@findex -usbdevice 88010adb8beSMarkus ArmbrusterAdd the USB device @var{devname}. @xref{usb_devices}. 88110adb8beSMarkus Armbruster 88210adb8beSMarkus Armbruster@table @option 88310adb8beSMarkus Armbruster 88410adb8beSMarkus Armbruster@item mouse 88510adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 88610adb8beSMarkus Armbruster 88710adb8beSMarkus Armbruster@item tablet 88810adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 88910adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 89010adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 89110adb8beSMarkus Armbruster 89210adb8beSMarkus Armbruster@item disk:[format=@var{format}]:@var{file} 89310adb8beSMarkus ArmbrusterMass storage device based on file. The optional @var{format} argument 894d33c8a7dSMichael Tokarevwill be used rather than detecting the format. Can be used to specify 89510adb8beSMarkus Armbruster@code{format=raw} to avoid interpreting an untrusted format header. 89610adb8beSMarkus Armbruster 89710adb8beSMarkus Armbruster@item host:@var{bus}.@var{addr} 89810adb8beSMarkus ArmbrusterPass through the host device identified by @var{bus}.@var{addr} (Linux only). 89910adb8beSMarkus Armbruster 90010adb8beSMarkus Armbruster@item host:@var{vendor_id}:@var{product_id} 90110adb8beSMarkus ArmbrusterPass through the host device identified by @var{vendor_id}:@var{product_id} 90210adb8beSMarkus Armbruster(Linux only). 90310adb8beSMarkus Armbruster 90410adb8beSMarkus Armbruster@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} 90510adb8beSMarkus ArmbrusterSerial converter to host character device @var{dev}, see @code{-serial} for the 90610adb8beSMarkus Armbrusteravailable devices. 90710adb8beSMarkus Armbruster 90810adb8beSMarkus Armbruster@item braille 90910adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 91010adb8beSMarkus Armbrusteror fake device. 91110adb8beSMarkus Armbruster 91210adb8beSMarkus Armbruster@item net:@var{options} 91310adb8beSMarkus ArmbrusterNetwork adapter that supports CDC ethernet and RNDIS protocols. 91410adb8beSMarkus Armbruster 91510adb8beSMarkus Armbruster@end table 91610adb8beSMarkus ArmbrusterETEXI 91710adb8beSMarkus Armbruster 91810adb8beSMarkus ArmbrusterSTEXI 91910adb8beSMarkus Armbruster@end table 92010adb8beSMarkus ArmbrusterETEXI 92110adb8beSMarkus ArmbrusterDEFHEADING() 92210adb8beSMarkus Armbruster 9235824d651Sblueswir1DEFHEADING(Display options:) 9245824d651Sblueswir1STEXI 9255824d651Sblueswir1@table @option 9265824d651Sblueswir1ETEXI 9275824d651Sblueswir1 9281472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 9291472a95bSJes Sorensen "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 930f04ec5afSRobert Ho " [,window_close=on|off][,gl=on|off]|curses|none|\n" 931f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 932f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 933f04ec5afSRobert Ho "-display curses\n" 934f04ec5afSRobert Ho "-display none" 935f04ec5afSRobert Ho " select display type\n" 936f04ec5afSRobert Ho "The default display is equivalent to\n" 937f04ec5afSRobert Ho#if defined(CONFIG_GTK) 938f04ec5afSRobert Ho "\t\"-display gtk\"\n" 939f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 940f04ec5afSRobert Ho "\t\"-display sdl\"\n" 941f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 942f04ec5afSRobert Ho "\t\"-display cocoa\"\n" 943f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 944f04ec5afSRobert Ho "\t\"-vnc localhost:0,to=99,id=default\"\n" 945f04ec5afSRobert Ho#else 946f04ec5afSRobert Ho "\t\"-display none\"\n" 947f04ec5afSRobert Ho#endif 948f04ec5afSRobert Ho , QEMU_ARCH_ALL) 9491472a95bSJes SorensenSTEXI 9501472a95bSJes Sorensen@item -display @var{type} 9511472a95bSJes Sorensen@findex -display 9521472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 9531472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 9541472a95bSJes Sorensen@table @option 9551472a95bSJes Sorensen@item sdl 9561472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 9571472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 9581472a95bSJes Sorensen@item curses 9591472a95bSJes SorensenDisplay video output via curses. For graphics device models which 9601472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 9611472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 9621472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 9631472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 9644171d32eSJes Sorensen@item none 9654171d32eSJes SorensenDo not display video output. The guest will still see an emulated 9664171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 9674171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 9684171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 9694171d32eSJes Sorensenthe destination of the serial and parallel port data. 970881249c7SJan Kiszka@item gtk 971881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 972881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 973881249c7SJan Kiszkaruntime. 9743264ff12SJes Sorensen@item vnc 9753264ff12SJes SorensenStart a VNC server on display <arg> 9761472a95bSJes Sorensen@end table 9771472a95bSJes SorensenETEXI 9781472a95bSJes Sorensen 9795824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 980ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 981ad96090aSBlue Swirl QEMU_ARCH_ALL) 9825824d651Sblueswir1STEXI 9835824d651Sblueswir1@item -nographic 9846616b2adSStefan Weil@findex -nographic 985dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 986dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 987dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 988dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 989dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 990dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 991dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 992dc0a3e44SColin Lordswitching between the console and monitor. 9935824d651Sblueswir1ETEXI 9945824d651Sblueswir1 9955824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 996f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 997ad96090aSBlue Swirl QEMU_ARCH_ALL) 9985824d651Sblueswir1STEXI 9995824d651Sblueswir1@item -curses 1000b8f490ebSMarkus Armbruster@findex -curses 1001dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1002dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1003dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1004dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1005dc0a3e44SColin Lordmode. 10065824d651Sblueswir1ETEXI 10075824d651Sblueswir1 10085824d651Sblueswir1DEF("no-frame", 0, QEMU_OPTION_no_frame, 1009ad96090aSBlue Swirl "-no-frame open SDL window without a frame and window decorations\n", 1010ad96090aSBlue Swirl QEMU_ARCH_ALL) 10115824d651Sblueswir1STEXI 10125824d651Sblueswir1@item -no-frame 10136616b2adSStefan Weil@findex -no-frame 10145824d651Sblueswir1Do not use decorations for SDL windows and start them using the whole 10155824d651Sblueswir1available screen space. This makes the using QEMU in a dedicated desktop 10165824d651Sblueswir1workspace more convenient. 10175824d651Sblueswir1ETEXI 10185824d651Sblueswir1 10195824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1020ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1021ad96090aSBlue Swirl QEMU_ARCH_ALL) 10225824d651Sblueswir1STEXI 10235824d651Sblueswir1@item -alt-grab 10246616b2adSStefan Weil@findex -alt-grab 1025de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1026de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 10275824d651Sblueswir1ETEXI 10285824d651Sblueswir1 10290ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1030ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1031ad96090aSBlue Swirl QEMU_ARCH_ALL) 10320ca9f8a4SDustin KirklandSTEXI 10330ca9f8a4SDustin Kirkland@item -ctrl-grab 10346616b2adSStefan Weil@findex -ctrl-grab 1035de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1036de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 10370ca9f8a4SDustin KirklandETEXI 10380ca9f8a4SDustin Kirkland 10395824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1040ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 10415824d651Sblueswir1STEXI 10425824d651Sblueswir1@item -no-quit 10436616b2adSStefan Weil@findex -no-quit 10445824d651Sblueswir1Disable SDL window close capability. 10455824d651Sblueswir1ETEXI 10465824d651Sblueswir1 10475824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1048f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 10495824d651Sblueswir1STEXI 10505824d651Sblueswir1@item -sdl 10516616b2adSStefan Weil@findex -sdl 10525824d651Sblueswir1Enable SDL. 10535824d651Sblueswir1ETEXI 10545824d651Sblueswir1 105529b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 105627af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 105727af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 105827af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1059fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 106027af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 106127af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 106227af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 106327af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 106427af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 106527af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 106627af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 106727af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 10685ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 10695ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 1070474114b7SGerd Hoffmann " [,gl=[on|off]]\n" 107127af7788SYonit Halperin " enable spice\n" 107227af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 107327af7788SYonit Halperin QEMU_ARCH_ALL) 107429b0040bSGerd HoffmannSTEXI 107529b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 107629b0040bSGerd Hoffmann@findex -spice 107729b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 107829b0040bSGerd Hoffmann 107929b0040bSGerd Hoffmann@table @option 108029b0040bSGerd Hoffmann 108129b0040bSGerd Hoffmann@item port=<nr> 1082c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 108329b0040bSGerd Hoffmann 1084333b0eebSGerd Hoffmann@item addr=<addr> 1085333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1086333b0eebSGerd Hoffmann 1087333b0eebSGerd Hoffmann@item ipv4 1088f9cfd655SMarkus Armbruster@itemx ipv6 1089f9cfd655SMarkus Armbruster@itemx unix 1090333b0eebSGerd HoffmannForce using the specified IP version. 1091333b0eebSGerd Hoffmann 109229b0040bSGerd Hoffmann@item password=<secret> 109329b0040bSGerd HoffmannSet the password you need to authenticate. 109429b0040bSGerd Hoffmann 109548b3ed0aSMarc-André Lureau@item sasl 109648b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 109748b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 109848b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 109948b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 110048b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 110148b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 110248b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 110348b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 110448b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 110548b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 110648b3ed0aSMarc-André Lureaucredentials. 110748b3ed0aSMarc-André Lureau 110829b0040bSGerd Hoffmann@item disable-ticketing 110929b0040bSGerd HoffmannAllow client connects without authentication. 111029b0040bSGerd Hoffmann 1111d4970b07SHans de Goede@item disable-copy-paste 1112d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1113d4970b07SHans de Goede 11145ad24e5fSHans de Goede@item disable-agent-file-xfer 11155ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 11165ad24e5fSHans de Goede 1117c448e855SGerd Hoffmann@item tls-port=<nr> 1118c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1119c448e855SGerd Hoffmann 1120c448e855SGerd Hoffmann@item x509-dir=<dir> 1121c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1122c448e855SGerd Hoffmann 1123c448e855SGerd Hoffmann@item x509-key-file=<file> 1124f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1125f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1126f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1127f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1128c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1129c448e855SGerd Hoffmann 1130c448e855SGerd Hoffmann@item tls-ciphers=<list> 1131c448e855SGerd HoffmannSpecify which ciphers to use. 1132c448e855SGerd Hoffmann 1133d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1134f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 113517b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 113617b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 113717b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 113817b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 113917b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 114017b6dea0SGerd Hoffmann 11419f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 11429f04e09eSYonit HalperinConfigure image compression (lossless). 11439f04e09eSYonit HalperinDefault is auto_glz. 11449f04e09eSYonit Halperin 11459f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1146f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 11479f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 11489f04e09eSYonit HalperinDefault is auto. 11499f04e09eSYonit Halperin 115084a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 115193ca519eSLi ZhijianConfigure video stream detection. Default is off. 115284a23f25SGerd Hoffmann 115384a23f25SGerd Hoffmann@item agent-mouse=[on|off] 115484a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 115584a23f25SGerd Hoffmann 115684a23f25SGerd Hoffmann@item playback-compression=[on|off] 115784a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 115884a23f25SGerd Hoffmann 11598c957053SYonit Halperin@item seamless-migration=[on|off] 11608c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 11618c957053SYonit Halperin 1162474114b7SGerd Hoffmann@item gl=[on|off] 1163474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1164474114b7SGerd Hoffmann 116529b0040bSGerd Hoffmann@end table 116629b0040bSGerd HoffmannETEXI 116729b0040bSGerd Hoffmann 11685824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1169ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1170ad96090aSBlue Swirl QEMU_ARCH_ALL) 11715824d651Sblueswir1STEXI 11725824d651Sblueswir1@item -portrait 11736616b2adSStefan Weil@findex -portrait 11745824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 11755824d651Sblueswir1ETEXI 11765824d651Sblueswir1 11779312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 11789312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 11799312805dSVasily Khoruzhick QEMU_ARCH_ALL) 11809312805dSVasily KhoruzhickSTEXI 11816265c43bSMarkus Armbruster@item -rotate @var{deg} 11829312805dSVasily Khoruzhick@findex -rotate 11839312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 11849312805dSVasily KhoruzhickETEXI 11859312805dSVasily Khoruzhick 11865824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1187a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1188ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 11895824d651Sblueswir1STEXI 1190e4558dcaSmalc@item -vga @var{type} 11916616b2adSStefan Weil@findex -vga 11925824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1193b3f046c2SKevin Wolf@table @option 11945824d651Sblueswir1@item cirrus 11955824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 11965824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 11975824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 11985824d651Sblueswir1(This one is the default) 11995824d651Sblueswir1@item std 12005824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 12015824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 12025824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 12035824d651Sblueswir1this option. 12045824d651Sblueswir1@item vmware 12055824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 12065824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 12075824d651Sblueswir1card. 1208a19cbfb3SGerd Hoffmann@item qxl 1209a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1210a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1211a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 121233632788SMark Cave-Ayland@item tcx 121333632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 121433632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 121533632788SMark Cave-Aylandfixed resolution of 1024x768. 121633632788SMark Cave-Ayland@item cg3 121733632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 121833632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 121933632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1220a94f0c5cSGerd Hoffmann@item virtio 1221a94f0c5cSGerd HoffmannVirtio VGA card. 12225824d651Sblueswir1@item none 12235824d651Sblueswir1Disable VGA card. 12245824d651Sblueswir1@end table 12255824d651Sblueswir1ETEXI 12265824d651Sblueswir1 12275824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1228ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 12295824d651Sblueswir1STEXI 12305824d651Sblueswir1@item -full-screen 12316616b2adSStefan Weil@findex -full-screen 12325824d651Sblueswir1Start in full screen. 12335824d651Sblueswir1ETEXI 12345824d651Sblueswir1 12355824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1236ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1237ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 12385824d651Sblueswir1STEXI 123995d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 12406616b2adSStefan Weil@findex -g 124195d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 12425824d651Sblueswir1ETEXI 12435824d651Sblueswir1 12445824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1245f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 12465824d651Sblueswir1STEXI 12475824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 12486616b2adSStefan Weil@findex -vnc 1249dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1250dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1251dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1252dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1253dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1254dc0a3e44SColin Lord(option @option{-usbdevice tablet}). When using the VNC display, you 1255dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1256dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 12575824d651Sblueswir1 1258b3f046c2SKevin Wolf@table @option 12595824d651Sblueswir1 126099a9a52aSRobert Ho@item to=@var{L} 126199a9a52aSRobert Ho 126299a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 126399a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 126499a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 126599a9a52aSRobert Hoapplication. By default, to=0. 126699a9a52aSRobert Ho 12675824d651Sblueswir1@item @var{host}:@var{d} 12685824d651Sblueswir1 12695824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 12705824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 12715824d651Sblueswir1be omitted in which case the server will accept connections from any host. 12725824d651Sblueswir1 12734e257e5eSKevin Wolf@item unix:@var{path} 12745824d651Sblueswir1 12755824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 12765824d651Sblueswir1location of a unix socket to listen for connections on. 12775824d651Sblueswir1 12785824d651Sblueswir1@item none 12795824d651Sblueswir1 12805824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 12815824d651Sblueswir1can be used to later start the VNC server. 12825824d651Sblueswir1 12835824d651Sblueswir1@end table 12845824d651Sblueswir1 12855824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 12865824d651Sblueswir1separated by commas. Valid options are 12875824d651Sblueswir1 1288b3f046c2SKevin Wolf@table @option 12895824d651Sblueswir1 12905824d651Sblueswir1@item reverse 12915824d651Sblueswir1 12925824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 12935824d651Sblueswir1client is specified by the @var{display}. For reverse network 12945824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 12955824d651Sblueswir1is a TCP port number, not a display number. 12965824d651Sblueswir1 12977536ee4bSTim Hardeck@item websocket 12987536ee4bSTim Hardeck 12997536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1300085d8134SPeter MaydellBy definition the Websocket port is 5700+@var{display}. If @var{host} is 13017536ee4bSTim Hardeckspecified connections will only be allowed from this host. 13027536ee4bSTim HardeckAs an alternative the Websocket port could be specified by using 13037536ee4bSTim Hardeck@code{websocket}=@var{port}. 13043e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 13053e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 13063e305e4aSDaniel P. Berrangerequires encrypted client connections. 13077536ee4bSTim Hardeck 13085824d651Sblueswir1@item password 13095824d651Sblueswir1 13105824d651Sblueswir1Require that password based authentication is used for client connections. 131186ee5bc3SMichal Novotny 131286ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 131386ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 131486ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 131586ee5bc3SMichal Novotny"vnc" or "spice". 131686ee5bc3SMichal Novotny 131786ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 131886ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 131986ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 132086ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 132186ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 132286ee5bc3SMichal Novotnydate and time). 132386ee5bc3SMichal Novotny 132486ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 132586ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 13265824d651Sblueswir1 13273e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 13283e305e4aSDaniel P. Berrange 13293e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 13303e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 13313e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 13323e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 13333e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 13343e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 13353e305e4aSDaniel P. Berrange 13363e305e4aSDaniel P. BerrangeThe @option{tls-creds} parameter obsoletes the @option{tls}, 13373e305e4aSDaniel P. Berrange@option{x509}, and @option{x509verify} options, and as such 13383e305e4aSDaniel P. Berrangeit is not permitted to set both new and old type options at 13393e305e4aSDaniel P. Berrangethe same time. 13403e305e4aSDaniel P. Berrange 13415824d651Sblueswir1@item tls 13425824d651Sblueswir1 13435824d651Sblueswir1Require that client use TLS when communicating with the VNC server. This 13445824d651Sblueswir1uses anonymous TLS credentials so is susceptible to a man-in-the-middle 13455824d651Sblueswir1attack. It is recommended that this option be combined with either the 13464e257e5eSKevin Wolf@option{x509} or @option{x509verify} options. 13475824d651Sblueswir1 13483e305e4aSDaniel P. BerrangeThis option is now deprecated in favor of using the @option{tls-creds} 13493e305e4aSDaniel P. Berrangeargument. 13503e305e4aSDaniel P. Berrange 13515824d651Sblueswir1@item x509=@var{/path/to/certificate/dir} 13525824d651Sblueswir1 13535824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 13545824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 13555824d651Sblueswir1to the client. It is recommended that a password be set on the VNC server 13565824d651Sblueswir1to provide authentication of the client when this is used. The path following 13575824d651Sblueswir1this option specifies where the x509 certificates are to be loaded from. 13585824d651Sblueswir1See the @ref{vnc_security} section for details on generating certificates. 13595824d651Sblueswir1 13603e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 13613e305e4aSDaniel P. Berrangeargument. 13623e305e4aSDaniel P. Berrange 13635824d651Sblueswir1@item x509verify=@var{/path/to/certificate/dir} 13645824d651Sblueswir1 13655824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 13665824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 13675824d651Sblueswir1to the client, and request that the client send its own x509 certificate. 13685824d651Sblueswir1The server will validate the client's certificate against the CA certificate, 13695824d651Sblueswir1and reject clients when validation fails. If the certificate authority is 13705824d651Sblueswir1trusted, this is a sufficient authentication mechanism. You may still wish 13715824d651Sblueswir1to set a password on the VNC server as a second authentication layer. The 13725824d651Sblueswir1path following this option specifies where the x509 certificates are to 13735824d651Sblueswir1be loaded from. See the @ref{vnc_security} section for details on generating 13745824d651Sblueswir1certificates. 13755824d651Sblueswir1 13763e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 13773e305e4aSDaniel P. Berrangeargument. 13783e305e4aSDaniel P. Berrange 13795824d651Sblueswir1@item sasl 13805824d651Sblueswir1 13815824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 13825824d651Sblueswir1The exact choice of authentication method used is controlled from the 13835824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 13845824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 13855824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 13865824d651Sblueswir1to make it search alternate locations for the service config. 13875824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 13885824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 13895824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 13905824d651Sblueswir1ensures a data encryption preventing compromise of authentication 13915824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 13925824d651Sblueswir1SASL authentication. 13935824d651Sblueswir1 13945824d651Sblueswir1@item acl 13955824d651Sblueswir1 13965824d651Sblueswir1Turn on access control lists for checking of the x509 client certificate 13975824d651Sblueswir1and SASL party. For x509 certs, the ACL check is made against the 13985824d651Sblueswir1certificate's distinguished name. This is something that looks like 13995824d651Sblueswir1@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 14005824d651Sblueswir1made against the username, which depending on the SASL plugin, may 14015824d651Sblueswir1include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 14025824d651Sblueswir1When the @option{acl} flag is set, the initial access list will be 14035824d651Sblueswir1empty, with a @code{deny} policy. Thus no one will be allowed to 14045824d651Sblueswir1use the VNC server until the ACLs have been loaded. This can be 14055824d651Sblueswir1achieved using the @code{acl} monitor command. 14065824d651Sblueswir1 14076f9c78c1SCorentin Chary@item lossy 14086f9c78c1SCorentin Chary 14096f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 14106f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 14116f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 14126f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 14136f9c78c1SCorentin Chary 141480e0c8c3SCorentin Chary@item non-adaptive 141580e0c8c3SCorentin Chary 141680e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 141780e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 141880e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 141961cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 14209d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 142180e0c8c3SCorentin Charylike Tight. 142280e0c8c3SCorentin Chary 14238cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 14248cf36489SGerd Hoffmann 14258cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 14268cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 14278cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 14288cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 14298cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 14308cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 14318cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 14328cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 14338cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 1434b65ee4faSStefan Weilspec but is traditional QEMU behavior. 14358cf36489SGerd Hoffmann 1436c5ce8333SGerd Hoffmann@item key-delay-ms 1437c5ce8333SGerd Hoffmann 1438c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 1439c5ce8333SGerd HoffmannDefault is 1. Keyboards are low-bandwidth devices, so this slowdown 1440c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 1441c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 1442c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 1443c5ce8333SGerd Hoffmann 14445824d651Sblueswir1@end table 14455824d651Sblueswir1ETEXI 14465824d651Sblueswir1 14475824d651Sblueswir1STEXI 14485824d651Sblueswir1@end table 14495824d651Sblueswir1ETEXI 1450a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 14515824d651Sblueswir1 1452a3adb7adSMichael EllermanARCHHEADING(i386 target only:, QEMU_ARCH_I386) 14535824d651Sblueswir1STEXI 14545824d651Sblueswir1@table @option 14555824d651Sblueswir1ETEXI 14565824d651Sblueswir1 14575824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1458ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1459ad96090aSBlue Swirl QEMU_ARCH_I386) 14605824d651Sblueswir1STEXI 14615824d651Sblueswir1@item -win2k-hack 14626616b2adSStefan Weil@findex -win2k-hack 14635824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 14645824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 14655824d651Sblueswir1slows down the IDE transfers). 14665824d651Sblueswir1ETEXI 14675824d651Sblueswir1 14681ed2fc1fSJan KiszkaHXCOMM Deprecated by -rtc 1469ad96090aSBlue SwirlDEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 14705824d651Sblueswir1 14715824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1472ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1473ad96090aSBlue Swirl QEMU_ARCH_I386) 14745824d651Sblueswir1STEXI 14755824d651Sblueswir1@item -no-fd-bootchk 14766616b2adSStefan Weil@findex -no-fd-bootchk 14774eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 14785824d651Sblueswir1be needed to boot from old floppy disks. 14795824d651Sblueswir1ETEXI 14805824d651Sblueswir1 14815824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1482f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 14835824d651Sblueswir1STEXI 14845824d651Sblueswir1@item -no-acpi 14856616b2adSStefan Weil@findex -no-acpi 14865824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 14875824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 14885824d651Sblueswir1only). 14895824d651Sblueswir1ETEXI 14905824d651Sblueswir1 14915824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1492ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 14935824d651Sblueswir1STEXI 14945824d651Sblueswir1@item -no-hpet 14956616b2adSStefan Weil@findex -no-hpet 14965824d651Sblueswir1Disable HPET support. 14975824d651Sblueswir1ETEXI 14985824d651Sblueswir1 14995824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1500104bf02eSMichael Tokarev "-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" 1501ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 15025824d651Sblueswir1STEXI 15035824d651Sblueswir1@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}]...] 15046616b2adSStefan Weil@findex -acpitable 15055824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 1506104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 1507104bf02eSMichael TokarevACPI headers (possible overridden by other options). 1508104bf02eSMichael TokarevFor data=, only data 1509104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 1510104bf02eSMichael Tokarevcommand line. 1511ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 1512ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 1513ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 1514ae123749SLaszlo Ersekspec. 15155824d651Sblueswir1ETEXI 15165824d651Sblueswir1 1517b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1518b6f6e3d3Saliguori "-smbios file=binary\n" 1519ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 1520b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1521b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 1522ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 1523b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1524b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 1525b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 1526b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1527b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 1528b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 1529b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 1530b155eb1dSGabriel L. Somlo " [,sku=str]\n" 1531b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 1532b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 1533b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 1534b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 1535b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 15363ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 1537b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 1538c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1539b6f6e3d3SaliguoriSTEXI 1540b6f6e3d3Saliguori@item -smbios file=@var{binary} 15416616b2adSStefan Weil@findex -smbios 1542b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 1543b6f6e3d3Saliguori 154484351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 1545b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 1546b6f6e3d3Saliguori 1547b6f6e3d3Saliguori@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}] 1548b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 1549b155eb1dSGabriel L. Somlo 1550b155eb1dSGabriel L. Somlo@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}] 1551b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 1552b155eb1dSGabriel L. Somlo 1553b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 1554b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 1555b155eb1dSGabriel L. Somlo 1556b155eb1dSGabriel L. Somlo@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}] 1557b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 1558b155eb1dSGabriel L. Somlo 15593ebd6cc8SGabriel L. Somlo@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}] 1560b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 1561b6f6e3d3SaliguoriETEXI 1562b6f6e3d3Saliguori 15635824d651Sblueswir1STEXI 15645824d651Sblueswir1@end table 15655824d651Sblueswir1ETEXI 1566c70a01e4SMarkus ArmbrusterDEFHEADING() 15675824d651Sblueswir1 15685824d651Sblueswir1DEFHEADING(Network options:) 15695824d651Sblueswir1STEXI 15705824d651Sblueswir1@table @option 15715824d651Sblueswir1ETEXI 15725824d651Sblueswir1 1573ad196a9dSJan KiszkaHXCOMM Legacy slirp options (now moved to -net user): 1574ad196a9dSJan Kiszka#ifdef CONFIG_SLIRP 1575ad96090aSBlue SwirlDEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1576ad96090aSBlue SwirlDEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1577ad96090aSBlue SwirlDEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1578ad196a9dSJan Kiszka#ifndef _WIN32 1579ad96090aSBlue SwirlDEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1580ad196a9dSJan Kiszka#endif 1581ad196a9dSJan Kiszka#endif 1582ad196a9dSJan Kiszka 15836a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 15845824d651Sblueswir1#ifdef CONFIG_SLIRP 15850b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 15860b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 15870b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 1588d8eb3864SSamuel Thibault " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n" 158963d2960bSKlaus Stengel " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1590ad196a9dSJan Kiszka#ifndef _WIN32 1591c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 1592ad196a9dSJan Kiszka#endif 15936a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 15946a8b4a5bSThomas Huth " its DHCP server and optional services\n" 15955824d651Sblueswir1#endif 15965824d651Sblueswir1#ifdef _WIN32 15976a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 15986a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 15995824d651Sblueswir1#else 16006a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 16016a8b4a5bSThomas Huth " [,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 16026a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 160369e87b32SJason Wang " [,poll-us=n]\n" 16046a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 1605a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1606a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1607a7c36ee4SCorey Bryant " to deconfigure it\n" 1608ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 1609a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1610a7c36ee4SCorey Bryant " configure it\n" 16115824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 16122ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1613ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1614f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1615ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1616ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 161782b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 16185430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 16195430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 162082b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 16212ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1622ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 162369e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 162469e87b32SJason Wang " spent on busy polling for vhost net\n" 16256a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 16266a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 16276a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 16286a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 16290df0ff6dSMark McLoughlin#endif 16303fb69aa1SAnton Ivanov#ifdef __linux__ 16316a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 16326a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 16336a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 16346a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 16356a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 16366a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 16373fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 16382f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 16393fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 16403fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 16413fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 16423fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 16433fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 16443fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 16453952651aSGonglei " use 'srcport=' to specify source udp port\n" 16463fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 16473fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 16483fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 16493fb69aa1SAnton Ivanov " well as a weak security measure\n" 16503fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 16513fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 16523fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 16533fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 16543fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 16553fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 16563fb69aa1SAnton Ivanov#endif 16576a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 16586a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 16596a8b4a5bSThomas Huth " using a socket connection\n" 16606a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 16616a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 16623a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 16636a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 16646a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 16656a8b4a5bSThomas Huth " using an UDP tunnel\n" 16665824d651Sblueswir1#ifdef CONFIG_VDE 16676a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 16686a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 16696a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 16705824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 16715824d651Sblueswir1 " ownership and permissions for communication port.\n" 16725824d651Sblueswir1#endif 167358952137SVincenzo Maffione#ifdef CONFIG_NETMAP 16746a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 167558952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 167658952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 167758952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 167858952137SVincenzo Maffione#endif 16796a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 16806a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 16816a8b4a5bSThomas Huth "-netdev hubport,id=str,hubid=n\n" 16826a8b4a5bSThomas Huth " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL) 16836a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 16846a8b4a5bSThomas Huth "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 16856a8b4a5bSThomas Huth " old way to create a new NIC and connect it to VLAN 'n'\n" 16866a8b4a5bSThomas Huth " (use the '-device devtype,netdev=str' option if possible instead)\n" 1687bb9ea79eSaliguori "-net dump[,vlan=n][,file=f][,len=n]\n" 1688bb9ea79eSaliguori " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n" 1689ca1a8a06SBruce Rogers "-net none use it alone to have zero network devices. If no -net option\n" 16906a8b4a5bSThomas Huth " is provided, the default is '-net nic -net user'\n" 16916a8b4a5bSThomas Huth "-net [" 1692a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 1693a1ea458fSMark McLoughlin "user|" 1694a1ea458fSMark McLoughlin#endif 1695a1ea458fSMark McLoughlin "tap|" 1696a7c36ee4SCorey Bryant "bridge|" 1697a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 1698a1ea458fSMark McLoughlin "vde|" 1699a1ea458fSMark McLoughlin#endif 170058952137SVincenzo Maffione#ifdef CONFIG_NETMAP 170158952137SVincenzo Maffione "netmap|" 170258952137SVincenzo Maffione#endif 17036a8b4a5bSThomas Huth "socket][,vlan=n][,option][,option][,...]\n" 17046a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 17056a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 17065824d651Sblueswir1STEXI 1707ffe6370cSMichael S. Tsirkin@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 17086616b2adSStefan Weil@findex -net 17095824d651Sblueswir1Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} 17100d6b0b1dSAnthony Liguori= 0 is the default). The NIC is an e1000 by default on the PC 17115607c388SMarkus Armbrustertarget. Optionally, the MAC address can be changed to @var{mac}, the 17125607c388SMarkus Armbrusterdevice address set to @var{addr} (PCI cards only), 1713ffe6370cSMichael S. Tsirkinand a @var{name} can be assigned for use in monitor commands. 1714ffe6370cSMichael S. TsirkinOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 1715ffe6370cSMichael S. Tsirkinthat the card should have; this option currently only affects virtio cards; set 1716ffe6370cSMichael S. Tsirkin@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 1717071c9394SStefan WeilNIC is created. QEMU can emulate several different models of network card. 17185824d651Sblueswir1Valid values for @var{type} are 1719ffe6370cSMichael S. Tsirkin@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er}, 17205824d651Sblueswir1@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, 17215824d651Sblueswir1@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. 1722585f6036SPeter MaydellNot all devices are supported on all targets. Use @code{-net nic,model=help} 17235824d651Sblueswir1for a list of available devices for your target. 17245824d651Sblueswir1 172508d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 1726b8f490ebSMarkus Armbruster@findex -netdev 1727ad196a9dSJan Kiszka@item -net user[,@var{option}][,@var{option}][,...] 17285824d651Sblueswir1Use the user mode network stack which requires no administrator 1729ad196a9dSJan Kiszkaprivilege to run. Valid options are: 17305824d651Sblueswir1 1731b3f046c2SKevin Wolf@table @option 1732ad196a9dSJan Kiszka@item vlan=@var{n} 1733ad196a9dSJan KiszkaConnect user mode stack to VLAN @var{n} (@var{n} = 0 is the default). 1734ad196a9dSJan Kiszka 173508d12022SStefan Hajnoczi@item id=@var{id} 1736f9cfd655SMarkus Armbruster@itemx name=@var{name} 1737ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 1738ad196a9dSJan Kiszka 17390b11c036SSamuel Thibault@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must 17400b11c036SSamuel Thibaultbe enabled. If neither is specified both protocols are enabled. 17410b11c036SSamuel Thibault 1742c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 1743c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 1744c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 1745b0b36e5dSBrad Hards10.0.2.0/24. 1746c92ef6a2SJan Kiszka 1747c92ef6a2SJan Kiszka@item host=@var{addr} 1748c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 1749c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 1750ad196a9dSJan Kiszka 1751d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 1752d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 1753d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 1754d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 1755d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 17567aac531eSYann Bordenave 1757d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 17587aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 17597aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 17607aac531eSYann Bordenave 1761c54ed5bcSJan Kiszka@item restrict=on|off 1762caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 1763ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 1764caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 1765ad196a9dSJan Kiszka 1766ad196a9dSJan Kiszka@item hostname=@var{name} 176763d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 1768ad196a9dSJan Kiszka 1769c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 1770c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 1771b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 1772c92ef6a2SJan Kiszka 1773c92ef6a2SJan Kiszka@item dns=@var{addr} 1774c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 1775c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 1776c92ef6a2SJan Kiszkai.e. x.x.x.3. 1777c92ef6a2SJan Kiszka 1778d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 17797aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 17807aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 17817aac531eSYann Bordenavenetwork, i.e. xxxx::3. 17827aac531eSYann Bordenave 178363d2960bSKlaus Stengel@item dnssearch=@var{domain} 178463d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 178563d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 178663d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 178763d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 178863d2960bSKlaus Stengelcan not be resolved. 178963d2960bSKlaus Stengel 179063d2960bSKlaus StengelExample: 179163d2960bSKlaus Stengel@example 179263d2960bSKlaus Stengelqemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] 179363d2960bSKlaus Stengel@end example 179463d2960bSKlaus Stengel 1795ad196a9dSJan Kiszka@item tftp=@var{dir} 1796ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 1797ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 1798ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 1799c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 1800ad196a9dSJan Kiszka 1801ad196a9dSJan Kiszka@item bootfile=@var{file} 1802ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 1803ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 1804ad196a9dSJan Kiszkaa guest from a local directory. 1805ad196a9dSJan Kiszka 1806ad196a9dSJan KiszkaExample (using pxelinux): 1807ad196a9dSJan Kiszka@example 18083804da9dSStefan Weilqemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 1809ad196a9dSJan Kiszka@end example 1810ad196a9dSJan Kiszka 1811c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 1812ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 1813ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 1814c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 1815c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 1816ad196a9dSJan Kiszka 1817ad196a9dSJan KiszkaIn the guest Windows OS, the line: 1818ad196a9dSJan Kiszka@example 1819ad196a9dSJan Kiszka10.0.2.4 smbserver 1820ad196a9dSJan Kiszka@end example 1821ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 1822ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 1823ad196a9dSJan Kiszka 1824ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 1825ad196a9dSJan Kiszka 1826e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 1827e2d8830eSBradQEMU was tested successfully with smbd versions from Red Hat 9, 1828e2d8830eSBradFedora Core 3 and OpenSUSE 11.x. 1829ad196a9dSJan Kiszka 18303c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 1831c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 1832c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 1833c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 18343c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 18353c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 1836c92ef6a2SJan Kiszkaused. This option can be given multiple times. 1837ad196a9dSJan Kiszka 1838ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 1839ad196a9dSJan Kiszkascreen 0, use the following: 1840ad196a9dSJan Kiszka 1841ad196a9dSJan Kiszka@example 1842ad196a9dSJan Kiszka# on the host 18433804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] 1844ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 1845ad196a9dSJan Kiszkaxterm -display :1 1846ad196a9dSJan Kiszka@end example 1847ad196a9dSJan Kiszka 1848ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 1849ad196a9dSJan Kiszkathe guest, use the following: 1850ad196a9dSJan Kiszka 1851ad196a9dSJan Kiszka@example 1852ad196a9dSJan Kiszka# on the host 18533804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] 1854ad196a9dSJan Kiszkatelnet localhost 5555 1855ad196a9dSJan Kiszka@end example 1856ad196a9dSJan Kiszka 1857ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 1858ad196a9dSJan Kiszkaconnect to the guest telnet server. 1859ad196a9dSJan Kiszka 1860c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 1861f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 18623c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 1863b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 1864b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 1865b412eb61SAlexander Graf 186643ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 1867b412eb61SAlexander Graflifetime, like in the following example: 1868b412eb61SAlexander Graf 1869b412eb61SAlexander Graf@example 1870b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 1871b412eb61SAlexander Graf# the guest accesses it 1872b412eb61SAlexander Grafqemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] 1873b412eb61SAlexander Graf@end example 1874b412eb61SAlexander Graf 1875b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 187643ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 1877b412eb61SAlexander Graf 1878b412eb61SAlexander Graf@example 1879b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 1880b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 1881b412eb61SAlexander Grafqemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 1882b412eb61SAlexander Graf@end example 1883ad196a9dSJan Kiszka 1884ad196a9dSJan Kiszka@end table 1885ad196a9dSJan Kiszka 1886ad196a9dSJan KiszkaNote: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 1887ad196a9dSJan Kiszkaprocessed and applied to -net user. Mixing them with the new configuration 1888ad196a9dSJan Kiszkasyntax gives undefined results. Their use for new applications is discouraged 1889ad196a9dSJan Kiszkaas they will be removed from future versions. 18905824d651Sblueswir1 189108d12022SStefan Hajnoczi@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1892f9cfd655SMarkus Armbruster@itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1893a7c36ee4SCorey BryantConnect the host TAP network interface @var{name} to VLAN @var{n}. 1894a7c36ee4SCorey Bryant 1895a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 18965824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 1897a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 1898a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 1899a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 1900a7c36ee4SCorey Bryantto disable script execution. 1901a7c36ee4SCorey Bryant 1902a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 1903a7c36ee4SCorey Bryant@var{helper} to configure the TAP interface. The default network 1904420508fbSAmos Konghelper executable is @file{/path/to/qemu-bridge-helper}. 1905a7c36ee4SCorey Bryant 1906a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 1907a7c36ee4SCorey Bryantopened host TAP interface. 1908a7c36ee4SCorey Bryant 1909a7c36ee4SCorey BryantExamples: 19105824d651Sblueswir1 19115824d651Sblueswir1@example 1912a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 19133804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net tap 19145824d651Sblueswir1@end example 19155824d651Sblueswir1 19165824d651Sblueswir1@example 1917a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 1918a7c36ee4SCorey Bryant#to a TAP device 19193804da9dSStefan Weilqemu-system-i386 linux.img \ 19203804da9dSStefan Weil -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 19215824d651Sblueswir1 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 19225824d651Sblueswir1@end example 19235824d651Sblueswir1 1924a7c36ee4SCorey Bryant@example 1925a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1926a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 19273804da9dSStefan Weilqemu-system-i386 linux.img \ 1928420508fbSAmos Kong -net nic -net tap,"helper=/path/to/qemu-bridge-helper" 1929a7c36ee4SCorey Bryant@end example 1930a7c36ee4SCorey Bryant 193108d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 1932f9cfd655SMarkus Armbruster@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}] 1933a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 1934a7c36ee4SCorey Bryant 1935a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 1936a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 1937420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 1938a7c36ee4SCorey Bryantdevice is @file{br0}. 1939a7c36ee4SCorey Bryant 1940a7c36ee4SCorey BryantExamples: 1941a7c36ee4SCorey Bryant 1942a7c36ee4SCorey Bryant@example 1943a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1944a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 19453804da9dSStefan Weilqemu-system-i386 linux.img -net bridge -net nic,model=virtio 1946a7c36ee4SCorey Bryant@end example 1947a7c36ee4SCorey Bryant 1948a7c36ee4SCorey Bryant@example 1949a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1950a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 19513804da9dSStefan Weilqemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio 1952a7c36ee4SCorey Bryant@end example 1953a7c36ee4SCorey Bryant 195408d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1955f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 19565824d651Sblueswir1 19575824d651Sblueswir1Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual 19585824d651Sblueswir1machine using a TCP socket connection. If @option{listen} is 19595824d651Sblueswir1specified, QEMU waits for incoming connections on @var{port} 19605824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 19615824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 19625824d651Sblueswir1specifies an already opened TCP socket. 19635824d651Sblueswir1 19645824d651Sblueswir1Example: 19655824d651Sblueswir1@example 19665824d651Sblueswir1# launch a first QEMU instance 19673804da9dSStefan Weilqemu-system-i386 linux.img \ 19683804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 19695824d651Sblueswir1 -net socket,listen=:1234 19705824d651Sblueswir1# connect the VLAN 0 of this instance to the VLAN 0 19715824d651Sblueswir1# of the first instance 19723804da9dSStefan Weilqemu-system-i386 linux.img \ 19733804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 19745824d651Sblueswir1 -net socket,connect=127.0.0.1:1234 19755824d651Sblueswir1@end example 19765824d651Sblueswir1 197708d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1978f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 19795824d651Sblueswir1 19805824d651Sblueswir1Create a VLAN @var{n} shared with another QEMU virtual 19815824d651Sblueswir1machines using a UDP multicast socket, effectively making a bus for 19825824d651Sblueswir1every QEMU with same multicast address @var{maddr} and @var{port}. 19835824d651Sblueswir1NOTES: 19845824d651Sblueswir1@enumerate 19855824d651Sblueswir1@item 19865824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 19875824d651Sblueswir1correct multicast setup for these hosts). 19885824d651Sblueswir1@item 19895824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 19905824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 19915824d651Sblueswir1@item 19925824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 19935824d651Sblueswir1@end enumerate 19945824d651Sblueswir1 19955824d651Sblueswir1Example: 19965824d651Sblueswir1@example 19975824d651Sblueswir1# launch one QEMU instance 19983804da9dSStefan Weilqemu-system-i386 linux.img \ 19993804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 20005824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 20015824d651Sblueswir1# launch another QEMU instance on same "bus" 20023804da9dSStefan Weilqemu-system-i386 linux.img \ 20033804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 20045824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 20055824d651Sblueswir1# launch yet another QEMU instance on same "bus" 20063804da9dSStefan Weilqemu-system-i386 linux.img \ 20073804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:58 \ 20085824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 20095824d651Sblueswir1@end example 20105824d651Sblueswir1 20115824d651Sblueswir1Example (User Mode Linux compat.): 20125824d651Sblueswir1@example 20135824d651Sblueswir1# launch QEMU instance (note mcast address selected 20145824d651Sblueswir1# is UML's default) 20153804da9dSStefan Weilqemu-system-i386 linux.img \ 20163804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 20175824d651Sblueswir1 -net socket,mcast=239.192.168.1:1102 20185824d651Sblueswir1# launch UML 20195824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 20205824d651Sblueswir1@end example 20215824d651Sblueswir1 20223a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 20233a75e74cSMike Ryan@example 20243804da9dSStefan Weilqemu-system-i386 linux.img \ 20253804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 20263a75e74cSMike Ryan -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 20273a75e74cSMike Ryan@end example 20283a75e74cSMike Ryan 20293fb69aa1SAnton Ivanov@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}] 2030f9cfd655SMarkus Armbruster@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}] 20313fb69aa1SAnton IvanovConnect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular 20323fb69aa1SAnton Ivanovprotocol to transport Ethernet (and other Layer 2) data frames between 20333fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 20343fb69aa1SAnton Ivanov(from version 3.3 onwards). 20353fb69aa1SAnton Ivanov 20363fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 20373fb69aa1SAnton Ivanov 20383fb69aa1SAnton Ivanov@item src=@var{srcaddr} 20393fb69aa1SAnton Ivanov source address (mandatory) 20403fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 20413fb69aa1SAnton Ivanov destination address (mandatory) 20423fb69aa1SAnton Ivanov@item udp 20433fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 20443fb69aa1SAnton Ivanov@item srcport=@var{srcport} 20453fb69aa1SAnton Ivanov source udp port. 20463fb69aa1SAnton Ivanov@item dstport=@var{dstport} 20473fb69aa1SAnton Ivanov destination udp port. 20483fb69aa1SAnton Ivanov@item ipv6 20493fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 20503fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2051f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 20523fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 20533fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 20543fb69aa1SAnton Ivanovbit. 20553fb69aa1SAnton Ivanov@item cookie64 20563fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 20573fb69aa1SAnton Ivanov@item counter=off 20583fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 20593fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 20603fb69aa1SAnton Ivanov@item pincounter=on 20613fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 20623fb69aa1SAnton Ivanovnetworks which have packet reorder. 20633fb69aa1SAnton Ivanov@item offset=@var{offset} 20643fb69aa1SAnton Ivanov Add an extra offset between header and data 20653fb69aa1SAnton Ivanov 20663fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 20673fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 20683fb69aa1SAnton Ivanov@example 20693fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 20703fb69aa1SAnton Ivanov# on 1.2.3.4 20713fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 20723fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 20733fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 20743fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 20753fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 20763fb69aa1SAnton Ivanovifconfig vmtunnel0 up 20773fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 20783fb69aa1SAnton Ivanov 20793fb69aa1SAnton Ivanov 20803fb69aa1SAnton Ivanov# on 4.3.2.1 20813fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 20823fb69aa1SAnton Ivanov 20833fb69aa1SAnton Ivanovqemu-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 20843fb69aa1SAnton Ivanov 20853fb69aa1SAnton Ivanov 20863fb69aa1SAnton Ivanov@end example 20873fb69aa1SAnton Ivanov 208808d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2089f9cfd655SMarkus Armbruster@itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 20905824d651Sblueswir1Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and 20915824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 20925824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2093c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 20945824d651Sblueswir1with vde support enabled. 20955824d651Sblueswir1 20965824d651Sblueswir1Example: 20975824d651Sblueswir1@example 20985824d651Sblueswir1# launch vde switch 20995824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 21005824d651Sblueswir1# launch QEMU instance 21013804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch 21025824d651Sblueswir1@end example 21035824d651Sblueswir1 210440e8c26dSStefan Hajnoczi@item -netdev hubport,id=@var{id},hubid=@var{hubid} 210540e8c26dSStefan Hajnoczi 210640e8c26dSStefan HajnocziCreate a hub port on QEMU "vlan" @var{hubid}. 210740e8c26dSStefan Hajnoczi 210840e8c26dSStefan HajnocziThe hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single 210940e8c26dSStefan Hajnoczinetdev. @code{-net} and @code{-device} with parameter @option{vlan} create the 211040e8c26dSStefan Hajnoczirequired hub automatically. 211140e8c26dSStefan Hajnoczi 2112b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 211303ce5744SNikolay Nikolaev 211403ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 211503ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 211603ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 211703ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2118b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2119b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 212003ce5744SNikolay Nikolaev 212103ce5744SNikolay NikolaevExample: 212203ce5744SNikolay Nikolaev@example 212303ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 212403ce5744SNikolay Nikolaev -numa node,memdev=mem \ 212503ce5744SNikolay Nikolaev -chardev socket,path=/path/to/socket \ 212603ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 212703ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 212803ce5744SNikolay Nikolaev@end example 212903ce5744SNikolay Nikolaev 2130bb9ea79eSaliguori@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] 2131bb9ea79eSaliguoriDump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). 2132bb9ea79eSaliguoriAt most @var{len} bytes (64k by default) per packet are stored. The file format is 2133bb9ea79eSaliguorilibpcap, so it can be analyzed with tools such as tcpdump or Wireshark. 2134d3e0c032SThomas HuthNote: For devices created with '-netdev', use '-object filter-dump,...' instead. 2135bb9ea79eSaliguori 21365824d651Sblueswir1@item -net none 21375824d651Sblueswir1Indicate that no network devices should be configured. It is used to 21385824d651Sblueswir1override the default configuration (@option{-net nic -net user}) which 21395824d651Sblueswir1is activated if no @option{-net} options are provided. 21405824d651Sblueswir1ETEXI 21415824d651Sblueswir1 2142c70a01e4SMarkus ArmbrusterSTEXI 2143c70a01e4SMarkus Armbruster@end table 2144c70a01e4SMarkus ArmbrusterETEXI 21457273a2dbSMatthew BoothDEFHEADING() 21467273a2dbSMatthew Booth 21477273a2dbSMatthew BoothDEFHEADING(Character device options:) 2148c70a01e4SMarkus ArmbrusterSTEXI 2149c70a01e4SMarkus Armbruster 2150c70a01e4SMarkus ArmbrusterThe general form of a character device option is: 2151c70a01e4SMarkus Armbruster@table @option 2152c70a01e4SMarkus ArmbrusterETEXI 21537273a2dbSMatthew Booth 21547273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2155*517b3d40SLin Ma "-chardev help\n" 2156d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21575dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2158d0d7708bSDaniel P. Berrange " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n" 2159a8fb5427SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n" 2160d0d7708bSDaniel P. Berrange "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n" 2161d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 21627273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 216397331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2164d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2165d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21667273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2167d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2168d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2169d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2170d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21717273a2dbSMatthew Booth#ifdef _WIN32 2172d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2173d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21747273a2dbSMatthew Booth#else 2175d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2176d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 21777273a2dbSMatthew Booth#endif 21787273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2179d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21807273a2dbSMatthew Booth#endif 21817273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 21827273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2183d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2184d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21857273a2dbSMatthew Booth#endif 21867273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2187d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2188d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21897273a2dbSMatthew Booth#endif 2190cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2191d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2192d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2193cbcc6336SAlon Levy#endif 2194ad96090aSBlue Swirl , QEMU_ARCH_ALL 21957273a2dbSMatthew Booth) 21967273a2dbSMatthew Booth 21977273a2dbSMatthew BoothSTEXI 219897331287SJan Kiszka@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}] 21996616b2adSStefan Weil@findex -chardev 22007273a2dbSMatthew BoothBackend is one of: 22017273a2dbSMatthew Booth@option{null}, 22027273a2dbSMatthew Booth@option{socket}, 22037273a2dbSMatthew Booth@option{udp}, 22047273a2dbSMatthew Booth@option{msmouse}, 22057273a2dbSMatthew Booth@option{vc}, 22064f57378fSMarkus Armbruster@option{ringbuf}, 22077273a2dbSMatthew Booth@option{file}, 22087273a2dbSMatthew Booth@option{pipe}, 22097273a2dbSMatthew Booth@option{console}, 22107273a2dbSMatthew Booth@option{serial}, 22117273a2dbSMatthew Booth@option{pty}, 22127273a2dbSMatthew Booth@option{stdio}, 22137273a2dbSMatthew Booth@option{braille}, 22147273a2dbSMatthew Booth@option{tty}, 221588a946d3SGerd Hoffmann@option{parallel}, 2216cbcc6336SAlon Levy@option{parport}, 2217cbcc6336SAlon Levy@option{spicevmc}. 22185a49d3e9SMarc-André Lureau@option{spiceport}. 22197273a2dbSMatthew BoothThe specific backend will determine the applicable options. 22207273a2dbSMatthew Booth 2221*517b3d40SLin MaUse "-chardev help" to print all available chardev backend types. 2222*517b3d40SLin Ma 22237273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 22247273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 22257273a2dbSMatthew Booth 222697331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2227a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2228a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2229a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2230a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2231a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2232a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2233a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2234a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2235a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2236a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2237a40db1b3SPeter Maydell 2238a40db1b3SPeter Maydell@example 2239a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2240a40db1b3SPeter Maydell-mon chardev=char0,mode=readline,default \ 2241a40db1b3SPeter Maydell-serial chardev:char0 \ 2242a40db1b3SPeter Maydell-serial chardev:char0 2243a40db1b3SPeter Maydell@end example 2244a40db1b3SPeter Maydell 2245a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2246a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2247a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2248a40db1b3SPeter Maydell 2249a40db1b3SPeter Maydell@example 2250a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2251a40db1b3SPeter Maydell-mon chardev=char0,mode=readline,default \ 2252a40db1b3SPeter Maydell-parallel chardev:char0 \ 2253a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2254a40db1b3SPeter Maydell-serial chardev:char1 \ 2255a40db1b3SPeter Maydell-serial chardev:char1 2256a40db1b3SPeter Maydell@end example 2257a40db1b3SPeter Maydell 2258a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2259a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2260a40db1b3SPeter Maydellmultiplexer}. 2261a40db1b3SPeter Maydell 2262a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2263a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2264a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2265a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2266a40db1b3SPeter Maydellstdio. 2267a40db1b3SPeter Maydell 2268a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2269a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 227097331287SJan Kiszka 2271d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2272d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2273d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2274d0d7708bSDaniel P. Berrangeopened. 2275d0d7708bSDaniel P. Berrange 2276d0d7708bSDaniel P. BerrangeFurther options to each backend are described below. 22777273a2dbSMatthew Booth 22787273a2dbSMatthew Booth@item -chardev null ,id=@var{id} 22797273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 22807273a2dbSMatthew Boothreceives. The null backend does not take any options. 22817273a2dbSMatthew Booth 2282a8fb5427SDaniel P. Berrange@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}] 22837273a2dbSMatthew Booth 22847273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 22857273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 22867273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 22877273a2dbSMatthew Booth 22887273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 22897273a2dbSMatthew Booth 22907273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 22917273a2dbSMatthew Boothconnect to a listening socket. 22927273a2dbSMatthew Booth 22937273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 22947273a2dbSMatthew Boothescape sequences. 22957273a2dbSMatthew Booth 22965dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 22975dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 22985dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 22995dd1f02bSCorey Minyard 2300a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2301a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2302a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2303a8fb5427SDaniel P. Berrangeargument. 2304a8fb5427SDaniel P. Berrange 23057273a2dbSMatthew BoothTCP and unix socket options are given below: 23067273a2dbSMatthew Booth 23077273a2dbSMatthew Booth@table @option 23087273a2dbSMatthew Booth 23098d533561SAurelien Jarno@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay] 23107273a2dbSMatthew Booth 23117273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 23127273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 23137273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 23147273a2dbSMatthew Booth 23157273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 23167273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 23177273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 23187273a2dbSMatthew Booth@option{port} is required. 23197273a2dbSMatthew Booth 23207273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 23217273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 23227273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 23237273a2dbSMatthew Boothas a port number. 23247273a2dbSMatthew Booth 23257273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 23267273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 23277273a2dbSMatthew Booth 23287273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 23297273a2dbSMatthew Booth 23307273a2dbSMatthew Booth@item unix options: path=@var{path} 23317273a2dbSMatthew Booth 23327273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 23337273a2dbSMatthew Boothrequired. 23347273a2dbSMatthew Booth 23357273a2dbSMatthew Booth@end table 23367273a2dbSMatthew Booth 23377273a2dbSMatthew Booth@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6] 23387273a2dbSMatthew Booth 23397273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 23407273a2dbSMatthew Booth 23417273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 23427273a2dbSMatthew Boothdefaults to @code{localhost}. 23437273a2dbSMatthew Booth 23447273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 23457273a2dbSMatthew Boothis required. 23467273a2dbSMatthew Booth 23477273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 23487273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 23497273a2dbSMatthew Booth 23507273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 23517273a2dbSMatthew Boothavailable local port will be used. 23527273a2dbSMatthew Booth 23537273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 23547273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 23557273a2dbSMatthew Booth 23567273a2dbSMatthew Booth@item -chardev msmouse ,id=@var{id} 23577273a2dbSMatthew Booth 23587273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 23597273a2dbSMatthew Boothtake any options. 23607273a2dbSMatthew Booth 23617273a2dbSMatthew Booth@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]] 23627273a2dbSMatthew Booth 23637273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 23647273a2dbSMatthew Boothsize. 23657273a2dbSMatthew Booth 23667273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 23677273a2dbSMatthew Booththe console, in pixels. 23687273a2dbSMatthew Booth 23697273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 23707273a2dbSMatthew Boothconsole with the given dimensions. 23717273a2dbSMatthew Booth 23724f57378fSMarkus Armbruster@item -chardev ringbuf ,id=@var{id} [,size=@var{size}] 237351767e7cSLei Li 23743949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 23753949e594SMarkus Armbruster@var{size} must be a power of two, and defaults to @code{64K}). 237651767e7cSLei Li 23777273a2dbSMatthew Booth@item -chardev file ,id=@var{id} ,path=@var{path} 23787273a2dbSMatthew Booth 23797273a2dbSMatthew BoothLog all traffic received from the guest to a file. 23807273a2dbSMatthew Booth 23817273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 23827273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 23837273a2dbSMatthew Boothis required. 23847273a2dbSMatthew Booth 23857273a2dbSMatthew Booth@item -chardev pipe ,id=@var{id} ,path=@var{path} 23867273a2dbSMatthew Booth 23877273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 23887273a2dbSMatthew BoothWindows hosts and other hosts: 23897273a2dbSMatthew Booth 23907273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 23917273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 23927273a2dbSMatthew Booth 23937273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 23947273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 23957273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 23967273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 23977273a2dbSMatthew Boothbe present. 23987273a2dbSMatthew Booth 23997273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 24007273a2dbSMatthew Boothrequired. 24017273a2dbSMatthew Booth 24027273a2dbSMatthew Booth@item -chardev console ,id=@var{id} 24037273a2dbSMatthew Booth 24047273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 24057273a2dbSMatthew Boothtake any options. 24067273a2dbSMatthew Booth 24077273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 24087273a2dbSMatthew Booth 24097273a2dbSMatthew Booth@item -chardev serial ,id=@var{id} ,path=@option{path} 24107273a2dbSMatthew Booth 24117273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 24127273a2dbSMatthew Booth 2413d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 2414d59044efSGerd Hoffmannnot only serial lines. 24157273a2dbSMatthew Booth 24167273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 24177273a2dbSMatthew Booth 24187273a2dbSMatthew Booth@item -chardev pty ,id=@var{id} 24197273a2dbSMatthew Booth 24207273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 24217273a2dbSMatthew Boothnot take any options. 24227273a2dbSMatthew Booth 24237273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 24247273a2dbSMatthew Booth 2425b7fdb3abSAurelien Jarno@item -chardev stdio ,id=@var{id} [,signal=on|off] 2426b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 2427b7fdb3abSAurelien Jarno 2428b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 2429b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2430b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 2431b7fdb3abSAurelien Jarno 2432b7fdb3abSAurelien Jarno@option{stdio} is not available on Windows hosts. 24337273a2dbSMatthew Booth 24347273a2dbSMatthew Booth@item -chardev braille ,id=@var{id} 24357273a2dbSMatthew Booth 24367273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 24377273a2dbSMatthew Booth 24387273a2dbSMatthew Booth@item -chardev tty ,id=@var{id} ,path=@var{path} 24397273a2dbSMatthew Booth 24407273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2441d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 24427273a2dbSMatthew Booth 24437273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 24447273a2dbSMatthew Booth 244588a946d3SGerd Hoffmann@item -chardev parallel ,id=@var{id} ,path=@var{path} 2446f9cfd655SMarkus Armbruster@itemx -chardev parport ,id=@var{id} ,path=@var{path} 24477273a2dbSMatthew Booth 244888a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 24497273a2dbSMatthew Booth 24507273a2dbSMatthew BoothConnect to a local parallel port. 24517273a2dbSMatthew Booth 24527273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 24537273a2dbSMatthew Boothrequired. 24547273a2dbSMatthew Booth 2455cbcc6336SAlon Levy@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2456cbcc6336SAlon Levy 24573a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 24583a846906SStefan Hajnoczi 2459cbcc6336SAlon Levy@option{debug} debug level for spicevmc 2460cbcc6336SAlon Levy 2461cbcc6336SAlon Levy@option{name} name of spice channel to connect to 2462cbcc6336SAlon Levy 2463cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 2464cbcc6336SAlon Levy 24655a49d3e9SMarc-André Lureau@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name} 24665a49d3e9SMarc-André Lureau 24675a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 24685a49d3e9SMarc-André Lureau 24695a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 24705a49d3e9SMarc-André Lureau 24715a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 24725a49d3e9SMarc-André Lureau 24735a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 24745a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 24757273a2dbSMatthew BoothETEXI 24767273a2dbSMatthew Booth 2477c70a01e4SMarkus ArmbrusterSTEXI 2478c70a01e4SMarkus Armbruster@end table 2479c70a01e4SMarkus ArmbrusterETEXI 24807273a2dbSMatthew BoothDEFHEADING() 24817273a2dbSMatthew Booth 24820f5314a2SRonnie SahlbergDEFHEADING(Device URL Syntax:) 2483c70a01e4SMarkus ArmbrusterSTEXI 24840f5314a2SRonnie Sahlberg 24850f5314a2SRonnie SahlbergIn addition to using normal file images for the emulated storage devices, 24860f5314a2SRonnie SahlbergQEMU can also use networked resources such as iSCSI devices. These are 24870f5314a2SRonnie Sahlbergspecified using a special URL syntax. 24880f5314a2SRonnie Sahlberg 24890f5314a2SRonnie Sahlberg@table @option 24900f5314a2SRonnie Sahlberg@item iSCSI 24910f5314a2SRonnie SahlbergiSCSI support allows QEMU to access iSCSI resources directly and use as 24920f5314a2SRonnie Sahlbergimages for the guest storage. Both disk and cdrom images are supported. 24930f5314a2SRonnie Sahlberg 24940f5314a2SRonnie SahlbergSyntax for specifying iSCSI LUNs is 24950f5314a2SRonnie Sahlberg``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' 24960f5314a2SRonnie Sahlberg 249731459f46SRonnie SahlbergBy default qemu will use the iSCSI initiator-name 249831459f46SRonnie Sahlberg'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command 249931459f46SRonnie Sahlbergline or a configuration file. 250031459f46SRonnie Sahlberg 25015dd7a535SPeter LievenSince version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect 25025dd7a535SPeter Lievenstalled requests and force a reestablishment of the session. The timeout 25039049736eSPeter Lievenis specified in seconds. The default is 0 which means no timeout. Libiscsi 25049049736eSPeter Lieven1.15.0 or greater is required for this feature. 250531459f46SRonnie Sahlberg 25060f5314a2SRonnie SahlbergExample (without authentication): 25070f5314a2SRonnie Sahlberg@example 25083804da9dSStefan Weilqemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ 2509f9dadc98SRonnie Sahlberg -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ 2510f9dadc98SRonnie Sahlberg -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 25110f5314a2SRonnie Sahlberg@end example 25120f5314a2SRonnie Sahlberg 25130f5314a2SRonnie SahlbergExample (CHAP username/password via URL): 25140f5314a2SRonnie Sahlberg@example 25153804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 25160f5314a2SRonnie Sahlberg@end example 25170f5314a2SRonnie Sahlberg 25180f5314a2SRonnie SahlbergExample (CHAP username/password via environment variables): 25190f5314a2SRonnie Sahlberg@example 25200f5314a2SRonnie SahlbergLIBISCSI_CHAP_USERNAME="user" \ 25210f5314a2SRonnie SahlbergLIBISCSI_CHAP_PASSWORD="password" \ 25223804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 25230f5314a2SRonnie Sahlberg@end example 25240f5314a2SRonnie Sahlberg 25250f5314a2SRonnie SahlbergiSCSI support is an optional feature of QEMU and only available when 25260f5314a2SRonnie Sahlbergcompiled and linked against libiscsi. 2527f9dadc98SRonnie SahlbergETEXI 2528f9dadc98SRonnie SahlbergDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2529f9dadc98SRonnie Sahlberg "-iscsi [user=user][,password=password]\n" 2530f9dadc98SRonnie Sahlberg " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 25312fe3798cSPaolo Bonzini " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 25325dd7a535SPeter Lieven " [,timeout=timeout]\n" 2533f9dadc98SRonnie Sahlberg " iSCSI session parameters\n", QEMU_ARCH_ALL) 2534f9dadc98SRonnie SahlbergSTEXI 25350f5314a2SRonnie Sahlberg 253631459f46SRonnie SahlbergiSCSI parameters such as username and password can also be specified via 253731459f46SRonnie Sahlberga configuration file. See qemu-doc for more information and examples. 253831459f46SRonnie Sahlberg 253908ae330eSRonnie Sahlberg@item NBD 254008ae330eSRonnie SahlbergQEMU supports NBD (Network Block Devices) both using TCP protocol as well 254108ae330eSRonnie Sahlbergas Unix Domain Sockets. 254208ae330eSRonnie Sahlberg 254308ae330eSRonnie SahlbergSyntax for specifying a NBD device using TCP 254408ae330eSRonnie Sahlberg``nbd:<server-ip>:<port>[:exportname=<export>]'' 254508ae330eSRonnie Sahlberg 254608ae330eSRonnie SahlbergSyntax for specifying a NBD device using Unix Domain Sockets 254708ae330eSRonnie Sahlberg``nbd:unix:<domain-socket>[:exportname=<export>]'' 254808ae330eSRonnie Sahlberg 254908ae330eSRonnie Sahlberg 255008ae330eSRonnie SahlbergExample for TCP 255108ae330eSRonnie Sahlberg@example 25523804da9dSStefan Weilqemu-system-i386 --drive file=nbd:192.0.2.1:30000 255308ae330eSRonnie Sahlberg@end example 255408ae330eSRonnie Sahlberg 255508ae330eSRonnie SahlbergExample for Unix Domain Sockets 255608ae330eSRonnie Sahlberg@example 25573804da9dSStefan Weilqemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket 255808ae330eSRonnie Sahlberg@end example 255908ae330eSRonnie Sahlberg 25600a12ec87SRichard W.M. Jones@item SSH 25610a12ec87SRichard W.M. JonesQEMU supports SSH (Secure Shell) access to remote disks. 25620a12ec87SRichard W.M. Jones 25630a12ec87SRichard W.M. JonesExamples: 25640a12ec87SRichard W.M. Jones@example 25650a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img 25660a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img 25670a12ec87SRichard W.M. Jones@end example 25680a12ec87SRichard W.M. Jones 25690a12ec87SRichard W.M. JonesCurrently authentication must be done using ssh-agent. Other 25700a12ec87SRichard W.M. Jonesauthentication methods may be supported in future. 25710a12ec87SRichard W.M. Jones 2572d9990228SRonnie Sahlberg@item Sheepdog 2573d9990228SRonnie SahlbergSheepdog is a distributed storage system for QEMU. 2574d9990228SRonnie SahlbergQEMU supports using either local sheepdog devices or remote networked 2575d9990228SRonnie Sahlbergdevices. 2576d9990228SRonnie Sahlberg 2577d9990228SRonnie SahlbergSyntax for specifying a sheepdog device 25785d6768e3SMORITA Kazutaka@example 25791b8bbb46SMORITA Kazutakasheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] 25805d6768e3SMORITA Kazutaka@end example 2581d9990228SRonnie Sahlberg 2582d9990228SRonnie SahlbergExample 2583d9990228SRonnie Sahlberg@example 25845d6768e3SMORITA Kazutakaqemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine 2585d9990228SRonnie Sahlberg@end example 2586d9990228SRonnie Sahlberg 2587d9990228SRonnie SahlbergSee also @url{http://http://www.osrg.net/sheepdog/}. 2588d9990228SRonnie Sahlberg 25898809e289SBharata B Rao@item GlusterFS 25908809e289SBharata B RaoGlusterFS is an user space distributed file system. 25918809e289SBharata B RaoQEMU supports the use of GlusterFS volumes for hosting VM disk images using 25928809e289SBharata B RaoTCP, Unix Domain Sockets and RDMA transport protocols. 25938809e289SBharata B Rao 25948809e289SBharata B RaoSyntax for specifying a VM disk image on GlusterFS volume is 25958809e289SBharata B Rao@example 25968809e289SBharata B Raogluster[+transport]://[server[:port]]/volname/image[?socket=...] 25978809e289SBharata B Rao@end example 25988809e289SBharata B Rao 25998809e289SBharata B Rao 26008809e289SBharata B RaoExample 26018809e289SBharata B Rao@example 2602db2d5ebaSLei Liqemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img 26038809e289SBharata B Rao@end example 26048809e289SBharata B Rao 26058809e289SBharata B RaoSee also @url{http://www.gluster.org}. 26060a86cb73SMatthew Booth 26070a86cb73SMatthew Booth@item HTTP/HTTPS/FTP/FTPS/TFTP 26080a86cb73SMatthew BoothQEMU supports read-only access to files accessed over http(s), ftp(s) and tftp. 26090a86cb73SMatthew Booth 26100a86cb73SMatthew BoothSyntax using a single filename: 26110a86cb73SMatthew Booth@example 26120a86cb73SMatthew Booth<protocol>://[<username>[:<password>]@@]<host>/<path> 26130a86cb73SMatthew Booth@end example 26140a86cb73SMatthew Booth 26150a86cb73SMatthew Boothwhere: 26160a86cb73SMatthew Booth@table @option 26170a86cb73SMatthew Booth@item protocol 26180a86cb73SMatthew Booth'http', 'https', 'ftp', 'ftps', or 'tftp'. 26190a86cb73SMatthew Booth 26200a86cb73SMatthew Booth@item username 26210a86cb73SMatthew BoothOptional username for authentication to the remote server. 26220a86cb73SMatthew Booth 26230a86cb73SMatthew Booth@item password 26240a86cb73SMatthew BoothOptional password for authentication to the remote server. 26250a86cb73SMatthew Booth 26260a86cb73SMatthew Booth@item host 26270a86cb73SMatthew BoothAddress of the remote server. 26280a86cb73SMatthew Booth 26290a86cb73SMatthew Booth@item path 26300a86cb73SMatthew BoothPath on the remote server, including any query string. 26310a86cb73SMatthew Booth@end table 26320a86cb73SMatthew Booth 26330a86cb73SMatthew BoothThe following options are also supported: 26340a86cb73SMatthew Booth@table @option 26350a86cb73SMatthew Booth@item url 26360a86cb73SMatthew BoothThe full URL when passing options to the driver explicitly. 26370a86cb73SMatthew Booth 26380a86cb73SMatthew Booth@item readahead 26390a86cb73SMatthew BoothThe amount of data to read ahead with each range request to the remote server. 26400a86cb73SMatthew BoothThis value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it 26410a86cb73SMatthew Boothdoes not have a suffix, it will be assumed to be in bytes. The value must be a 26420a86cb73SMatthew Boothmultiple of 512 bytes. It defaults to 256k. 26430a86cb73SMatthew Booth 26440a86cb73SMatthew Booth@item sslverify 26450a86cb73SMatthew BoothWhether to verify the remote server's certificate when connecting over SSL. It 26460a86cb73SMatthew Boothcan have the value 'on' or 'off'. It defaults to 'on'. 2647212aefaaSDaniel Henrique Barboza 2648a94f83d9SRichard W.M. Jones@item cookie 2649a94f83d9SRichard W.M. JonesSend this cookie (it can also be a list of cookies separated by ';') with 2650a94f83d9SRichard W.M. Joneseach outgoing request. Only supported when using protocols such as HTTP 2651a94f83d9SRichard W.M. Joneswhich support cookies, otherwise ignored. 2652a94f83d9SRichard W.M. Jones 2653212aefaaSDaniel Henrique Barboza@item timeout 2654212aefaaSDaniel Henrique BarbozaSet the timeout in seconds of the CURL connection. This timeout is the time 2655212aefaaSDaniel Henrique Barbozathat CURL waits for a response from the remote server to get the size of the 2656212aefaaSDaniel Henrique Barbozaimage to be downloaded. If not set, the default timeout of 5 seconds is used. 26570a86cb73SMatthew Booth@end table 26580a86cb73SMatthew Booth 26590a86cb73SMatthew BoothNote that when passing options to qemu explicitly, @option{driver} is the value 26600a86cb73SMatthew Boothof <protocol>. 26610a86cb73SMatthew Booth 26620a86cb73SMatthew BoothExample: boot from a remote Fedora 20 live ISO image 26630a86cb73SMatthew Booth@example 26640a86cb73SMatthew Boothqemu-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 26650a86cb73SMatthew Booth 26660a86cb73SMatthew Boothqemu-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 26670a86cb73SMatthew Booth@end example 26680a86cb73SMatthew Booth 26690a86cb73SMatthew BoothExample: boot from a remote Fedora 20 cloud image using a local overlay for 26700a86cb73SMatthew Boothwrites, copy-on-read, and a readahead of 64k 26710a86cb73SMatthew Booth@example 26720a86cb73SMatthew Boothqemu-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 26730a86cb73SMatthew Booth 26740a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on 26750a86cb73SMatthew Booth@end example 26760a86cb73SMatthew Booth 26770a86cb73SMatthew BoothExample: boot from an image stored on a VMware vSphere server with a self-signed 2678212aefaaSDaniel Henrique Barbozacertificate using a local overlay for writes, a readahead of 64k and a timeout 2679212aefaaSDaniel Henrique Barbozaof 10 seconds. 26800a86cb73SMatthew Booth@example 2681212aefaaSDaniel Henrique Barbozaqemu-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 26820a86cb73SMatthew Booth 26830a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/test.qcow2 26840a86cb73SMatthew Booth@end example 2685c70a01e4SMarkus ArmbrusterETEXI 2686c70a01e4SMarkus Armbruster 2687c70a01e4SMarkus ArmbrusterSTEXI 26880f5314a2SRonnie Sahlberg@end table 26890f5314a2SRonnie SahlbergETEXI 26900f5314a2SRonnie Sahlberg 26917273a2dbSMatthew BoothDEFHEADING(Bluetooth(R) options:) 2692c70a01e4SMarkus ArmbrusterSTEXI 2693c70a01e4SMarkus Armbruster@table @option 2694c70a01e4SMarkus ArmbrusterETEXI 26957273a2dbSMatthew Booth 26965824d651Sblueswir1DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 26975824d651Sblueswir1 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 26985824d651Sblueswir1 "-bt hci,host[:id]\n" \ 26995824d651Sblueswir1 " use host's HCI with the given name\n" \ 27005824d651Sblueswir1 "-bt hci[,vlan=n]\n" \ 27015824d651Sblueswir1 " emulate a standard HCI in virtual scatternet 'n'\n" \ 27025824d651Sblueswir1 "-bt vhci[,vlan=n]\n" \ 27035824d651Sblueswir1 " add host computer to virtual scatternet 'n' using VHCI\n" \ 27045824d651Sblueswir1 "-bt device:dev[,vlan=n]\n" \ 2705ad96090aSBlue Swirl " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2706ad96090aSBlue Swirl QEMU_ARCH_ALL) 27075824d651Sblueswir1STEXI 27085824d651Sblueswir1@item -bt hci[...] 27096616b2adSStefan Weil@findex -bt 27105824d651Sblueswir1Defines the function of the corresponding Bluetooth HCI. -bt options 27115824d651Sblueswir1are matched with the HCIs present in the chosen machine type. For 27125824d651Sblueswir1example when emulating a machine with only one HCI built into it, only 27135824d651Sblueswir1the first @code{-bt hci[...]} option is valid and defines the HCI's 27145824d651Sblueswir1logic. The Transport Layer is decided by the machine type. Currently 27155824d651Sblueswir1the machines @code{n800} and @code{n810} have one HCI and all other 27165824d651Sblueswir1machines have none. 27175824d651Sblueswir1 27185824d651Sblueswir1@anchor{bt-hcis} 27195824d651Sblueswir1The following three types are recognized: 27205824d651Sblueswir1 2721b3f046c2SKevin Wolf@table @option 27225824d651Sblueswir1@item -bt hci,null 27235824d651Sblueswir1(default) The corresponding Bluetooth HCI assumes no internal logic 27245824d651Sblueswir1and will not respond to any HCI commands or emit events. 27255824d651Sblueswir1 27265824d651Sblueswir1@item -bt hci,host[:@var{id}] 27275824d651Sblueswir1(@code{bluez} only) The corresponding HCI passes commands / events 27285824d651Sblueswir1to / from the physical HCI identified by the name @var{id} (default: 27295824d651Sblueswir1@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 27305824d651Sblueswir1capable systems like Linux. 27315824d651Sblueswir1 27325824d651Sblueswir1@item -bt hci[,vlan=@var{n}] 27335824d651Sblueswir1Add a virtual, standard HCI that will participate in the Bluetooth 27345824d651Sblueswir1scatternet @var{n} (default @code{0}). Similarly to @option{-net} 27355824d651Sblueswir1VLANs, devices inside a bluetooth network @var{n} can only communicate 27365824d651Sblueswir1with other devices in the same network (scatternet). 27375824d651Sblueswir1@end table 27385824d651Sblueswir1 27395824d651Sblueswir1@item -bt vhci[,vlan=@var{n}] 27405824d651Sblueswir1(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 27415824d651Sblueswir1to the host bluetooth stack instead of to the emulated target. This 27425824d651Sblueswir1allows the host and target machines to participate in a common scatternet 27435824d651Sblueswir1and communicate. Requires the Linux @code{vhci} driver installed. Can 27445824d651Sblueswir1be used as following: 27455824d651Sblueswir1 27465824d651Sblueswir1@example 27473804da9dSStefan Weilqemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 27485824d651Sblueswir1@end example 27495824d651Sblueswir1 27505824d651Sblueswir1@item -bt device:@var{dev}[,vlan=@var{n}] 27515824d651Sblueswir1Emulate a bluetooth device @var{dev} and place it in network @var{n} 27525824d651Sblueswir1(default @code{0}). QEMU can only emulate one type of bluetooth devices 27535824d651Sblueswir1currently: 27545824d651Sblueswir1 2755b3f046c2SKevin Wolf@table @option 27565824d651Sblueswir1@item keyboard 27575824d651Sblueswir1Virtual wireless keyboard implementing the HIDP bluetooth profile. 27585824d651Sblueswir1@end table 27595824d651Sblueswir1ETEXI 27605824d651Sblueswir1 2761c70a01e4SMarkus ArmbrusterSTEXI 2762c70a01e4SMarkus Armbruster@end table 2763c70a01e4SMarkus ArmbrusterETEXI 27645824d651Sblueswir1DEFHEADING() 27655824d651Sblueswir1 2766d1a0cf73SStefan Berger#ifdef CONFIG_TPM 2767d1a0cf73SStefan BergerDEFHEADING(TPM device options:) 2768d1a0cf73SStefan Berger 2769d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 277092dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 277192dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 277292dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 277392dcc234SStefan Berger " not provided it will be searched for in /sys/class/misc/tpm?/device\n", 2774d1a0cf73SStefan Berger QEMU_ARCH_ALL) 2775d1a0cf73SStefan BergerSTEXI 2776d1a0cf73SStefan Berger 2777d1a0cf73SStefan BergerThe general form of a TPM device option is: 2778d1a0cf73SStefan Berger@table @option 2779d1a0cf73SStefan Berger 2780d1a0cf73SStefan Berger@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] 2781d1a0cf73SStefan Berger@findex -tpmdev 2782d1a0cf73SStefan BergerBackend type must be: 27834549a8b7SStefan Berger@option{passthrough}. 2784d1a0cf73SStefan Berger 2785d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 278628c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 278728c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 2788d1a0cf73SStefan Berger 2789d1a0cf73SStefan BergerOptions to each backend are described below. 2790d1a0cf73SStefan Berger 2791d1a0cf73SStefan BergerUse 'help' to print all available TPM backend types. 2792d1a0cf73SStefan Berger@example 2793d1a0cf73SStefan Bergerqemu -tpmdev help 2794d1a0cf73SStefan Berger@end example 2795d1a0cf73SStefan Berger 279692dcc234SStefan Berger@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path} 27974549a8b7SStefan Berger 27984549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 27994549a8b7SStefan Bergerdriver. 28004549a8b7SStefan Berger 28014549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 28024549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 28034549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 28044549a8b7SStefan Berger 280592dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 280692dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 280792dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 280892dcc234SStefan Bergersysfs entry to use. 280992dcc234SStefan Berger 28104549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 28114549a8b7SStefan Berger 28124549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 28134549a8b7SStefan Bergerused by any other application on the host. 28144549a8b7SStefan Berger 28154549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 28164549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 28174549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 28184549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 28194549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 28204549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 28214549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 28224549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 28234549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 28244549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 28254549a8b7SStefan Berger 28264549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 28274549a8b7SStefan Berger@example 28284549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 28294549a8b7SStefan Berger@end example 28304549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 28314549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 28324549a8b7SStefan Berger 2833d1a0cf73SStefan Berger@end table 2834d1a0cf73SStefan Berger 2835d1a0cf73SStefan BergerETEXI 2836d1a0cf73SStefan Berger 2837d1a0cf73SStefan BergerDEFHEADING() 2838d1a0cf73SStefan Berger 2839d1a0cf73SStefan Berger#endif 2840d1a0cf73SStefan Berger 28417677f05dSAlexander GrafDEFHEADING(Linux/Multiboot boot specific:) 28425824d651Sblueswir1STEXI 28437677f05dSAlexander Graf 28447677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 28457677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 28465824d651Sblueswir1for easier testing of various kernels. 28475824d651Sblueswir1 28485824d651Sblueswir1@table @option 28495824d651Sblueswir1ETEXI 28505824d651Sblueswir1 28515824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2852ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 28535824d651Sblueswir1STEXI 28545824d651Sblueswir1@item -kernel @var{bzImage} 28556616b2adSStefan Weil@findex -kernel 28567677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 28577677f05dSAlexander Grafor in multiboot format. 28585824d651Sblueswir1ETEXI 28595824d651Sblueswir1 28605824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 2861ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 28625824d651Sblueswir1STEXI 28635824d651Sblueswir1@item -append @var{cmdline} 28646616b2adSStefan Weil@findex -append 28655824d651Sblueswir1Use @var{cmdline} as kernel command line 28665824d651Sblueswir1ETEXI 28675824d651Sblueswir1 28685824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 2869ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 28705824d651Sblueswir1STEXI 28715824d651Sblueswir1@item -initrd @var{file} 28726616b2adSStefan Weil@findex -initrd 28735824d651Sblueswir1Use @var{file} as initial ram disk. 28747677f05dSAlexander Graf 28757677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 28767677f05dSAlexander Graf 28777677f05dSAlexander GrafThis syntax is only available with multiboot. 28787677f05dSAlexander Graf 28797677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 28807677f05dSAlexander Graffirst module. 28815824d651Sblueswir1ETEXI 28825824d651Sblueswir1 2883412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 2884379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 2885412beee6SGrant LikelySTEXI 2886412beee6SGrant Likely@item -dtb @var{file} 2887412beee6SGrant Likely@findex -dtb 2888412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 2889412beee6SGrant Likelyon boot. 2890412beee6SGrant LikelyETEXI 2891412beee6SGrant Likely 28925824d651Sblueswir1STEXI 28935824d651Sblueswir1@end table 28945824d651Sblueswir1ETEXI 28955824d651Sblueswir1DEFHEADING() 28965824d651Sblueswir1 28975824d651Sblueswir1DEFHEADING(Debug/Expert options:) 28985824d651Sblueswir1STEXI 28995824d651Sblueswir1@table @option 29005824d651Sblueswir1ETEXI 29015824d651Sblueswir1 290281b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 290381b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 290463d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 29056407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 290663d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 290781b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 290881b2b810SGabriel L. SomloSTEXI 290963d3145aSMarkus Armbruster 291081b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 291181b2b810SGabriel L. Somlo@findex -fw_cfg 291263d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 29136407d76eSGabriel L. Somlo 29146407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 291563d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 291663d3145aSMarkus Armbruster 291763d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 291863d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 291963d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 292063d3145aSMarkus Armbruster 292163d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 292263d3145aSMarkus Armbruster 292363d3145aSMarkus ArmbrusterExample: 292463d3145aSMarkus Armbruster@example 292563d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 292663d3145aSMarkus Armbruster@end example 292763d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 292863d3145aSMarkus Armbrusterfrom ./my_blob.bin. 292963d3145aSMarkus Armbruster 293081b2b810SGabriel L. SomloETEXI 293181b2b810SGabriel L. Somlo 29325824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 2933ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 2934ad96090aSBlue Swirl QEMU_ARCH_ALL) 29355824d651Sblueswir1STEXI 29365824d651Sblueswir1@item -serial @var{dev} 29376616b2adSStefan Weil@findex -serial 29385824d651Sblueswir1Redirect the virtual serial port to host character device 29395824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 29405824d651Sblueswir1@code{stdio} in non graphical mode. 29415824d651Sblueswir1 29425824d651Sblueswir1This option can be used several times to simulate up to 4 serial 29435824d651Sblueswir1ports. 29445824d651Sblueswir1 29455824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 29465824d651Sblueswir1 29475824d651Sblueswir1Available character devices are: 2948b3f046c2SKevin Wolf@table @option 29494e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 29505824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 29515824d651Sblueswir1@example 29525824d651Sblueswir1vc:800x600 29535824d651Sblueswir1@end example 29545824d651Sblueswir1It is also possible to specify width or height in characters: 29555824d651Sblueswir1@example 29565824d651Sblueswir1vc:80Cx24C 29575824d651Sblueswir1@end example 29585824d651Sblueswir1@item pty 29595824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 29605824d651Sblueswir1@item none 29615824d651Sblueswir1No device is allocated. 29625824d651Sblueswir1@item null 29635824d651Sblueswir1void device 296488e020e5SIngo van Lil@item chardev:@var{id} 296588e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 29665824d651Sblueswir1@item /dev/XXX 29675824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 29685824d651Sblueswir1parameters are set according to the emulated ones. 29695824d651Sblueswir1@item /dev/parport@var{N} 29705824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 29715824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 29725824d651Sblueswir1@item file:@var{filename} 29735824d651Sblueswir1Write output to @var{filename}. No character can be read. 29745824d651Sblueswir1@item stdio 29755824d651Sblueswir1[Unix only] standard input/output 29765824d651Sblueswir1@item pipe:@var{filename} 29775824d651Sblueswir1name pipe @var{filename} 29785824d651Sblueswir1@item COM@var{n} 29795824d651Sblueswir1[Windows only] Use host serial port @var{n} 29805824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 29815824d651Sblueswir1This implements UDP Net Console. 29825824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 29835824d651Sblueswir1they default to @code{0.0.0.0}. 29845824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 29855824d651Sblueswir1 29865824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 2987b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 2988b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 29895824d651Sblueswir1will appear in the netconsole session. 29905824d651Sblueswir1 29915824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 2992b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 29935824d651Sblueswir1source port each time by using something like @code{-serial 2994b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 29955824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 29965824d651Sblueswir1characters via udp. If you have a patched version of netcat which 29975824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 29985824d651Sblueswir1use the following options to step up a netcat redirector to allow 2999b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 30005824d651Sblueswir1@table @code 3001071c9394SStefan Weil@item QEMU Options: 30025824d651Sblueswir1-serial udp::4555@@:4556 30035824d651Sblueswir1@item netcat options: 30045824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 30055824d651Sblueswir1@item telnet options: 30065824d651Sblueswir1localhost 5555 30075824d651Sblueswir1@end table 30085824d651Sblueswir1 30095dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 30105824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 30115824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 30125824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 30135824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 30145824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 30155824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 30165dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 30175dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 30185dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 30195824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 30205824d651Sblueswir1connect to the corresponding character device. 30215824d651Sblueswir1@table @code 30225824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 30235824d651Sblueswir1-serial tcp:192.168.0.2:4444 30245824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 30255824d651Sblueswir1-serial tcp::4444,server 30265824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 30275824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 30285824d651Sblueswir1@end table 30295824d651Sblueswir1 30305824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 30315824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 30325824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 30335824d651Sblueswir1difference is that the port acts like a telnet server or client using 30345824d651Sblueswir1telnet option negotiation. This will also allow you to send the 30355824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 30365824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 30375824d651Sblueswir1type "send break" followed by pressing the enter key. 30385824d651Sblueswir1 30395dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 30405824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 30415824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 30425824d651Sblueswir1@var{path} is used for connections. 30435824d651Sblueswir1 30445824d651Sblueswir1@item mon:@var{dev_string} 30455824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 30465824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 304702c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 30485824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 30495824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 30505824d651Sblueswir1listening on port 4444 would be: 30515824d651Sblueswir1@table @code 30525824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 30535824d651Sblueswir1@end table 3054be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 305502c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 30565824d651Sblueswir1 30575824d651Sblueswir1@item braille 30585824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 30595824d651Sblueswir1or fake device. 30605824d651Sblueswir1 3061be8b28a9SKevin Wolf@item msmouse 3062be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 30635824d651Sblueswir1@end table 30645824d651Sblueswir1ETEXI 30655824d651Sblueswir1 30665824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3067ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3068ad96090aSBlue Swirl QEMU_ARCH_ALL) 30695824d651Sblueswir1STEXI 30705824d651Sblueswir1@item -parallel @var{dev} 30716616b2adSStefan Weil@findex -parallel 30725824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 30735824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 30745824d651Sblueswir1be used to use hardware devices connected on the corresponding host 30755824d651Sblueswir1parallel port. 30765824d651Sblueswir1 30775824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 30785824d651Sblueswir1ports. 30795824d651Sblueswir1 30805824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 30815824d651Sblueswir1ETEXI 30825824d651Sblueswir1 30835824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3084ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3085ad96090aSBlue Swirl QEMU_ARCH_ALL) 30865824d651Sblueswir1STEXI 30874e307fc8SGerd Hoffmann@item -monitor @var{dev} 30886616b2adSStefan Weil@findex -monitor 30895824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 30905824d651Sblueswir1serial port). 30915824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 30925824d651Sblueswir1non graphical mode. 309370e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 30945824d651Sblueswir1ETEXI 30956ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3096ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3097ad96090aSBlue Swirl QEMU_ARCH_ALL) 309895d5f08bSStefan WeilSTEXI 309995d5f08bSStefan Weil@item -qmp @var{dev} 31006616b2adSStefan Weil@findex -qmp 310195d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 310295d5f08bSStefan WeilETEXI 31034821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 31044821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 31054821cd4cSMax Reitz QEMU_ARCH_ALL) 31064821cd4cSMax ReitzSTEXI 31074821cd4cSMax Reitz@item -qmp-pretty @var{dev} 31084821cd4cSMax Reitz@findex -qmp-pretty 31094821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 31104821cd4cSMax ReitzETEXI 31115824d651Sblueswir1 311222a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3113f17e4eaaSMichael Tokarev "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL) 311422a0e04bSGerd HoffmannSTEXI 3115f17e4eaaSMichael Tokarev@item -mon [chardev=]name[,mode=readline|control][,default] 31166616b2adSStefan Weil@findex -mon 311722a0e04bSGerd HoffmannSetup monitor on chardev @var{name}. 311822a0e04bSGerd HoffmannETEXI 311922a0e04bSGerd Hoffmann 3120c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3121ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3122ad96090aSBlue Swirl QEMU_ARCH_ALL) 3123c9f398e5SH. Peter AnvinSTEXI 3124c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 31256616b2adSStefan Weil@findex -debugcon 3126c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3127c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3128c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3129c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3130c9f398e5SH. Peter Anvinnon graphical mode. 3131c9f398e5SH. Peter AnvinETEXI 3132c9f398e5SH. Peter Anvin 31335824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3134ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 31355824d651Sblueswir1STEXI 31365824d651Sblueswir1@item -pidfile @var{file} 31376616b2adSStefan Weil@findex -pidfile 31385824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 31395824d651Sblueswir1from a script. 31405824d651Sblueswir1ETEXI 31415824d651Sblueswir1 31421b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3143ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 31441b530a6dSaurel32STEXI 31451b530a6dSaurel32@item -singlestep 31466616b2adSStefan Weil@findex -singlestep 31471b530a6dSaurel32Run the emulation in single step mode. 31481b530a6dSaurel32ETEXI 31491b530a6dSaurel32 31505824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3151ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3152ad96090aSBlue Swirl QEMU_ARCH_ALL) 31535824d651Sblueswir1STEXI 31545824d651Sblueswir1@item -S 31556616b2adSStefan Weil@findex -S 31565824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 31575824d651Sblueswir1ETEXI 31585824d651Sblueswir1 3159888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3160888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3161888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3162888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3163888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3164888a6bc6SSatoru MoriyaSTEXI 3165888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3166888a6bc6SSatoru Moriya@findex -realtime 3167888a6bc6SSatoru MoriyaRun qemu with realtime features. 3168888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3169888a6bc6SSatoru Moriya(enabled by default). 3170888a6bc6SSatoru MoriyaETEXI 3171888a6bc6SSatoru Moriya 317259030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3173ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 31745824d651Sblueswir1STEXI 317559030a8cSaliguori@item -gdb @var{dev} 31766616b2adSStefan Weil@findex -gdb 317759030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 317859030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3179b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 318059030a8cSaliguoriwithin gdb and establish the connection via a pipe: 318159030a8cSaliguori@example 31823804da9dSStefan Weil(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 318359030a8cSaliguori@end example 31845824d651Sblueswir1ETEXI 31855824d651Sblueswir1 318659030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3187ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3188ad96090aSBlue Swirl QEMU_ARCH_ALL) 31895824d651Sblueswir1STEXI 319059030a8cSaliguori@item -s 31916616b2adSStefan Weil@findex -s 319259030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 319359030a8cSaliguori(@pxref{gdb_usage}). 31945824d651Sblueswir1ETEXI 31955824d651Sblueswir1 31965824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3197989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3198ad96090aSBlue Swirl QEMU_ARCH_ALL) 31995824d651Sblueswir1STEXI 3200989b697dSPeter Maydell@item -d @var{item1}[,...] 32016616b2adSStefan Weil@findex -d 3202989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 32035824d651Sblueswir1ETEXI 32045824d651Sblueswir1 3205c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3206989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3207c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3208c235d738SMatthew FernandezSTEXI 32098bd383b4SStefan Weil@item -D @var{logfile} 3210c235d738SMatthew Fernandez@findex -D 3211989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3212c235d738SMatthew FernandezETEXI 3213c235d738SMatthew Fernandez 32143514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 32153514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 32163514552eSAlex Bennée QEMU_ARCH_ALL) 32173514552eSAlex BennéeSTEXI 32183514552eSAlex Bennée@item -dfilter @var{range1}[,...] 32193514552eSAlex Bennée@findex -dfilter 32203514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 32213514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 32223514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 32233514552eSAlex Bennéeaddresses and sizes required. For example: 32243514552eSAlex Bennée@example 32253514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 32263514552eSAlex Bennée@end example 32273514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 32283514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 32293514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 32303514552eSAlex BennéeETEXI 32313514552eSAlex Bennée 32325824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3233ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3234ad96090aSBlue Swirl QEMU_ARCH_ALL) 32355824d651Sblueswir1STEXI 32365824d651Sblueswir1@item -L @var{path} 32376616b2adSStefan Weil@findex -L 32385824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 323937146e7eSRichard W.M. Jones 324037146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 32415824d651Sblueswir1ETEXI 32425824d651Sblueswir1 32435824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3244ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 32455824d651Sblueswir1STEXI 32465824d651Sblueswir1@item -bios @var{file} 32476616b2adSStefan Weil@findex -bios 32485824d651Sblueswir1Set the filename for the BIOS. 32495824d651Sblueswir1ETEXI 32505824d651Sblueswir1 32515824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3252ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 32535824d651Sblueswir1STEXI 32545824d651Sblueswir1@item -enable-kvm 32556616b2adSStefan Weil@findex -enable-kvm 32565824d651Sblueswir1Enable KVM full virtualization support. This option is only available 32575824d651Sblueswir1if KVM support is enabled when compiling. 32585824d651Sblueswir1ETEXI 32595824d651Sblueswir1 3260e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3261ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3262e37630caSaliguoriDEF("xen-create", 0, QEMU_OPTION_xen_create, 3263e37630caSaliguori "-xen-create create domain using xen hypercalls, bypassing xend\n" 3264ad96090aSBlue Swirl " warning: should not be used when xend is in use\n", 3265ad96090aSBlue Swirl QEMU_ARCH_ALL) 3266e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3267e37630caSaliguori "-xen-attach attach to existing xen domain\n" 3268b65ee4faSStefan Weil " xend will use this when starting QEMU\n", 3269ad96090aSBlue Swirl QEMU_ARCH_ALL) 327095d5f08bSStefan WeilSTEXI 327195d5f08bSStefan Weil@item -xen-domid @var{id} 32726616b2adSStefan Weil@findex -xen-domid 327395d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 327495d5f08bSStefan Weil@item -xen-create 32756616b2adSStefan Weil@findex -xen-create 327695d5f08bSStefan WeilCreate domain using xen hypercalls, bypassing xend. 327795d5f08bSStefan WeilWarning: should not be used when xend is in use (XEN only). 327895d5f08bSStefan Weil@item -xen-attach 32796616b2adSStefan Weil@findex -xen-attach 328095d5f08bSStefan WeilAttach to existing xen domain. 3281b65ee4faSStefan Weilxend will use this when starting QEMU (XEN only). 328295d5f08bSStefan WeilETEXI 3283e37630caSaliguori 32845824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3285ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 32865824d651Sblueswir1STEXI 32875824d651Sblueswir1@item -no-reboot 32886616b2adSStefan Weil@findex -no-reboot 32895824d651Sblueswir1Exit instead of rebooting. 32905824d651Sblueswir1ETEXI 32915824d651Sblueswir1 32925824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3293ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 32945824d651Sblueswir1STEXI 32955824d651Sblueswir1@item -no-shutdown 32966616b2adSStefan Weil@findex -no-shutdown 32975824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 32985824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 32995824d651Sblueswir1disk image. 33005824d651Sblueswir1ETEXI 33015824d651Sblueswir1 33025824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 33035824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3304ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3305ad96090aSBlue Swirl QEMU_ARCH_ALL) 33065824d651Sblueswir1STEXI 33075824d651Sblueswir1@item -loadvm @var{file} 33086616b2adSStefan Weil@findex -loadvm 33095824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 33105824d651Sblueswir1ETEXI 33115824d651Sblueswir1 33125824d651Sblueswir1#ifndef _WIN32 33135824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3314ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 33155824d651Sblueswir1#endif 33165824d651Sblueswir1STEXI 33175824d651Sblueswir1@item -daemonize 33186616b2adSStefan Weil@findex -daemonize 33195824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 33205824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 33215824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 33225824d651Sblueswir1to cope with initialization race conditions. 33235824d651Sblueswir1ETEXI 33245824d651Sblueswir1 33255824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3326ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3327ad96090aSBlue Swirl QEMU_ARCH_ALL) 33285824d651Sblueswir1STEXI 33295824d651Sblueswir1@item -option-rom @var{file} 33306616b2adSStefan Weil@findex -option-rom 33315824d651Sblueswir1Load the contents of @var{file} as an option ROM. 33325824d651Sblueswir1This option is useful to load things like EtherBoot. 33335824d651Sblueswir1ETEXI 33345824d651Sblueswir1 3335e218052fSMarkus ArmbrusterHXCOMM Silently ignored for compatibility 3336e218052fSMarkus ArmbrusterDEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL) 33375824d651Sblueswir1 33381ed2fc1fSJan KiszkaHXCOMM Options deprecated by -rtc 3339ad96090aSBlue SwirlDEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 3340ad96090aSBlue SwirlDEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 33415824d651Sblueswir1 33421ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 334378808141SPaolo Bonzini "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3344ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3345ad96090aSBlue Swirl QEMU_ARCH_ALL) 33461ed2fc1fSJan Kiszka 33475824d651Sblueswir1STEXI 33485824d651Sblueswir1 33496875204cSJan Kiszka@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 33506616b2adSStefan Weil@findex -rtc 33511ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 33521ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 33531ed2fc1fSJan KiszkaMS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 33541ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 33551ed2fc1fSJan Kiszka 33569d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 33576875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 33586875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 335978808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 336078808141SPaolo Bonzinito @code{rt} instead. To even prevent it from progressing during suspension, 336178808141SPaolo Bonziniyou can set it to @code{vm}. 33626875204cSJan Kiszka 33631ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 33641ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 33651ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 33661ed2fc1fSJan Kiszkare-inject them. 33675824d651Sblueswir1ETEXI 33685824d651Sblueswir1 33695824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 3370778d9f9bSPranith Kumar "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>]\n" \ 3371bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3372f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3373f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 33745824d651Sblueswir1STEXI 33754c27b859SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename}] 33766616b2adSStefan Weil@findex -icount 33775824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 33784e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 33795824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 33805824d651Sblueswir1time within a few seconds of real time. 33815824d651Sblueswir1 3382f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3383778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3384778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3385f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3386f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3387f1f4b57eSVictor CLEMENTthe guest point of view. 3388f1f4b57eSVictor CLEMENT 33895824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 33905824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 33915824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 33925824d651Sblueswir1executed often has little or no correlation with actual performance. 3393a8bfac37SSebastian Tanase 3394b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3395a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3396a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3397a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 339882597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3399a8bfac37SSebastian Tanaseto inform about the delay. 3400a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3401a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3402a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3403a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 34044c27b859SPavel Dovgalyuk 34054c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 34064c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 34074c27b859SPavel Dovgalyukread from this file in replay mode. 34085824d651Sblueswir1ETEXI 34095824d651Sblueswir1 34109dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3411d7933ef3SXu Wang "-watchdog model\n" \ 3412ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3413ad96090aSBlue Swirl QEMU_ARCH_ALL) 34149dd986ccSRichard W.M. JonesSTEXI 34159dd986ccSRichard W.M. Jones@item -watchdog @var{model} 34166616b2adSStefan Weil@findex -watchdog 34179dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 34189dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3419d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3420d7933ef3SXu Wangwhich your guest has drivers. 34219dd986ccSRichard W.M. Jones 3422d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3423d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 34249dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3425d7933ef3SXu Wang 3426d7933ef3SXu WangThe following models may be available: 3427d7933ef3SXu Wang@table @option 3428d7933ef3SXu Wang@item ib700 3429d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3430d7933ef3SXu Wang@item i6300esb 3431d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3432d7933ef3SXu Wangdual-timer watchdog. 3433188f24c2SXu Wang@item diag288 3434188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3435188f24c2SXu Wang(currently KVM only). 3436d7933ef3SXu Wang@end table 34379dd986ccSRichard W.M. JonesETEXI 34389dd986ccSRichard W.M. Jones 34399dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 34409dd986ccSRichard W.M. Jones "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \ 3441ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3442ad96090aSBlue Swirl QEMU_ARCH_ALL) 34439dd986ccSRichard W.M. JonesSTEXI 34449dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3445b8f490ebSMarkus Armbruster@findex -watchdog-action 34469dd986ccSRichard W.M. Jones 34479dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 34489dd986ccSRichard W.M. Jonesexpires. 34499dd986ccSRichard W.M. JonesThe default is 34509dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 34519dd986ccSRichard W.M. JonesOther possible actions are: 34529dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 34539dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 34549dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 34559dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 34569dd986ccSRichard W.M. Jones@code{none} (do nothing). 34579dd986ccSRichard W.M. Jones 34589dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 34599dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 34609dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 34619dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 34629dd986ccSRichard W.M. Jones 34639dd986ccSRichard W.M. JonesExamples: 34649dd986ccSRichard W.M. Jones 34659dd986ccSRichard W.M. Jones@table @code 34669dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3467f9cfd655SMarkus Armbruster@itemx -watchdog ib700 34689dd986ccSRichard W.M. Jones@end table 34699dd986ccSRichard W.M. JonesETEXI 34709dd986ccSRichard W.M. Jones 34715824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3472ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3473ad96090aSBlue Swirl QEMU_ARCH_ALL) 34745824d651Sblueswir1STEXI 34755824d651Sblueswir1 34764e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 34776616b2adSStefan Weil@findex -echr 34785824d651Sblueswir1Change the escape character used for switching to the monitor when using 34795824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 34805824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 34815824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 34825824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 34835824d651Sblueswir1instance you could use the either of the following to change the escape 34845824d651Sblueswir1character to Control-t. 34855824d651Sblueswir1@table @code 34865824d651Sblueswir1@item -echr 0x14 3487f9cfd655SMarkus Armbruster@itemx -echr 20 34885824d651Sblueswir1@end table 34895824d651Sblueswir1ETEXI 34905824d651Sblueswir1 34915824d651Sblueswir1DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 34925824d651Sblueswir1 "-virtioconsole c\n" \ 3493ad96090aSBlue Swirl " set virtio console\n", QEMU_ARCH_ALL) 34945824d651Sblueswir1STEXI 34955824d651Sblueswir1@item -virtioconsole @var{c} 34966616b2adSStefan Weil@findex -virtioconsole 34975824d651Sblueswir1Set virtio console. 349898b19252SAmit Shah 349998b19252SAmit ShahThis option is maintained for backward compatibility. 350098b19252SAmit Shah 350198b19252SAmit ShahPlease use @code{-device virtconsole} for the new way of invocation. 35025824d651Sblueswir1ETEXI 35035824d651Sblueswir1 35045824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3505ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 35065824d651Sblueswir1STEXI 350795d5f08bSStefan Weil@item -show-cursor 35086616b2adSStefan Weil@findex -show-cursor 350995d5f08bSStefan WeilShow cursor. 35105824d651Sblueswir1ETEXI 35115824d651Sblueswir1 35125824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3513ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 35145824d651Sblueswir1STEXI 351595d5f08bSStefan Weil@item -tb-size @var{n} 35166616b2adSStefan Weil@findex -tb-size 351795d5f08bSStefan WeilSet TB size. 35185824d651Sblueswir1ETEXI 35195824d651Sblueswir1 35205824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 35217c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 35227c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 35237c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 35247c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 35257c601803SMichael Tokarev " specified protocol and socket address\n" \ 35267c601803SMichael Tokarev "-incoming fd:fd\n" \ 35277c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 35287c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 35291597051bSDr. David Alan Gilbert " or from given external command\n" \ 35301597051bSDr. David Alan Gilbert "-incoming defer\n" \ 35311597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 3532ad96090aSBlue Swirl QEMU_ARCH_ALL) 35335824d651Sblueswir1STEXI 35347c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3535f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 35366616b2adSStefan Weil@findex -incoming 35377c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 35387c601803SMichael Tokarev 35397c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 35407c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 35417c601803SMichael Tokarev 35427c601803SMichael Tokarev@item -incoming fd:@var{fd} 35437c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 35447c601803SMichael Tokarev 35457c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 35467c601803SMichael TokarevAccept incoming migration as an output from specified external command. 35471597051bSDr. David Alan Gilbert 35481597051bSDr. David Alan Gilbert@item -incoming defer 35491597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 35501597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 35511597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 35525824d651Sblueswir1ETEXI 35535824d651Sblueswir1 3554d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3555ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3556d8c208ddSGerd HoffmannSTEXI 35573dbf2c7fSStefan Weil@item -nodefaults 35586616b2adSStefan Weil@findex -nodefaults 355966c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 356066c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 356166c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 356266c19bf1SMichal Novotnydefault devices. 3563d8c208ddSGerd HoffmannETEXI 3564d8c208ddSGerd Hoffmann 35655824d651Sblueswir1#ifndef _WIN32 35665824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3567ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 3568ad96090aSBlue Swirl QEMU_ARCH_ALL) 35695824d651Sblueswir1#endif 35705824d651Sblueswir1STEXI 35714e257e5eSKevin Wolf@item -chroot @var{dir} 35726616b2adSStefan Weil@findex -chroot 35735824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 35745824d651Sblueswir1directory. Especially useful in combination with -runas. 35755824d651Sblueswir1ETEXI 35765824d651Sblueswir1 35775824d651Sblueswir1#ifndef _WIN32 35785824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 3579ad96090aSBlue Swirl "-runas user change to user id user just before starting the VM\n", 3580ad96090aSBlue Swirl QEMU_ARCH_ALL) 35815824d651Sblueswir1#endif 35825824d651Sblueswir1STEXI 35834e257e5eSKevin Wolf@item -runas @var{user} 35846616b2adSStefan Weil@findex -runas 35855824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 35865824d651Sblueswir1to the specified user. 35875824d651Sblueswir1ETEXI 35885824d651Sblueswir1 35895824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 35905824d651Sblueswir1 "-prom-env variable=value\n" 3591ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 3592ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 359395d5f08bSStefan WeilSTEXI 359495d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 35956616b2adSStefan Weil@findex -prom-env 359695d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 359795d5f08bSStefan WeilETEXI 35985824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 3599f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 36003b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 36013b3c1694SLeon Alrae QEMU_ARCH_MIPS) 360295d5f08bSStefan WeilSTEXI 360395d5f08bSStefan Weil@item -semihosting 36046616b2adSStefan Weil@findex -semihosting 36053b3c1694SLeon AlraeEnable semihosting mode (ARM, M68K, Xtensa, MIPS only). 3606a38bb079SLiviu IonescuETEXI 3607a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 3608a59d31a1SLeon Alrae "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \ 3609a59d31a1SLeon Alrae " semihosting configuration\n", 36103b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 36113b3c1694SLeon AlraeQEMU_ARCH_MIPS) 3612a38bb079SLiviu IonescuSTEXI 3613a59d31a1SLeon Alrae@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] 3614a38bb079SLiviu Ionescu@findex -semihosting-config 36153b3c1694SLeon AlraeEnable and configure semihosting (ARM, M68K, Xtensa, MIPS only). 3616a59d31a1SLeon Alrae@table @option 3617a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 3618a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 3619a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 3620a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 3621a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 3622a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 3623a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 3624a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 3625a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 3626a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 3627a59d31a1SLeon Alrae@end table 362895d5f08bSStefan WeilETEXI 36295824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 3630ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 363195d5f08bSStefan WeilSTEXI 363295d5f08bSStefan Weil@item -old-param 36336616b2adSStefan Weil@findex -old-param (ARM) 363495d5f08bSStefan WeilOld param mode (ARM only). 363595d5f08bSStefan WeilETEXI 363695d5f08bSStefan Weil 36377d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 36387d76ad4fSEduardo Otubo "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n", 36397d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 36407d76ad4fSEduardo OtuboSTEXI 36416265c43bSMarkus Armbruster@item -sandbox @var{arg} 36427d76ad4fSEduardo Otubo@findex -sandbox 36437d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 36447d76ad4fSEduardo Otubodisable it. The default is 'off'. 36457d76ad4fSEduardo OtuboETEXI 36467d76ad4fSEduardo Otubo 3647715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3648ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 36493dbf2c7fSStefan WeilSTEXI 36503dbf2c7fSStefan Weil@item -readconfig @var{file} 36516616b2adSStefan Weil@findex -readconfig 3652ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 3653ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 3654ed24cfacSMichal Novotnycharacter limit. 36553dbf2c7fSStefan WeilETEXI 3656715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3657715a664aSGerd Hoffmann "-writeconfig <file>\n" 3658ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 36593dbf2c7fSStefan WeilSTEXI 36603dbf2c7fSStefan Weil@item -writeconfig @var{file} 36616616b2adSStefan Weil@findex -writeconfig 3662ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 3663ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 3664ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 36653dbf2c7fSStefan WeilETEXI 3666292444cbSAnthony LiguoriDEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, 3667292444cbSAnthony Liguori "-nodefconfig\n" 3668ad96090aSBlue Swirl " do not load default config files at startup\n", 3669ad96090aSBlue Swirl QEMU_ARCH_ALL) 3670292444cbSAnthony LiguoriSTEXI 3671292444cbSAnthony Liguori@item -nodefconfig 36726616b2adSStefan Weil@findex -nodefconfig 3673f29a5614SEduardo HabkostNormally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup. 3674f29a5614SEduardo HabkostThe @code{-nodefconfig} option will prevent QEMU from loading any of those config files. 3675f29a5614SEduardo HabkostETEXI 3676f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3677f29a5614SEduardo Habkost "-no-user-config\n" 3678f29a5614SEduardo Habkost " do not load user-provided config files at startup\n", 3679f29a5614SEduardo Habkost QEMU_ARCH_ALL) 3680f29a5614SEduardo HabkostSTEXI 3681f29a5614SEduardo Habkost@item -no-user-config 3682f29a5614SEduardo Habkost@findex -no-user-config 3683f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 3684f29a5614SEduardo Habkostconfig files on @var{sysconfdir}, but won't make it skip the QEMU-provided config 3685f29a5614SEduardo Habkostfiles from @var{datadir}. 3686292444cbSAnthony LiguoriETEXI 3687ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 368810578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 368923d15e86SLluís " specify tracing options\n", 3690ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 3691ab6540d5SPrerna SaxenaSTEXI 369223d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 369323d15e86SLluísHXCOMM HX does not support conditional compilation of text. 3694e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 3695ab6540d5SPrerna Saxena@findex -trace 3696eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 3697ab6540d5SPrerna SaxenaETEXI 36983dbf2c7fSStefan Weil 369931e70d6cSMarkus ArmbrusterHXCOMM Internal use 370031e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 370131e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3702c7f0f3b1SAnthony Liguori 37030f66998fSPaul Moore#ifdef __linux__ 37040f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 37050f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 37060f66998fSPaul Moore QEMU_ARCH_ALL) 37070f66998fSPaul Moore#endif 37080f66998fSPaul MooreSTEXI 37090f66998fSPaul Moore@item -enable-fips 37100f66998fSPaul Moore@findex -enable-fips 37110f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 37120f66998fSPaul MooreETEXI 37130f66998fSPaul Moore 3714a0dac021SJan KiszkaHXCOMM Deprecated by -machine accel=tcg property 3715c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3716a0dac021SJan Kiszka 3717c21fb4f8SJan KiszkaHXCOMM Deprecated by kvm-pit driver properties 3718c6e88b3bSBruce RogersDEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection, 3719c21fb4f8SJan Kiszka "", QEMU_ARCH_I386) 3720c21fb4f8SJan Kiszka 37214086bde8SJan KiszkaHXCOMM Deprecated (ignored) 3722c6e88b3bSBruce RogersDEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386) 37234086bde8SJan Kiszka 3724e43d594eSJan KiszkaHXCOMM Deprecated by -machine kernel_irqchip=on|off property 3725c6e88b3bSBruce RogersDEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386) 3726e43d594eSJan Kiszka 372788eed34aSJan KiszkaHXCOMM Deprecated (ignored) 372888eed34aSJan KiszkaDEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL) 372988eed34aSJan Kiszka 37305e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 37315e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 37325e2ac519SSeiji Aguchi " change the format of messages\n" 37335e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 37345e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 37355e2ac519SSeiji AguchiSTEXI 37365e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 37375e2ac519SSeiji Aguchi@findex -msg 37385e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 37395e2ac519SSeiji AguchiETEXI 37405e2ac519SSeiji Aguchi 3741abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 3742abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 3743abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 3744abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 3745abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 37462382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 3747abfd9ce3SAmit Shah QEMU_ARCH_ALL) 3748abfd9ce3SAmit ShahSTEXI 3749abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 3750abfd9ce3SAmit Shah@findex -dump-vmstate 3751abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 3752abfd9ce3SAmit Shahin @var{file} 3753abfd9ce3SAmit ShahETEXI 3754abfd9ce3SAmit Shah 3755b9174d4fSDaniel P. BerrangeDEFHEADING(Generic object creation) 3756b9174d4fSDaniel P. Berrange 3757b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 3758b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 3759b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 3760b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 3761b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 3762b9174d4fSDaniel P. Berrange " '/objects' path.\n", 3763b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 3764b9174d4fSDaniel P. BerrangeSTEXI 3765b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3766b9174d4fSDaniel P. Berrange@findex -object 3767b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 3768b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 3769b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 3770b9174d4fSDaniel P. Berrange'/objects' path. 3771b9174d4fSDaniel P. Berrange 3772b9174d4fSDaniel P. Berrange@table @option 3773b9174d4fSDaniel P. Berrange 3774b9174d4fSDaniel P. Berrange@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off} 3775b9174d4fSDaniel P. Berrange 3776b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 3777b9174d4fSDaniel P. Berrangethe guest RAM with huge pages. The @option{id} parameter is a 3778b9174d4fSDaniel P. Berrangeunique ID that will be used to reference this memory region 3779b9174d4fSDaniel P. Berrangewhen configuring the @option{-numa} argument. The @option{size} 3780b9174d4fSDaniel P. Berrangeoption provides the size of the memory region, and accepts 3781b9174d4fSDaniel P. Berrangecommon suffixes, eg @option{500M}. The @option{mem-path} provides 3782b9174d4fSDaniel P. Berrangethe path to either a shared memory or huge page filesystem mount. 3783b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 3784b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 3785b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 3786b9174d4fSDaniel P. Berrange 3787b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 3788b9174d4fSDaniel P. Berrange 3789b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 3790b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 3791b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 3792b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 3793b9174d4fSDaniel P. Berrangeentropy from and if omitted defaults to @option{/dev/random}. 3794b9174d4fSDaniel P. Berrange 3795b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 3796b9174d4fSDaniel P. Berrange 3797b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 3798b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 3799b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 3800b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 3801b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 3802b9174d4fSDaniel P. Berrangeto the RNG daemon. 3803b9174d4fSDaniel P. Berrange 3804e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 3805e00adf6cSDaniel P. Berrange 3806e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 3807e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 3808e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 3809e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 3810e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 3811e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 3812e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 3813e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 3814e00adf6cSDaniel P. Berrange 3815e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 3816e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 3817e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 3818e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 3819e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 3820e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 3821e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 3822e00adf6cSDaniel P. Berrangeupfront and saved. 3823e00adf6cSDaniel P. Berrange 38241d7b5b4aSDaniel P. Berrange@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} 382585bcbc78SDaniel P. Berrange 382685bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 382785bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 382885bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 382985bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 383085bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 383185bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 383285bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 383385bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 383485bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 383585bcbc78SDaniel P. Berrange 383685bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 383785bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 383885bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 383985bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 384085bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 384185bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 384285bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 384385bcbc78SDaniel P. Berrangeupfront and saved. 384485bcbc78SDaniel P. Berrange 384585bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 384685bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 384785bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 384885bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 384985bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 385085bcbc78SDaniel P. Berrange 38511d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 38521d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 38531d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 38541d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 38551d7b5b4aSDaniel P. Berrangepassword for decryption. 38561d7b5b4aSDaniel P. Berrange 3857338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 38587dbb11c8SYang Hongyang 38597dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 38607dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 38617dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 3862338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 3863338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 38647dbb11c8SYang Hongyang 38657dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 38667dbb11c8SYang Hongyang 38677dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 38687dbb11c8SYang Hongyang queue of the netdev (default). 38697dbb11c8SYang Hongyang 38707dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 38717dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 38727dbb11c8SYang Hongyang 38737dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 38747dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 38757dbb11c8SYang Hongyang 3876f6d3afb5SZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}] 3877f6d3afb5SZhang Chen 3878f6d3afb5SZhang Chenfilter-mirror on netdev @var{netdevid},mirror net packet to chardev 3879f6d3afb5SZhang Chen@var{chardevid} 3880f6d3afb5SZhang Chen 3881d46f75b2SZhang Chen@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid}, 3882d46f75b2SZhang Chenoutdev=@var{chardevid}[,queue=@var{all|rx|tx}] 3883d46f75b2SZhang Chen 3884d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 3885d46f75b2SZhang Chen@var{chardevid},and redirect indev's packet to filter. 3886d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 3887d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 3888d46f75b2SZhang Chenneed to be specified. 3889d46f75b2SZhang Chen 3890d3e0c032SThomas Huth@item -object filter-dump,id=@var{id},netdev=@var{dev},file=@var{filename}][,maxlen=@var{len}] 3891d3e0c032SThomas Huth 3892d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 3893d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 3894d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 3895d3e0c032SThomas Huthor Wireshark. 3896d3e0c032SThomas Huth 3897ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 3898ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 3899ac1d8878SDaniel P. Berrange 3900ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 3901ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 3902ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 3903ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 3904ac1d8878SDaniel P. Berrange 3905ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 3906ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 3907ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 3908ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 3909ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 3910ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 3911ac1d8878SDaniel P. Berrange 3912ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 3913ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 3914ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 3915ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 3916ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 3917ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 3918ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 391969c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 3920ac1d8878SDaniel P. Berrange 3921ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 3922ac1d8878SDaniel P. Berrange 3923ac1d8878SDaniel P. Berrange@example 3924ac1d8878SDaniel P. Berrange 3925ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,data=letmein,format=raw 3926ac1d8878SDaniel P. Berrange 3927ac1d8878SDaniel P. Berrange@end example 3928ac1d8878SDaniel P. Berrange 3929ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 3930ac1d8878SDaniel P. Berrange 3931ac1d8878SDaniel P. Berrange # echo -n "letmein" > mypasswd.txt 3932ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw 3933ac1d8878SDaniel P. Berrange 3934ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 3935ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 3936ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 3937ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 3938ac1d8878SDaniel P. Berrange 3939ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 3940ac1d8878SDaniel P. Berrange 3941ac1d8878SDaniel P. Berrange@example 3942ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 3943ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 3944ac1d8878SDaniel P. Berrange@end example 3945ac1d8878SDaniel P. Berrange 3946ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 3947ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 3948ac1d8878SDaniel P. Berrange 3949ac1d8878SDaniel P. Berrange@example 3950ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 3951ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 3952ac1d8878SDaniel P. Berrange@end example 3953ac1d8878SDaniel P. Berrange 3954ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 3955ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 3956ac1d8878SDaniel P. Berrangeas raw bytes if desired. 3957ac1d8878SDaniel P. Berrange 3958ac1d8878SDaniel P. Berrange@example 3959ac1d8878SDaniel P. Berrange # SECRET=$(echo -n "letmein" | 3960ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 3961ac1d8878SDaniel P. Berrange@end example 3962ac1d8878SDaniel P. Berrange 3963ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 3964ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 3965ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 3966ac1d8878SDaniel P. Berrange 3967ac1d8878SDaniel P. Berrange@example 3968ac1d8878SDaniel P. Berrange # $QEMU \ 3969ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 3970ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 3971ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 3972ac1d8878SDaniel P. Berrange@end example 3973ac1d8878SDaniel P. Berrange 3974b9174d4fSDaniel P. Berrange@end table 3975b9174d4fSDaniel P. Berrange 3976b9174d4fSDaniel P. BerrangeETEXI 3977b9174d4fSDaniel P. Berrange 3978b9174d4fSDaniel P. Berrange 39793dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 39803dbf2c7fSStefan WeilSTEXI 39813dbf2c7fSStefan Weil@end table 39823dbf2c7fSStefan WeilETEXI 3983