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" 38ddb97f1dSJason Baron " kvm_shadow_mem=size of KVM shadow MMU\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" 412eb1cd07STony Krowiak " iommu=on|off controls emulated Intel IOMMU (VT-d) support (default=off)\n" 4279814179STiejun Chen " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n" 432eb1cd07STony Krowiak " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 449850c604SAlexander Graf " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 4587252e1bSXiao Guangrong " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 46902c053dSGreg Kurz " nvdimm=on|off controls NVDIMM support (default=off)\n" 47902c053dSGreg Kurz " enforce-config-section=on|off enforce configuration section migration (default=off)\n", 4880f52a66SJan Kiszka QEMU_ARCH_ALL) 495824d651Sblueswir1STEXI 5080f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 5180f52a66SJan Kiszka@findex -machine 52585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 5380f52a66SJan Kiszkaavailable machines. Supported machine properties are: 5480f52a66SJan Kiszka@table @option 5580f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 5680f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 5780f52a66SJan Kiszkakvm, xen, or tcg can be available. By default, tcg is used. If there is more 5880f52a66SJan Kiszkathan one accelerator specified, the next one is used if the previous one fails 5980f52a66SJan Kiszkato initialize. 606a48ffaaSJan Kiszka@item kernel_irqchip=on|off 6132c18a2dSMatt GingellControls in-kernel irqchip support for the chosen accelerator when available. 6279814179STiejun Chen@item gfx_passthru=on|off 6379814179STiejun ChenEnables IGD GFX passthrough support for the chosen machine when available. 64d1048befSDon Slutz@item vmport=on|off|auto 65d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 66d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 67d1048befSDon Slutzis on. 6839d6960aSJan Kiszka@item kvm_shadow_mem=size 6939d6960aSJan KiszkaDefines the size of the KVM shadow MMU. 70ddb97f1dSJason Baron@item dump-guest-core=on|off 71ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 728490fc78SLuiz Capitulino@item mem-merge=on|off 738490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 748490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 758490fc78SLuiz Capitulino(enabled by default). 76a52a7fdfSLe Tan@item iommu=on|off 77a52a7fdfSLe TanEnables or disables emulated Intel IOMMU (VT-d) support. The default is off. 782eb1cd07STony Krowiak@item aes-key-wrap=on|off 792eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 802eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 812eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 822eb1cd07STony Krowiak@item dea-key-wrap=on|off 832eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 842eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 852eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 8687252e1bSXiao Guangrong@item nvdimm=on|off 8787252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 8880f52a66SJan Kiszka@end table 895824d651Sblueswir1ETEXI 905824d651Sblueswir1 9180f52a66SJan KiszkaHXCOMM Deprecated by -machine 9280f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 9380f52a66SJan Kiszka 945824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 95585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 965824d651Sblueswir1STEXI 975824d651Sblueswir1@item -cpu @var{model} 986616b2adSStefan Weil@findex -cpu 99585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 1005824d651Sblueswir1ETEXI 1015824d651Sblueswir1 1025824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 10312b7f57eSMichael Tokarev "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 1046be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1056be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 106ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 10758a04db1SAndre Przywara " cores= number of CPU cores on one socket\n" 10858a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 109ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 110ad96090aSBlue Swirl QEMU_ARCH_ALL) 1115824d651Sblueswir1STEXI 11212b7f57eSMichael Tokarev@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1136616b2adSStefan Weil@findex -smp 1145824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1155824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1165824d651Sblueswir1to 4. 11758a04db1SAndre PrzywaraFor the PC target, the number of @var{cores} per socket, the number 11858a04db1SAndre Przywaraof @var{threads} per cores and the total number of @var{sockets} can be 11958a04db1SAndre Przywaraspecified. Missing values will be computed. If any on the three values is 12058a04db1SAndre Przywaragiven, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 12158a04db1SAndre Przywaraspecifies the maximum number of hotpluggable CPUs. 1225824d651Sblueswir1ETEXI 1235824d651Sblueswir1 124268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 1257febe36fSPaolo Bonzini "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n" 1267febe36fSPaolo Bonzini "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL) 127268a362cSaliguoriSTEXI 1284932b897SLuiz Capitulino@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}] 129f9cfd655SMarkus Armbruster@itemx -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}] 1306616b2adSStefan Weil@findex -numa 1317febe36fSPaolo BonziniSimulate a multi node NUMA system. If @samp{mem}, @samp{memdev} 1324932b897SLuiz Capitulinoand @samp{cpus} are omitted, resources are split equally. Also, note 1334932b897SLuiz Capitulinothat the -@option{numa} option doesn't allocate any of the specified 1344932b897SLuiz Capitulinoresources. That is, it just assigns existing resources to NUMA nodes. This 1354932b897SLuiz Capitulinomeans that one still has to use the @option{-m}, @option{-smp} options 1367febe36fSPaolo Bonzinito allocate RAM and VCPUs respectively, and possibly @option{-object} 1377febe36fSPaolo Bonzinito specify the memory backend for the @samp{memdev} suboption. 1387febe36fSPaolo Bonzini 1397febe36fSPaolo Bonzini@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, if one 1407febe36fSPaolo Bonzininode uses @samp{memdev}, all of them have to use it. 141268a362cSaliguoriETEXI 142268a362cSaliguori 14310adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 14410adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 14510adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 14610adb8beSMarkus ArmbrusterSTEXI 14710adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 14810adb8beSMarkus Armbruster@findex -add-fd 14910adb8beSMarkus Armbruster 15010adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 15110adb8beSMarkus Armbruster 15210adb8beSMarkus Armbruster@table @option 15310adb8beSMarkus Armbruster@item fd=@var{fd} 15410adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 15510adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 15610adb8beSMarkus Armbruster@item set=@var{set} 15710adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 15810adb8beSMarkus Armbruster@item opaque=@var{opaque} 15910adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 16010adb8beSMarkus Armbruster@end table 16110adb8beSMarkus Armbruster 16210adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 16310adb8beSMarkus Armbruster@example 16410adb8beSMarkus Armbrusterqemu-system-i386 16510adb8beSMarkus Armbruster-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 16610adb8beSMarkus Armbruster-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 16710adb8beSMarkus Armbruster-drive file=/dev/fdset/2,index=0,media=disk 16810adb8beSMarkus Armbruster@end example 16910adb8beSMarkus ArmbrusterETEXI 17010adb8beSMarkus Armbruster 17110adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 17210adb8beSMarkus Armbruster "-set group.id.arg=value\n" 17310adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 17410adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 17510adb8beSMarkus ArmbrusterSTEXI 17610adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 17710adb8beSMarkus Armbruster@findex -set 17810adb8beSMarkus ArmbrusterSet parameter @var{arg} for item @var{id} of type @var{group}\n" 17910adb8beSMarkus ArmbrusterETEXI 18010adb8beSMarkus Armbruster 18110adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 1823751d7c4SPaolo Bonzini "-global driver.property=value\n" 1833751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 18410adb8beSMarkus Armbruster " set a global default for a driver property\n", 18510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 18610adb8beSMarkus ArmbrusterSTEXI 18710adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 1883751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 18910adb8beSMarkus Armbruster@findex -global 19010adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 19110adb8beSMarkus Armbruster 19210adb8beSMarkus Armbruster@example 19310adb8beSMarkus Armbrusterqemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk 19410adb8beSMarkus Armbruster@end example 19510adb8beSMarkus Armbruster 19610adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 19710adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 19810adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 1993751d7c4SPaolo Bonzini 200ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 201ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 202ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 20310adb8beSMarkus ArmbrusterETEXI 20410adb8beSMarkus Armbruster 20510adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 20610adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 207c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 20810adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 20910adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 21010adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 21110adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 21210adb8beSMarkus Armbruster QEMU_ARCH_ALL) 21310adb8beSMarkus ArmbrusterSTEXI 214c8a6ae8bSAmos 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] 21510adb8beSMarkus Armbruster@findex -boot 21610adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 217d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 21810adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 21910adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 22010adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 22110adb8beSMarkus Armbruster@option{once}. 22210adb8beSMarkus Armbruster 22310adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 22410adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 22510adb8beSMarkus Armbruster 22610adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 22710adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 22810adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 22910adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 23010adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 23110adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 23210adb8beSMarkus Armbruster 23310adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 23410adb8beSMarkus Armbrusterwhen boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 23510adb8beSMarkus Armbrusterreboot, qemu passes '-1' to bios by default. Currently Seabios for X86 23610adb8beSMarkus Armbrustersystem support it. 23710adb8beSMarkus Armbruster 238c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 239c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 240c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 241c8a6ae8bSAmos Kong 24210adb8beSMarkus Armbruster@example 24310adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 24410adb8beSMarkus Armbrusterqemu-system-i386 -boot order=nc 24510adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 24610adb8beSMarkus Armbrusterqemu-system-i386 -boot once=d 24710adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 24810adb8beSMarkus Armbrusterqemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 24910adb8beSMarkus Armbruster@end example 25010adb8beSMarkus Armbruster 25110adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 25210adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 25310adb8beSMarkus ArmbrusterETEXI 25410adb8beSMarkus Armbruster 25510adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 256c270fb9eSIgor Mammedov "-m[emory] [size=]megs[,slots=n,maxmem=size]\n" 2576e1d3c1cSIgor Mammedov " configure guest RAM\n" 2580daba1f0SAlexander Graf " size: initial amount of guest memory\n" 259c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 260b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 261b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 2626e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 26310adb8beSMarkus ArmbrusterSTEXI 2649fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 26510adb8beSMarkus Armbruster@findex -m 2669fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 2679fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 2689fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 2699fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 2709fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 2719fcc0794SLuiz Capitulino 2729fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 2739fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 2749fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 2759fcc0794SLuiz Capitulino 2769fcc0794SLuiz Capitulino@example 2779fcc0794SLuiz Capitulinoqemu-system-x86_64 -m 1G,slots=3,maxmem=4G 2789fcc0794SLuiz Capitulino@end example 2799fcc0794SLuiz Capitulino 2809fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 2819fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 28210adb8beSMarkus ArmbrusterETEXI 28310adb8beSMarkus Armbruster 28410adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 28510adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 28610adb8beSMarkus ArmbrusterSTEXI 28710adb8beSMarkus Armbruster@item -mem-path @var{path} 28810adb8beSMarkus Armbruster@findex -mem-path 28910adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 29010adb8beSMarkus ArmbrusterETEXI 29110adb8beSMarkus Armbruster 29210adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 29310adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 29410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 29510adb8beSMarkus ArmbrusterSTEXI 29610adb8beSMarkus Armbruster@item -mem-prealloc 29710adb8beSMarkus Armbruster@findex -mem-prealloc 29810adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 29910adb8beSMarkus ArmbrusterETEXI 30010adb8beSMarkus Armbruster 30110adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 30210adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 30310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 30410adb8beSMarkus ArmbrusterSTEXI 30510adb8beSMarkus Armbruster@item -k @var{language} 30610adb8beSMarkus Armbruster@findex -k 30710adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 30810adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 30910adb8beSMarkus Armbrusterkeycodes (e.g. on Macs, with some X11 servers or with a VNC 31010adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 31110adb8beSMarkus Armbrusterhosts. 31210adb8beSMarkus Armbruster 31310adb8beSMarkus ArmbrusterThe available layouts are: 31410adb8beSMarkus Armbruster@example 31510adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 31610adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 31710adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 31810adb8beSMarkus Armbruster@end example 31910adb8beSMarkus Armbruster 32010adb8beSMarkus ArmbrusterThe default is @code{en-us}. 32110adb8beSMarkus ArmbrusterETEXI 32210adb8beSMarkus Armbruster 32310adb8beSMarkus Armbruster 32410adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 32510adb8beSMarkus Armbruster "-audio-help print list of audio drivers and their options\n", 32610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 32710adb8beSMarkus ArmbrusterSTEXI 32810adb8beSMarkus Armbruster@item -audio-help 32910adb8beSMarkus Armbruster@findex -audio-help 33010adb8beSMarkus ArmbrusterWill show the audio subsystem help: list of drivers, tunable 33110adb8beSMarkus Armbrusterparameters. 33210adb8beSMarkus ArmbrusterETEXI 33310adb8beSMarkus Armbruster 33410adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 33510adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 33610adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 33710adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 33810adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 33910adb8beSMarkus ArmbrusterSTEXI 34010adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 34110adb8beSMarkus Armbruster@findex -soundhw 34210adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 34310adb8beSMarkus Armbrusteravailable sound hardware. 34410adb8beSMarkus Armbruster 34510adb8beSMarkus Armbruster@example 34610adb8beSMarkus Armbrusterqemu-system-i386 -soundhw sb16,adlib disk.img 34710adb8beSMarkus Armbrusterqemu-system-i386 -soundhw es1370 disk.img 34810adb8beSMarkus Armbrusterqemu-system-i386 -soundhw ac97 disk.img 34910adb8beSMarkus Armbrusterqemu-system-i386 -soundhw hda disk.img 35010adb8beSMarkus Armbrusterqemu-system-i386 -soundhw all disk.img 35110adb8beSMarkus Armbrusterqemu-system-i386 -soundhw help 35210adb8beSMarkus Armbruster@end example 35310adb8beSMarkus Armbruster 35410adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 35510adb8beSMarkus Armbrusterrequire manually specifying clocking. 35610adb8beSMarkus Armbruster 35710adb8beSMarkus Armbruster@example 35810adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 35910adb8beSMarkus Armbruster@end example 36010adb8beSMarkus ArmbrusterETEXI 36110adb8beSMarkus Armbruster 36210adb8beSMarkus ArmbrusterDEF("balloon", HAS_ARG, QEMU_OPTION_balloon, 36310adb8beSMarkus Armbruster "-balloon none disable balloon device\n" 36410adb8beSMarkus Armbruster "-balloon virtio[,addr=str]\n" 36510adb8beSMarkus Armbruster " enable virtio balloon device (default)\n", QEMU_ARCH_ALL) 36610adb8beSMarkus ArmbrusterSTEXI 36710adb8beSMarkus Armbruster@item -balloon none 36810adb8beSMarkus Armbruster@findex -balloon 36910adb8beSMarkus ArmbrusterDisable balloon device. 37010adb8beSMarkus Armbruster@item -balloon virtio[,addr=@var{addr}] 37110adb8beSMarkus ArmbrusterEnable virtio balloon device (default), optionally with PCI address 37210adb8beSMarkus Armbruster@var{addr}. 37310adb8beSMarkus ArmbrusterETEXI 37410adb8beSMarkus Armbruster 37510adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 37610adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 37710adb8beSMarkus Armbruster " add device (based on driver)\n" 37810adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 37910adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 38010adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 38110adb8beSMarkus Armbruster QEMU_ARCH_ALL) 38210adb8beSMarkus ArmbrusterSTEXI 38310adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 38410adb8beSMarkus Armbruster@findex -device 38510adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 38610adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 38710adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 38810adb8beSMarkus Armbruster@code{-device @var{driver},help}. 389f8490451SCorey Minyard 390f8490451SCorey MinyardSome drivers are: 391f8490451SCorey Minyard@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}] 392f8490451SCorey Minyard 393f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 394f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 395f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 396f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 397f8490451SCorey Minyard 398f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 399f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 400f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 401f8490451SCorey Minyardit. 402f8490451SCorey Minyard 403f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 404f8490451SCorey Minyard 405f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 406f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 407f8490451SCorey Minyardto an external entity that provides the IPMI services. 408f8490451SCorey Minyard 409f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 410f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 411f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 412f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 413f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 414f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 415f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 416f8490451SCorey Minyardexposed to any outside network. 417f8490451SCorey Minyard 418f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 419f8490451SCorey Minyarddetails on the external interface. 420f8490451SCorey Minyard 421f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 422f8490451SCorey Minyard 423f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 424f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 425f8490451SCorey Minyard 426f8490451SCorey Minyard@table @option 427f8490451SCorey Minyard@item bmc=@var{id} 428f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 429f8490451SCorey Minyard@item ioport=@var{val} 430f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 431f8490451SCorey Minyard@item irq=@var{val} 432f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 433f8490451SCorey Minyardset this to 0. 434f8490451SCorey Minyard@end table 435f8490451SCorey Minyard 436f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 437f8490451SCorey Minyard 438f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 439f8490451SCorey Minyard0xe4 and the default interrupt is 5. 440f8490451SCorey Minyard 44110adb8beSMarkus ArmbrusterETEXI 44210adb8beSMarkus Armbruster 44310adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 4448f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 44510adb8beSMarkus Armbruster " set the name of the guest\n" 4468f480de0SDr. David Alan Gilbert " string1 sets the window title and string2 the process name (on Linux)\n" 4478f480de0SDr. David Alan Gilbert " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n" 4488f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 44910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 45010adb8beSMarkus ArmbrusterSTEXI 45110adb8beSMarkus Armbruster@item -name @var{name} 45210adb8beSMarkus Armbruster@findex -name 45310adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 45410adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 45510adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 45610adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 4578f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 45810adb8beSMarkus ArmbrusterETEXI 45910adb8beSMarkus Armbruster 46010adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 46110adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 46210adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 46310adb8beSMarkus ArmbrusterSTEXI 46410adb8beSMarkus Armbruster@item -uuid @var{uuid} 46510adb8beSMarkus Armbruster@findex -uuid 46610adb8beSMarkus ArmbrusterSet system UUID. 46710adb8beSMarkus ArmbrusterETEXI 46810adb8beSMarkus Armbruster 46910adb8beSMarkus ArmbrusterSTEXI 47010adb8beSMarkus Armbruster@end table 47110adb8beSMarkus ArmbrusterETEXI 47210adb8beSMarkus ArmbrusterDEFHEADING() 47310adb8beSMarkus Armbruster 47410adb8beSMarkus ArmbrusterDEFHEADING(Block device options:) 47510adb8beSMarkus ArmbrusterSTEXI 47610adb8beSMarkus Armbruster@table @option 47710adb8beSMarkus ArmbrusterETEXI 47810adb8beSMarkus Armbruster 4795824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 480ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 481ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 4825824d651Sblueswir1STEXI 4835824d651Sblueswir1@item -fda @var{file} 484f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 4856616b2adSStefan Weil@findex -fda 4866616b2adSStefan Weil@findex -fdb 48792a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 4885824d651Sblueswir1ETEXI 4895824d651Sblueswir1 4905824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 491ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 492ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 4935824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 494ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 495ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 4965824d651Sblueswir1STEXI 4975824d651Sblueswir1@item -hda @var{file} 498f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 499f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 500f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 5016616b2adSStefan Weil@findex -hda 5026616b2adSStefan Weil@findex -hdb 5036616b2adSStefan Weil@findex -hdc 5046616b2adSStefan Weil@findex -hdd 5055824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 5065824d651Sblueswir1ETEXI 5075824d651Sblueswir1 5085824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 509ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 510ad96090aSBlue Swirl QEMU_ARCH_ALL) 5115824d651Sblueswir1STEXI 5125824d651Sblueswir1@item -cdrom @var{file} 5136616b2adSStefan Weil@findex -cdrom 5145824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 5155824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 5165824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 5175824d651Sblueswir1ETEXI 5185824d651Sblueswir1 5195824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 5205824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 5215824d651Sblueswir1 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" 52292196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 523d1db760dSStefan Hajnoczi " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n" 524d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 525fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 5262f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 5273e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 5283e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 5293e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 5303e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 5312024c1dfSBenoît Canet " [[,iops_size=is]]\n" 53276f4afb4SAlberto Garcia " [[,group=g]]\n" 533ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 5345824d651Sblueswir1STEXI 5355824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 5366616b2adSStefan Weil@findex -drive 5375824d651Sblueswir1 5385824d651Sblueswir1Define a new drive. Valid options are: 5395824d651Sblueswir1 540b3f046c2SKevin Wolf@table @option 5415824d651Sblueswir1@item file=@var{file} 5425824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 5435824d651Sblueswir1this drive. If the filename contains comma, you must double it 5445824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 5450f5314a2SRonnie Sahlberg 5460f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 5470f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 5485824d651Sblueswir1@item if=@var{interface} 5495824d651Sblueswir1This option defines on which type on interface the drive is connected. 5505824d651Sblueswir1Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. 5515824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 5525824d651Sblueswir1These options define where is connected the drive by defining the bus number and 5535824d651Sblueswir1the unit id. 5545824d651Sblueswir1@item index=@var{index} 5555824d651Sblueswir1This option defines where is connected the drive by using an index in the list 5565824d651Sblueswir1of available connectors of a given interface type. 5575824d651Sblueswir1@item media=@var{media} 5585824d651Sblueswir1This option defines the type of the media: disk or cdrom. 5595824d651Sblueswir1@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] 5605824d651Sblueswir1These options have the same definition as they have in @option{-hdachs}. 5615824d651Sblueswir1@item snapshot=@var{snapshot} 5629d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 5639d85d557SMichael Tokarev(see @option{-snapshot}). 5645824d651Sblueswir1@item cache=@var{cache} 56592196b2fSStefan Hajnoczi@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data. 5665c6c3a6cSChristoph Hellwig@item aio=@var{aio} 5675c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 568a9384affSPaolo Bonzini@item discard=@var{discard} 569a9384affSPaolo 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. 5705824d651Sblueswir1@item format=@var{format} 5715824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 5725824d651Sblueswir1the format. Can be used to specifiy format=raw to avoid interpreting 5735824d651Sblueswir1an untrusted format header. 5745824d651Sblueswir1@item serial=@var{serial} 5755824d651Sblueswir1This option specifies the serial number to assign to the device. 576c2cc47a4SMarkus Armbruster@item addr=@var{addr} 577c2cc47a4SMarkus ArmbrusterSpecify the controller's PCI address (if=virtio only). 578ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 579ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 580ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 581ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 582ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 583ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 584ae73e591SLuiz Capitulino@item readonly 585ae73e591SLuiz CapitulinoOpen drive @option{file} as read-only. Guest write attempts will fail. 586fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 587fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 588fb0490f6SStefan Hajnoczifile sectors into the image file. 589465bee1dSPeter Lieven@item detect-zeroes=@var{detect-zeroes} 590465bee1dSPeter Lieven@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 591465bee1dSPeter Lievenconversion of plain zero writes by the OS to driver specific optimized 592465bee1dSPeter Lievenzero write commands. You may even choose "unmap" if @var{discard} is set 593465bee1dSPeter Lievento "unmap" to allow a zero write to be converted to an UNMAP operation. 5945824d651Sblueswir1@end table 5955824d651Sblueswir1 596a13e5e05SKevin WolfBy default, the @option{cache=writeback} mode is used. It will report data 597a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 598a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 599a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 600a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 601a13e5e05SKevin Wolfdata corruption. 6025824d651Sblueswir1 603a13e5e05SKevin WolfFor such guests, you should consider using @option{cache=writethrough}. This 604a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 605a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 606a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 6075824d651Sblueswir1 608c304d317SAurelien JarnoThe host page cache can be avoided entirely with @option{cache=none}. This will 609a13e5e05SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform 610a13e5e05SKevin Wolfan internal copy of the data. Note that this is considered a writeback mode and 611a13e5e05SKevin Wolfthe guest OS must handle the disk write cache correctly in order to avoid data 612a13e5e05SKevin Wolfcorruption on host crashes. 6135824d651Sblueswir1 61492196b2fSStefan HajnocziThe host page cache can be avoided while only sending write notifications to 615a13e5e05SKevin Wolfthe guest when the data has been flushed to the disk using 616a13e5e05SKevin Wolf@option{cache=directsync}. 6175824d651Sblueswir1 618016f5cf6SAlexander GrafIn case you don't care about data integrity over host failures, use 619a13e5e05SKevin Wolf@option{cache=unsafe}. This option tells QEMU that it never needs to write any 620a13e5e05SKevin Wolfdata to the disk but can instead keep things in cache. If anything goes wrong, 621e7d81004SStefan Weillike your host losing power, the disk storage getting disconnected accidentally, 622a13e5e05SKevin Wolfetc. your image will most probably be rendered unusable. When using 623c3177288SAlexander Grafthe @option{-snapshot} option, unsafe caching is always used. 624016f5cf6SAlexander Graf 625fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 626fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 627fb0490f6SStefan Hajnocziis off. 628fb0490f6SStefan Hajnoczi 6295824d651Sblueswir1Instead of @option{-cdrom} you can use: 6305824d651Sblueswir1@example 6313804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=cdrom 6325824d651Sblueswir1@end example 6335824d651Sblueswir1 6345824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 6355824d651Sblueswir1use: 6365824d651Sblueswir1@example 6373804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,media=disk 6383804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,media=disk 6393804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=disk 6403804da9dSStefan Weilqemu-system-i386 -drive file=file,index=3,media=disk 6415824d651Sblueswir1@end example 6425824d651Sblueswir1 643587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 644587ed6beSCorey Bryant@example 645587ed6beSCorey Bryantqemu-system-i386 646587ed6beSCorey Bryant-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 647587ed6beSCorey Bryant-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 648587ed6beSCorey Bryant-drive file=/dev/fdset/2,index=0,media=disk 649587ed6beSCorey Bryant@end example 650587ed6beSCorey Bryant 6515824d651Sblueswir1You can connect a CDROM to the slave of ide0: 6525824d651Sblueswir1@example 6533804da9dSStefan Weilqemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 6545824d651Sblueswir1@end example 6555824d651Sblueswir1 6565824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 6575824d651Sblueswir1@example 6583804da9dSStefan Weilqemu-system-i386 -drive if=ide,index=1,media=cdrom 6595824d651Sblueswir1@end example 6605824d651Sblueswir1 6615824d651Sblueswir1You can connect a SCSI disk with unit ID 6 on the bus #0: 6625824d651Sblueswir1@example 6633804da9dSStefan Weilqemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6 6645824d651Sblueswir1@end example 6655824d651Sblueswir1 6665824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 6675824d651Sblueswir1@example 6683804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,if=floppy 6693804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,if=floppy 6705824d651Sblueswir1@end example 6715824d651Sblueswir1 6725824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 6735824d651Sblueswir1incremented: 6745824d651Sblueswir1@example 6753804da9dSStefan Weilqemu-system-i386 -drive file=a -drive file=b" 6765824d651Sblueswir1@end example 6775824d651Sblueswir1is interpreted like: 6785824d651Sblueswir1@example 6793804da9dSStefan Weilqemu-system-i386 -hda a -hdb b 6805824d651Sblueswir1@end example 6815824d651Sblueswir1ETEXI 6825824d651Sblueswir1 6835824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 684ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 685ad96090aSBlue Swirl QEMU_ARCH_ALL) 6865824d651Sblueswir1STEXI 6874e257e5eSKevin Wolf@item -mtdblock @var{file} 6886616b2adSStefan Weil@findex -mtdblock 6894e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 6905824d651Sblueswir1ETEXI 6915824d651Sblueswir1 6925824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 693ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 6945824d651Sblueswir1STEXI 6954e257e5eSKevin Wolf@item -sd @var{file} 6966616b2adSStefan Weil@findex -sd 6974e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 6985824d651Sblueswir1ETEXI 6995824d651Sblueswir1 7005824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 701ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 7025824d651Sblueswir1STEXI 7034e257e5eSKevin Wolf@item -pflash @var{file} 7046616b2adSStefan Weil@findex -pflash 7054e257e5eSKevin WolfUse @var{file} as a parallel flash image. 7065824d651Sblueswir1ETEXI 7075824d651Sblueswir1 7085824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 709ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 710ad96090aSBlue Swirl QEMU_ARCH_ALL) 7115824d651Sblueswir1STEXI 7125824d651Sblueswir1@item -snapshot 7136616b2adSStefan Weil@findex -snapshot 7145824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 7155824d651Sblueswir1the raw disk image you use is not written back. You can however force 7165824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 7175824d651Sblueswir1ETEXI 7185824d651Sblueswir1 71910adb8beSMarkus ArmbrusterDEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ 72010adb8beSMarkus Armbruster "-hdachs c,h,s[,t]\n" \ 72110adb8beSMarkus Armbruster " force hard disk 0 physical geometry and the optional BIOS\n" \ 72210adb8beSMarkus Armbruster " translation (t=none or lba) (usually QEMU can guess them)\n", 723ad96090aSBlue Swirl QEMU_ARCH_ALL) 724c902760fSMarcelo TosattiSTEXI 72510adb8beSMarkus Armbruster@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] 72610adb8beSMarkus Armbruster@findex -hdachs 72710adb8beSMarkus ArmbrusterForce hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= 72810adb8beSMarkus Armbruster@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS 72910adb8beSMarkus Armbrustertranslation mode (@var{t}=none, lba or auto). Usually QEMU can guess 73010adb8beSMarkus Armbrusterall those parameters. This option is useful for old MS-DOS disk 73110adb8beSMarkus Armbrusterimages. 732c70a01e4SMarkus ArmbrusterETEXI 73374db920cSGautham R Shenoy 73474db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 7352c30dd74SAneesh Kumar K.V "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 73684a87cc4SM. Mohan Kumar " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 73774db920cSGautham R Shenoy QEMU_ARCH_ALL) 73874db920cSGautham R Shenoy 73974db920cSGautham R ShenoySTEXI 74074db920cSGautham R Shenoy 74184a87cc4SM. 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}] 74274db920cSGautham R Shenoy@findex -fsdev 7437c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 7447c92a3d2SAneesh Kumar K.V@table @option 7457c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 7467c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 747f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 7487c92a3d2SAneesh Kumar K.V@item id=@var{id} 7497c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 7507c92a3d2SAneesh Kumar K.V@item path=@var{path} 7517c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 7527c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 7537c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 7547c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 7552c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 7567c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 757b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 7582c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 7597c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 7602c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 7612c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 7627c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 7637c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 764d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 765f67e3ffdSM. Mohan Kumaronly for local fsdriver. Other fsdrivers (like handle, proxy) don't take 766d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 7677c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 7687c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 7697c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 7707c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 7717c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 7722c74c2cbSM. Mohan Kumar@item readonly 7732c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 7742c74c2cbSM. Mohan Kumarread-write access is given. 77584a87cc4SM. Mohan Kumar@item socket=@var{socket} 77684a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 77784a87cc4SM. Mohan Kumarwith virtfs-proxy-helper 778f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 779f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 780f67e3ffdSM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 781f67e3ffdSM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 78274db920cSGautham R Shenoy@end table 7837c92a3d2SAneesh Kumar K.V 7847c92a3d2SAneesh Kumar K.V-fsdev option is used along with -device driver "virtio-9p-pci". 7857c92a3d2SAneesh Kumar K.V@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 7867c92a3d2SAneesh Kumar K.VOptions for virtio-9p-pci driver are: 7877c92a3d2SAneesh Kumar K.V@table @option 7887c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 7897c92a3d2SAneesh Kumar K.VSpecifies the id value specified along with -fsdev option 7907c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 7917c92a3d2SAneesh Kumar K.VSpecifies the tag name to be used by the guest to mount this export point 7927c92a3d2SAneesh Kumar K.V@end table 7937c92a3d2SAneesh Kumar K.V 79474db920cSGautham R ShenoyETEXI 79574db920cSGautham R Shenoy 7963d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 7972c30dd74SAneesh Kumar K.V "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 79884a87cc4SM. Mohan Kumar " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 7993d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 8003d54abc7SGautham R Shenoy 8013d54abc7SGautham R ShenoySTEXI 8023d54abc7SGautham R Shenoy 80384a87cc4SM. 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}] 8043d54abc7SGautham R Shenoy@findex -virtfs 8053d54abc7SGautham R Shenoy 8067c92a3d2SAneesh Kumar K.VThe general form of a Virtual File system pass-through options are: 8077c92a3d2SAneesh Kumar K.V@table @option 8087c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 8097c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 810f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 8117c92a3d2SAneesh Kumar K.V@item id=@var{id} 8127c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 8137c92a3d2SAneesh Kumar K.V@item path=@var{path} 8147c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 8157c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 8167c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 8177c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 8182c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 8197c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 820b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 8212c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 8227c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 8232c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 8242c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 8257c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 8267c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 827d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 828f67e3ffdSM. Mohan Kumarfor local fsdriver. Other fsdrivers (like handle, proxy) don't take security 829d9b36a6eSM. Mohan Kumarmodel as a parameter. 8307c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 8317c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 8327c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 8337c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 8347c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 8352c74c2cbSM. Mohan Kumar@item readonly 8362c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 8372c74c2cbSM. Mohan Kumarread-write access is given. 83884a87cc4SM. Mohan Kumar@item socket=@var{socket} 83984a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 84084a87cc4SM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 84184a87cc4SM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 842f67e3ffdSM. Mohan Kumar@item sock_fd 843f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 844f67e3ffdSM. Mohan Kumardescriptor for interfacing with virtfs-proxy-helper 8453d54abc7SGautham R Shenoy@end table 8463d54abc7SGautham R ShenoyETEXI 8473d54abc7SGautham R Shenoy 8489db221aeSAneesh Kumar K.VDEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 8499db221aeSAneesh Kumar K.V "-virtfs_synth Create synthetic file system image\n", 8509db221aeSAneesh Kumar K.V QEMU_ARCH_ALL) 8519db221aeSAneesh Kumar K.VSTEXI 8529db221aeSAneesh Kumar K.V@item -virtfs_synth 8539db221aeSAneesh Kumar K.V@findex -virtfs_synth 8549db221aeSAneesh Kumar K.VCreate synthetic file system image 8559db221aeSAneesh Kumar K.VETEXI 8569db221aeSAneesh Kumar K.V 8575824d651Sblueswir1STEXI 8585824d651Sblueswir1@end table 8595824d651Sblueswir1ETEXI 8605824d651Sblueswir1DEFHEADING() 8615824d651Sblueswir1 86210adb8beSMarkus ArmbrusterDEFHEADING(USB options:) 86310adb8beSMarkus ArmbrusterSTEXI 86410adb8beSMarkus Armbruster@table @option 86510adb8beSMarkus ArmbrusterETEXI 86610adb8beSMarkus Armbruster 86710adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 86810adb8beSMarkus Armbruster "-usb enable the USB driver (will be the default soon)\n", 86910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 87010adb8beSMarkus ArmbrusterSTEXI 87110adb8beSMarkus Armbruster@item -usb 87210adb8beSMarkus Armbruster@findex -usb 87310adb8beSMarkus ArmbrusterEnable the USB driver (will be the default soon) 87410adb8beSMarkus ArmbrusterETEXI 87510adb8beSMarkus Armbruster 87610adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 87710adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 87810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 87910adb8beSMarkus ArmbrusterSTEXI 88010adb8beSMarkus Armbruster 88110adb8beSMarkus Armbruster@item -usbdevice @var{devname} 88210adb8beSMarkus Armbruster@findex -usbdevice 88310adb8beSMarkus ArmbrusterAdd the USB device @var{devname}. @xref{usb_devices}. 88410adb8beSMarkus Armbruster 88510adb8beSMarkus Armbruster@table @option 88610adb8beSMarkus Armbruster 88710adb8beSMarkus Armbruster@item mouse 88810adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 88910adb8beSMarkus Armbruster 89010adb8beSMarkus Armbruster@item tablet 89110adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 89210adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 89310adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 89410adb8beSMarkus Armbruster 89510adb8beSMarkus Armbruster@item disk:[format=@var{format}]:@var{file} 89610adb8beSMarkus ArmbrusterMass storage device based on file. The optional @var{format} argument 89710adb8beSMarkus Armbrusterwill be used rather than detecting the format. Can be used to specifiy 89810adb8beSMarkus Armbruster@code{format=raw} to avoid interpreting an untrusted format header. 89910adb8beSMarkus Armbruster 90010adb8beSMarkus Armbruster@item host:@var{bus}.@var{addr} 90110adb8beSMarkus ArmbrusterPass through the host device identified by @var{bus}.@var{addr} (Linux only). 90210adb8beSMarkus Armbruster 90310adb8beSMarkus Armbruster@item host:@var{vendor_id}:@var{product_id} 90410adb8beSMarkus ArmbrusterPass through the host device identified by @var{vendor_id}:@var{product_id} 90510adb8beSMarkus Armbruster(Linux only). 90610adb8beSMarkus Armbruster 90710adb8beSMarkus Armbruster@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} 90810adb8beSMarkus ArmbrusterSerial converter to host character device @var{dev}, see @code{-serial} for the 90910adb8beSMarkus Armbrusteravailable devices. 91010adb8beSMarkus Armbruster 91110adb8beSMarkus Armbruster@item braille 91210adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 91310adb8beSMarkus Armbrusteror fake device. 91410adb8beSMarkus Armbruster 91510adb8beSMarkus Armbruster@item net:@var{options} 91610adb8beSMarkus ArmbrusterNetwork adapter that supports CDC ethernet and RNDIS protocols. 91710adb8beSMarkus Armbruster 91810adb8beSMarkus Armbruster@end table 91910adb8beSMarkus ArmbrusterETEXI 92010adb8beSMarkus Armbruster 92110adb8beSMarkus ArmbrusterSTEXI 92210adb8beSMarkus Armbruster@end table 92310adb8beSMarkus ArmbrusterETEXI 92410adb8beSMarkus ArmbrusterDEFHEADING() 92510adb8beSMarkus Armbruster 9265824d651Sblueswir1DEFHEADING(Display options:) 9275824d651Sblueswir1STEXI 9285824d651Sblueswir1@table @option 9295824d651Sblueswir1ETEXI 9305824d651Sblueswir1 9311472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 9321472a95bSJes Sorensen "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 9333264ff12SJes Sorensen " [,window_close=on|off]|curses|none|\n" 934881249c7SJan Kiszka " gtk[,grab_on_hover=on|off]|\n" 9353264ff12SJes Sorensen " vnc=<display>[,<optargs>]\n" 9361472a95bSJes Sorensen " select display type\n", QEMU_ARCH_ALL) 9371472a95bSJes SorensenSTEXI 9381472a95bSJes Sorensen@item -display @var{type} 9391472a95bSJes Sorensen@findex -display 9401472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 9411472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 9421472a95bSJes Sorensen@table @option 9431472a95bSJes Sorensen@item sdl 9441472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 9451472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 9461472a95bSJes Sorensen@item curses 9471472a95bSJes SorensenDisplay video output via curses. For graphics device models which 9481472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 9491472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 9501472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 9511472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 9524171d32eSJes Sorensen@item none 9534171d32eSJes SorensenDo not display video output. The guest will still see an emulated 9544171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 9554171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 9564171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 9574171d32eSJes Sorensenthe destination of the serial and parallel port data. 958881249c7SJan Kiszka@item gtk 959881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 960881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 961881249c7SJan Kiszkaruntime. 9623264ff12SJes Sorensen@item vnc 9633264ff12SJes SorensenStart a VNC server on display <arg> 9641472a95bSJes Sorensen@end table 9651472a95bSJes SorensenETEXI 9661472a95bSJes Sorensen 9675824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 968ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 969ad96090aSBlue Swirl QEMU_ARCH_ALL) 9705824d651Sblueswir1STEXI 9715824d651Sblueswir1@item -nographic 9726616b2adSStefan Weil@findex -nographic 9735824d651Sblueswir1Normally, QEMU uses SDL to display the VGA output. With this option, 9745824d651Sblueswir1you can totally disable graphical output so that QEMU is a simple 9755824d651Sblueswir1command line application. The emulated serial port is redirected on 97602c4bdf1SPaolo Bonzinithe console and muxed with the monitor (unless redirected elsewhere 97702c4bdf1SPaolo Bonziniexplicitly). Therefore, you can still use QEMU to debug a Linux kernel 978b031f413SRamkumar Ramachandrawith a serial console. Use @key{C-a h} for help on switching between 979b031f413SRamkumar Ramachandrathe console and monitor. 9805824d651Sblueswir1ETEXI 9815824d651Sblueswir1 9825824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 983ad96090aSBlue Swirl "-curses use a curses/ncurses interface instead of SDL\n", 984ad96090aSBlue Swirl QEMU_ARCH_ALL) 9855824d651Sblueswir1STEXI 9865824d651Sblueswir1@item -curses 987b8f490ebSMarkus Armbruster@findex -curses 9885824d651Sblueswir1Normally, QEMU uses SDL to display the VGA output. With this option, 9895824d651Sblueswir1QEMU can display the VGA output when in text mode using a 9905824d651Sblueswir1curses/ncurses interface. Nothing is displayed in graphical mode. 9915824d651Sblueswir1ETEXI 9925824d651Sblueswir1 9935824d651Sblueswir1DEF("no-frame", 0, QEMU_OPTION_no_frame, 994ad96090aSBlue Swirl "-no-frame open SDL window without a frame and window decorations\n", 995ad96090aSBlue Swirl QEMU_ARCH_ALL) 9965824d651Sblueswir1STEXI 9975824d651Sblueswir1@item -no-frame 9986616b2adSStefan Weil@findex -no-frame 9995824d651Sblueswir1Do not use decorations for SDL windows and start them using the whole 10005824d651Sblueswir1available screen space. This makes the using QEMU in a dedicated desktop 10015824d651Sblueswir1workspace more convenient. 10025824d651Sblueswir1ETEXI 10035824d651Sblueswir1 10045824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1005ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1006ad96090aSBlue Swirl QEMU_ARCH_ALL) 10075824d651Sblueswir1STEXI 10085824d651Sblueswir1@item -alt-grab 10096616b2adSStefan Weil@findex -alt-grab 1010de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1011de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 10125824d651Sblueswir1ETEXI 10135824d651Sblueswir1 10140ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1015ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1016ad96090aSBlue Swirl QEMU_ARCH_ALL) 10170ca9f8a4SDustin KirklandSTEXI 10180ca9f8a4SDustin Kirkland@item -ctrl-grab 10196616b2adSStefan Weil@findex -ctrl-grab 1020de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1021de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 10220ca9f8a4SDustin KirklandETEXI 10230ca9f8a4SDustin Kirkland 10245824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1025ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 10265824d651Sblueswir1STEXI 10275824d651Sblueswir1@item -no-quit 10286616b2adSStefan Weil@findex -no-quit 10295824d651Sblueswir1Disable SDL window close capability. 10305824d651Sblueswir1ETEXI 10315824d651Sblueswir1 10325824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1033ad96090aSBlue Swirl "-sdl enable SDL\n", QEMU_ARCH_ALL) 10345824d651Sblueswir1STEXI 10355824d651Sblueswir1@item -sdl 10366616b2adSStefan Weil@findex -sdl 10375824d651Sblueswir1Enable SDL. 10385824d651Sblueswir1ETEXI 10395824d651Sblueswir1 104029b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 104127af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 104227af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 104327af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1044fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 104527af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 104627af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 104727af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 104827af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 104927af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 105027af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 105127af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 105227af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 10535ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 10545ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 1055474114b7SGerd Hoffmann " [,gl=[on|off]]\n" 105627af7788SYonit Halperin " enable spice\n" 105727af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 105827af7788SYonit Halperin QEMU_ARCH_ALL) 105929b0040bSGerd HoffmannSTEXI 106029b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 106129b0040bSGerd Hoffmann@findex -spice 106229b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 106329b0040bSGerd Hoffmann 106429b0040bSGerd Hoffmann@table @option 106529b0040bSGerd Hoffmann 106629b0040bSGerd Hoffmann@item port=<nr> 1067c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 106829b0040bSGerd Hoffmann 1069333b0eebSGerd Hoffmann@item addr=<addr> 1070333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1071333b0eebSGerd Hoffmann 1072333b0eebSGerd Hoffmann@item ipv4 1073f9cfd655SMarkus Armbruster@itemx ipv6 1074f9cfd655SMarkus Armbruster@itemx unix 1075333b0eebSGerd HoffmannForce using the specified IP version. 1076333b0eebSGerd Hoffmann 107729b0040bSGerd Hoffmann@item password=<secret> 107829b0040bSGerd HoffmannSet the password you need to authenticate. 107929b0040bSGerd Hoffmann 108048b3ed0aSMarc-André Lureau@item sasl 108148b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 108248b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 108348b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 108448b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 108548b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 108648b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 108748b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 108848b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 108948b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 109048b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 109148b3ed0aSMarc-André Lureaucredentials. 109248b3ed0aSMarc-André Lureau 109329b0040bSGerd Hoffmann@item disable-ticketing 109429b0040bSGerd HoffmannAllow client connects without authentication. 109529b0040bSGerd Hoffmann 1096d4970b07SHans de Goede@item disable-copy-paste 1097d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1098d4970b07SHans de Goede 10995ad24e5fSHans de Goede@item disable-agent-file-xfer 11005ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 11015ad24e5fSHans de Goede 1102c448e855SGerd Hoffmann@item tls-port=<nr> 1103c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1104c448e855SGerd Hoffmann 1105c448e855SGerd Hoffmann@item x509-dir=<dir> 1106c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1107c448e855SGerd Hoffmann 1108c448e855SGerd Hoffmann@item x509-key-file=<file> 1109f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1110f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1111f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1112f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1113c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1114c448e855SGerd Hoffmann 1115c448e855SGerd Hoffmann@item tls-ciphers=<list> 1116c448e855SGerd HoffmannSpecify which ciphers to use. 1117c448e855SGerd Hoffmann 1118d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1119f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 112017b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 112117b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 112217b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 112317b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 112417b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 112517b6dea0SGerd Hoffmann 11269f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 11279f04e09eSYonit HalperinConfigure image compression (lossless). 11289f04e09eSYonit HalperinDefault is auto_glz. 11299f04e09eSYonit Halperin 11309f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1131f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 11329f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 11339f04e09eSYonit HalperinDefault is auto. 11349f04e09eSYonit Halperin 113584a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 113684a23f25SGerd HoffmannConfigure video stream detection. Default is filter. 113784a23f25SGerd Hoffmann 113884a23f25SGerd Hoffmann@item agent-mouse=[on|off] 113984a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 114084a23f25SGerd Hoffmann 114184a23f25SGerd Hoffmann@item playback-compression=[on|off] 114284a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 114384a23f25SGerd Hoffmann 11448c957053SYonit Halperin@item seamless-migration=[on|off] 11458c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 11468c957053SYonit Halperin 1147474114b7SGerd Hoffmann@item gl=[on|off] 1148474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1149474114b7SGerd Hoffmann 115029b0040bSGerd Hoffmann@end table 115129b0040bSGerd HoffmannETEXI 115229b0040bSGerd Hoffmann 11535824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1154ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1155ad96090aSBlue Swirl QEMU_ARCH_ALL) 11565824d651Sblueswir1STEXI 11575824d651Sblueswir1@item -portrait 11586616b2adSStefan Weil@findex -portrait 11595824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 11605824d651Sblueswir1ETEXI 11615824d651Sblueswir1 11629312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 11639312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 11649312805dSVasily Khoruzhick QEMU_ARCH_ALL) 11659312805dSVasily KhoruzhickSTEXI 11666265c43bSMarkus Armbruster@item -rotate @var{deg} 11679312805dSVasily Khoruzhick@findex -rotate 11689312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 11699312805dSVasily KhoruzhickETEXI 11709312805dSVasily Khoruzhick 11715824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1172a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1173ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 11745824d651Sblueswir1STEXI 1175e4558dcaSmalc@item -vga @var{type} 11766616b2adSStefan Weil@findex -vga 11775824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1178b3f046c2SKevin Wolf@table @option 11795824d651Sblueswir1@item cirrus 11805824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 11815824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 11825824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 11835824d651Sblueswir1(This one is the default) 11845824d651Sblueswir1@item std 11855824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 11865824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 11875824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 11885824d651Sblueswir1this option. 11895824d651Sblueswir1@item vmware 11905824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 11915824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 11925824d651Sblueswir1card. 1193a19cbfb3SGerd Hoffmann@item qxl 1194a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1195a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1196a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 119733632788SMark Cave-Ayland@item tcx 119833632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 119933632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 120033632788SMark Cave-Aylandfixed resolution of 1024x768. 120133632788SMark Cave-Ayland@item cg3 120233632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 120333632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 120433632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1205a94f0c5cSGerd Hoffmann@item virtio 1206a94f0c5cSGerd HoffmannVirtio VGA card. 12075824d651Sblueswir1@item none 12085824d651Sblueswir1Disable VGA card. 12095824d651Sblueswir1@end table 12105824d651Sblueswir1ETEXI 12115824d651Sblueswir1 12125824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1213ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 12145824d651Sblueswir1STEXI 12155824d651Sblueswir1@item -full-screen 12166616b2adSStefan Weil@findex -full-screen 12175824d651Sblueswir1Start in full screen. 12185824d651Sblueswir1ETEXI 12195824d651Sblueswir1 12205824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1221ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1222ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 12235824d651Sblueswir1STEXI 122495d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 12256616b2adSStefan Weil@findex -g 122695d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 12275824d651Sblueswir1ETEXI 12285824d651Sblueswir1 12295824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1230ad96090aSBlue Swirl "-vnc display start a VNC server on display\n", QEMU_ARCH_ALL) 12315824d651Sblueswir1STEXI 12325824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 12336616b2adSStefan Weil@findex -vnc 12345824d651Sblueswir1Normally, QEMU uses SDL to display the VGA output. With this option, 12355824d651Sblueswir1you can have QEMU listen on VNC display @var{display} and redirect the VGA 12365824d651Sblueswir1display over the VNC session. It is very useful to enable the usb 12375824d651Sblueswir1tablet device when using this option (option @option{-usbdevice 12385824d651Sblueswir1tablet}). When using the VNC display, you must use the @option{-k} 12395824d651Sblueswir1parameter to set the keyboard layout if you are not using en-us. Valid 12405824d651Sblueswir1syntax for the @var{display} is 12415824d651Sblueswir1 1242b3f046c2SKevin Wolf@table @option 12435824d651Sblueswir1 12445824d651Sblueswir1@item @var{host}:@var{d} 12455824d651Sblueswir1 12465824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 12475824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 12485824d651Sblueswir1be omitted in which case the server will accept connections from any host. 12495824d651Sblueswir1 12504e257e5eSKevin Wolf@item unix:@var{path} 12515824d651Sblueswir1 12525824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 12535824d651Sblueswir1location of a unix socket to listen for connections on. 12545824d651Sblueswir1 12555824d651Sblueswir1@item none 12565824d651Sblueswir1 12575824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 12585824d651Sblueswir1can be used to later start the VNC server. 12595824d651Sblueswir1 12605824d651Sblueswir1@end table 12615824d651Sblueswir1 12625824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 12635824d651Sblueswir1separated by commas. Valid options are 12645824d651Sblueswir1 1265b3f046c2SKevin Wolf@table @option 12665824d651Sblueswir1 12675824d651Sblueswir1@item reverse 12685824d651Sblueswir1 12695824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 12705824d651Sblueswir1client is specified by the @var{display}. For reverse network 12715824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 12725824d651Sblueswir1is a TCP port number, not a display number. 12735824d651Sblueswir1 12747536ee4bSTim Hardeck@item websocket 12757536ee4bSTim Hardeck 12767536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1277085d8134SPeter MaydellBy definition the Websocket port is 5700+@var{display}. If @var{host} is 12787536ee4bSTim Hardeckspecified connections will only be allowed from this host. 12797536ee4bSTim HardeckAs an alternative the Websocket port could be specified by using 12807536ee4bSTim Hardeck@code{websocket}=@var{port}. 12813e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 12823e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 12833e305e4aSDaniel P. Berrangerequires encrypted client connections. 12847536ee4bSTim Hardeck 12855824d651Sblueswir1@item password 12865824d651Sblueswir1 12875824d651Sblueswir1Require that password based authentication is used for client connections. 128886ee5bc3SMichal Novotny 128986ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 129086ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 129186ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 129286ee5bc3SMichal Novotny"vnc" or "spice". 129386ee5bc3SMichal Novotny 129486ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 129586ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 129686ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 129786ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 129886ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 129986ee5bc3SMichal Novotnydate and time). 130086ee5bc3SMichal Novotny 130186ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 130286ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 13035824d651Sblueswir1 13043e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 13053e305e4aSDaniel P. Berrange 13063e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 13073e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 13083e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 13093e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 13103e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 13113e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 13123e305e4aSDaniel P. Berrange 13133e305e4aSDaniel P. BerrangeThe @option{tls-creds} parameter obsoletes the @option{tls}, 13143e305e4aSDaniel P. Berrange@option{x509}, and @option{x509verify} options, and as such 13153e305e4aSDaniel P. Berrangeit is not permitted to set both new and old type options at 13163e305e4aSDaniel P. Berrangethe same time. 13173e305e4aSDaniel P. Berrange 13185824d651Sblueswir1@item tls 13195824d651Sblueswir1 13205824d651Sblueswir1Require that client use TLS when communicating with the VNC server. This 13215824d651Sblueswir1uses anonymous TLS credentials so is susceptible to a man-in-the-middle 13225824d651Sblueswir1attack. It is recommended that this option be combined with either the 13234e257e5eSKevin Wolf@option{x509} or @option{x509verify} options. 13245824d651Sblueswir1 13253e305e4aSDaniel P. BerrangeThis option is now deprecated in favor of using the @option{tls-creds} 13263e305e4aSDaniel P. Berrangeargument. 13273e305e4aSDaniel P. Berrange 13285824d651Sblueswir1@item x509=@var{/path/to/certificate/dir} 13295824d651Sblueswir1 13305824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 13315824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 13325824d651Sblueswir1to the client. It is recommended that a password be set on the VNC server 13335824d651Sblueswir1to provide authentication of the client when this is used. The path following 13345824d651Sblueswir1this option specifies where the x509 certificates are to be loaded from. 13355824d651Sblueswir1See the @ref{vnc_security} section for details on generating certificates. 13365824d651Sblueswir1 13373e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 13383e305e4aSDaniel P. Berrangeargument. 13393e305e4aSDaniel P. Berrange 13405824d651Sblueswir1@item x509verify=@var{/path/to/certificate/dir} 13415824d651Sblueswir1 13425824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 13435824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 13445824d651Sblueswir1to the client, and request that the client send its own x509 certificate. 13455824d651Sblueswir1The server will validate the client's certificate against the CA certificate, 13465824d651Sblueswir1and reject clients when validation fails. If the certificate authority is 13475824d651Sblueswir1trusted, this is a sufficient authentication mechanism. You may still wish 13485824d651Sblueswir1to set a password on the VNC server as a second authentication layer. The 13495824d651Sblueswir1path following this option specifies where the x509 certificates are to 13505824d651Sblueswir1be loaded from. See the @ref{vnc_security} section for details on generating 13515824d651Sblueswir1certificates. 13525824d651Sblueswir1 13533e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 13543e305e4aSDaniel P. Berrangeargument. 13553e305e4aSDaniel P. Berrange 13565824d651Sblueswir1@item sasl 13575824d651Sblueswir1 13585824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 13595824d651Sblueswir1The exact choice of authentication method used is controlled from the 13605824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 13615824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 13625824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 13635824d651Sblueswir1to make it search alternate locations for the service config. 13645824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 13655824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 13665824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 13675824d651Sblueswir1ensures a data encryption preventing compromise of authentication 13685824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 13695824d651Sblueswir1SASL authentication. 13705824d651Sblueswir1 13715824d651Sblueswir1@item acl 13725824d651Sblueswir1 13735824d651Sblueswir1Turn on access control lists for checking of the x509 client certificate 13745824d651Sblueswir1and SASL party. For x509 certs, the ACL check is made against the 13755824d651Sblueswir1certificate's distinguished name. This is something that looks like 13765824d651Sblueswir1@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 13775824d651Sblueswir1made against the username, which depending on the SASL plugin, may 13785824d651Sblueswir1include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 13795824d651Sblueswir1When the @option{acl} flag is set, the initial access list will be 13805824d651Sblueswir1empty, with a @code{deny} policy. Thus no one will be allowed to 13815824d651Sblueswir1use the VNC server until the ACLs have been loaded. This can be 13825824d651Sblueswir1achieved using the @code{acl} monitor command. 13835824d651Sblueswir1 13846f9c78c1SCorentin Chary@item lossy 13856f9c78c1SCorentin Chary 13866f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 13876f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 13886f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 13896f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 13906f9c78c1SCorentin Chary 139180e0c8c3SCorentin Chary@item non-adaptive 139280e0c8c3SCorentin Chary 139380e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 139480e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 139580e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 139661cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 13979d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 139880e0c8c3SCorentin Charylike Tight. 139980e0c8c3SCorentin Chary 14008cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 14018cf36489SGerd Hoffmann 14028cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 14038cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 14048cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 14058cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 14068cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 14078cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 14088cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 14098cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 14108cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 1411b65ee4faSStefan Weilspec but is traditional QEMU behavior. 14128cf36489SGerd Hoffmann 14135824d651Sblueswir1@end table 14145824d651Sblueswir1ETEXI 14155824d651Sblueswir1 14165824d651Sblueswir1STEXI 14175824d651Sblueswir1@end table 14185824d651Sblueswir1ETEXI 1419a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 14205824d651Sblueswir1 1421a3adb7adSMichael EllermanARCHHEADING(i386 target only:, QEMU_ARCH_I386) 14225824d651Sblueswir1STEXI 14235824d651Sblueswir1@table @option 14245824d651Sblueswir1ETEXI 14255824d651Sblueswir1 14265824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1427ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1428ad96090aSBlue Swirl QEMU_ARCH_I386) 14295824d651Sblueswir1STEXI 14305824d651Sblueswir1@item -win2k-hack 14316616b2adSStefan Weil@findex -win2k-hack 14325824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 14335824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 14345824d651Sblueswir1slows down the IDE transfers). 14355824d651Sblueswir1ETEXI 14365824d651Sblueswir1 14371ed2fc1fSJan KiszkaHXCOMM Deprecated by -rtc 1438ad96090aSBlue SwirlDEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 14395824d651Sblueswir1 14405824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1441ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1442ad96090aSBlue Swirl QEMU_ARCH_I386) 14435824d651Sblueswir1STEXI 14445824d651Sblueswir1@item -no-fd-bootchk 14456616b2adSStefan Weil@findex -no-fd-bootchk 14464eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 14475824d651Sblueswir1be needed to boot from old floppy disks. 14485824d651Sblueswir1ETEXI 14495824d651Sblueswir1 14505824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1451f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 14525824d651Sblueswir1STEXI 14535824d651Sblueswir1@item -no-acpi 14546616b2adSStefan Weil@findex -no-acpi 14555824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 14565824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 14575824d651Sblueswir1only). 14585824d651Sblueswir1ETEXI 14595824d651Sblueswir1 14605824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1461ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 14625824d651Sblueswir1STEXI 14635824d651Sblueswir1@item -no-hpet 14646616b2adSStefan Weil@findex -no-hpet 14655824d651Sblueswir1Disable HPET support. 14665824d651Sblueswir1ETEXI 14675824d651Sblueswir1 14685824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1469104bf02eSMichael 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" 1470ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 14715824d651Sblueswir1STEXI 14725824d651Sblueswir1@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}]...] 14736616b2adSStefan Weil@findex -acpitable 14745824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 1475104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 1476104bf02eSMichael TokarevACPI headers (possible overridden by other options). 1477104bf02eSMichael TokarevFor data=, only data 1478104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 1479104bf02eSMichael Tokarevcommand line. 1480ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 1481ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 1482ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 1483ae123749SLaszlo Ersekspec. 14845824d651Sblueswir1ETEXI 14855824d651Sblueswir1 1486b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1487b6f6e3d3Saliguori "-smbios file=binary\n" 1488ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 1489b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1490b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 1491ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 1492b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1493b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 1494b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 1495b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1496b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 1497b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 1498b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 1499b155eb1dSGabriel L. Somlo " [,sku=str]\n" 1500b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 1501b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 1502b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 1503b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 1504b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 15053ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 1506b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 1507c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1508b6f6e3d3SaliguoriSTEXI 1509b6f6e3d3Saliguori@item -smbios file=@var{binary} 15106616b2adSStefan Weil@findex -smbios 1511b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 1512b6f6e3d3Saliguori 151384351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 1514b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 1515b6f6e3d3Saliguori 1516b6f6e3d3Saliguori@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}] 1517b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 1518b155eb1dSGabriel L. Somlo 1519b155eb1dSGabriel 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}] 1520b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 1521b155eb1dSGabriel L. Somlo 1522b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 1523b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 1524b155eb1dSGabriel L. Somlo 1525b155eb1dSGabriel 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}] 1526b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 1527b155eb1dSGabriel L. Somlo 15283ebd6cc8SGabriel 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}] 1529b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 1530b6f6e3d3SaliguoriETEXI 1531b6f6e3d3Saliguori 15325824d651Sblueswir1STEXI 15335824d651Sblueswir1@end table 15345824d651Sblueswir1ETEXI 1535c70a01e4SMarkus ArmbrusterDEFHEADING() 15365824d651Sblueswir1 15375824d651Sblueswir1DEFHEADING(Network options:) 15385824d651Sblueswir1STEXI 15395824d651Sblueswir1@table @option 15405824d651Sblueswir1ETEXI 15415824d651Sblueswir1 1542ad196a9dSJan KiszkaHXCOMM Legacy slirp options (now moved to -net user): 1543ad196a9dSJan Kiszka#ifdef CONFIG_SLIRP 1544ad96090aSBlue SwirlDEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1545ad96090aSBlue SwirlDEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1546ad96090aSBlue SwirlDEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1547ad196a9dSJan Kiszka#ifndef _WIN32 1548ad96090aSBlue SwirlDEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1549ad196a9dSJan Kiszka#endif 1550ad196a9dSJan Kiszka#endif 1551ad196a9dSJan Kiszka 15526a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 15535824d651Sblueswir1#ifdef CONFIG_SLIRP 15540b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 15550b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 15560b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 1557d8eb3864SSamuel Thibault " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n" 155863d2960bSKlaus Stengel " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1559ad196a9dSJan Kiszka#ifndef _WIN32 1560c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 1561ad196a9dSJan Kiszka#endif 15626a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 15636a8b4a5bSThomas Huth " its DHCP server and optional services\n" 15645824d651Sblueswir1#endif 15655824d651Sblueswir1#ifdef _WIN32 15666a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 15676a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 15685824d651Sblueswir1#else 15696a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 15706a8b4a5bSThomas Huth " [,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 15716a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 15726a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 1573a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1574a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1575a7c36ee4SCorey Bryant " to deconfigure it\n" 1576ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 1577a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1578a7c36ee4SCorey Bryant " configure it\n" 15795824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 15802ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1581ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1582f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1583ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1584ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 158582b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 15865430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 15875430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 158882b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 15892ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1590ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 15916a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 15926a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 15936a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 15946a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 15950df0ff6dSMark McLoughlin#endif 15963fb69aa1SAnton Ivanov#ifdef __linux__ 15976a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 15986a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 15996a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 16006a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 16016a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 16026a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 16033fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 16042f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 16053fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 16063fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 16073fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 16083fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 16093fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 16103fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 16113952651aSGonglei " use 'srcport=' to specify source udp port\n" 16123fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 16133fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 16143fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 16153fb69aa1SAnton Ivanov " well as a weak security measure\n" 16163fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 16173fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 16183fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 16193fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 16203fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 16213fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 16223fb69aa1SAnton Ivanov#endif 16236a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 16246a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 16256a8b4a5bSThomas Huth " using a socket connection\n" 16266a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 16276a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 16283a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 16296a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 16306a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 16316a8b4a5bSThomas Huth " using an UDP tunnel\n" 16325824d651Sblueswir1#ifdef CONFIG_VDE 16336a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 16346a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 16356a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 16365824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 16375824d651Sblueswir1 " ownership and permissions for communication port.\n" 16385824d651Sblueswir1#endif 163958952137SVincenzo Maffione#ifdef CONFIG_NETMAP 16406a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 164158952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 164258952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 164358952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 164458952137SVincenzo Maffione#endif 16456a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 16466a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 16476a8b4a5bSThomas Huth "-netdev hubport,id=str,hubid=n\n" 16486a8b4a5bSThomas Huth " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL) 16496a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 16506a8b4a5bSThomas Huth "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 16516a8b4a5bSThomas Huth " old way to create a new NIC and connect it to VLAN 'n'\n" 16526a8b4a5bSThomas Huth " (use the '-device devtype,netdev=str' option if possible instead)\n" 1653bb9ea79eSaliguori "-net dump[,vlan=n][,file=f][,len=n]\n" 1654bb9ea79eSaliguori " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n" 1655ca1a8a06SBruce Rogers "-net none use it alone to have zero network devices. If no -net option\n" 16566a8b4a5bSThomas Huth " is provided, the default is '-net nic -net user'\n" 16576a8b4a5bSThomas Huth "-net [" 1658a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 1659a1ea458fSMark McLoughlin "user|" 1660a1ea458fSMark McLoughlin#endif 1661a1ea458fSMark McLoughlin "tap|" 1662a7c36ee4SCorey Bryant "bridge|" 1663a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 1664a1ea458fSMark McLoughlin "vde|" 1665a1ea458fSMark McLoughlin#endif 166658952137SVincenzo Maffione#ifdef CONFIG_NETMAP 166758952137SVincenzo Maffione "netmap|" 166858952137SVincenzo Maffione#endif 16696a8b4a5bSThomas Huth "socket][,vlan=n][,option][,option][,...]\n" 16706a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 16716a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 16725824d651Sblueswir1STEXI 1673ffe6370cSMichael S. Tsirkin@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 16746616b2adSStefan Weil@findex -net 16755824d651Sblueswir1Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} 16760d6b0b1dSAnthony Liguori= 0 is the default). The NIC is an e1000 by default on the PC 16775607c388SMarkus Armbrustertarget. Optionally, the MAC address can be changed to @var{mac}, the 16785607c388SMarkus Armbrusterdevice address set to @var{addr} (PCI cards only), 1679ffe6370cSMichael S. Tsirkinand a @var{name} can be assigned for use in monitor commands. 1680ffe6370cSMichael S. TsirkinOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 1681ffe6370cSMichael S. Tsirkinthat the card should have; this option currently only affects virtio cards; set 1682ffe6370cSMichael S. Tsirkin@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 1683071c9394SStefan WeilNIC is created. QEMU can emulate several different models of network card. 16845824d651Sblueswir1Valid values for @var{type} are 1685ffe6370cSMichael S. Tsirkin@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er}, 16865824d651Sblueswir1@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, 16875824d651Sblueswir1@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. 1688585f6036SPeter MaydellNot all devices are supported on all targets. Use @code{-net nic,model=help} 16895824d651Sblueswir1for a list of available devices for your target. 16905824d651Sblueswir1 169108d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 1692b8f490ebSMarkus Armbruster@findex -netdev 1693ad196a9dSJan Kiszka@item -net user[,@var{option}][,@var{option}][,...] 16945824d651Sblueswir1Use the user mode network stack which requires no administrator 1695ad196a9dSJan Kiszkaprivilege to run. Valid options are: 16965824d651Sblueswir1 1697b3f046c2SKevin Wolf@table @option 1698ad196a9dSJan Kiszka@item vlan=@var{n} 1699ad196a9dSJan KiszkaConnect user mode stack to VLAN @var{n} (@var{n} = 0 is the default). 1700ad196a9dSJan Kiszka 170108d12022SStefan Hajnoczi@item id=@var{id} 1702f9cfd655SMarkus Armbruster@itemx name=@var{name} 1703ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 1704ad196a9dSJan Kiszka 17050b11c036SSamuel Thibault@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must 17060b11c036SSamuel Thibaultbe enabled. If neither is specified both protocols are enabled. 17070b11c036SSamuel Thibault 1708c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 1709c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 1710c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 1711b0b36e5dSBrad Hards10.0.2.0/24. 1712c92ef6a2SJan Kiszka 1713c92ef6a2SJan Kiszka@item host=@var{addr} 1714c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 1715c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 1716ad196a9dSJan Kiszka 1717d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 1718d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 1719d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 1720d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 1721d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 17227aac531eSYann Bordenave 1723d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 17247aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 17257aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 17267aac531eSYann Bordenave 1727c54ed5bcSJan Kiszka@item restrict=on|off 1728caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 1729ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 1730caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 1731ad196a9dSJan Kiszka 1732ad196a9dSJan Kiszka@item hostname=@var{name} 173363d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 1734ad196a9dSJan Kiszka 1735c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 1736c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 1737b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 1738c92ef6a2SJan Kiszka 1739c92ef6a2SJan Kiszka@item dns=@var{addr} 1740c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 1741c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 1742c92ef6a2SJan Kiszkai.e. x.x.x.3. 1743c92ef6a2SJan Kiszka 1744d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 17457aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 17467aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 17477aac531eSYann Bordenavenetwork, i.e. xxxx::3. 17487aac531eSYann Bordenave 174963d2960bSKlaus Stengel@item dnssearch=@var{domain} 175063d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 175163d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 175263d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 175363d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 175463d2960bSKlaus Stengelcan not be resolved. 175563d2960bSKlaus Stengel 175663d2960bSKlaus StengelExample: 175763d2960bSKlaus Stengel@example 175863d2960bSKlaus Stengelqemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] 175963d2960bSKlaus Stengel@end example 176063d2960bSKlaus Stengel 1761ad196a9dSJan Kiszka@item tftp=@var{dir} 1762ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 1763ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 1764ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 1765c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 1766ad196a9dSJan Kiszka 1767ad196a9dSJan Kiszka@item bootfile=@var{file} 1768ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 1769ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 1770ad196a9dSJan Kiszkaa guest from a local directory. 1771ad196a9dSJan Kiszka 1772ad196a9dSJan KiszkaExample (using pxelinux): 1773ad196a9dSJan Kiszka@example 17743804da9dSStefan Weilqemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 1775ad196a9dSJan Kiszka@end example 1776ad196a9dSJan Kiszka 1777c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 1778ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 1779ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 1780c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 1781c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 1782ad196a9dSJan Kiszka 1783ad196a9dSJan KiszkaIn the guest Windows OS, the line: 1784ad196a9dSJan Kiszka@example 1785ad196a9dSJan Kiszka10.0.2.4 smbserver 1786ad196a9dSJan Kiszka@end example 1787ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 1788ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 1789ad196a9dSJan Kiszka 1790ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 1791ad196a9dSJan Kiszka 1792e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 1793e2d8830eSBradQEMU was tested successfully with smbd versions from Red Hat 9, 1794e2d8830eSBradFedora Core 3 and OpenSUSE 11.x. 1795ad196a9dSJan Kiszka 17963c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 1797c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 1798c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 1799c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 18003c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 18013c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 1802c92ef6a2SJan Kiszkaused. This option can be given multiple times. 1803ad196a9dSJan Kiszka 1804ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 1805ad196a9dSJan Kiszkascreen 0, use the following: 1806ad196a9dSJan Kiszka 1807ad196a9dSJan Kiszka@example 1808ad196a9dSJan Kiszka# on the host 18093804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] 1810ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 1811ad196a9dSJan Kiszkaxterm -display :1 1812ad196a9dSJan Kiszka@end example 1813ad196a9dSJan Kiszka 1814ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 1815ad196a9dSJan Kiszkathe guest, use the following: 1816ad196a9dSJan Kiszka 1817ad196a9dSJan Kiszka@example 1818ad196a9dSJan Kiszka# on the host 18193804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] 1820ad196a9dSJan Kiszkatelnet localhost 5555 1821ad196a9dSJan Kiszka@end example 1822ad196a9dSJan Kiszka 1823ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 1824ad196a9dSJan Kiszkaconnect to the guest telnet server. 1825ad196a9dSJan Kiszka 1826c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 1827f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 18283c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 1829b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 1830b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 1831b412eb61SAlexander Graf 183243ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 1833b412eb61SAlexander Graflifetime, like in the following example: 1834b412eb61SAlexander Graf 1835b412eb61SAlexander Graf@example 1836b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 1837b412eb61SAlexander Graf# the guest accesses it 1838b412eb61SAlexander Grafqemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] 1839b412eb61SAlexander Graf@end example 1840b412eb61SAlexander Graf 1841b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 184243ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 1843b412eb61SAlexander Graf 1844b412eb61SAlexander Graf@example 1845b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 1846b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 1847b412eb61SAlexander Grafqemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 1848b412eb61SAlexander Graf@end example 1849ad196a9dSJan Kiszka 1850ad196a9dSJan Kiszka@end table 1851ad196a9dSJan Kiszka 1852ad196a9dSJan KiszkaNote: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 1853ad196a9dSJan Kiszkaprocessed and applied to -net user. Mixing them with the new configuration 1854ad196a9dSJan Kiszkasyntax gives undefined results. Their use for new applications is discouraged 1855ad196a9dSJan Kiszkaas they will be removed from future versions. 18565824d651Sblueswir1 185708d12022SStefan Hajnoczi@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1858f9cfd655SMarkus 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}] 1859a7c36ee4SCorey BryantConnect the host TAP network interface @var{name} to VLAN @var{n}. 1860a7c36ee4SCorey Bryant 1861a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 18625824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 1863a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 1864a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 1865a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 1866a7c36ee4SCorey Bryantto disable script execution. 1867a7c36ee4SCorey Bryant 1868a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 1869a7c36ee4SCorey Bryant@var{helper} to configure the TAP interface. The default network 1870420508fbSAmos Konghelper executable is @file{/path/to/qemu-bridge-helper}. 1871a7c36ee4SCorey Bryant 1872a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 1873a7c36ee4SCorey Bryantopened host TAP interface. 1874a7c36ee4SCorey Bryant 1875a7c36ee4SCorey BryantExamples: 18765824d651Sblueswir1 18775824d651Sblueswir1@example 1878a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 18793804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net tap 18805824d651Sblueswir1@end example 18815824d651Sblueswir1 18825824d651Sblueswir1@example 1883a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 1884a7c36ee4SCorey Bryant#to a TAP device 18853804da9dSStefan Weilqemu-system-i386 linux.img \ 18863804da9dSStefan Weil -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 18875824d651Sblueswir1 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 18885824d651Sblueswir1@end example 18895824d651Sblueswir1 1890a7c36ee4SCorey Bryant@example 1891a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1892a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 18933804da9dSStefan Weilqemu-system-i386 linux.img \ 1894420508fbSAmos Kong -net nic -net tap,"helper=/path/to/qemu-bridge-helper" 1895a7c36ee4SCorey Bryant@end example 1896a7c36ee4SCorey Bryant 189708d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 1898f9cfd655SMarkus Armbruster@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}] 1899a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 1900a7c36ee4SCorey Bryant 1901a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 1902a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 1903420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 1904a7c36ee4SCorey Bryantdevice is @file{br0}. 1905a7c36ee4SCorey Bryant 1906a7c36ee4SCorey BryantExamples: 1907a7c36ee4SCorey Bryant 1908a7c36ee4SCorey Bryant@example 1909a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1910a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 19113804da9dSStefan Weilqemu-system-i386 linux.img -net bridge -net nic,model=virtio 1912a7c36ee4SCorey Bryant@end example 1913a7c36ee4SCorey Bryant 1914a7c36ee4SCorey Bryant@example 1915a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1916a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 19173804da9dSStefan Weilqemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio 1918a7c36ee4SCorey Bryant@end example 1919a7c36ee4SCorey Bryant 192008d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1921f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 19225824d651Sblueswir1 19235824d651Sblueswir1Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual 19245824d651Sblueswir1machine using a TCP socket connection. If @option{listen} is 19255824d651Sblueswir1specified, QEMU waits for incoming connections on @var{port} 19265824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 19275824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 19285824d651Sblueswir1specifies an already opened TCP socket. 19295824d651Sblueswir1 19305824d651Sblueswir1Example: 19315824d651Sblueswir1@example 19325824d651Sblueswir1# launch a first QEMU instance 19333804da9dSStefan Weilqemu-system-i386 linux.img \ 19343804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 19355824d651Sblueswir1 -net socket,listen=:1234 19365824d651Sblueswir1# connect the VLAN 0 of this instance to the VLAN 0 19375824d651Sblueswir1# of the first instance 19383804da9dSStefan Weilqemu-system-i386 linux.img \ 19393804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 19405824d651Sblueswir1 -net socket,connect=127.0.0.1:1234 19415824d651Sblueswir1@end example 19425824d651Sblueswir1 194308d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1944f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 19455824d651Sblueswir1 19465824d651Sblueswir1Create a VLAN @var{n} shared with another QEMU virtual 19475824d651Sblueswir1machines using a UDP multicast socket, effectively making a bus for 19485824d651Sblueswir1every QEMU with same multicast address @var{maddr} and @var{port}. 19495824d651Sblueswir1NOTES: 19505824d651Sblueswir1@enumerate 19515824d651Sblueswir1@item 19525824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 19535824d651Sblueswir1correct multicast setup for these hosts). 19545824d651Sblueswir1@item 19555824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 19565824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 19575824d651Sblueswir1@item 19585824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 19595824d651Sblueswir1@end enumerate 19605824d651Sblueswir1 19615824d651Sblueswir1Example: 19625824d651Sblueswir1@example 19635824d651Sblueswir1# launch one QEMU instance 19643804da9dSStefan Weilqemu-system-i386 linux.img \ 19653804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 19665824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 19675824d651Sblueswir1# launch another QEMU instance on same "bus" 19683804da9dSStefan Weilqemu-system-i386 linux.img \ 19693804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 19705824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 19715824d651Sblueswir1# launch yet another QEMU instance on same "bus" 19723804da9dSStefan Weilqemu-system-i386 linux.img \ 19733804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:58 \ 19745824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 19755824d651Sblueswir1@end example 19765824d651Sblueswir1 19775824d651Sblueswir1Example (User Mode Linux compat.): 19785824d651Sblueswir1@example 19795824d651Sblueswir1# launch QEMU instance (note mcast address selected 19805824d651Sblueswir1# is UML's default) 19813804da9dSStefan Weilqemu-system-i386 linux.img \ 19823804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 19835824d651Sblueswir1 -net socket,mcast=239.192.168.1:1102 19845824d651Sblueswir1# launch UML 19855824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 19865824d651Sblueswir1@end example 19875824d651Sblueswir1 19883a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 19893a75e74cSMike Ryan@example 19903804da9dSStefan Weilqemu-system-i386 linux.img \ 19913804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 19923a75e74cSMike Ryan -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 19933a75e74cSMike Ryan@end example 19943a75e74cSMike Ryan 19953fb69aa1SAnton 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}] 1996f9cfd655SMarkus 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}] 19973fb69aa1SAnton IvanovConnect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular 19983fb69aa1SAnton Ivanovprotocol to transport Ethernet (and other Layer 2) data frames between 19993fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 20003fb69aa1SAnton Ivanov(from version 3.3 onwards). 20013fb69aa1SAnton Ivanov 20023fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 20033fb69aa1SAnton Ivanov 20043fb69aa1SAnton Ivanov@item src=@var{srcaddr} 20053fb69aa1SAnton Ivanov source address (mandatory) 20063fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 20073fb69aa1SAnton Ivanov destination address (mandatory) 20083fb69aa1SAnton Ivanov@item udp 20093fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 20103fb69aa1SAnton Ivanov@item srcport=@var{srcport} 20113fb69aa1SAnton Ivanov source udp port. 20123fb69aa1SAnton Ivanov@item dstport=@var{dstport} 20133fb69aa1SAnton Ivanov destination udp port. 20143fb69aa1SAnton Ivanov@item ipv6 20153fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 20163fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2017f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 20183fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 20193fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 20203fb69aa1SAnton Ivanovbit. 20213fb69aa1SAnton Ivanov@item cookie64 20223fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 20233fb69aa1SAnton Ivanov@item counter=off 20243fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 20253fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 20263fb69aa1SAnton Ivanov@item pincounter=on 20273fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 20283fb69aa1SAnton Ivanovnetworks which have packet reorder. 20293fb69aa1SAnton Ivanov@item offset=@var{offset} 20303fb69aa1SAnton Ivanov Add an extra offset between header and data 20313fb69aa1SAnton Ivanov 20323fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 20333fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 20343fb69aa1SAnton Ivanov@example 20353fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 20363fb69aa1SAnton Ivanov# on 1.2.3.4 20373fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 20383fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 20393fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 20403fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 20413fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 20423fb69aa1SAnton Ivanovifconfig vmtunnel0 up 20433fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 20443fb69aa1SAnton Ivanov 20453fb69aa1SAnton Ivanov 20463fb69aa1SAnton Ivanov# on 4.3.2.1 20473fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 20483fb69aa1SAnton Ivanov 20493fb69aa1SAnton 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 20503fb69aa1SAnton Ivanov 20513fb69aa1SAnton Ivanov 20523fb69aa1SAnton Ivanov@end example 20533fb69aa1SAnton Ivanov 205408d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2055f9cfd655SMarkus Armbruster@itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 20565824d651Sblueswir1Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and 20575824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 20585824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2059c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 20605824d651Sblueswir1with vde support enabled. 20615824d651Sblueswir1 20625824d651Sblueswir1Example: 20635824d651Sblueswir1@example 20645824d651Sblueswir1# launch vde switch 20655824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 20665824d651Sblueswir1# launch QEMU instance 20673804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch 20685824d651Sblueswir1@end example 20695824d651Sblueswir1 207040e8c26dSStefan Hajnoczi@item -netdev hubport,id=@var{id},hubid=@var{hubid} 207140e8c26dSStefan Hajnoczi 207240e8c26dSStefan HajnocziCreate a hub port on QEMU "vlan" @var{hubid}. 207340e8c26dSStefan Hajnoczi 207440e8c26dSStefan HajnocziThe hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single 207540e8c26dSStefan Hajnoczinetdev. @code{-net} and @code{-device} with parameter @option{vlan} create the 207640e8c26dSStefan Hajnoczirequired hub automatically. 207740e8c26dSStefan Hajnoczi 2078b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 207903ce5744SNikolay Nikolaev 208003ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 208103ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 208203ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 208303ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2084b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2085b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 208603ce5744SNikolay Nikolaev 208703ce5744SNikolay NikolaevExample: 208803ce5744SNikolay Nikolaev@example 208903ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 209003ce5744SNikolay Nikolaev -numa node,memdev=mem \ 209103ce5744SNikolay Nikolaev -chardev socket,path=/path/to/socket \ 209203ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 209303ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 209403ce5744SNikolay Nikolaev@end example 209503ce5744SNikolay Nikolaev 2096bb9ea79eSaliguori@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] 2097bb9ea79eSaliguoriDump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). 2098bb9ea79eSaliguoriAt most @var{len} bytes (64k by default) per packet are stored. The file format is 2099bb9ea79eSaliguorilibpcap, so it can be analyzed with tools such as tcpdump or Wireshark. 2100d3e0c032SThomas HuthNote: For devices created with '-netdev', use '-object filter-dump,...' instead. 2101bb9ea79eSaliguori 21025824d651Sblueswir1@item -net none 21035824d651Sblueswir1Indicate that no network devices should be configured. It is used to 21045824d651Sblueswir1override the default configuration (@option{-net nic -net user}) which 21055824d651Sblueswir1is activated if no @option{-net} options are provided. 21065824d651Sblueswir1ETEXI 21075824d651Sblueswir1 2108c70a01e4SMarkus ArmbrusterSTEXI 2109c70a01e4SMarkus Armbruster@end table 2110c70a01e4SMarkus ArmbrusterETEXI 21117273a2dbSMatthew BoothDEFHEADING() 21127273a2dbSMatthew Booth 21137273a2dbSMatthew BoothDEFHEADING(Character device options:) 2114c70a01e4SMarkus ArmbrusterSTEXI 2115c70a01e4SMarkus Armbruster 2116c70a01e4SMarkus ArmbrusterThe general form of a character device option is: 2117c70a01e4SMarkus Armbruster@table @option 2118c70a01e4SMarkus ArmbrusterETEXI 21197273a2dbSMatthew Booth 21207273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2121d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21225dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2123d0d7708bSDaniel P. Berrange " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n" 2124a8fb5427SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n" 2125d0d7708bSDaniel P. Berrange "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n" 2126d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 21277273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 212897331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2129d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2130d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21317273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2132d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2133d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2134d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2135d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21367273a2dbSMatthew Booth#ifdef _WIN32 2137d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2138d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21397273a2dbSMatthew Booth#else 2140d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2141d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 21427273a2dbSMatthew Booth#endif 21437273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2144d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21457273a2dbSMatthew Booth#endif 21467273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 21477273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2148d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2149d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21507273a2dbSMatthew Booth#endif 21517273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2152d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2153d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21547273a2dbSMatthew Booth#endif 2155cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2156d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2157d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2158cbcc6336SAlon Levy#endif 2159ad96090aSBlue Swirl , QEMU_ARCH_ALL 21607273a2dbSMatthew Booth) 21617273a2dbSMatthew Booth 21627273a2dbSMatthew BoothSTEXI 216397331287SJan Kiszka@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}] 21646616b2adSStefan Weil@findex -chardev 21657273a2dbSMatthew BoothBackend is one of: 21667273a2dbSMatthew Booth@option{null}, 21677273a2dbSMatthew Booth@option{socket}, 21687273a2dbSMatthew Booth@option{udp}, 21697273a2dbSMatthew Booth@option{msmouse}, 21707273a2dbSMatthew Booth@option{vc}, 21714f57378fSMarkus Armbruster@option{ringbuf}, 21727273a2dbSMatthew Booth@option{file}, 21737273a2dbSMatthew Booth@option{pipe}, 21747273a2dbSMatthew Booth@option{console}, 21757273a2dbSMatthew Booth@option{serial}, 21767273a2dbSMatthew Booth@option{pty}, 21777273a2dbSMatthew Booth@option{stdio}, 21787273a2dbSMatthew Booth@option{braille}, 21797273a2dbSMatthew Booth@option{tty}, 218088a946d3SGerd Hoffmann@option{parallel}, 2181cbcc6336SAlon Levy@option{parport}, 2182cbcc6336SAlon Levy@option{spicevmc}. 21835a49d3e9SMarc-André Lureau@option{spiceport}. 21847273a2dbSMatthew BoothThe specific backend will determine the applicable options. 21857273a2dbSMatthew Booth 21867273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 21877273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 21887273a2dbSMatthew Booth 218997331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2190a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2191a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2192a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2193a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2194a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2195a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2196a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2197a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2198a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2199a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2200a40db1b3SPeter Maydell 2201a40db1b3SPeter Maydell@example 2202a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2203a40db1b3SPeter Maydell-mon chardev=char0,mode=readline,default \ 2204a40db1b3SPeter Maydell-serial chardev:char0 \ 2205a40db1b3SPeter Maydell-serial chardev:char0 2206a40db1b3SPeter Maydell@end example 2207a40db1b3SPeter Maydell 2208a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2209a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2210a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2211a40db1b3SPeter Maydell 2212a40db1b3SPeter Maydell@example 2213a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2214a40db1b3SPeter Maydell-mon chardev=char0,mode=readline,default \ 2215a40db1b3SPeter Maydell-parallel chardev:char0 \ 2216a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2217a40db1b3SPeter Maydell-serial chardev:char1 \ 2218a40db1b3SPeter Maydell-serial chardev:char1 2219a40db1b3SPeter Maydell@end example 2220a40db1b3SPeter Maydell 2221a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2222a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2223a40db1b3SPeter Maydellmultiplexer}. 2224a40db1b3SPeter Maydell 2225a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2226a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2227a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2228a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2229a40db1b3SPeter Maydellstdio. 2230a40db1b3SPeter Maydell 2231a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2232a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 223397331287SJan Kiszka 2234d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2235d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2236d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2237d0d7708bSDaniel P. Berrangeopened. 2238d0d7708bSDaniel P. Berrange 2239d0d7708bSDaniel P. BerrangeFurther options to each backend are described below. 22407273a2dbSMatthew Booth 22417273a2dbSMatthew Booth@item -chardev null ,id=@var{id} 22427273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 22437273a2dbSMatthew Boothreceives. The null backend does not take any options. 22447273a2dbSMatthew Booth 2245a8fb5427SDaniel 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}] 22467273a2dbSMatthew Booth 22477273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 22487273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 22497273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 22507273a2dbSMatthew Booth 22517273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 22527273a2dbSMatthew Booth 22537273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 22547273a2dbSMatthew Boothconnect to a listening socket. 22557273a2dbSMatthew Booth 22567273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 22577273a2dbSMatthew Boothescape sequences. 22587273a2dbSMatthew Booth 22595dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 22605dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 22615dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 22625dd1f02bSCorey Minyard 2263a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2264a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2265a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2266a8fb5427SDaniel P. Berrangeargument. 2267a8fb5427SDaniel P. Berrange 22687273a2dbSMatthew BoothTCP and unix socket options are given below: 22697273a2dbSMatthew Booth 22707273a2dbSMatthew Booth@table @option 22717273a2dbSMatthew Booth 22728d533561SAurelien Jarno@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay] 22737273a2dbSMatthew Booth 22747273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 22757273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 22767273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 22777273a2dbSMatthew Booth 22787273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 22797273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 22807273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 22817273a2dbSMatthew Booth@option{port} is required. 22827273a2dbSMatthew Booth 22837273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 22847273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 22857273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 22867273a2dbSMatthew Boothas a port number. 22877273a2dbSMatthew Booth 22887273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 22897273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 22907273a2dbSMatthew Booth 22917273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 22927273a2dbSMatthew Booth 22937273a2dbSMatthew Booth@item unix options: path=@var{path} 22947273a2dbSMatthew Booth 22957273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 22967273a2dbSMatthew Boothrequired. 22977273a2dbSMatthew Booth 22987273a2dbSMatthew Booth@end table 22997273a2dbSMatthew Booth 23007273a2dbSMatthew Booth@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6] 23017273a2dbSMatthew Booth 23027273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 23037273a2dbSMatthew Booth 23047273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 23057273a2dbSMatthew Boothdefaults to @code{localhost}. 23067273a2dbSMatthew Booth 23077273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 23087273a2dbSMatthew Boothis required. 23097273a2dbSMatthew Booth 23107273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 23117273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 23127273a2dbSMatthew Booth 23137273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 23147273a2dbSMatthew Boothavailable local port will be used. 23157273a2dbSMatthew Booth 23167273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 23177273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 23187273a2dbSMatthew Booth 23197273a2dbSMatthew Booth@item -chardev msmouse ,id=@var{id} 23207273a2dbSMatthew Booth 23217273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 23227273a2dbSMatthew Boothtake any options. 23237273a2dbSMatthew Booth 23247273a2dbSMatthew Booth@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]] 23257273a2dbSMatthew Booth 23267273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 23277273a2dbSMatthew Boothsize. 23287273a2dbSMatthew Booth 23297273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 23307273a2dbSMatthew Booththe console, in pixels. 23317273a2dbSMatthew Booth 23327273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 23337273a2dbSMatthew Boothconsole with the given dimensions. 23347273a2dbSMatthew Booth 23354f57378fSMarkus Armbruster@item -chardev ringbuf ,id=@var{id} [,size=@var{size}] 233651767e7cSLei Li 23373949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 23383949e594SMarkus Armbruster@var{size} must be a power of two, and defaults to @code{64K}). 233951767e7cSLei Li 23407273a2dbSMatthew Booth@item -chardev file ,id=@var{id} ,path=@var{path} 23417273a2dbSMatthew Booth 23427273a2dbSMatthew BoothLog all traffic received from the guest to a file. 23437273a2dbSMatthew Booth 23447273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 23457273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 23467273a2dbSMatthew Boothis required. 23477273a2dbSMatthew Booth 23487273a2dbSMatthew Booth@item -chardev pipe ,id=@var{id} ,path=@var{path} 23497273a2dbSMatthew Booth 23507273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 23517273a2dbSMatthew BoothWindows hosts and other hosts: 23527273a2dbSMatthew Booth 23537273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 23547273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 23557273a2dbSMatthew Booth 23567273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 23577273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 23587273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 23597273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 23607273a2dbSMatthew Boothbe present. 23617273a2dbSMatthew Booth 23627273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 23637273a2dbSMatthew Boothrequired. 23647273a2dbSMatthew Booth 23657273a2dbSMatthew Booth@item -chardev console ,id=@var{id} 23667273a2dbSMatthew Booth 23677273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 23687273a2dbSMatthew Boothtake any options. 23697273a2dbSMatthew Booth 23707273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 23717273a2dbSMatthew Booth 23727273a2dbSMatthew Booth@item -chardev serial ,id=@var{id} ,path=@option{path} 23737273a2dbSMatthew Booth 23747273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 23757273a2dbSMatthew Booth 2376d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 2377d59044efSGerd Hoffmannnot only serial lines. 23787273a2dbSMatthew Booth 23797273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 23807273a2dbSMatthew Booth 23817273a2dbSMatthew Booth@item -chardev pty ,id=@var{id} 23827273a2dbSMatthew Booth 23837273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 23847273a2dbSMatthew Boothnot take any options. 23857273a2dbSMatthew Booth 23867273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 23877273a2dbSMatthew Booth 2388b7fdb3abSAurelien Jarno@item -chardev stdio ,id=@var{id} [,signal=on|off] 2389b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 2390b7fdb3abSAurelien Jarno 2391b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 2392b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2393b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 2394b7fdb3abSAurelien Jarno 2395b7fdb3abSAurelien Jarno@option{stdio} is not available on Windows hosts. 23967273a2dbSMatthew Booth 23977273a2dbSMatthew Booth@item -chardev braille ,id=@var{id} 23987273a2dbSMatthew Booth 23997273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 24007273a2dbSMatthew Booth 24017273a2dbSMatthew Booth@item -chardev tty ,id=@var{id} ,path=@var{path} 24027273a2dbSMatthew Booth 24037273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2404d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 24057273a2dbSMatthew Booth 24067273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 24077273a2dbSMatthew Booth 240888a946d3SGerd Hoffmann@item -chardev parallel ,id=@var{id} ,path=@var{path} 2409f9cfd655SMarkus Armbruster@itemx -chardev parport ,id=@var{id} ,path=@var{path} 24107273a2dbSMatthew Booth 241188a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 24127273a2dbSMatthew Booth 24137273a2dbSMatthew BoothConnect to a local parallel port. 24147273a2dbSMatthew Booth 24157273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 24167273a2dbSMatthew Boothrequired. 24177273a2dbSMatthew Booth 2418cbcc6336SAlon Levy@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2419cbcc6336SAlon Levy 24203a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 24213a846906SStefan Hajnoczi 2422cbcc6336SAlon Levy@option{debug} debug level for spicevmc 2423cbcc6336SAlon Levy 2424cbcc6336SAlon Levy@option{name} name of spice channel to connect to 2425cbcc6336SAlon Levy 2426cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 2427cbcc6336SAlon Levy 24285a49d3e9SMarc-André Lureau@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name} 24295a49d3e9SMarc-André Lureau 24305a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 24315a49d3e9SMarc-André Lureau 24325a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 24335a49d3e9SMarc-André Lureau 24345a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 24355a49d3e9SMarc-André Lureau 24365a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 24375a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 24387273a2dbSMatthew BoothETEXI 24397273a2dbSMatthew Booth 2440c70a01e4SMarkus ArmbrusterSTEXI 2441c70a01e4SMarkus Armbruster@end table 2442c70a01e4SMarkus ArmbrusterETEXI 24437273a2dbSMatthew BoothDEFHEADING() 24447273a2dbSMatthew Booth 24450f5314a2SRonnie SahlbergDEFHEADING(Device URL Syntax:) 2446c70a01e4SMarkus ArmbrusterSTEXI 24470f5314a2SRonnie Sahlberg 24480f5314a2SRonnie SahlbergIn addition to using normal file images for the emulated storage devices, 24490f5314a2SRonnie SahlbergQEMU can also use networked resources such as iSCSI devices. These are 24500f5314a2SRonnie Sahlbergspecified using a special URL syntax. 24510f5314a2SRonnie Sahlberg 24520f5314a2SRonnie Sahlberg@table @option 24530f5314a2SRonnie Sahlberg@item iSCSI 24540f5314a2SRonnie SahlbergiSCSI support allows QEMU to access iSCSI resources directly and use as 24550f5314a2SRonnie Sahlbergimages for the guest storage. Both disk and cdrom images are supported. 24560f5314a2SRonnie Sahlberg 24570f5314a2SRonnie SahlbergSyntax for specifying iSCSI LUNs is 24580f5314a2SRonnie Sahlberg``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' 24590f5314a2SRonnie Sahlberg 246031459f46SRonnie SahlbergBy default qemu will use the iSCSI initiator-name 246131459f46SRonnie Sahlberg'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command 246231459f46SRonnie Sahlbergline or a configuration file. 246331459f46SRonnie Sahlberg 24645dd7a535SPeter LievenSince version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect 24655dd7a535SPeter Lievenstalled requests and force a reestablishment of the session. The timeout 24669049736eSPeter Lievenis specified in seconds. The default is 0 which means no timeout. Libiscsi 24679049736eSPeter Lieven1.15.0 or greater is required for this feature. 246831459f46SRonnie Sahlberg 24690f5314a2SRonnie SahlbergExample (without authentication): 24700f5314a2SRonnie Sahlberg@example 24713804da9dSStefan Weilqemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ 2472f9dadc98SRonnie Sahlberg -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ 2473f9dadc98SRonnie Sahlberg -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 24740f5314a2SRonnie Sahlberg@end example 24750f5314a2SRonnie Sahlberg 24760f5314a2SRonnie SahlbergExample (CHAP username/password via URL): 24770f5314a2SRonnie Sahlberg@example 24783804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 24790f5314a2SRonnie Sahlberg@end example 24800f5314a2SRonnie Sahlberg 24810f5314a2SRonnie SahlbergExample (CHAP username/password via environment variables): 24820f5314a2SRonnie Sahlberg@example 24830f5314a2SRonnie SahlbergLIBISCSI_CHAP_USERNAME="user" \ 24840f5314a2SRonnie SahlbergLIBISCSI_CHAP_PASSWORD="password" \ 24853804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 24860f5314a2SRonnie Sahlberg@end example 24870f5314a2SRonnie Sahlberg 24880f5314a2SRonnie SahlbergiSCSI support is an optional feature of QEMU and only available when 24890f5314a2SRonnie Sahlbergcompiled and linked against libiscsi. 2490f9dadc98SRonnie SahlbergETEXI 2491f9dadc98SRonnie SahlbergDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2492f9dadc98SRonnie Sahlberg "-iscsi [user=user][,password=password]\n" 2493f9dadc98SRonnie Sahlberg " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 24942fe3798cSPaolo Bonzini " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 24955dd7a535SPeter Lieven " [,timeout=timeout]\n" 2496f9dadc98SRonnie Sahlberg " iSCSI session parameters\n", QEMU_ARCH_ALL) 2497f9dadc98SRonnie SahlbergSTEXI 24980f5314a2SRonnie Sahlberg 249931459f46SRonnie SahlbergiSCSI parameters such as username and password can also be specified via 250031459f46SRonnie Sahlberga configuration file. See qemu-doc for more information and examples. 250131459f46SRonnie Sahlberg 250208ae330eSRonnie Sahlberg@item NBD 250308ae330eSRonnie SahlbergQEMU supports NBD (Network Block Devices) both using TCP protocol as well 250408ae330eSRonnie Sahlbergas Unix Domain Sockets. 250508ae330eSRonnie Sahlberg 250608ae330eSRonnie SahlbergSyntax for specifying a NBD device using TCP 250708ae330eSRonnie Sahlberg``nbd:<server-ip>:<port>[:exportname=<export>]'' 250808ae330eSRonnie Sahlberg 250908ae330eSRonnie SahlbergSyntax for specifying a NBD device using Unix Domain Sockets 251008ae330eSRonnie Sahlberg``nbd:unix:<domain-socket>[:exportname=<export>]'' 251108ae330eSRonnie Sahlberg 251208ae330eSRonnie Sahlberg 251308ae330eSRonnie SahlbergExample for TCP 251408ae330eSRonnie Sahlberg@example 25153804da9dSStefan Weilqemu-system-i386 --drive file=nbd:192.0.2.1:30000 251608ae330eSRonnie Sahlberg@end example 251708ae330eSRonnie Sahlberg 251808ae330eSRonnie SahlbergExample for Unix Domain Sockets 251908ae330eSRonnie Sahlberg@example 25203804da9dSStefan Weilqemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket 252108ae330eSRonnie Sahlberg@end example 252208ae330eSRonnie Sahlberg 25230a12ec87SRichard W.M. Jones@item SSH 25240a12ec87SRichard W.M. JonesQEMU supports SSH (Secure Shell) access to remote disks. 25250a12ec87SRichard W.M. Jones 25260a12ec87SRichard W.M. JonesExamples: 25270a12ec87SRichard W.M. Jones@example 25280a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img 25290a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img 25300a12ec87SRichard W.M. Jones@end example 25310a12ec87SRichard W.M. Jones 25320a12ec87SRichard W.M. JonesCurrently authentication must be done using ssh-agent. Other 25330a12ec87SRichard W.M. Jonesauthentication methods may be supported in future. 25340a12ec87SRichard W.M. Jones 2535d9990228SRonnie Sahlberg@item Sheepdog 2536d9990228SRonnie SahlbergSheepdog is a distributed storage system for QEMU. 2537d9990228SRonnie SahlbergQEMU supports using either local sheepdog devices or remote networked 2538d9990228SRonnie Sahlbergdevices. 2539d9990228SRonnie Sahlberg 2540d9990228SRonnie SahlbergSyntax for specifying a sheepdog device 25415d6768e3SMORITA Kazutaka@example 25421b8bbb46SMORITA Kazutakasheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] 25435d6768e3SMORITA Kazutaka@end example 2544d9990228SRonnie Sahlberg 2545d9990228SRonnie SahlbergExample 2546d9990228SRonnie Sahlberg@example 25475d6768e3SMORITA Kazutakaqemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine 2548d9990228SRonnie Sahlberg@end example 2549d9990228SRonnie Sahlberg 2550d9990228SRonnie SahlbergSee also @url{http://http://www.osrg.net/sheepdog/}. 2551d9990228SRonnie Sahlberg 25528809e289SBharata B Rao@item GlusterFS 25538809e289SBharata B RaoGlusterFS is an user space distributed file system. 25548809e289SBharata B RaoQEMU supports the use of GlusterFS volumes for hosting VM disk images using 25558809e289SBharata B RaoTCP, Unix Domain Sockets and RDMA transport protocols. 25568809e289SBharata B Rao 25578809e289SBharata B RaoSyntax for specifying a VM disk image on GlusterFS volume is 25588809e289SBharata B Rao@example 25598809e289SBharata B Raogluster[+transport]://[server[:port]]/volname/image[?socket=...] 25608809e289SBharata B Rao@end example 25618809e289SBharata B Rao 25628809e289SBharata B Rao 25638809e289SBharata B RaoExample 25648809e289SBharata B Rao@example 2565db2d5ebaSLei Liqemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img 25668809e289SBharata B Rao@end example 25678809e289SBharata B Rao 25688809e289SBharata B RaoSee also @url{http://www.gluster.org}. 25690a86cb73SMatthew Booth 25700a86cb73SMatthew Booth@item HTTP/HTTPS/FTP/FTPS/TFTP 25710a86cb73SMatthew BoothQEMU supports read-only access to files accessed over http(s), ftp(s) and tftp. 25720a86cb73SMatthew Booth 25730a86cb73SMatthew BoothSyntax using a single filename: 25740a86cb73SMatthew Booth@example 25750a86cb73SMatthew Booth<protocol>://[<username>[:<password>]@@]<host>/<path> 25760a86cb73SMatthew Booth@end example 25770a86cb73SMatthew Booth 25780a86cb73SMatthew Boothwhere: 25790a86cb73SMatthew Booth@table @option 25800a86cb73SMatthew Booth@item protocol 25810a86cb73SMatthew Booth'http', 'https', 'ftp', 'ftps', or 'tftp'. 25820a86cb73SMatthew Booth 25830a86cb73SMatthew Booth@item username 25840a86cb73SMatthew BoothOptional username for authentication to the remote server. 25850a86cb73SMatthew Booth 25860a86cb73SMatthew Booth@item password 25870a86cb73SMatthew BoothOptional password for authentication to the remote server. 25880a86cb73SMatthew Booth 25890a86cb73SMatthew Booth@item host 25900a86cb73SMatthew BoothAddress of the remote server. 25910a86cb73SMatthew Booth 25920a86cb73SMatthew Booth@item path 25930a86cb73SMatthew BoothPath on the remote server, including any query string. 25940a86cb73SMatthew Booth@end table 25950a86cb73SMatthew Booth 25960a86cb73SMatthew BoothThe following options are also supported: 25970a86cb73SMatthew Booth@table @option 25980a86cb73SMatthew Booth@item url 25990a86cb73SMatthew BoothThe full URL when passing options to the driver explicitly. 26000a86cb73SMatthew Booth 26010a86cb73SMatthew Booth@item readahead 26020a86cb73SMatthew BoothThe amount of data to read ahead with each range request to the remote server. 26030a86cb73SMatthew BoothThis value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it 26040a86cb73SMatthew Boothdoes not have a suffix, it will be assumed to be in bytes. The value must be a 26050a86cb73SMatthew Boothmultiple of 512 bytes. It defaults to 256k. 26060a86cb73SMatthew Booth 26070a86cb73SMatthew Booth@item sslverify 26080a86cb73SMatthew BoothWhether to verify the remote server's certificate when connecting over SSL. It 26090a86cb73SMatthew Boothcan have the value 'on' or 'off'. It defaults to 'on'. 2610212aefaaSDaniel Henrique Barboza 2611a94f83d9SRichard W.M. Jones@item cookie 2612a94f83d9SRichard W.M. JonesSend this cookie (it can also be a list of cookies separated by ';') with 2613a94f83d9SRichard W.M. Joneseach outgoing request. Only supported when using protocols such as HTTP 2614a94f83d9SRichard W.M. Joneswhich support cookies, otherwise ignored. 2615a94f83d9SRichard W.M. Jones 2616212aefaaSDaniel Henrique Barboza@item timeout 2617212aefaaSDaniel Henrique BarbozaSet the timeout in seconds of the CURL connection. This timeout is the time 2618212aefaaSDaniel Henrique Barbozathat CURL waits for a response from the remote server to get the size of the 2619212aefaaSDaniel Henrique Barbozaimage to be downloaded. If not set, the default timeout of 5 seconds is used. 26200a86cb73SMatthew Booth@end table 26210a86cb73SMatthew Booth 26220a86cb73SMatthew BoothNote that when passing options to qemu explicitly, @option{driver} is the value 26230a86cb73SMatthew Boothof <protocol>. 26240a86cb73SMatthew Booth 26250a86cb73SMatthew BoothExample: boot from a remote Fedora 20 live ISO image 26260a86cb73SMatthew Booth@example 26270a86cb73SMatthew 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 26280a86cb73SMatthew Booth 26290a86cb73SMatthew 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 26300a86cb73SMatthew Booth@end example 26310a86cb73SMatthew Booth 26320a86cb73SMatthew BoothExample: boot from a remote Fedora 20 cloud image using a local overlay for 26330a86cb73SMatthew Boothwrites, copy-on-read, and a readahead of 64k 26340a86cb73SMatthew Booth@example 26350a86cb73SMatthew 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 26360a86cb73SMatthew Booth 26370a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on 26380a86cb73SMatthew Booth@end example 26390a86cb73SMatthew Booth 26400a86cb73SMatthew BoothExample: boot from an image stored on a VMware vSphere server with a self-signed 2641212aefaaSDaniel Henrique Barbozacertificate using a local overlay for writes, a readahead of 64k and a timeout 2642212aefaaSDaniel Henrique Barbozaof 10 seconds. 26430a86cb73SMatthew Booth@example 2644212aefaaSDaniel 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 26450a86cb73SMatthew Booth 26460a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/test.qcow2 26470a86cb73SMatthew Booth@end example 2648c70a01e4SMarkus ArmbrusterETEXI 2649c70a01e4SMarkus Armbruster 2650c70a01e4SMarkus ArmbrusterSTEXI 26510f5314a2SRonnie Sahlberg@end table 26520f5314a2SRonnie SahlbergETEXI 26530f5314a2SRonnie Sahlberg 26547273a2dbSMatthew BoothDEFHEADING(Bluetooth(R) options:) 2655c70a01e4SMarkus ArmbrusterSTEXI 2656c70a01e4SMarkus Armbruster@table @option 2657c70a01e4SMarkus ArmbrusterETEXI 26587273a2dbSMatthew Booth 26595824d651Sblueswir1DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 26605824d651Sblueswir1 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 26615824d651Sblueswir1 "-bt hci,host[:id]\n" \ 26625824d651Sblueswir1 " use host's HCI with the given name\n" \ 26635824d651Sblueswir1 "-bt hci[,vlan=n]\n" \ 26645824d651Sblueswir1 " emulate a standard HCI in virtual scatternet 'n'\n" \ 26655824d651Sblueswir1 "-bt vhci[,vlan=n]\n" \ 26665824d651Sblueswir1 " add host computer to virtual scatternet 'n' using VHCI\n" \ 26675824d651Sblueswir1 "-bt device:dev[,vlan=n]\n" \ 2668ad96090aSBlue Swirl " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2669ad96090aSBlue Swirl QEMU_ARCH_ALL) 26705824d651Sblueswir1STEXI 26715824d651Sblueswir1@item -bt hci[...] 26726616b2adSStefan Weil@findex -bt 26735824d651Sblueswir1Defines the function of the corresponding Bluetooth HCI. -bt options 26745824d651Sblueswir1are matched with the HCIs present in the chosen machine type. For 26755824d651Sblueswir1example when emulating a machine with only one HCI built into it, only 26765824d651Sblueswir1the first @code{-bt hci[...]} option is valid and defines the HCI's 26775824d651Sblueswir1logic. The Transport Layer is decided by the machine type. Currently 26785824d651Sblueswir1the machines @code{n800} and @code{n810} have one HCI and all other 26795824d651Sblueswir1machines have none. 26805824d651Sblueswir1 26815824d651Sblueswir1@anchor{bt-hcis} 26825824d651Sblueswir1The following three types are recognized: 26835824d651Sblueswir1 2684b3f046c2SKevin Wolf@table @option 26855824d651Sblueswir1@item -bt hci,null 26865824d651Sblueswir1(default) The corresponding Bluetooth HCI assumes no internal logic 26875824d651Sblueswir1and will not respond to any HCI commands or emit events. 26885824d651Sblueswir1 26895824d651Sblueswir1@item -bt hci,host[:@var{id}] 26905824d651Sblueswir1(@code{bluez} only) The corresponding HCI passes commands / events 26915824d651Sblueswir1to / from the physical HCI identified by the name @var{id} (default: 26925824d651Sblueswir1@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 26935824d651Sblueswir1capable systems like Linux. 26945824d651Sblueswir1 26955824d651Sblueswir1@item -bt hci[,vlan=@var{n}] 26965824d651Sblueswir1Add a virtual, standard HCI that will participate in the Bluetooth 26975824d651Sblueswir1scatternet @var{n} (default @code{0}). Similarly to @option{-net} 26985824d651Sblueswir1VLANs, devices inside a bluetooth network @var{n} can only communicate 26995824d651Sblueswir1with other devices in the same network (scatternet). 27005824d651Sblueswir1@end table 27015824d651Sblueswir1 27025824d651Sblueswir1@item -bt vhci[,vlan=@var{n}] 27035824d651Sblueswir1(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 27045824d651Sblueswir1to the host bluetooth stack instead of to the emulated target. This 27055824d651Sblueswir1allows the host and target machines to participate in a common scatternet 27065824d651Sblueswir1and communicate. Requires the Linux @code{vhci} driver installed. Can 27075824d651Sblueswir1be used as following: 27085824d651Sblueswir1 27095824d651Sblueswir1@example 27103804da9dSStefan Weilqemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 27115824d651Sblueswir1@end example 27125824d651Sblueswir1 27135824d651Sblueswir1@item -bt device:@var{dev}[,vlan=@var{n}] 27145824d651Sblueswir1Emulate a bluetooth device @var{dev} and place it in network @var{n} 27155824d651Sblueswir1(default @code{0}). QEMU can only emulate one type of bluetooth devices 27165824d651Sblueswir1currently: 27175824d651Sblueswir1 2718b3f046c2SKevin Wolf@table @option 27195824d651Sblueswir1@item keyboard 27205824d651Sblueswir1Virtual wireless keyboard implementing the HIDP bluetooth profile. 27215824d651Sblueswir1@end table 27225824d651Sblueswir1ETEXI 27235824d651Sblueswir1 2724c70a01e4SMarkus ArmbrusterSTEXI 2725c70a01e4SMarkus Armbruster@end table 2726c70a01e4SMarkus ArmbrusterETEXI 27275824d651Sblueswir1DEFHEADING() 27285824d651Sblueswir1 2729d1a0cf73SStefan Berger#ifdef CONFIG_TPM 2730d1a0cf73SStefan BergerDEFHEADING(TPM device options:) 2731d1a0cf73SStefan Berger 2732d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 273392dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 273492dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 273592dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 273692dcc234SStefan Berger " not provided it will be searched for in /sys/class/misc/tpm?/device\n", 2737d1a0cf73SStefan Berger QEMU_ARCH_ALL) 2738d1a0cf73SStefan BergerSTEXI 2739d1a0cf73SStefan Berger 2740d1a0cf73SStefan BergerThe general form of a TPM device option is: 2741d1a0cf73SStefan Berger@table @option 2742d1a0cf73SStefan Berger 2743d1a0cf73SStefan Berger@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] 2744d1a0cf73SStefan Berger@findex -tpmdev 2745d1a0cf73SStefan BergerBackend type must be: 27464549a8b7SStefan Berger@option{passthrough}. 2747d1a0cf73SStefan Berger 2748d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 274928c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 275028c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 2751d1a0cf73SStefan Berger 2752d1a0cf73SStefan BergerOptions to each backend are described below. 2753d1a0cf73SStefan Berger 2754d1a0cf73SStefan BergerUse 'help' to print all available TPM backend types. 2755d1a0cf73SStefan Berger@example 2756d1a0cf73SStefan Bergerqemu -tpmdev help 2757d1a0cf73SStefan Berger@end example 2758d1a0cf73SStefan Berger 275992dcc234SStefan Berger@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path} 27604549a8b7SStefan Berger 27614549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 27624549a8b7SStefan Bergerdriver. 27634549a8b7SStefan Berger 27644549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 27654549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 27664549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 27674549a8b7SStefan Berger 276892dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 276992dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 277092dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 277192dcc234SStefan Bergersysfs entry to use. 277292dcc234SStefan Berger 27734549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 27744549a8b7SStefan Berger 27754549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 27764549a8b7SStefan Bergerused by any other application on the host. 27774549a8b7SStefan Berger 27784549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 27794549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 27804549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 27814549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 27824549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 27834549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 27844549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 27854549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 27864549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 27874549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 27884549a8b7SStefan Berger 27894549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 27904549a8b7SStefan Berger@example 27914549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 27924549a8b7SStefan Berger@end example 27934549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 27944549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 27954549a8b7SStefan Berger 2796d1a0cf73SStefan Berger@end table 2797d1a0cf73SStefan Berger 2798d1a0cf73SStefan BergerETEXI 2799d1a0cf73SStefan Berger 2800d1a0cf73SStefan BergerDEFHEADING() 2801d1a0cf73SStefan Berger 2802d1a0cf73SStefan Berger#endif 2803d1a0cf73SStefan Berger 28047677f05dSAlexander GrafDEFHEADING(Linux/Multiboot boot specific:) 28055824d651Sblueswir1STEXI 28067677f05dSAlexander Graf 28077677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 28087677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 28095824d651Sblueswir1for easier testing of various kernels. 28105824d651Sblueswir1 28115824d651Sblueswir1@table @option 28125824d651Sblueswir1ETEXI 28135824d651Sblueswir1 28145824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2815ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 28165824d651Sblueswir1STEXI 28175824d651Sblueswir1@item -kernel @var{bzImage} 28186616b2adSStefan Weil@findex -kernel 28197677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 28207677f05dSAlexander Grafor in multiboot format. 28215824d651Sblueswir1ETEXI 28225824d651Sblueswir1 28235824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 2824ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 28255824d651Sblueswir1STEXI 28265824d651Sblueswir1@item -append @var{cmdline} 28276616b2adSStefan Weil@findex -append 28285824d651Sblueswir1Use @var{cmdline} as kernel command line 28295824d651Sblueswir1ETEXI 28305824d651Sblueswir1 28315824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 2832ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 28335824d651Sblueswir1STEXI 28345824d651Sblueswir1@item -initrd @var{file} 28356616b2adSStefan Weil@findex -initrd 28365824d651Sblueswir1Use @var{file} as initial ram disk. 28377677f05dSAlexander Graf 28387677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 28397677f05dSAlexander Graf 28407677f05dSAlexander GrafThis syntax is only available with multiboot. 28417677f05dSAlexander Graf 28427677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 28437677f05dSAlexander Graffirst module. 28445824d651Sblueswir1ETEXI 28455824d651Sblueswir1 2846412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 2847379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 2848412beee6SGrant LikelySTEXI 2849412beee6SGrant Likely@item -dtb @var{file} 2850412beee6SGrant Likely@findex -dtb 2851412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 2852412beee6SGrant Likelyon boot. 2853412beee6SGrant LikelyETEXI 2854412beee6SGrant Likely 28555824d651Sblueswir1STEXI 28565824d651Sblueswir1@end table 28575824d651Sblueswir1ETEXI 28585824d651Sblueswir1DEFHEADING() 28595824d651Sblueswir1 28605824d651Sblueswir1DEFHEADING(Debug/Expert options:) 28615824d651Sblueswir1STEXI 28625824d651Sblueswir1@table @option 28635824d651Sblueswir1ETEXI 28645824d651Sblueswir1 286581b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 286681b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 28676407d76eSGabriel L. Somlo " add named fw_cfg entry from file\n" 28686407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 28696407d76eSGabriel L. Somlo " add named fw_cfg entry from string\n", 287081b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 287181b2b810SGabriel L. SomloSTEXI 287281b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 287381b2b810SGabriel L. Somlo@findex -fw_cfg 287481b2b810SGabriel L. SomloAdd named fw_cfg entry from file. @var{name} determines the name of 287581b2b810SGabriel L. Somlothe entry in the fw_cfg file directory exposed to the guest. 28766407d76eSGabriel L. Somlo 28776407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 28786407d76eSGabriel L. SomloAdd named fw_cfg entry from string. 287981b2b810SGabriel L. SomloETEXI 288081b2b810SGabriel L. Somlo 28815824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 2882ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 2883ad96090aSBlue Swirl QEMU_ARCH_ALL) 28845824d651Sblueswir1STEXI 28855824d651Sblueswir1@item -serial @var{dev} 28866616b2adSStefan Weil@findex -serial 28875824d651Sblueswir1Redirect the virtual serial port to host character device 28885824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 28895824d651Sblueswir1@code{stdio} in non graphical mode. 28905824d651Sblueswir1 28915824d651Sblueswir1This option can be used several times to simulate up to 4 serial 28925824d651Sblueswir1ports. 28935824d651Sblueswir1 28945824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 28955824d651Sblueswir1 28965824d651Sblueswir1Available character devices are: 2897b3f046c2SKevin Wolf@table @option 28984e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 28995824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 29005824d651Sblueswir1@example 29015824d651Sblueswir1vc:800x600 29025824d651Sblueswir1@end example 29035824d651Sblueswir1It is also possible to specify width or height in characters: 29045824d651Sblueswir1@example 29055824d651Sblueswir1vc:80Cx24C 29065824d651Sblueswir1@end example 29075824d651Sblueswir1@item pty 29085824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 29095824d651Sblueswir1@item none 29105824d651Sblueswir1No device is allocated. 29115824d651Sblueswir1@item null 29125824d651Sblueswir1void device 291388e020e5SIngo van Lil@item chardev:@var{id} 291488e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 29155824d651Sblueswir1@item /dev/XXX 29165824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 29175824d651Sblueswir1parameters are set according to the emulated ones. 29185824d651Sblueswir1@item /dev/parport@var{N} 29195824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 29205824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 29215824d651Sblueswir1@item file:@var{filename} 29225824d651Sblueswir1Write output to @var{filename}. No character can be read. 29235824d651Sblueswir1@item stdio 29245824d651Sblueswir1[Unix only] standard input/output 29255824d651Sblueswir1@item pipe:@var{filename} 29265824d651Sblueswir1name pipe @var{filename} 29275824d651Sblueswir1@item COM@var{n} 29285824d651Sblueswir1[Windows only] Use host serial port @var{n} 29295824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 29305824d651Sblueswir1This implements UDP Net Console. 29315824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 29325824d651Sblueswir1they default to @code{0.0.0.0}. 29335824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 29345824d651Sblueswir1 29355824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 2936b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 2937b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 29385824d651Sblueswir1will appear in the netconsole session. 29395824d651Sblueswir1 29405824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 2941b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 29425824d651Sblueswir1source port each time by using something like @code{-serial 2943b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 29445824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 29455824d651Sblueswir1characters via udp. If you have a patched version of netcat which 29465824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 29475824d651Sblueswir1use the following options to step up a netcat redirector to allow 2948b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 29495824d651Sblueswir1@table @code 2950071c9394SStefan Weil@item QEMU Options: 29515824d651Sblueswir1-serial udp::4555@@:4556 29525824d651Sblueswir1@item netcat options: 29535824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 29545824d651Sblueswir1@item telnet options: 29555824d651Sblueswir1localhost 5555 29565824d651Sblueswir1@end table 29575824d651Sblueswir1 29585dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 29595824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 29605824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 29615824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 29625824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 29635824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 29645824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 29655dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 29665dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 29675dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 29685824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 29695824d651Sblueswir1connect to the corresponding character device. 29705824d651Sblueswir1@table @code 29715824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 29725824d651Sblueswir1-serial tcp:192.168.0.2:4444 29735824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 29745824d651Sblueswir1-serial tcp::4444,server 29755824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 29765824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 29775824d651Sblueswir1@end table 29785824d651Sblueswir1 29795824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 29805824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 29815824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 29825824d651Sblueswir1difference is that the port acts like a telnet server or client using 29835824d651Sblueswir1telnet option negotiation. This will also allow you to send the 29845824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 29855824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 29865824d651Sblueswir1type "send break" followed by pressing the enter key. 29875824d651Sblueswir1 29885dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 29895824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 29905824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 29915824d651Sblueswir1@var{path} is used for connections. 29925824d651Sblueswir1 29935824d651Sblueswir1@item mon:@var{dev_string} 29945824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 29955824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 299602c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 29975824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 29985824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 29995824d651Sblueswir1listening on port 4444 would be: 30005824d651Sblueswir1@table @code 30015824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 30025824d651Sblueswir1@end table 3003be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 300402c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 30055824d651Sblueswir1 30065824d651Sblueswir1@item braille 30075824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 30085824d651Sblueswir1or fake device. 30095824d651Sblueswir1 3010be8b28a9SKevin Wolf@item msmouse 3011be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 30125824d651Sblueswir1@end table 30135824d651Sblueswir1ETEXI 30145824d651Sblueswir1 30155824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3016ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3017ad96090aSBlue Swirl QEMU_ARCH_ALL) 30185824d651Sblueswir1STEXI 30195824d651Sblueswir1@item -parallel @var{dev} 30206616b2adSStefan Weil@findex -parallel 30215824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 30225824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 30235824d651Sblueswir1be used to use hardware devices connected on the corresponding host 30245824d651Sblueswir1parallel port. 30255824d651Sblueswir1 30265824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 30275824d651Sblueswir1ports. 30285824d651Sblueswir1 30295824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 30305824d651Sblueswir1ETEXI 30315824d651Sblueswir1 30325824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3033ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3034ad96090aSBlue Swirl QEMU_ARCH_ALL) 30355824d651Sblueswir1STEXI 30364e307fc8SGerd Hoffmann@item -monitor @var{dev} 30376616b2adSStefan Weil@findex -monitor 30385824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 30395824d651Sblueswir1serial port). 30405824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 30415824d651Sblueswir1non graphical mode. 304270e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 30435824d651Sblueswir1ETEXI 30446ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3045ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3046ad96090aSBlue Swirl QEMU_ARCH_ALL) 304795d5f08bSStefan WeilSTEXI 304895d5f08bSStefan Weil@item -qmp @var{dev} 30496616b2adSStefan Weil@findex -qmp 305095d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 305195d5f08bSStefan WeilETEXI 30524821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 30534821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 30544821cd4cSMax Reitz QEMU_ARCH_ALL) 30554821cd4cSMax ReitzSTEXI 30564821cd4cSMax Reitz@item -qmp-pretty @var{dev} 30574821cd4cSMax Reitz@findex -qmp-pretty 30584821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 30594821cd4cSMax ReitzETEXI 30605824d651Sblueswir1 306122a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3062f17e4eaaSMichael Tokarev "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL) 306322a0e04bSGerd HoffmannSTEXI 3064f17e4eaaSMichael Tokarev@item -mon [chardev=]name[,mode=readline|control][,default] 30656616b2adSStefan Weil@findex -mon 306622a0e04bSGerd HoffmannSetup monitor on chardev @var{name}. 306722a0e04bSGerd HoffmannETEXI 306822a0e04bSGerd Hoffmann 3069c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3070ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3071ad96090aSBlue Swirl QEMU_ARCH_ALL) 3072c9f398e5SH. Peter AnvinSTEXI 3073c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 30746616b2adSStefan Weil@findex -debugcon 3075c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3076c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3077c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3078c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3079c9f398e5SH. Peter Anvinnon graphical mode. 3080c9f398e5SH. Peter AnvinETEXI 3081c9f398e5SH. Peter Anvin 30825824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3083ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 30845824d651Sblueswir1STEXI 30855824d651Sblueswir1@item -pidfile @var{file} 30866616b2adSStefan Weil@findex -pidfile 30875824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 30885824d651Sblueswir1from a script. 30895824d651Sblueswir1ETEXI 30905824d651Sblueswir1 30911b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3092ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 30931b530a6dSaurel32STEXI 30941b530a6dSaurel32@item -singlestep 30956616b2adSStefan Weil@findex -singlestep 30961b530a6dSaurel32Run the emulation in single step mode. 30971b530a6dSaurel32ETEXI 30981b530a6dSaurel32 30995824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3100ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3101ad96090aSBlue Swirl QEMU_ARCH_ALL) 31025824d651Sblueswir1STEXI 31035824d651Sblueswir1@item -S 31046616b2adSStefan Weil@findex -S 31055824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 31065824d651Sblueswir1ETEXI 31075824d651Sblueswir1 3108888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3109888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3110888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3111888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3112888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3113888a6bc6SSatoru MoriyaSTEXI 3114888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3115888a6bc6SSatoru Moriya@findex -realtime 3116888a6bc6SSatoru MoriyaRun qemu with realtime features. 3117888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3118888a6bc6SSatoru Moriya(enabled by default). 3119888a6bc6SSatoru MoriyaETEXI 3120888a6bc6SSatoru Moriya 312159030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3122ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 31235824d651Sblueswir1STEXI 312459030a8cSaliguori@item -gdb @var{dev} 31256616b2adSStefan Weil@findex -gdb 312659030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 312759030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3128b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 312959030a8cSaliguoriwithin gdb and establish the connection via a pipe: 313059030a8cSaliguori@example 31313804da9dSStefan Weil(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 313259030a8cSaliguori@end example 31335824d651Sblueswir1ETEXI 31345824d651Sblueswir1 313559030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3136ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3137ad96090aSBlue Swirl QEMU_ARCH_ALL) 31385824d651Sblueswir1STEXI 313959030a8cSaliguori@item -s 31406616b2adSStefan Weil@findex -s 314159030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 314259030a8cSaliguori(@pxref{gdb_usage}). 31435824d651Sblueswir1ETEXI 31445824d651Sblueswir1 31455824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3146989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3147ad96090aSBlue Swirl QEMU_ARCH_ALL) 31485824d651Sblueswir1STEXI 3149989b697dSPeter Maydell@item -d @var{item1}[,...] 31506616b2adSStefan Weil@findex -d 3151989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 31525824d651Sblueswir1ETEXI 31535824d651Sblueswir1 3154c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3155989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3156c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3157c235d738SMatthew FernandezSTEXI 31588bd383b4SStefan Weil@item -D @var{logfile} 3159c235d738SMatthew Fernandez@findex -D 3160989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3161c235d738SMatthew FernandezETEXI 3162c235d738SMatthew Fernandez 31633514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 31643514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 31653514552eSAlex Bennée QEMU_ARCH_ALL) 31663514552eSAlex BennéeSTEXI 31673514552eSAlex Bennée@item -dfilter @var{range1}[,...] 31683514552eSAlex Bennée@findex -dfilter 31693514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 31703514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 31713514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 31723514552eSAlex Bennéeaddresses and sizes required. For example: 31733514552eSAlex Bennée@example 31743514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 31753514552eSAlex Bennée@end example 31763514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 31773514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 31783514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 31793514552eSAlex BennéeETEXI 31803514552eSAlex Bennée 31815824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3182ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3183ad96090aSBlue Swirl QEMU_ARCH_ALL) 31845824d651Sblueswir1STEXI 31855824d651Sblueswir1@item -L @var{path} 31866616b2adSStefan Weil@findex -L 31875824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 31885824d651Sblueswir1ETEXI 31895824d651Sblueswir1 31905824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3191ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 31925824d651Sblueswir1STEXI 31935824d651Sblueswir1@item -bios @var{file} 31946616b2adSStefan Weil@findex -bios 31955824d651Sblueswir1Set the filename for the BIOS. 31965824d651Sblueswir1ETEXI 31975824d651Sblueswir1 31985824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3199ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 32005824d651Sblueswir1STEXI 32015824d651Sblueswir1@item -enable-kvm 32026616b2adSStefan Weil@findex -enable-kvm 32035824d651Sblueswir1Enable KVM full virtualization support. This option is only available 32045824d651Sblueswir1if KVM support is enabled when compiling. 32055824d651Sblueswir1ETEXI 32065824d651Sblueswir1 3207e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3208ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3209e37630caSaliguoriDEF("xen-create", 0, QEMU_OPTION_xen_create, 3210e37630caSaliguori "-xen-create create domain using xen hypercalls, bypassing xend\n" 3211ad96090aSBlue Swirl " warning: should not be used when xend is in use\n", 3212ad96090aSBlue Swirl QEMU_ARCH_ALL) 3213e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3214e37630caSaliguori "-xen-attach attach to existing xen domain\n" 3215b65ee4faSStefan Weil " xend will use this when starting QEMU\n", 3216ad96090aSBlue Swirl QEMU_ARCH_ALL) 321795d5f08bSStefan WeilSTEXI 321895d5f08bSStefan Weil@item -xen-domid @var{id} 32196616b2adSStefan Weil@findex -xen-domid 322095d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 322195d5f08bSStefan Weil@item -xen-create 32226616b2adSStefan Weil@findex -xen-create 322395d5f08bSStefan WeilCreate domain using xen hypercalls, bypassing xend. 322495d5f08bSStefan WeilWarning: should not be used when xend is in use (XEN only). 322595d5f08bSStefan Weil@item -xen-attach 32266616b2adSStefan Weil@findex -xen-attach 322795d5f08bSStefan WeilAttach to existing xen domain. 3228b65ee4faSStefan Weilxend will use this when starting QEMU (XEN only). 322995d5f08bSStefan WeilETEXI 3230e37630caSaliguori 32315824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3232ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 32335824d651Sblueswir1STEXI 32345824d651Sblueswir1@item -no-reboot 32356616b2adSStefan Weil@findex -no-reboot 32365824d651Sblueswir1Exit instead of rebooting. 32375824d651Sblueswir1ETEXI 32385824d651Sblueswir1 32395824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3240ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 32415824d651Sblueswir1STEXI 32425824d651Sblueswir1@item -no-shutdown 32436616b2adSStefan Weil@findex -no-shutdown 32445824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 32455824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 32465824d651Sblueswir1disk image. 32475824d651Sblueswir1ETEXI 32485824d651Sblueswir1 32495824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 32505824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3251ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3252ad96090aSBlue Swirl QEMU_ARCH_ALL) 32535824d651Sblueswir1STEXI 32545824d651Sblueswir1@item -loadvm @var{file} 32556616b2adSStefan Weil@findex -loadvm 32565824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 32575824d651Sblueswir1ETEXI 32585824d651Sblueswir1 32595824d651Sblueswir1#ifndef _WIN32 32605824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3261ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 32625824d651Sblueswir1#endif 32635824d651Sblueswir1STEXI 32645824d651Sblueswir1@item -daemonize 32656616b2adSStefan Weil@findex -daemonize 32665824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 32675824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 32685824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 32695824d651Sblueswir1to cope with initialization race conditions. 32705824d651Sblueswir1ETEXI 32715824d651Sblueswir1 32725824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3273ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3274ad96090aSBlue Swirl QEMU_ARCH_ALL) 32755824d651Sblueswir1STEXI 32765824d651Sblueswir1@item -option-rom @var{file} 32776616b2adSStefan Weil@findex -option-rom 32785824d651Sblueswir1Load the contents of @var{file} as an option ROM. 32795824d651Sblueswir1This option is useful to load things like EtherBoot. 32805824d651Sblueswir1ETEXI 32815824d651Sblueswir1 3282e218052fSMarkus ArmbrusterHXCOMM Silently ignored for compatibility 3283e218052fSMarkus ArmbrusterDEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL) 32845824d651Sblueswir1 32851ed2fc1fSJan KiszkaHXCOMM Options deprecated by -rtc 3286ad96090aSBlue SwirlDEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 3287ad96090aSBlue SwirlDEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 32885824d651Sblueswir1 32891ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 329078808141SPaolo Bonzini "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3291ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3292ad96090aSBlue Swirl QEMU_ARCH_ALL) 32931ed2fc1fSJan Kiszka 32945824d651Sblueswir1STEXI 32955824d651Sblueswir1 32966875204cSJan Kiszka@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 32976616b2adSStefan Weil@findex -rtc 32981ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 32991ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 33001ed2fc1fSJan KiszkaMS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 33011ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 33021ed2fc1fSJan Kiszka 33039d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 33046875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 33056875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 330678808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 330778808141SPaolo Bonzinito @code{rt} instead. To even prevent it from progressing during suspension, 330878808141SPaolo Bonziniyou can set it to @code{vm}. 33096875204cSJan Kiszka 33101ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 33111ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 33121ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 33131ed2fc1fSJan Kiszkare-inject them. 33145824d651Sblueswir1ETEXI 33155824d651Sblueswir1 33165824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 3317778d9f9bSPranith Kumar "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>]\n" \ 3318bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3319f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3320f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 33215824d651Sblueswir1STEXI 33224c27b859SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename}] 33236616b2adSStefan Weil@findex -icount 33245824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 33254e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 33265824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 33275824d651Sblueswir1time within a few seconds of real time. 33285824d651Sblueswir1 3329f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3330778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3331778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3332f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3333f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3334f1f4b57eSVictor CLEMENTthe guest point of view. 3335f1f4b57eSVictor CLEMENT 33365824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 33375824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 33385824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 33395824d651Sblueswir1executed often has little or no correlation with actual performance. 3340a8bfac37SSebastian Tanase 3341b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3342a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3343a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3344a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 334582597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3346a8bfac37SSebastian Tanaseto inform about the delay. 3347a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3348a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3349a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3350a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 33514c27b859SPavel Dovgalyuk 33524c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 33534c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 33544c27b859SPavel Dovgalyukread from this file in replay mode. 33555824d651Sblueswir1ETEXI 33565824d651Sblueswir1 33579dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3358d7933ef3SXu Wang "-watchdog model\n" \ 3359ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3360ad96090aSBlue Swirl QEMU_ARCH_ALL) 33619dd986ccSRichard W.M. JonesSTEXI 33629dd986ccSRichard W.M. Jones@item -watchdog @var{model} 33636616b2adSStefan Weil@findex -watchdog 33649dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 33659dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3366d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3367d7933ef3SXu Wangwhich your guest has drivers. 33689dd986ccSRichard W.M. Jones 3369d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3370d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 33719dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3372d7933ef3SXu Wang 3373d7933ef3SXu WangThe following models may be available: 3374d7933ef3SXu Wang@table @option 3375d7933ef3SXu Wang@item ib700 3376d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3377d7933ef3SXu Wang@item i6300esb 3378d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3379d7933ef3SXu Wangdual-timer watchdog. 3380188f24c2SXu Wang@item diag288 3381188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3382188f24c2SXu Wang(currently KVM only). 3383d7933ef3SXu Wang@end table 33849dd986ccSRichard W.M. JonesETEXI 33859dd986ccSRichard W.M. Jones 33869dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 33879dd986ccSRichard W.M. Jones "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \ 3388ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3389ad96090aSBlue Swirl QEMU_ARCH_ALL) 33909dd986ccSRichard W.M. JonesSTEXI 33919dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3392b8f490ebSMarkus Armbruster@findex -watchdog-action 33939dd986ccSRichard W.M. Jones 33949dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 33959dd986ccSRichard W.M. Jonesexpires. 33969dd986ccSRichard W.M. JonesThe default is 33979dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 33989dd986ccSRichard W.M. JonesOther possible actions are: 33999dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 34009dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 34019dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 34029dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 34039dd986ccSRichard W.M. Jones@code{none} (do nothing). 34049dd986ccSRichard W.M. Jones 34059dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 34069dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 34079dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 34089dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 34099dd986ccSRichard W.M. Jones 34109dd986ccSRichard W.M. JonesExamples: 34119dd986ccSRichard W.M. Jones 34129dd986ccSRichard W.M. Jones@table @code 34139dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3414f9cfd655SMarkus Armbruster@itemx -watchdog ib700 34159dd986ccSRichard W.M. Jones@end table 34169dd986ccSRichard W.M. JonesETEXI 34179dd986ccSRichard W.M. Jones 34185824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3419ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3420ad96090aSBlue Swirl QEMU_ARCH_ALL) 34215824d651Sblueswir1STEXI 34225824d651Sblueswir1 34234e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 34246616b2adSStefan Weil@findex -echr 34255824d651Sblueswir1Change the escape character used for switching to the monitor when using 34265824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 34275824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 34285824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 34295824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 34305824d651Sblueswir1instance you could use the either of the following to change the escape 34315824d651Sblueswir1character to Control-t. 34325824d651Sblueswir1@table @code 34335824d651Sblueswir1@item -echr 0x14 3434f9cfd655SMarkus Armbruster@itemx -echr 20 34355824d651Sblueswir1@end table 34365824d651Sblueswir1ETEXI 34375824d651Sblueswir1 34385824d651Sblueswir1DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 34395824d651Sblueswir1 "-virtioconsole c\n" \ 3440ad96090aSBlue Swirl " set virtio console\n", QEMU_ARCH_ALL) 34415824d651Sblueswir1STEXI 34425824d651Sblueswir1@item -virtioconsole @var{c} 34436616b2adSStefan Weil@findex -virtioconsole 34445824d651Sblueswir1Set virtio console. 344598b19252SAmit Shah 344698b19252SAmit ShahThis option is maintained for backward compatibility. 344798b19252SAmit Shah 344898b19252SAmit ShahPlease use @code{-device virtconsole} for the new way of invocation. 34495824d651Sblueswir1ETEXI 34505824d651Sblueswir1 34515824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3452ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 34535824d651Sblueswir1STEXI 345495d5f08bSStefan Weil@item -show-cursor 34556616b2adSStefan Weil@findex -show-cursor 345695d5f08bSStefan WeilShow cursor. 34575824d651Sblueswir1ETEXI 34585824d651Sblueswir1 34595824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3460ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 34615824d651Sblueswir1STEXI 346295d5f08bSStefan Weil@item -tb-size @var{n} 34636616b2adSStefan Weil@findex -tb-size 346495d5f08bSStefan WeilSet TB size. 34655824d651Sblueswir1ETEXI 34665824d651Sblueswir1 34675824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 34687c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 34697c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 34707c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 34717c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 34727c601803SMichael Tokarev " specified protocol and socket address\n" \ 34737c601803SMichael Tokarev "-incoming fd:fd\n" \ 34747c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 34757c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 34761597051bSDr. David Alan Gilbert " or from given external command\n" \ 34771597051bSDr. David Alan Gilbert "-incoming defer\n" \ 34781597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 3479ad96090aSBlue Swirl QEMU_ARCH_ALL) 34805824d651Sblueswir1STEXI 34817c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3482f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 34836616b2adSStefan Weil@findex -incoming 34847c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 34857c601803SMichael Tokarev 34867c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 34877c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 34887c601803SMichael Tokarev 34897c601803SMichael Tokarev@item -incoming fd:@var{fd} 34907c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 34917c601803SMichael Tokarev 34927c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 34937c601803SMichael TokarevAccept incoming migration as an output from specified external command. 34941597051bSDr. David Alan Gilbert 34951597051bSDr. David Alan Gilbert@item -incoming defer 34961597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 34971597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 34981597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 34995824d651Sblueswir1ETEXI 35005824d651Sblueswir1 3501d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3502ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3503d8c208ddSGerd HoffmannSTEXI 35043dbf2c7fSStefan Weil@item -nodefaults 35056616b2adSStefan Weil@findex -nodefaults 350666c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 350766c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 350866c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 350966c19bf1SMichal Novotnydefault devices. 3510d8c208ddSGerd HoffmannETEXI 3511d8c208ddSGerd Hoffmann 35125824d651Sblueswir1#ifndef _WIN32 35135824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3514ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 3515ad96090aSBlue Swirl QEMU_ARCH_ALL) 35165824d651Sblueswir1#endif 35175824d651Sblueswir1STEXI 35184e257e5eSKevin Wolf@item -chroot @var{dir} 35196616b2adSStefan Weil@findex -chroot 35205824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 35215824d651Sblueswir1directory. Especially useful in combination with -runas. 35225824d651Sblueswir1ETEXI 35235824d651Sblueswir1 35245824d651Sblueswir1#ifndef _WIN32 35255824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 3526ad96090aSBlue Swirl "-runas user change to user id user just before starting the VM\n", 3527ad96090aSBlue Swirl QEMU_ARCH_ALL) 35285824d651Sblueswir1#endif 35295824d651Sblueswir1STEXI 35304e257e5eSKevin Wolf@item -runas @var{user} 35316616b2adSStefan Weil@findex -runas 35325824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 35335824d651Sblueswir1to the specified user. 35345824d651Sblueswir1ETEXI 35355824d651Sblueswir1 35365824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 35375824d651Sblueswir1 "-prom-env variable=value\n" 3538ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 3539ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 354095d5f08bSStefan WeilSTEXI 354195d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 35426616b2adSStefan Weil@findex -prom-env 354395d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 354495d5f08bSStefan WeilETEXI 35455824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 3546f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 35473b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 35483b3c1694SLeon Alrae QEMU_ARCH_MIPS) 354995d5f08bSStefan WeilSTEXI 355095d5f08bSStefan Weil@item -semihosting 35516616b2adSStefan Weil@findex -semihosting 35523b3c1694SLeon AlraeEnable semihosting mode (ARM, M68K, Xtensa, MIPS only). 3553a38bb079SLiviu IonescuETEXI 3554a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 3555a59d31a1SLeon Alrae "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \ 3556a59d31a1SLeon Alrae " semihosting configuration\n", 35573b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 35583b3c1694SLeon AlraeQEMU_ARCH_MIPS) 3559a38bb079SLiviu IonescuSTEXI 3560a59d31a1SLeon Alrae@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] 3561a38bb079SLiviu Ionescu@findex -semihosting-config 35623b3c1694SLeon AlraeEnable and configure semihosting (ARM, M68K, Xtensa, MIPS only). 3563a59d31a1SLeon Alrae@table @option 3564a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 3565a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 3566a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 3567a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 3568a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 3569a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 3570a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 3571a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 3572a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 3573a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 3574a59d31a1SLeon Alrae@end table 357595d5f08bSStefan WeilETEXI 35765824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 3577ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 357895d5f08bSStefan WeilSTEXI 357995d5f08bSStefan Weil@item -old-param 35806616b2adSStefan Weil@findex -old-param (ARM) 358195d5f08bSStefan WeilOld param mode (ARM only). 358295d5f08bSStefan WeilETEXI 358395d5f08bSStefan Weil 35847d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 35857d76ad4fSEduardo Otubo "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n", 35867d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 35877d76ad4fSEduardo OtuboSTEXI 35886265c43bSMarkus Armbruster@item -sandbox @var{arg} 35897d76ad4fSEduardo Otubo@findex -sandbox 35907d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 35917d76ad4fSEduardo Otubodisable it. The default is 'off'. 35927d76ad4fSEduardo OtuboETEXI 35937d76ad4fSEduardo Otubo 3594715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3595ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 35963dbf2c7fSStefan WeilSTEXI 35973dbf2c7fSStefan Weil@item -readconfig @var{file} 35986616b2adSStefan Weil@findex -readconfig 3599ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 3600ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 3601ed24cfacSMichal Novotnycharacter limit. 36023dbf2c7fSStefan WeilETEXI 3603715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3604715a664aSGerd Hoffmann "-writeconfig <file>\n" 3605ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 36063dbf2c7fSStefan WeilSTEXI 36073dbf2c7fSStefan Weil@item -writeconfig @var{file} 36086616b2adSStefan Weil@findex -writeconfig 3609ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 3610ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 3611ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 36123dbf2c7fSStefan WeilETEXI 3613292444cbSAnthony LiguoriDEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, 3614292444cbSAnthony Liguori "-nodefconfig\n" 3615ad96090aSBlue Swirl " do not load default config files at startup\n", 3616ad96090aSBlue Swirl QEMU_ARCH_ALL) 3617292444cbSAnthony LiguoriSTEXI 3618292444cbSAnthony Liguori@item -nodefconfig 36196616b2adSStefan Weil@findex -nodefconfig 3620f29a5614SEduardo HabkostNormally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup. 3621f29a5614SEduardo HabkostThe @code{-nodefconfig} option will prevent QEMU from loading any of those config files. 3622f29a5614SEduardo HabkostETEXI 3623f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3624f29a5614SEduardo Habkost "-no-user-config\n" 3625f29a5614SEduardo Habkost " do not load user-provided config files at startup\n", 3626f29a5614SEduardo Habkost QEMU_ARCH_ALL) 3627f29a5614SEduardo HabkostSTEXI 3628f29a5614SEduardo Habkost@item -no-user-config 3629f29a5614SEduardo Habkost@findex -no-user-config 3630f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 3631f29a5614SEduardo Habkostconfig files on @var{sysconfdir}, but won't make it skip the QEMU-provided config 3632f29a5614SEduardo Habkostfiles from @var{datadir}. 3633292444cbSAnthony LiguoriETEXI 3634ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 363510578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 363623d15e86SLluís " specify tracing options\n", 3637ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 3638ab6540d5SPrerna SaxenaSTEXI 363923d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 364023d15e86SLluísHXCOMM HX does not support conditional compilation of text. 364123d15e86SLluís@item -trace [events=@var{file}][,file=@var{file}] 3642ab6540d5SPrerna Saxena@findex -trace 3643e4858974SLluís 364423d15e86SLluísSpecify tracing options. 364523d15e86SLluís 364623d15e86SLluís@table @option 364710578a25SPaolo Bonzini@item [enable=]@var{pattern} 364810578a25SPaolo BonziniImmediately enable events matching @var{pattern}. 364910578a25SPaolo BonziniThe file must contain one event name (as listed in the @file{trace-events} file) 365010578a25SPaolo Bonziniper line; globbing patterns are accepted too. This option is only 365110578a25SPaolo Bonziniavailable if QEMU has been compiled with the @var{simple}, @var{stderr} 365210578a25SPaolo Bonzinior @var{ftrace} tracing backend. To specify multiple events or patterns, 365310578a25SPaolo Bonzinispecify the @option{-trace} option multiple times. 365410578a25SPaolo Bonzini 3655e9527dd3SPaolo BonziniUse @code{-trace help} to print a list of names of trace points. 3656e9527dd3SPaolo Bonzini 365723d15e86SLluís@item events=@var{file} 365823d15e86SLluísImmediately enable events listed in @var{file}. 365952449a31SPaolo BonziniThe file must contain one event name (as listed in the @file{trace-events} file) 366052449a31SPaolo Bonziniper line; globbing patterns are accepted too. This option is only 366152449a31SPaolo Bonziniavailable if QEMU has been compiled with the @var{simple}, @var{stderr} or 366252449a31SPaolo Bonzini@var{ftrace} tracing backend. 366352449a31SPaolo Bonzini 366423d15e86SLluís@item file=@var{file} 366523d15e86SLluísLog output traces to @var{file}. 3666c1ba4e0bSStefan WeilThis option is only available if QEMU has been compiled with 3667c1ba4e0bSStefan Weilthe @var{simple} tracing backend. 366823d15e86SLluís@end table 3669ab6540d5SPrerna SaxenaETEXI 36703dbf2c7fSStefan Weil 367131e70d6cSMarkus ArmbrusterHXCOMM Internal use 367231e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 367331e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3674c7f0f3b1SAnthony Liguori 36750f66998fSPaul Moore#ifdef __linux__ 36760f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 36770f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 36780f66998fSPaul Moore QEMU_ARCH_ALL) 36790f66998fSPaul Moore#endif 36800f66998fSPaul MooreSTEXI 36810f66998fSPaul Moore@item -enable-fips 36820f66998fSPaul Moore@findex -enable-fips 36830f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 36840f66998fSPaul MooreETEXI 36850f66998fSPaul Moore 3686a0dac021SJan KiszkaHXCOMM Deprecated by -machine accel=tcg property 3687c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3688a0dac021SJan Kiszka 3689c21fb4f8SJan KiszkaHXCOMM Deprecated by kvm-pit driver properties 3690c6e88b3bSBruce RogersDEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection, 3691c21fb4f8SJan Kiszka "", QEMU_ARCH_I386) 3692c21fb4f8SJan Kiszka 36934086bde8SJan KiszkaHXCOMM Deprecated (ignored) 3694c6e88b3bSBruce RogersDEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386) 36954086bde8SJan Kiszka 3696e43d594eSJan KiszkaHXCOMM Deprecated by -machine kernel_irqchip=on|off property 3697c6e88b3bSBruce RogersDEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386) 3698e43d594eSJan Kiszka 369988eed34aSJan KiszkaHXCOMM Deprecated (ignored) 370088eed34aSJan KiszkaDEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL) 370188eed34aSJan Kiszka 37025e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 37035e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 37045e2ac519SSeiji Aguchi " change the format of messages\n" 37055e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 37065e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 37075e2ac519SSeiji AguchiSTEXI 37085e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 37095e2ac519SSeiji Aguchi@findex -msg 37105e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 37115e2ac519SSeiji AguchiETEXI 37125e2ac519SSeiji Aguchi 3713abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 3714abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 3715abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 3716abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 3717abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 37182382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 3719abfd9ce3SAmit Shah QEMU_ARCH_ALL) 3720abfd9ce3SAmit ShahSTEXI 3721abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 3722abfd9ce3SAmit Shah@findex -dump-vmstate 3723abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 3724abfd9ce3SAmit Shahin @var{file} 3725abfd9ce3SAmit ShahETEXI 3726abfd9ce3SAmit Shah 3727b9174d4fSDaniel P. BerrangeDEFHEADING(Generic object creation) 3728b9174d4fSDaniel P. Berrange 3729b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 3730b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 3731b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 3732b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 3733b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 3734b9174d4fSDaniel P. Berrange " '/objects' path.\n", 3735b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 3736b9174d4fSDaniel P. BerrangeSTEXI 3737b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3738b9174d4fSDaniel P. Berrange@findex -object 3739b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 3740b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 3741b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 3742b9174d4fSDaniel P. Berrange'/objects' path. 3743b9174d4fSDaniel P. Berrange 3744b9174d4fSDaniel P. Berrange@table @option 3745b9174d4fSDaniel P. Berrange 3746b9174d4fSDaniel P. Berrange@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off} 3747b9174d4fSDaniel P. Berrange 3748b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 3749b9174d4fSDaniel P. Berrangethe guest RAM with huge pages. The @option{id} parameter is a 3750b9174d4fSDaniel P. Berrangeunique ID that will be used to reference this memory region 3751b9174d4fSDaniel P. Berrangewhen configuring the @option{-numa} argument. The @option{size} 3752b9174d4fSDaniel P. Berrangeoption provides the size of the memory region, and accepts 3753b9174d4fSDaniel P. Berrangecommon suffixes, eg @option{500M}. The @option{mem-path} provides 3754b9174d4fSDaniel P. Berrangethe path to either a shared memory or huge page filesystem mount. 3755b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 3756b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 3757b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 3758b9174d4fSDaniel P. Berrange 3759b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 3760b9174d4fSDaniel P. Berrange 3761b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 3762b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 3763b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 3764b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 3765b9174d4fSDaniel P. Berrangeentropy from and if omitted defaults to @option{/dev/random}. 3766b9174d4fSDaniel P. Berrange 3767b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 3768b9174d4fSDaniel P. Berrange 3769b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 3770b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 3771b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 3772b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 3773b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 3774b9174d4fSDaniel P. Berrangeto the RNG daemon. 3775b9174d4fSDaniel P. Berrange 3776e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 3777e00adf6cSDaniel P. Berrange 3778e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 3779e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 3780e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 3781e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 3782e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 3783e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 3784e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 3785e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 3786e00adf6cSDaniel P. Berrange 3787e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 3788e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 3789e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 3790e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 3791e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 3792e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 3793e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 3794e00adf6cSDaniel P. Berrangeupfront and saved. 3795e00adf6cSDaniel P. Berrange 37961d7b5b4aSDaniel 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} 379785bcbc78SDaniel P. Berrange 379885bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 379985bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 380085bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 380185bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 380285bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 380385bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 380485bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 380585bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 380685bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 380785bcbc78SDaniel P. Berrange 380885bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 380985bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 381085bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 381185bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 381285bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 381385bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 381485bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 381585bcbc78SDaniel P. Berrangeupfront and saved. 381685bcbc78SDaniel P. Berrange 381785bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 381885bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 381985bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 382085bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 382185bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 382285bcbc78SDaniel P. Berrange 38231d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 38241d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 38251d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 38261d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 38271d7b5b4aSDaniel P. Berrangepassword for decryption. 38281d7b5b4aSDaniel P. Berrange 3829338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 38307dbb11c8SYang Hongyang 38317dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 38327dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 38337dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 3834338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 3835338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 38367dbb11c8SYang Hongyang 38377dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 38387dbb11c8SYang Hongyang 38397dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 38407dbb11c8SYang Hongyang queue of the netdev (default). 38417dbb11c8SYang Hongyang 38427dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 38437dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 38447dbb11c8SYang Hongyang 38457dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 38467dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 38477dbb11c8SYang Hongyang 3848f6d3afb5SZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}] 3849f6d3afb5SZhang Chen 3850f6d3afb5SZhang Chenfilter-mirror on netdev @var{netdevid},mirror net packet to chardev 3851f6d3afb5SZhang Chen@var{chardevid} 3852f6d3afb5SZhang Chen 3853d46f75b2SZhang Chen@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid}, 3854d46f75b2SZhang Chenoutdev=@var{chardevid}[,queue=@var{all|rx|tx}] 3855d46f75b2SZhang Chen 3856d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 3857d46f75b2SZhang Chen@var{chardevid},and redirect indev's packet to filter. 3858d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 3859d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 3860d46f75b2SZhang Chenneed to be specified. 3861d46f75b2SZhang Chen 3862d3e0c032SThomas Huth@item -object filter-dump,id=@var{id},netdev=@var{dev},file=@var{filename}][,maxlen=@var{len}] 3863d3e0c032SThomas Huth 3864d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 3865d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 3866d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 3867d3e0c032SThomas Huthor Wireshark. 3868d3e0c032SThomas Huth 3869ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 3870ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 3871ac1d8878SDaniel P. Berrange 3872ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 3873ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 3874ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 3875ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 3876ac1d8878SDaniel P. Berrange 3877ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 3878ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 3879ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 3880ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 3881ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 3882ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 3883ac1d8878SDaniel P. Berrange 3884ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 3885ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 3886ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 3887ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 3888ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 3889ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 3890ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 3891*69c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 3892ac1d8878SDaniel P. Berrange 3893ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 3894ac1d8878SDaniel P. Berrange 3895ac1d8878SDaniel P. Berrange@example 3896ac1d8878SDaniel P. Berrange 3897ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,data=letmein,format=raw 3898ac1d8878SDaniel P. Berrange 3899ac1d8878SDaniel P. Berrange@end example 3900ac1d8878SDaniel P. Berrange 3901ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 3902ac1d8878SDaniel P. Berrange 3903ac1d8878SDaniel P. Berrange # echo -n "letmein" > mypasswd.txt 3904ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw 3905ac1d8878SDaniel P. Berrange 3906ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 3907ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 3908ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 3909ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 3910ac1d8878SDaniel P. Berrange 3911ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 3912ac1d8878SDaniel P. Berrange 3913ac1d8878SDaniel P. Berrange@example 3914ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 3915ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 3916ac1d8878SDaniel P. Berrange@end example 3917ac1d8878SDaniel P. Berrange 3918ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 3919ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 3920ac1d8878SDaniel P. Berrange 3921ac1d8878SDaniel P. Berrange@example 3922ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 3923ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 3924ac1d8878SDaniel P. Berrange@end example 3925ac1d8878SDaniel P. Berrange 3926ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 3927ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 3928ac1d8878SDaniel P. Berrangeas raw bytes if desired. 3929ac1d8878SDaniel P. Berrange 3930ac1d8878SDaniel P. Berrange@example 3931ac1d8878SDaniel P. Berrange # SECRET=$(echo -n "letmein" | 3932ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 3933ac1d8878SDaniel P. Berrange@end example 3934ac1d8878SDaniel P. Berrange 3935ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 3936ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 3937ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 3938ac1d8878SDaniel P. Berrange 3939ac1d8878SDaniel P. Berrange@example 3940ac1d8878SDaniel P. Berrange # $QEMU \ 3941ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 3942ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 3943ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 3944ac1d8878SDaniel P. Berrange@end example 3945ac1d8878SDaniel P. Berrange 3946b9174d4fSDaniel P. Berrange@end table 3947b9174d4fSDaniel P. Berrange 3948b9174d4fSDaniel P. BerrangeETEXI 3949b9174d4fSDaniel P. Berrange 3950b9174d4fSDaniel P. Berrange 39513dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 39523dbf2c7fSStefan WeilSTEXI 39533dbf2c7fSStefan Weil@end table 39543dbf2c7fSStefan WeilETEXI 3955