blob: fe8c04f6443c08601c55fdecb279a0b12bc6690d [file] [log] [blame]
blueswir15824d652009-03-28 06:44:27 +00001HXCOMM Use DEFHEADING() to define headings in both help text and texi
2HXCOMM Text between STEXI and ETEXI are copied to texi version and
3HXCOMM discarded from C version
Blue Swirlad960902010-03-29 19:23:52 +00004HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5HXCOMM construct option structures, enums and help message for specified
6HXCOMM architectures.
blueswir15824d652009-03-28 06:44:27 +00007HXCOMM HXCOMM can be used for comments, discarded from both texi and C
8
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02009DEFHEADING(Standard options:)
blueswir15824d652009-03-28 06:44:27 +000010STEXI
11@table @option
12ETEXI
13
14DEF("help", 0, QEMU_OPTION_h,
Blue Swirlad960902010-03-29 19:23:52 +000015 "-h or -help display this help and exit\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000016STEXI
17@item -h
Stefan Weil6616b2a2010-02-05 23:52:05 +010018@findex -h
blueswir15824d652009-03-28 06:44:27 +000019Display help and exit
20ETEXI
21
pbrook9bd7e6d2009-04-07 22:58:45 +000022DEF("version", 0, QEMU_OPTION_version,
Blue Swirlad960902010-03-29 19:23:52 +000023 "-version display version information and exit\n", QEMU_ARCH_ALL)
pbrook9bd7e6d2009-04-07 22:58:45 +000024STEXI
25@item -version
Stefan Weil6616b2a2010-02-05 23:52:05 +010026@findex -version
pbrook9bd7e6d2009-04-07 22:58:45 +000027Display version information and exit
28ETEXI
29
Jan Kiszka80f52a62011-07-23 12:39:46 +020030DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
31 "-machine [type=]name[,prop[=value][,...]]\n"
Peter Maydell585f6032012-10-04 16:22:01 +010032 " selects emulated machine ('-machine help' for list)\n"
Jan Kiszka80f52a62011-07-23 12:39:46 +020033 " property accel=accel1[:accel2[:...]] selects accelerator\n"
Sergio Andres Gomez Del Realc97d6d22017-09-13 04:05:09 -050034 " supported accelerators are kvm, xen, hax, hvf or tcg (default: tcg)\n"
Matt Gingell32c18a22015-11-16 10:03:06 -080035 " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n"
Don Slutzd1048be2014-11-21 11:18:52 -050036 " vmport=on|off|auto controls emulation of vmport (default: auto)\n"
Peter Maydell96404012016-05-10 16:49:29 +010037 " kvm_shadow_mem=size of KVM shadow MMU in bytes\n"
Luiz Capitulino8490fc72012-09-05 16:50:16 -030038 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
Le Tana52a7fd2014-08-16 13:55:40 +080039 " mem-merge=on|off controls memory merge support (default: on)\n"
Tiejun Chen79814172015-07-15 13:37:45 +080040 " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n"
Tony Krowiak2eb1cd02015-03-12 13:53:51 +010041 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
Alexander Graf9850c602015-02-23 13:56:42 +010042 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
Xiao Guangrong87252e12015-12-02 15:20:58 +080043 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
Greg Kurz902c0532016-02-18 12:32:25 +010044 " nvdimm=on|off controls NVDIMM support (default=off)\n"
Xiao Feng Ren274250c2017-05-17 02:48:03 +020045 " enforce-config-section=on|off enforce configuration section migration (default=off)\n"
Halil Pasicd69969e2017-12-06 15:44:38 +010046 " s390-squash-mcss=on|off (deprecated) controls support for squashing into default css (default=off)\n",
Jan Kiszka80f52a62011-07-23 12:39:46 +020047 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000048STEXI
Jan Kiszka80f52a62011-07-23 12:39:46 +020049@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
50@findex -machine
Peter Maydell585f6032012-10-04 16:22:01 +010051Select the emulated machine by @var{name}. Use @code{-machine help} to list
Daniel P. Berrange8bfce832017-07-25 15:10:41 +010052available machines.
53
54For architectures which aim to support live migration compatibility
55across releases, each release will introduce a new versioned machine
56type. For example, the 2.8.0 release introduced machine types
57``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures.
58
59To allow live migration of guests from QEMU version 2.8.0, to QEMU
60version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8''
61and ``pc-q35-2.8'' machines too. To allow users live migrating VMs
62to skip multiple intermediate releases when upgrading, new releases
63of QEMU will support machine types from many previous versions.
64
65Supported machine properties are:
Jan Kiszka80f52a62011-07-23 12:39:46 +020066@table @option
67@item accel=@var{accels1}[:@var{accels2}[:...]]
68This is used to enable an accelerator. Depending on the target architecture,
Sergio Andres Gomez Del Realc97d6d22017-09-13 04:05:09 -050069kvm, xen, hax, hvf or tcg can be available. By default, tcg is used. If there is
Thomas Huthbde4d922017-05-04 07:24:41 +020070more than one accelerator specified, the next one is used if the previous one
71fails to initialize.
Jan Kiszka6a48ffa2011-10-15 13:43:48 +020072@item kernel_irqchip=on|off
Matt Gingell32c18a22015-11-16 10:03:06 -080073Controls in-kernel irqchip support for the chosen accelerator when available.
Tiejun Chen79814172015-07-15 13:37:45 +080074@item gfx_passthru=on|off
75Enables IGD GFX passthrough support for the chosen machine when available.
Don Slutzd1048be2014-11-21 11:18:52 -050076@item vmport=on|off|auto
77Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
78value based on accel. For accel=xen the default is off otherwise the default
79is on.
Jan Kiszka39d69602012-01-25 18:14:15 +010080@item kvm_shadow_mem=size
81Defines the size of the KVM shadow MMU.
Jason Baronddb97f12012-08-02 15:44:16 -040082@item dump-guest-core=on|off
83Include guest memory in a core dump. The default is on.
Luiz Capitulino8490fc72012-09-05 16:50:16 -030084@item mem-merge=on|off
85Enables or disables memory merge support. This feature, when supported by
86the host, de-duplicates identical memory pages among VMs instances
87(enabled by default).
Tony Krowiak2eb1cd02015-03-12 13:53:51 +010088@item aes-key-wrap=on|off
89Enables or disables AES key wrapping support on s390-ccw hosts. This feature
90controls whether AES wrapping keys will be created to allow
91execution of AES cryptographic functions. The default is on.
92@item dea-key-wrap=on|off
93Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
94controls whether DEA wrapping keys will be created to allow
95execution of DEA cryptographic functions. The default is on.
Xiao Guangrong87252e12015-12-02 15:20:58 +080096@item nvdimm=on|off
97Enables or disables NVDIMM support. The default is off.
Xiao Feng Ren274250c2017-05-17 02:48:03 +020098@item s390-squash-mcss=on|off
99Enables or disables squashing subchannels into the default css.
100The default is off.
Halil Pasicd69969e2017-12-06 15:44:38 +0100101NOTE: This property is deprecated and will be removed in future releases.
102The ``s390-squash-mcss=on`` property has been obsoleted by allowing the
103cssid to be chosen freely. Instead of squashing subchannels into the
104default channel subsystem image for guests that do not support multiple
105channel subsystems, all devices can be put into the default channel
106subsystem image.
Peter Xu16f72442017-07-07 10:54:08 +0800107@item enforce-config-section=on|off
108If @option{enforce-config-section} is set to @var{on}, force migration
109code to send configuration section even if the machine-type sets the
110@option{migration.send-configuration} property to @var{off}.
111NOTE: this parameter is deprecated. Please use @option{-global}
112@option{migration.send-configuration}=@var{on|off} instead.
Jan Kiszka80f52a62011-07-23 12:39:46 +0200113@end table
blueswir15824d652009-03-28 06:44:27 +0000114ETEXI
115
Jan Kiszka80f52a62011-07-23 12:39:46 +0200116HXCOMM Deprecated by -machine
117DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
118
blueswir15824d652009-03-28 06:44:27 +0000119DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
Peter Maydell585f6032012-10-04 16:22:01 +0100120 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000121STEXI
122@item -cpu @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100123@findex -cpu
Peter Maydell585f6032012-10-04 16:22:01 +0100124Select CPU model (@code{-cpu help} for list and additional feature selection)
blueswir15824d652009-03-28 06:44:27 +0000125ETEXI
126
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000127DEF("accel", HAS_ARG, QEMU_OPTION_accel,
128 "-accel [accel=]accelerator[,thread=single|multi]\n"
Sergio Andres Gomez Del Realc97d6d22017-09-13 04:05:09 -0500129 " select accelerator (kvm, xen, hax, hvf or tcg; use 'help' for a list)\n"
130 " thread=single|multi (enable multi-threaded TCG)", QEMU_ARCH_ALL)
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000131STEXI
132@item -accel @var{name}[,prop=@var{value}[,...]]
133@findex -accel
134This is used to enable an accelerator. Depending on the target architecture,
Sergio Andres Gomez Del Realc97d6d22017-09-13 04:05:09 -0500135kvm, xen, hax, hvf or tcg can be available. By default, tcg is used. If there is
Thomas Huthbde4d922017-05-04 07:24:41 +0200136more than one accelerator specified, the next one is used if the previous one
137fails to initialize.
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000138@table @option
139@item thread=single|multi
140Controls number of TCG threads. When the TCG is multi-threaded there will be one
141thread per vCPU therefor taking advantage of additional host cores. The default
142is to enable multi-threading where both the back-end and front-ends support it and
143no incompatible TCG features have been enabled (e.g. icount/replay).
144@end table
145ETEXI
146
blueswir15824d652009-03-28 06:44:27 +0000147DEF("smp", HAS_ARG, QEMU_OPTION_smp,
Michael Tokarev12b7f572013-06-24 15:06:52 +0400148 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
Jes Sorensen6be68d72009-07-23 17:03:42 +0200149 " set the number of CPUs to 'n' [default=1]\n"
150 " maxcpus= maximum number of total cpus, including\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -0700151 " offline CPUs for hotplug, etc\n"
Andre Przywara58a04db2009-08-28 10:49:57 +0200152 " cores= number of CPU cores on one socket\n"
153 " threads= number of threads on one CPU core\n"
Blue Swirlad960902010-03-29 19:23:52 +0000154 " sockets= number of discrete sockets in the system\n",
155 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000156STEXI
Michael Tokarev12b7f572013-06-24 15:06:52 +0400157@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100158@findex -smp
blueswir15824d652009-03-28 06:44:27 +0000159Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
160CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
161to 4.
Andre Przywara58a04db2009-08-28 10:49:57 +0200162For the PC target, the number of @var{cores} per socket, the number
163of @var{threads} per cores and the total number of @var{sockets} can be
164specified. Missing values will be computed. If any on the three values is
165given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
166specifies the maximum number of hotpluggable CPUs.
blueswir15824d652009-03-28 06:44:27 +0000167ETEXI
168
aliguori268a3622009-04-21 22:30:27 +0000169DEF("numa", HAS_ARG, QEMU_OPTION_numa,
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200170 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
He Chen0f203432017-04-27 10:35:58 +0800171 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
172 "-numa dist,src=source,dst=destination,val=distance\n", QEMU_ARCH_ALL)
aliguori268a3622009-04-21 22:30:27 +0000173STEXI
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200174@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
175@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
He Chen0f203432017-04-27 10:35:58 +0800176@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
Igor Mammedov419fcde2017-05-10 13:30:01 +0200177@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100178@findex -numa
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200179Define a NUMA node and assign RAM and VCPUs to it.
He Chen0f203432017-04-27 10:35:58 +0800180Set the NUMA distance from a source node to a destination node.
Paolo Bonzini7febe362014-05-14 17:43:17 +0800181
Igor Mammedov419fcde2017-05-10 13:30:01 +0200182Legacy VCPU assignment uses @samp{cpus} option where
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200183@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
184@samp{cpus} option represent a contiguous range of CPU indexes
185(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
186set of VCPUs can be represented by providing multiple @samp{cpus}
187options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
188split between them.
189
190For example, the following option assigns VCPUs 0, 1, 2 and 5 to
191a NUMA node:
192@example
193-numa node,cpus=0-2,cpus=5
194@end example
195
Igor Mammedov419fcde2017-05-10 13:30:01 +0200196@samp{cpu} option is a new alternative to @samp{cpus} option
197which uses @samp{socket-id|core-id|thread-id} properties to assign
198CPU objects to a @var{node} using topology layout properties of CPU.
199The set of properties is machine specific, and depends on used
200machine type/@samp{smp} options. It could be queried with
201@samp{hotpluggable-cpus} monitor command.
202@samp{node-id} property specifies @var{node} to which CPU object
203will be assigned, it's required for @var{node} to be declared
204with @samp{node} option before it's used with @samp{cpu} option.
205
206For example:
207@example
208-M pc \
209-smp 1,sockets=2,maxcpus=2 \
210-numa node,nodeid=0 -numa node,nodeid=1 \
211-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
212@end example
213
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200214@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
215assigns RAM from a given memory backend device to a node. If
216@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
217split equally between them.
218
219@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
220if one node uses @samp{memdev}, all of them have to use it.
221
He Chen0f203432017-04-27 10:35:58 +0800222@var{source} and @var{destination} are NUMA node IDs.
223@var{distance} is the NUMA distance from @var{source} to @var{destination}.
224The distance from a node to itself is always 10. If any pair of nodes is
225given a distance, then all pairs must be given distances. Although, when
226distances are only given in one direction for each pair of nodes, then
227the distances in the opposite directions are assumed to be the same. If,
228however, an asymmetrical pair of distances is given for even one node
229pair, then all node pairs must be provided distance values for both
230directions, even when they are symmetrical. When a node is unreachable
231from another node, set the pair's distance to 255.
232
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200233Note that the -@option{numa} option doesn't allocate any of the
234specified resources, it just assigns existing resources to NUMA
235nodes. This means that one still has to use the @option{-m},
236@option{-smp} options to allocate RAM and VCPUs respectively.
237
aliguori268a3622009-04-21 22:30:27 +0000238ETEXI
239
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100240DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
241 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
242 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
243STEXI
244@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
245@findex -add-fd
246
247Add a file descriptor to an fd set. Valid options are:
248
249@table @option
250@item fd=@var{fd}
251This option defines the file descriptor of which a duplicate is added to fd set.
252The file descriptor cannot be stdin, stdout, or stderr.
253@item set=@var{set}
254This option defines the ID of the fd set to add the file descriptor to.
255@item opaque=@var{opaque}
256This option defines a free-form string that can be used to describe @var{fd}.
257@end table
258
259You can open an image using pre-opened file descriptors from an fd set:
260@example
261qemu-system-i386
262-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
263-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
264-drive file=/dev/fdset/2,index=0,media=disk
265@end example
266ETEXI
267
268DEF("set", HAS_ARG, QEMU_OPTION_set,
269 "-set group.id.arg=value\n"
270 " set <arg> parameter for item <id> of type <group>\n"
271 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
272STEXI
273@item -set @var{group}.@var{id}.@var{arg}=@var{value}
274@findex -set
Michael Tokareve1f3b972016-10-16 17:21:37 +0300275Set parameter @var{arg} for item @var{id} of type @var{group}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100276ETEXI
277
278DEF("global", HAS_ARG, QEMU_OPTION_global,
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200279 "-global driver.property=value\n"
280 "-global driver=driver,property=property,value=value\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100281 " set a global default for a driver property\n",
282 QEMU_ARCH_ALL)
283STEXI
284@item -global @var{driver}.@var{prop}=@var{value}
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200285@itemx -global driver=@var{driver},property=@var{property},value=@var{value}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100286@findex -global
287Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
288
289@example
Markus Armbruster1c9f3b82017-05-09 11:41:15 +0200290qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100291@end example
292
Michael Tokareva295d242017-09-23 19:31:59 +0300293In particular, you can use this to set driver properties for devices which are
294created automatically by the machine model. To create a device which is not
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100295created automatically and set properties on it, use -@option{device}.
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200296
Markus Armbrusterae08fd52015-06-15 14:35:58 +0200297-global @var{driver}.@var{prop}=@var{value} is shorthand for -global
298driver=@var{driver},property=@var{prop},value=@var{value}. The
299longhand syntax works even when @var{driver} contains a dot.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100300ETEXI
301
302DEF("boot", HAS_ARG, QEMU_OPTION_boot,
303 "-boot [order=drives][,once=drives][,menu=on|off]\n"
Amos Kongc8a6ae82013-03-19 14:23:27 +0800304 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100305 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
306 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
307 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
308 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
309 QEMU_ARCH_ALL)
310STEXI
Amos Kongc8a6ae82013-03-19 14:23:27 +0800311@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]
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100312@findex -boot
313Specify boot order @var{drives} as a string of drive letters. Valid
Gongleid274e072015-07-03 17:50:57 +0800314drive letters depend on the target architecture. The x86 PC uses: a, b
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100315(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
316from network adapter 1-4), hard disk boot is the default. To apply a
317particular boot order only on the first startup, specify it via
Thomas Huthc0d9f7d2017-02-28 18:40:01 +0100318@option{once}. Note that the @option{order} or @option{once} parameter
319should not be used together with the @option{bootindex} property of
320devices, since the firmware implementations normally do not support both
321at the same time.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100322
323Interactive boot menus/prompts can be enabled via @option{menu=on} as far
324as firmware/BIOS supports them. The default is non-interactive boot.
325
326A splash picture could be passed to bios, enabling user to show it as logo,
327when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
328supports them. Currently Seabios for X86 system support it.
329limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
330format(true color). The resolution should be supported by the SVGA mode, so
331the recommended is 320x240, 640x480, 800x640.
332
333A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
334when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
335reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
336system support it.
337
Amos Kongc8a6ae82013-03-19 14:23:27 +0800338Do strict boot via @option{strict=on} as far as firmware/BIOS
339supports it. This only effects when boot priority is changed by
340bootindex options. The default is non-strict boot.
341
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100342@example
343# try to boot from network first, then from hard disk
344qemu-system-i386 -boot order=nc
345# boot from CD-ROM first, switch back to default order after reboot
346qemu-system-i386 -boot once=d
347# boot with a splash picture for 5 seconds.
348qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
349@end example
350
351Note: The legacy format '-boot @var{drives}' is still supported but its
352use is discouraged as it may be removed from future versions.
353ETEXI
354
355DEF("m", HAS_ARG, QEMU_OPTION_m,
Michael Tokarev89f3ea22016-11-10 17:51:32 +0300356 "-m [size=]megs[,slots=n,maxmem=size]\n"
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100357 " configure guest RAM\n"
Alexander Graf0daba1f2015-06-05 11:05:03 +0200358 " size: initial amount of guest memory\n"
Igor Mammedovc270fb92014-06-02 15:25:02 +0200359 " slots: number of hotplug slots (default: none)\n"
Matthew Rosatob6fe0122014-08-28 11:25:33 -0400360 " maxmem: maximum amount of guest memory (default: none)\n"
361 "NOTE: Some architectures might enforce a specific granularity\n",
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100362 QEMU_ARCH_ALL)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100363STEXI
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500364@item -m [size=]@var{megs}[,slots=n,maxmem=size]
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100365@findex -m
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500366Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
367Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
368megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
369could be used to set amount of hotpluggable memory slots and maximum amount of
370memory. Note that @var{maxmem} must be aligned to the page size.
371
372For example, the following command-line sets the guest startup RAM size to
3731GB, creates 3 slots to hotplug additional memory and sets the maximum
374memory the guest can reach to 4GB:
375
376@example
377qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
378@end example
379
380If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
381be enabled and the guest startup RAM will never increase.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100382ETEXI
383
384DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
385 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
386STEXI
387@item -mem-path @var{path}
388@findex -mem-path
389Allocate guest RAM from a temporarily created file in @var{path}.
390ETEXI
391
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100392DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
393 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
394 QEMU_ARCH_ALL)
395STEXI
396@item -mem-prealloc
397@findex -mem-prealloc
398Preallocate memory when using -mem-path.
399ETEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100400
401DEF("k", HAS_ARG, QEMU_OPTION_k,
402 "-k language use keyboard layout (for example 'fr' for French)\n",
403 QEMU_ARCH_ALL)
404STEXI
405@item -k @var{language}
406@findex -k
407Use keyboard layout @var{language} (for example @code{fr} for
408French). This option is only needed where it is not easy to get raw PC
Samuel Thibault32945472016-06-22 17:48:31 +0200409keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100410display). You don't normally need to use it on PC/Linux or PC/Windows
411hosts.
412
413The available layouts are:
414@example
415ar de-ch es fo fr-ca hu ja mk no pt-br sv
416da en-gb et fr fr-ch is lt nl pl ru th
417de en-us fi fr-be hr it lv nl-be pt sl tr
418@end example
419
420The default is @code{en-us}.
421ETEXI
422
423
424DEF("audio-help", 0, QEMU_OPTION_audio_help,
425 "-audio-help print list of audio drivers and their options\n",
426 QEMU_ARCH_ALL)
427STEXI
428@item -audio-help
429@findex -audio-help
430Will show the audio subsystem help: list of drivers, tunable
431parameters.
432ETEXI
433
434DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
435 "-soundhw c1,... enable audio support\n"
436 " and only specified sound cards (comma separated list)\n"
437 " use '-soundhw help' to get the list of supported cards\n"
438 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
439STEXI
440@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
441@findex -soundhw
442Enable audio and selected sound hardware. Use 'help' to print all
443available sound hardware.
444
445@example
446qemu-system-i386 -soundhw sb16,adlib disk.img
447qemu-system-i386 -soundhw es1370 disk.img
448qemu-system-i386 -soundhw ac97 disk.img
449qemu-system-i386 -soundhw hda disk.img
450qemu-system-i386 -soundhw all disk.img
451qemu-system-i386 -soundhw help
452@end example
453
454Note that Linux's i810_audio OSS kernel (for AC97) module might
455require manually specifying clocking.
456
457@example
458modprobe i810_audio clocking=48000
459@end example
460ETEXI
461
462DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
463 "-balloon none disable balloon device\n"
464 "-balloon virtio[,addr=str]\n"
465 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
466STEXI
467@item -balloon none
468@findex -balloon
469Disable balloon device.
470@item -balloon virtio[,addr=@var{addr}]
471Enable virtio balloon device (default), optionally with PCI address
472@var{addr}.
473ETEXI
474
475DEF("device", HAS_ARG, QEMU_OPTION_device,
476 "-device driver[,prop[=value][,...]]\n"
477 " add device (based on driver)\n"
478 " prop=value,... sets driver properties\n"
479 " use '-device help' to print all possible drivers\n"
480 " use '-device driver,help' to print all possible properties\n",
481 QEMU_ARCH_ALL)
482STEXI
483@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
484@findex -device
485Add device @var{driver}. @var{prop}=@var{value} sets driver
486properties. Valid properties depend on the driver. To get help on
487possible drivers and properties, use @code{-device help} and
488@code{-device @var{driver},help}.
Corey Minyardf8490452015-12-17 12:50:10 -0600489
490Some drivers are:
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200491@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}]
Corey Minyardf8490452015-12-17 12:50:10 -0600492
493Add an IPMI BMC. This is a simulation of a hardware management
494interface processor that normally sits on a system. It provides
495a watchdog and the ability to reset and power control the system.
496You need to connect this to an IPMI interface to make it useful
497
498The IPMI slave address to use for the BMC. The default is 0x20.
499This address is the BMC's address on the I2C network of management
500controllers. If you don't know what this means, it is safe to ignore
501it.
502
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200503@table @option
504@item bmc=@var{id}
505The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
506@item slave_addr=@var{val}
507Define slave address to use for the BMC. The default is 0x20.
508@item sdrfile=@var{file}
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200509file containing raw Sensor Data Records (SDR) data. The default is none.
510@item fruareasize=@var{val}
511size of a Field Replaceable Unit (FRU) area. The default is 1024.
512@item frudatafile=@var{file}
513file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200514@end table
515
Corey Minyardf8490452015-12-17 12:50:10 -0600516@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
517
518Add a connection to an external IPMI BMC simulator. Instead of
519locally emulating the BMC like the above item, instead connect
520to an external entity that provides the IPMI services.
521
522A connection is made to an external BMC simulator. If you do this, it
523is strongly recommended that you use the "reconnect=" chardev option
524to reconnect to the simulator if the connection is lost. Note that if
525this is not used carefully, it can be a security issue, as the
526interface has the ability to send resets, NMIs, and power off the VM.
527It's best if QEMU makes a connection to an external simulator running
528on a secure port on localhost, so neither the simulator nor QEMU is
529exposed to any outside network.
530
531See the "lanserv/README.vm" file in the OpenIPMI library for more
532details on the external interface.
533
534@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
535
536Add a KCS IPMI interafce on the ISA bus. This also adds a
537corresponding ACPI and SMBIOS entries, if appropriate.
538
539@table @option
540@item bmc=@var{id}
541The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
542@item ioport=@var{val}
543Define the I/O address of the interface. The default is 0xca0 for KCS.
544@item irq=@var{val}
545Define the interrupt to use. The default is 5. To disable interrupts,
546set this to 0.
547@end table
548
549@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
550
551Like the KCS interface, but defines a BT interface. The default port is
5520xe4 and the default interrupt is 5.
553
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100554ETEXI
555
556DEF("name", HAS_ARG, QEMU_OPTION_name,
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000557 "-name string1[,process=string2][,debug-threads=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100558 " set the name of the guest\n"
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000559 " string1 sets the window title and string2 the process name (on Linux)\n"
560 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
561 " NOTE: The thread names are for debugging and not a stable API.\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100562 QEMU_ARCH_ALL)
563STEXI
564@item -name @var{name}
565@findex -name
566Sets the @var{name} of the guest.
567This name will be displayed in the SDL window caption.
568The @var{name} will also be used for the VNC server.
569Also optionally set the top visible process name in Linux.
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000570Naming of individual threads can also be enabled on Linux to aid debugging.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100571ETEXI
572
573DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
574 "-uuid %08x-%04x-%04x-%04x-%012x\n"
575 " specify machine UUID\n", QEMU_ARCH_ALL)
576STEXI
577@item -uuid @var{uuid}
578@findex -uuid
579Set system UUID.
580ETEXI
581
582STEXI
583@end table
584ETEXI
585DEFHEADING()
586
Markus Armbrusterde6b4f92017-10-02 16:03:00 +0200587DEFHEADING(Block device options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100588STEXI
589@table @option
590ETEXI
591
blueswir15824d652009-03-28 06:44:27 +0000592DEF("fda", HAS_ARG, QEMU_OPTION_fda,
Blue Swirlad960902010-03-29 19:23:52 +0000593 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
594DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000595STEXI
596@item -fda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200597@itemx -fdb @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100598@findex -fda
599@findex -fdb
Markus Armbruster92a539d2015-03-17 17:02:20 +0100600Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
blueswir15824d652009-03-28 06:44:27 +0000601ETEXI
602
603DEF("hda", HAS_ARG, QEMU_OPTION_hda,
Blue Swirlad960902010-03-29 19:23:52 +0000604 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
605DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000606DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
Blue Swirlad960902010-03-29 19:23:52 +0000607 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
608DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000609STEXI
610@item -hda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200611@itemx -hdb @var{file}
612@itemx -hdc @var{file}
613@itemx -hdd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100614@findex -hda
615@findex -hdb
616@findex -hdc
617@findex -hdd
blueswir15824d652009-03-28 06:44:27 +0000618Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
619ETEXI
620
621DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
Blue Swirlad960902010-03-29 19:23:52 +0000622 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
623 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000624STEXI
625@item -cdrom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100626@findex -cdrom
blueswir15824d652009-03-28 06:44:27 +0000627Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
628@option{-cdrom} at the same time). You can use the host CD-ROM by
629using @file{/dev/cdrom} as filename (@pxref{host_drives}).
630ETEXI
631
Markus Armbruster42e5f392017-02-28 22:27:07 +0100632DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
633 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
634 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
635 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
636 " [,driver specific parameters...]\n"
637 " configure a block backend\n", QEMU_ARCH_ALL)
Kevin Wolfdfaca462016-09-22 16:53:24 +0200638STEXI
639@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
640@findex -blockdev
641
Kevin Wolf370e8322016-09-22 17:24:38 +0200642Define a new block driver node. Some of the options apply to all block drivers,
643other options are only accepted for a specific block driver. See below for a
644list of generic options and options for the most common block drivers.
645
646Options that expect a reference to another node (e.g. @code{file}) can be
647given in two ways. Either you specify the node name of an already existing node
648(file=@var{node-name}), or you define a new node inline, adding options
649for the referenced node after a dot (file.filename=@var{path},file.aio=native).
650
651A block driver node created with @option{-blockdev} can be used for a guest
652device by specifying its node name for the @code{drive} property in a
653@option{-device} argument that defines a block device.
Kevin Wolfdfaca462016-09-22 16:53:24 +0200654
655@table @option
656@item Valid options for any block driver node:
657
658@table @code
659@item driver
660Specifies the block driver to use for the given node.
661@item node-name
662This defines the name of the block driver node by which it will be referenced
663later. The name must be unique, i.e. it must not match the name of a different
664block driver node, or (if you use @option{-drive} as well) the ID of a drive.
665
666If no node name is specified, it is automatically generated. The generated node
667name is not intended to be predictable and changes between QEMU invocations.
668For the top level, an explicit node name must be specified.
669@item read-only
670Open the node read-only. Guest write attempts will fail.
671@item cache.direct
672The host page cache can be avoided with @option{cache.direct=on}. This will
673attempt to do disk IO directly to the guest's memory. QEMU may still perform an
674internal copy of the data.
675@item cache.no-flush
676In case you don't care about data integrity over host failures, you can use
677@option{cache.no-flush=on}. This option tells QEMU that it never needs to write
678any data to the disk but can instead keep things in cache. If anything goes
679wrong, like your host losing power, the disk storage getting disconnected
680accidentally, etc. your image will most probably be rendered unusable.
681@item discard=@var{discard}
682@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
683whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
684ignored or passed to the filesystem. Some machine types may not support
685discard requests.
686@item detect-zeroes=@var{detect-zeroes}
687@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
688conversion of plain zero writes by the OS to driver specific optimized
689zero write commands. You may even choose "unmap" if @var{discard} is set
690to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
691@end table
692
Kevin Wolf370e8322016-09-22 17:24:38 +0200693@item Driver-specific options for @code{file}
694
695This is the protocol-level block driver for accessing regular files.
696
697@table @code
698@item filename
699The path to the image file in the local filesystem
700@item aio
701Specifies the AIO backend (threads/native, default: threads)
Fam Zheng1878eaf2017-11-24 16:53:51 +0800702@item locking
703Specifies whether the image file is protected with Linux OFD / POSIX locks. The
704default is to use the Linux Open File Descriptor API if available, otherwise no
705lock is applied. (auto/on/off, default: auto)
Kevin Wolf370e8322016-09-22 17:24:38 +0200706@end table
707Example:
708@example
709-blockdev driver=file,node-name=disk,filename=disk.img
710@end example
711
712@item Driver-specific options for @code{raw}
713
714This is the image format block driver for raw images. It is usually
715stacked on top of a protocol level block driver such as @code{file}.
716
717@table @code
718@item file
719Reference to or definition of the data source block driver node
720(e.g. a @code{file} driver node)
721@end table
722Example 1:
723@example
724-blockdev driver=file,node-name=disk_file,filename=disk.img
725-blockdev driver=raw,node-name=disk,file=disk_file
726@end example
727Example 2:
728@example
729-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
730@end example
731
732@item Driver-specific options for @code{qcow2}
733
734This is the image format block driver for qcow2 images. It is usually
735stacked on top of a protocol level block driver such as @code{file}.
736
737@table @code
738@item file
739Reference to or definition of the data source block driver node
740(e.g. a @code{file} driver node)
741
742@item backing
743Reference to or definition of the backing file block device (default is taken
744from the image file). It is allowed to pass an empty string here in order to
745disable the default backing file.
746
747@item lazy-refcounts
748Whether to enable the lazy refcounts feature (on/off; default is taken from the
749image file)
750
751@item cache-size
752The maximum total size of the L2 table and refcount block caches in bytes
753(default: 1048576 bytes or 8 clusters, whichever is larger)
754
755@item l2-cache-size
756The maximum size of the L2 table cache in bytes
757(default: 4/5 of the total cache size)
758
759@item refcount-cache-size
760The maximum size of the refcount block cache in bytes
761(default: 1/5 of the total cache size)
762
763@item cache-clean-interval
764Clean unused entries in the L2 and refcount caches. The interval is in seconds.
765The default value is 0 and it disables this feature.
766
767@item pass-discard-request
768Whether discard requests to the qcow2 device should be forwarded to the data
769source (on/off; default: on if discard=unmap is specified, off otherwise)
770
771@item pass-discard-snapshot
772Whether discard requests for the data source should be issued when a snapshot
773operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
774default: on)
775
776@item pass-discard-other
777Whether discard requests for the data source should be issued on other
778occasions where a cluster gets freed (on/off; default: off)
779
780@item overlap-check
781Which overlap checks to perform for writes to the image
782(none/constant/cached/all; default: cached). For details or finer
783granularity control refer to the QAPI documentation of @code{blockdev-add}.
784@end table
785
786Example 1:
787@example
788-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
789-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
790@end example
791Example 2:
792@example
793-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
794@end example
795
796@item Driver-specific options for other drivers
797Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
798
Kevin Wolfdfaca462016-09-22 16:53:24 +0200799@end table
800
801ETEXI
Markus Armbruster42e5f392017-02-28 22:27:07 +0100802
blueswir15824d652009-03-28 06:44:27 +0000803DEF("drive", HAS_ARG, QEMU_OPTION_drive,
804 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
805 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100806 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
Stefan Hajnoczid1db7602014-04-23 13:55:37 +0200807 " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
808 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000809 " [,readonly=on|off][,copy-on-read=on|off]\n"
Peter Lieven2f7133b2014-07-28 21:53:02 +0200810 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
Benoît Canet3e9fab62013-09-02 14:14:40 +0200811 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
812 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
813 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
814 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
Benoît Canet2024c1d2013-09-02 14:14:41 +0200815 " [[,iops_size=is]]\n"
Alberto Garcia76f4afb2015-06-08 18:17:44 +0200816 " [[,group=g]]\n"
Blue Swirlad960902010-03-29 19:23:52 +0000817 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000818STEXI
819@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100820@findex -drive
blueswir15824d652009-03-28 06:44:27 +0000821
Kevin Wolfdfaca462016-09-22 16:53:24 +0200822Define a new drive. This includes creating a block driver node (the backend) as
823well as a guest device, and is mostly a shortcut for defining the corresponding
824@option{-blockdev} and @option{-device} options.
825
826@option{-drive} accepts all options that are accepted by @option{-blockdev}. In
827addition, it knows the following options:
blueswir15824d652009-03-28 06:44:27 +0000828
Kevin Wolfb3f046c2009-10-09 10:58:35 +0200829@table @option
blueswir15824d652009-03-28 06:44:27 +0000830@item file=@var{file}
831This option defines which disk image (@pxref{disk_images}) to use with
832this drive. If the filename contains comma, you must double it
833(for instance, "file=my,,file" to use file "my,file").
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +1100834
835Special files such as iSCSI devices can be specified using protocol
836specific URLs. See the section for "Device URL Syntax" for more information.
blueswir15824d652009-03-28 06:44:27 +0000837@item if=@var{interface}
838This option defines on which type on interface the drive is connected.
Craig Jellicked1fcd02017-03-17 08:49:55 -0700839Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
blueswir15824d652009-03-28 06:44:27 +0000840@item bus=@var{bus},unit=@var{unit}
841These options define where is connected the drive by defining the bus number and
842the unit id.
843@item index=@var{index}
844This option defines where is connected the drive by using an index in the list
845of available connectors of a given interface type.
846@item media=@var{media}
847This option defines the type of the media: disk or cdrom.
848@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
Thomas Huthd1cdd922017-12-18 18:14:32 +0100849Force disk physical geometry and the optional BIOS translation (trans=none or
850lba). These parameters are deprecated, use the corresponding parameters
Thomas Huthc616f162017-05-12 12:33:49 +0200851of @code{-device} instead.
blueswir15824d652009-03-28 06:44:27 +0000852@item snapshot=@var{snapshot}
Michael Tokarev9d85d552014-04-07 13:34:58 +0400853@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
854(see @option{-snapshot}).
blueswir15824d652009-03-28 06:44:27 +0000855@item cache=@var{cache}
Kevin Wolfdfaca462016-09-22 16:53:24 +0200856@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
857and controls how the host cache is used to access block data. This is a
858shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
859options (as in @option{-blockdev}), and additionally @option{cache.writeback},
860which provides a default for the @option{write-cache} option of block guest
861devices (as in @option{-device}). The modes correspond to the following
862settings:
863
864@c Our texi2pod.pl script doesn't support @multitable, so fall back to using
865@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
866@c and the HTML output.
867@example
868@ │ cache.writeback cache.direct cache.no-flush
869─────────────┼─────────────────────────────────────────────────
870writeback │ on off off
871none │ on on off
872writethrough │ off off off
873directsync │ off on off
874unsafe │ on off on
875@end example
876
877The default mode is @option{cache=writeback}.
878
Christoph Hellwig5c6c3a62009-08-20 16:58:35 +0200879@item aio=@var{aio}
880@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
blueswir15824d652009-03-28 06:44:27 +0000881@item format=@var{format}
882Specify which disk @var{format} will be used rather than detecting
Michael Tokarevd33c8a72016-05-18 15:47:53 +0300883the format. Can be used to specify format=raw to avoid interpreting
blueswir15824d652009-03-28 06:44:27 +0000884an untrusted format header.
885@item serial=@var{serial}
Thomas Huthc616f162017-05-12 12:33:49 +0200886This option specifies the serial number to assign to the device. This
887parameter is deprecated, use the corresponding parameter of @code{-device}
888instead.
Markus Armbrusterc2cc47a2009-06-18 15:14:10 +0200889@item addr=@var{addr}
Thomas Huthc616f162017-05-12 12:33:49 +0200890Specify the controller's PCI address (if=virtio only). This parameter is
891deprecated, use the corresponding parameter of @code{-device} instead.
Luiz Capitulinoae73e592011-07-12 17:35:08 -0300892@item werror=@var{action},rerror=@var{action}
893Specify which @var{action} to take on write and read errors. Valid actions are:
894"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
895"report" (report the error to the guest), "enospc" (pause QEMU only if the
896host disk is full; report the error to the guest otherwise).
897The default setting is @option{werror=enospc} and @option{rerror=report}.
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000898@item copy-on-read=@var{copy-on-read}
899@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
900file sectors into the image file.
Stefan Hajnoczi01f9cfa2017-03-01 11:50:24 +0000901@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
902Specify bandwidth throttling limits in bytes per second, either for all request
903types or for reads or writes only. Small values can lead to timeouts or hangs
904inside the guest. A safe minimum for disks is 2 MB/s.
905@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
906Specify bursts in bytes per second, either for all request types or for reads
907or writes only. Bursts allow the guest I/O to spike above the limit
908temporarily.
909@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
910Specify request rate limits in requests per second, either for all request
911types or for reads or writes only.
912@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
913Specify bursts in requests per second, either for all request types or for reads
914or writes only. Bursts allow the guest I/O to spike above the limit
915temporarily.
916@item iops_size=@var{is}
917Let every @var{is} bytes of a request count as a new request for iops
918throttling purposes. Use this option to prevent guests from circumventing iops
919limits by sending fewer but larger requests.
920@item group=@var{g}
921Join a throttling quota group with given name @var{g}. All drives that are
922members of the same group are accounted for together. Use this option to
923prevent guests from circumventing throttling limits by using many small disks
924instead of a single larger disk.
blueswir15824d652009-03-28 06:44:27 +0000925@end table
926
Kevin Wolfdfaca462016-09-22 16:53:24 +0200927By default, the @option{cache.writeback=on} mode is used. It will report data
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100928writes as completed as soon as the data is present in the host page cache.
929This is safe as long as your guest OS makes sure to correctly flush disk caches
930where needed. If your guest OS does not handle volatile disk write caches
931correctly and your host crashes or loses power, then the guest may experience
932data corruption.
blueswir15824d652009-03-28 06:44:27 +0000933
Kevin Wolfdfaca462016-09-22 16:53:24 +0200934For such guests, you should consider using @option{cache.writeback=off}. This
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100935means that the host page cache will be used to read and write data, but write
936notification will be sent to the guest only after QEMU has made sure to flush
937each write to the disk. Be aware that this has a major impact on performance.
blueswir15824d652009-03-28 06:44:27 +0000938
Kevin Wolfdfaca462016-09-22 16:53:24 +0200939When using the @option{-snapshot} option, unsafe caching is always used.
Alexander Graf016f5cf2010-05-26 17:51:49 +0200940
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000941Copy-on-read avoids accessing the same backing file sectors repeatedly and is
942useful when the backing file is over a slow network. By default copy-on-read
943is off.
944
blueswir15824d652009-03-28 06:44:27 +0000945Instead of @option{-cdrom} you can use:
946@example
Stefan Weil3804da92012-05-11 22:21:50 +0200947qemu-system-i386 -drive file=file,index=2,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000948@end example
949
950Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
951use:
952@example
Stefan Weil3804da92012-05-11 22:21:50 +0200953qemu-system-i386 -drive file=file,index=0,media=disk
954qemu-system-i386 -drive file=file,index=1,media=disk
955qemu-system-i386 -drive file=file,index=2,media=disk
956qemu-system-i386 -drive file=file,index=3,media=disk
blueswir15824d652009-03-28 06:44:27 +0000957@end example
958
Corey Bryant587ed6b2012-10-18 15:19:34 -0400959You can open an image using pre-opened file descriptors from an fd set:
960@example
961qemu-system-i386
962-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
963-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
964-drive file=/dev/fdset/2,index=0,media=disk
965@end example
966
blueswir15824d652009-03-28 06:44:27 +0000967You can connect a CDROM to the slave of ide0:
968@example
Stefan Weil3804da92012-05-11 22:21:50 +0200969qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000970@end example
971
972If you don't specify the "file=" argument, you define an empty drive:
973@example
Stefan Weil3804da92012-05-11 22:21:50 +0200974qemu-system-i386 -drive if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000975@end example
976
blueswir15824d652009-03-28 06:44:27 +0000977Instead of @option{-fda}, @option{-fdb}, you can use:
978@example
Stefan Weil3804da92012-05-11 22:21:50 +0200979qemu-system-i386 -drive file=file,index=0,if=floppy
980qemu-system-i386 -drive file=file,index=1,if=floppy
blueswir15824d652009-03-28 06:44:27 +0000981@end example
982
983By default, @var{interface} is "ide" and @var{index} is automatically
984incremented:
985@example
Stefan Weil3804da92012-05-11 22:21:50 +0200986qemu-system-i386 -drive file=a -drive file=b"
blueswir15824d652009-03-28 06:44:27 +0000987@end example
988is interpreted like:
989@example
Stefan Weil3804da92012-05-11 22:21:50 +0200990qemu-system-i386 -hda a -hdb b
blueswir15824d652009-03-28 06:44:27 +0000991@end example
992ETEXI
993
994DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
Blue Swirlad960902010-03-29 19:23:52 +0000995 "-mtdblock file use 'file' as on-board Flash memory image\n",
996 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000997STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200998@item -mtdblock @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100999@findex -mtdblock
Kevin Wolf4e257e52009-10-09 10:58:36 +02001000Use @var{file} as on-board Flash memory image.
blueswir15824d652009-03-28 06:44:27 +00001001ETEXI
1002
1003DEF("sd", HAS_ARG, QEMU_OPTION_sd,
Blue Swirlad960902010-03-29 19:23:52 +00001004 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001005STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02001006@item -sd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001007@findex -sd
Kevin Wolf4e257e52009-10-09 10:58:36 +02001008Use @var{file} as SecureDigital card image.
blueswir15824d652009-03-28 06:44:27 +00001009ETEXI
1010
1011DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
Blue Swirlad960902010-03-29 19:23:52 +00001012 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001013STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02001014@item -pflash @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001015@findex -pflash
Kevin Wolf4e257e52009-10-09 10:58:36 +02001016Use @var{file} as a parallel flash image.
blueswir15824d652009-03-28 06:44:27 +00001017ETEXI
1018
blueswir15824d652009-03-28 06:44:27 +00001019DEF("snapshot", 0, QEMU_OPTION_snapshot,
Blue Swirlad960902010-03-29 19:23:52 +00001020 "-snapshot write to temporary files instead of disk image files\n",
1021 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001022STEXI
1023@item -snapshot
Stefan Weil6616b2a2010-02-05 23:52:05 +01001024@findex -snapshot
blueswir15824d652009-03-28 06:44:27 +00001025Write to temporary files instead of disk image files. In this case,
1026the raw disk image you use is not written back. You can however force
1027the write back by pressing @key{C-a s} (@pxref{disk_images}).
1028ETEXI
1029
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301030DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301031 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001032 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
Pradeep Jagadeeshb8bbdb82017-02-28 10:31:46 +01001033 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1034 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1035 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1036 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1037 " [[,throttling.iops-size=is]]\n",
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301038 QEMU_ARCH_ALL)
1039
1040STEXI
1041
Tobias Schrammb96feb22017-06-29 15:11:50 +02001042@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}][,fmode=@var{fmode}][,dmode=@var{dmode}]
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301043@findex -fsdev
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301044Define a new file system device. Valid options are:
1045@table @option
1046@item @var{fsdriver}
1047This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301048Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301049@item id=@var{id}
1050Specifies identifier for this device
1051@item path=@var{path}
1052Specifies the export path for the file system device. Files under
1053this path will be available to the 9p client on the guest.
1054@item security_model=@var{security_model}
1055Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301056Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301057In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001058credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301059to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301060attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301061file attributes. For "mapped-file" these attributes are stored in the
1062hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301063interact with other unix tools. "none" security model is same as
1064passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301065set file attributes like ownership. Security model is mandatory
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301066only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301067security model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301068@item writeout=@var{writeout}
1069This is an optional argument. The only supported value is "immediate".
1070This means that host page cache will be used to read and write data but
1071write notification will be sent to the guest only when the data has been
1072reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301073@item readonly
1074Enables exporting 9p share as a readonly mount for guests. By default
1075read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301076@item socket=@var{socket}
1077Enables proxy filesystem driver to use passed socket file for communicating
1078with virtfs-proxy-helper
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301079@item sock_fd=@var{sock_fd}
1080Enables proxy filesystem driver to use passed socket descriptor for
1081communicating with virtfs-proxy-helper. Usually a helper like libvirt
1082will create socketpair and pass one of the fds as sock_fd
Tobias Schrammb96feb22017-06-29 15:11:50 +02001083@item fmode=@var{fmode}
1084Specifies the default mode for newly created files on the host. Works only
1085with security models "mapped-xattr" and "mapped-file".
1086@item dmode=@var{dmode}
1087Specifies the default mode for newly created directories on the host. Works
1088only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301089@end table
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301090
1091-fsdev option is used along with -device driver "virtio-9p-pci".
1092@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
1093Options for virtio-9p-pci driver are:
1094@table @option
1095@item fsdev=@var{id}
1096Specifies the id value specified along with -fsdev option
1097@item mount_tag=@var{mount_tag}
1098Specifies the tag name to be used by the guest to mount this export point
1099@end table
1100
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301101ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301102
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301103DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301104 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001105 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n",
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301106 QEMU_ARCH_ALL)
1107
1108STEXI
1109
Tobias Schrammb96feb22017-06-29 15:11:50 +02001110@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}][,fmode=@var{fmode}][,dmode=@var{dmode}]
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301111@findex -virtfs
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301112
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301113The general form of a Virtual File system pass-through options are:
1114@table @option
1115@item @var{fsdriver}
1116This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301117Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301118@item id=@var{id}
1119Specifies identifier for this device
1120@item path=@var{path}
1121Specifies the export path for the file system device. Files under
1122this path will be available to the 9p client on the guest.
1123@item security_model=@var{security_model}
1124Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301125Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301126In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001127credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301128to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301129attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301130file attributes. For "mapped-file" these attributes are stored in the
1131hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301132interact with other unix tools. "none" security model is same as
1133passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301134set file attributes like ownership. Security model is mandatory only
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301135for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301136model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301137@item writeout=@var{writeout}
1138This is an optional argument. The only supported value is "immediate".
1139This means that host page cache will be used to read and write data but
1140write notification will be sent to the guest only when the data has been
1141reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301142@item readonly
1143Enables exporting 9p share as a readonly mount for guests. By default
1144read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301145@item socket=@var{socket}
1146Enables proxy filesystem driver to use passed socket file for
1147communicating with virtfs-proxy-helper. Usually a helper like libvirt
1148will create socketpair and pass one of the fds as sock_fd
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301149@item sock_fd
1150Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1151descriptor for interfacing with virtfs-proxy-helper
Tobias Schrammb96feb22017-06-29 15:11:50 +02001152@item fmode=@var{fmode}
1153Specifies the default mode for newly created files on the host. Works only
1154with security models "mapped-xattr" and "mapped-file".
1155@item dmode=@var{dmode}
1156Specifies the default mode for newly created directories on the host. Works
1157only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301158@end table
1159ETEXI
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301160
Aneesh Kumar K.V9db221a2011-10-25 12:10:40 +05301161DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
1162 "-virtfs_synth Create synthetic file system image\n",
1163 QEMU_ARCH_ALL)
1164STEXI
1165@item -virtfs_synth
1166@findex -virtfs_synth
1167Create synthetic file system image
1168ETEXI
1169
Markus Armbruster61d70482017-10-02 16:03:03 +02001170DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1171 "-iscsi [user=user][,password=password]\n"
1172 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1173 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1174 " [,timeout=timeout]\n"
1175 " iSCSI session parameters\n", QEMU_ARCH_ALL)
1176
blueswir15824d652009-03-28 06:44:27 +00001177STEXI
Markus Armbruster44743142017-10-02 16:03:04 +02001178@item -iscsi
1179@findex -iscsi
1180Configure iSCSI session parameters.
1181ETEXI
1182
1183STEXI
blueswir15824d652009-03-28 06:44:27 +00001184@end table
1185ETEXI
blueswir15824d652009-03-28 06:44:27 +00001186DEFHEADING()
1187
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001188DEFHEADING(USB options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001189STEXI
1190@table @option
1191ETEXI
1192
1193DEF("usb", 0, QEMU_OPTION_usb,
Thomas Hutha358a3a2017-05-19 08:35:16 +02001194 "-usb enable the USB driver (if it is not used by default yet)\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001195 QEMU_ARCH_ALL)
1196STEXI
1197@item -usb
1198@findex -usb
Thomas Hutha358a3a2017-05-19 08:35:16 +02001199Enable the USB driver (if it is not used by default yet).
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001200ETEXI
1201
1202DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1203 "-usbdevice name add the host or guest USB device 'name'\n",
1204 QEMU_ARCH_ALL)
1205STEXI
1206
1207@item -usbdevice @var{devname}
1208@findex -usbdevice
Thomas Hutha358a3a2017-05-19 08:35:16 +02001209Add the USB device @var{devname}. Note that this option is deprecated,
1210please use @code{-device usb-...} instead. @xref{usb_devices}.
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001211
1212@table @option
1213
1214@item mouse
1215Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1216
1217@item tablet
1218Pointer device that uses absolute coordinates (like a touchscreen). This
1219means QEMU is able to report the mouse position without having to grab the
1220mouse. Also overrides the PS/2 mouse emulation when activated.
1221
1222@item disk:[format=@var{format}]:@var{file}
1223Mass storage device based on file. The optional @var{format} argument
Michael Tokarevd33c8a72016-05-18 15:47:53 +03001224will be used rather than detecting the format. Can be used to specify
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001225@code{format=raw} to avoid interpreting an untrusted format header.
1226
1227@item host:@var{bus}.@var{addr}
1228Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
1229
1230@item host:@var{vendor_id}:@var{product_id}
1231Pass through the host device identified by @var{vendor_id}:@var{product_id}
1232(Linux only).
1233
1234@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
1235Serial converter to host character device @var{dev}, see @code{-serial} for the
1236available devices.
1237
1238@item braille
1239Braille device. This will use BrlAPI to display the braille output on a real
1240or fake device.
1241
1242@item net:@var{options}
1243Network adapter that supports CDC ethernet and RNDIS protocols.
1244
1245@end table
1246ETEXI
1247
1248STEXI
1249@end table
1250ETEXI
1251DEFHEADING()
1252
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001253DEFHEADING(Display options:)
blueswir15824d652009-03-28 06:44:27 +00001254STEXI
1255@table @option
1256ETEXI
1257
Jes Sorensen1472a952011-03-16 13:33:31 +01001258DEF("display", HAS_ARG, QEMU_OPTION_display,
1259 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
Samuel Thibault87eb2ba2017-01-15 21:30:14 +01001260 " [,window_close=on|off][,gl=on|off]\n"
Robert Hof04ec5a2016-07-26 18:17:11 +08001261 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1262 "-display vnc=<display>[,<optargs>]\n"
1263 "-display curses\n"
1264 "-display none"
1265 " select display type\n"
1266 "The default display is equivalent to\n"
1267#if defined(CONFIG_GTK)
1268 "\t\"-display gtk\"\n"
1269#elif defined(CONFIG_SDL)
1270 "\t\"-display sdl\"\n"
1271#elif defined(CONFIG_COCOA)
1272 "\t\"-display cocoa\"\n"
1273#elif defined(CONFIG_VNC)
1274 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1275#else
1276 "\t\"-display none\"\n"
1277#endif
1278 , QEMU_ARCH_ALL)
Jes Sorensen1472a952011-03-16 13:33:31 +01001279STEXI
1280@item -display @var{type}
1281@findex -display
1282Select type of display to use. This option is a replacement for the
1283old style -sdl/-curses/... options. Valid values for @var{type} are
1284@table @option
1285@item sdl
1286Display video output via SDL (usually in a separate graphics
1287window; see the SDL documentation for other possibilities).
1288@item curses
1289Display video output via curses. For graphics device models which
1290support a text mode, QEMU can display this output using a
1291curses/ncurses interface. Nothing is displayed when the graphics
1292device is in graphical mode or if the graphics device does not support
1293a text mode. Generally only the VGA device models support text mode.
Jes Sorensen4171d322011-03-16 13:33:32 +01001294@item none
1295Do not display video output. The guest will still see an emulated
1296graphics card, but its output will not be displayed to the QEMU
1297user. This option differs from the -nographic option in that it
1298only affects what is done with video output; -nographic also changes
1299the destination of the serial and parallel port data.
Jan Kiszka881249c2014-03-12 08:33:50 +01001300@item gtk
1301Display video output in a GTK window. This interface provides drop-down
1302menus and other UI elements to configure and control the VM during
1303runtime.
Jes Sorensen3264ff12011-03-16 13:33:33 +01001304@item vnc
1305Start a VNC server on display <arg>
Jes Sorensen1472a952011-03-16 13:33:31 +01001306@end table
1307ETEXI
1308
blueswir15824d652009-03-28 06:44:27 +00001309DEF("nographic", 0, QEMU_OPTION_nographic,
Blue Swirlad960902010-03-29 19:23:52 +00001310 "-nographic disable graphical output and redirect serial I/Os to console\n",
1311 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001312STEXI
1313@item -nographic
Stefan Weil6616b2a2010-02-05 23:52:05 +01001314@findex -nographic
Colin Lorddc0a3e42016-08-12 15:30:48 -04001315Normally, if QEMU is compiled with graphical window support, it displays
1316output such as guest graphics, guest console, and the QEMU monitor in a
1317window. With this option, you can totally disable graphical output so
1318that QEMU is a simple command line application. The emulated serial port
1319is redirected on the console and muxed with the monitor (unless
1320redirected elsewhere explicitly). Therefore, you can still use QEMU to
1321debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1322switching between the console and monitor.
blueswir15824d652009-03-28 06:44:27 +00001323ETEXI
1324
blueswir15824d652009-03-28 06:44:27 +00001325DEF("curses", 0, QEMU_OPTION_curses,
Robert Hof04ec5a2016-07-26 18:17:11 +08001326 "-curses shorthand for -display curses\n",
Blue Swirlad960902010-03-29 19:23:52 +00001327 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001328STEXI
1329@item -curses
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001330@findex -curses
Colin Lorddc0a3e42016-08-12 15:30:48 -04001331Normally, if QEMU is compiled with graphical window support, it displays
1332output such as guest graphics, guest console, and the QEMU monitor in a
1333window. With this option, QEMU can display the VGA output when in text
1334mode using a curses/ncurses interface. Nothing is displayed in graphical
1335mode.
blueswir15824d652009-03-28 06:44:27 +00001336ETEXI
1337
blueswir15824d652009-03-28 06:44:27 +00001338DEF("no-frame", 0, QEMU_OPTION_no_frame,
Blue Swirlad960902010-03-29 19:23:52 +00001339 "-no-frame open SDL window without a frame and window decorations\n",
1340 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001341STEXI
1342@item -no-frame
Stefan Weil6616b2a2010-02-05 23:52:05 +01001343@findex -no-frame
blueswir15824d652009-03-28 06:44:27 +00001344Do not use decorations for SDL windows and start them using the whole
1345available screen space. This makes the using QEMU in a dedicated desktop
1346workspace more convenient.
1347ETEXI
1348
blueswir15824d652009-03-28 06:44:27 +00001349DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001350 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1351 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001352STEXI
1353@item -alt-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001354@findex -alt-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001355Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1356affects the special keys (for fullscreen, monitor-mode switching, etc).
blueswir15824d652009-03-28 06:44:27 +00001357ETEXI
1358
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001359DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001360 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1361 QEMU_ARCH_ALL)
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001362STEXI
1363@item -ctrl-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001364@findex -ctrl-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001365Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1366affects the special keys (for fullscreen, monitor-mode switching, etc).
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001367ETEXI
1368
blueswir15824d652009-03-28 06:44:27 +00001369DEF("no-quit", 0, QEMU_OPTION_no_quit,
Blue Swirlad960902010-03-29 19:23:52 +00001370 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001371STEXI
1372@item -no-quit
Stefan Weil6616b2a2010-02-05 23:52:05 +01001373@findex -no-quit
blueswir15824d652009-03-28 06:44:27 +00001374Disable SDL window close capability.
1375ETEXI
1376
blueswir15824d652009-03-28 06:44:27 +00001377DEF("sdl", 0, QEMU_OPTION_sdl,
Robert Hof04ec5a2016-07-26 18:17:11 +08001378 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001379STEXI
1380@item -sdl
Stefan Weil6616b2a2010-02-05 23:52:05 +01001381@findex -sdl
blueswir15824d652009-03-28 06:44:27 +00001382Enable SDL.
1383ETEXI
1384
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001385DEF("spice", HAS_ARG, QEMU_OPTION_spice,
Yonit Halperin27af7782012-08-21 13:54:20 +03001386 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1387 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1388 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
Marc-André Lureaufe4831b2015-01-13 17:57:51 +01001389 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001390 " [,tls-ciphers=<list>]\n"
1391 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1392 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1393 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1394 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1395 " [,jpeg-wan-compression=[auto|never|always]]\n"
1396 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1397 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
Hans de Goede5ad24e52013-06-08 15:37:27 +02001398 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1399 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
Marc-André Lureau7b525502017-02-12 15:21:18 +04001400 " [,gl=[on|off]][,rendernode=<file>]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001401 " enable spice\n"
1402 " at least one of {port, tls-port} is mandatory\n",
1403 QEMU_ARCH_ALL)
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001404STEXI
1405@item -spice @var{option}[,@var{option}[,...]]
1406@findex -spice
1407Enable the spice remote desktop protocol. Valid options are
1408
1409@table @option
1410
1411@item port=<nr>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001412Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001413
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001414@item addr=<addr>
1415Set the IP address spice is listening on. Default is any address.
1416
1417@item ipv4
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001418@itemx ipv6
1419@itemx unix
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001420Force using the specified IP version.
1421
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001422@item password=<secret>
1423Set the password you need to authenticate.
1424
Marc-André Lureau48b3ed02011-05-17 10:40:33 +02001425@item sasl
1426Require that the client use SASL to authenticate with the spice.
1427The exact choice of authentication method used is controlled from the
1428system / user's SASL configuration file for the 'qemu' service. This
1429is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1430unprivileged user, an environment variable SASL_CONF_PATH can be used
1431to make it search alternate locations for the service config.
1432While some SASL auth methods can also provide data encryption (eg GSSAPI),
1433it is recommended that SASL always be combined with the 'tls' and
1434'x509' settings to enable use of SSL and server certificates. This
1435ensures a data encryption preventing compromise of authentication
1436credentials.
1437
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001438@item disable-ticketing
1439Allow client connects without authentication.
1440
Hans de Goeded4970b02011-03-27 16:43:54 +02001441@item disable-copy-paste
1442Disable copy paste between the client and the guest.
1443
Hans de Goede5ad24e52013-06-08 15:37:27 +02001444@item disable-agent-file-xfer
1445Disable spice-vdagent based file-xfer between the client and the guest.
1446
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001447@item tls-port=<nr>
1448Set the TCP port spice is listening on for encrypted channels.
1449
1450@item x509-dir=<dir>
1451Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1452
1453@item x509-key-file=<file>
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001454@itemx x509-key-password=<file>
1455@itemx x509-cert-file=<file>
1456@itemx x509-cacert-file=<file>
1457@itemx x509-dh-key-file=<file>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001458The x509 file names can also be configured individually.
1459
1460@item tls-ciphers=<list>
1461Specify which ciphers to use.
1462
Alon Levyd70d6b32011-12-20 13:05:18 +02001463@item tls-channel=[main|display|cursor|inputs|record|playback]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001464@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
Gerd Hoffmann17b6dea2010-08-27 14:09:56 +02001465Force specific channel to be used with or without TLS encryption. The
1466options can be specified multiple times to configure multiple
1467channels. The special name "default" can be used to set the default
1468mode. For channels which are not explicitly forced into one mode the
1469spice client is allowed to pick tls/plaintext as he pleases.
1470
Yonit Halperin9f04e092010-07-14 13:26:34 +03001471@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1472Configure image compression (lossless).
1473Default is auto_glz.
1474
1475@item jpeg-wan-compression=[auto|never|always]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001476@itemx zlib-glz-wan-compression=[auto|never|always]
Yonit Halperin9f04e092010-07-14 13:26:34 +03001477Configure wan image compression (lossy for slow links).
1478Default is auto.
1479
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001480@item streaming-video=[off|all|filter]
Li Zhijian93ca5192016-08-01 12:06:59 +08001481Configure video stream detection. Default is off.
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001482
1483@item agent-mouse=[on|off]
1484Enable/disable passing mouse events via vdagent. Default is on.
1485
1486@item playback-compression=[on|off]
1487Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1488
Yonit Halperin8c957052012-08-21 11:51:59 +03001489@item seamless-migration=[on|off]
1490Enable/disable spice seamless migration. Default is off.
1491
Gerd Hoffmann474114b2015-10-13 15:39:34 +02001492@item gl=[on|off]
1493Enable/disable OpenGL context. Default is off.
1494
Marc-André Lureau7b525502017-02-12 15:21:18 +04001495@item rendernode=<file>
1496DRM render node for OpenGL rendering. If not specified, it will pick
1497the first available. (Since 2.9)
1498
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001499@end table
1500ETEXI
1501
blueswir15824d652009-03-28 06:44:27 +00001502DEF("portrait", 0, QEMU_OPTION_portrait,
Blue Swirlad960902010-03-29 19:23:52 +00001503 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1504 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001505STEXI
1506@item -portrait
Stefan Weil6616b2a2010-02-05 23:52:05 +01001507@findex -portrait
blueswir15824d652009-03-28 06:44:27 +00001508Rotate graphical output 90 deg left (only PXA LCD).
1509ETEXI
1510
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001511DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1512 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1513 QEMU_ARCH_ALL)
1514STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01001515@item -rotate @var{deg}
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001516@findex -rotate
1517Rotate graphical output some deg left (only PXA LCD).
1518ETEXI
1519
blueswir15824d652009-03-28 06:44:27 +00001520DEF("vga", HAS_ARG, QEMU_OPTION_vga,
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001521 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001522 " select video card type\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001523STEXI
malce4558dc2012-08-27 18:33:21 +04001524@item -vga @var{type}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001525@findex -vga
blueswir15824d652009-03-28 06:44:27 +00001526Select type of VGA card to emulate. Valid values for @var{type} are
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001527@table @option
blueswir15824d652009-03-28 06:44:27 +00001528@item cirrus
1529Cirrus Logic GD5446 Video card. All Windows versions starting from
1530Windows 95 should recognize and use this graphic card. For optimal
1531performances, use 16 bit color depth in the guest and the host OS.
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001532(This card was the default before QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001533@item std
1534Standard VGA card with Bochs VBE extensions. If your guest OS
1535supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1536to use high resolution modes (>= 1280x1024x16) then you should use
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001537this option. (This card is the default since QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001538@item vmware
1539VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1540recent XFree86/XOrg server or Windows guest with a driver for this
1541card.
Gerd Hoffmanna19cbfb2010-04-27 11:50:11 +02001542@item qxl
1543QXL paravirtual graphic card. It is VGA compatible (including VESA
15442.0 VBE support). Works best with qxl guest drivers installed though.
1545Recommended choice when using the spice protocol.
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001546@item tcx
1547(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1548sun4m machines and offers both 8-bit and 24-bit colour depths at a
1549fixed resolution of 1024x768.
1550@item cg3
1551(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1552for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1553resolutions aimed at people wishing to run older Solaris versions.
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001554@item virtio
1555Virtio VGA card.
blueswir15824d652009-03-28 06:44:27 +00001556@item none
1557Disable VGA card.
1558@end table
1559ETEXI
1560
1561DEF("full-screen", 0, QEMU_OPTION_full_screen,
Blue Swirlad960902010-03-29 19:23:52 +00001562 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001563STEXI
1564@item -full-screen
Stefan Weil6616b2a2010-02-05 23:52:05 +01001565@findex -full-screen
blueswir15824d652009-03-28 06:44:27 +00001566Start in full screen.
1567ETEXI
1568
blueswir15824d652009-03-28 06:44:27 +00001569DEF("g", 1, QEMU_OPTION_g ,
Blue Swirlad960902010-03-29 19:23:52 +00001570 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1571 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
blueswir15824d652009-03-28 06:44:27 +00001572STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01001573@item -g @var{width}x@var{height}[x@var{depth}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001574@findex -g
Stefan Weil95d5f082010-01-20 22:25:27 +01001575Set the initial graphical resolution and depth (PPC, SPARC only).
blueswir15824d652009-03-28 06:44:27 +00001576ETEXI
1577
1578DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
Robert Hof04ec5a2016-07-26 18:17:11 +08001579 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001580STEXI
1581@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001582@findex -vnc
Colin Lorddc0a3e42016-08-12 15:30:48 -04001583Normally, if QEMU is compiled with graphical window support, it displays
1584output such as guest graphics, guest console, and the QEMU monitor in a
1585window. With this option, you can have QEMU listen on VNC display
1586@var{display} and redirect the VGA display over the VNC session. It is
1587very useful to enable the usb tablet device when using this option
Thomas Hutha358a3a2017-05-19 08:35:16 +02001588(option @option{-device usb-tablet}). When using the VNC display, you
Colin Lorddc0a3e42016-08-12 15:30:48 -04001589must use the @option{-k} parameter to set the keyboard layout if you are
1590not using en-us. Valid syntax for the @var{display} is
blueswir15824d652009-03-28 06:44:27 +00001591
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001592@table @option
blueswir15824d652009-03-28 06:44:27 +00001593
Robert Ho99a9a522016-05-31 15:03:09 +08001594@item to=@var{L}
1595
1596With this option, QEMU will try next available VNC @var{display}s, until the
1597number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1598available, e.g. port 5900+@var{display} is already used by another
1599application. By default, to=0.
1600
blueswir15824d652009-03-28 06:44:27 +00001601@item @var{host}:@var{d}
1602
1603TCP connections will only be allowed from @var{host} on display @var{d}.
1604By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1605be omitted in which case the server will accept connections from any host.
1606
Kevin Wolf4e257e52009-10-09 10:58:36 +02001607@item unix:@var{path}
blueswir15824d652009-03-28 06:44:27 +00001608
1609Connections will be allowed over UNIX domain sockets where @var{path} is the
1610location of a unix socket to listen for connections on.
1611
1612@item none
1613
1614VNC is initialized but not started. The monitor @code{change} command
1615can be used to later start the VNC server.
1616
1617@end table
1618
1619Following the @var{display} value there may be one or more @var{option} flags
1620separated by commas. Valid options are
1621
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001622@table @option
blueswir15824d652009-03-28 06:44:27 +00001623
1624@item reverse
1625
1626Connect to a listening VNC client via a ``reverse'' connection. The
1627client is specified by the @var{display}. For reverse network
1628connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1629is a TCP port number, not a display number.
1630
Tim Hardeck7536ee42013-01-21 11:04:44 +01001631@item websocket
1632
1633Opens an additional TCP listening port dedicated to VNC Websocket connections.
Daniel P. Berrange275e0d62017-02-03 12:06:45 +00001634If a bare @var{websocket} option is given, the Websocket port is
16355700+@var{display}. An alternative port can be specified with the
1636syntax @code{websocket}=@var{port}.
1637
1638If @var{host} is specified connections will only be allowed from this host.
1639It is possible to control the websocket listen address independently, using
1640the syntax @code{websocket}=@var{host}:@var{port}.
1641
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001642If no TLS credentials are provided, the websocket connection runs in
1643unencrypted mode. If TLS credentials are provided, the websocket connection
1644requires encrypted client connections.
Tim Hardeck7536ee42013-01-21 11:04:44 +01001645
blueswir15824d652009-03-28 06:44:27 +00001646@item password
1647
1648Require that password based authentication is used for client connections.
Michal Novotny86ee5bc2012-07-16 15:54:38 +02001649
1650The password must be set separately using the @code{set_password} command in
1651the @ref{pcsys_monitor}. The syntax to change your password is:
1652@code{set_password <protocol> <password>} where <protocol> could be either
1653"vnc" or "spice".
1654
1655If you would like to change <protocol> password expiration, you should use
1656@code{expire_password <protocol> <expiration-time>} where expiration time could
1657be one of the following options: now, never, +seconds or UNIX time of
1658expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1659to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1660date and time).
1661
1662You can also use keywords "now" or "never" for the expiration time to
1663allow <protocol> password to expire immediately or never expire.
blueswir15824d652009-03-28 06:44:27 +00001664
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001665@item tls-creds=@var{ID}
1666
1667Provides the ID of a set of TLS credentials to use to secure the
1668VNC server. They will apply to both the normal VNC server socket
1669and the websocket socket (if enabled). Setting TLS credentials
1670will cause the VNC server socket to enable the VeNCrypt auth
1671mechanism. The credentials should have been previously created
1672using the @option{-object tls-creds} argument.
1673
1674The @option{tls-creds} parameter obsoletes the @option{tls},
1675@option{x509}, and @option{x509verify} options, and as such
1676it is not permitted to set both new and old type options at
1677the same time.
1678
blueswir15824d652009-03-28 06:44:27 +00001679@item tls
1680
1681Require that client use TLS when communicating with the VNC server. This
1682uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1683attack. It is recommended that this option be combined with either the
Kevin Wolf4e257e52009-10-09 10:58:36 +02001684@option{x509} or @option{x509verify} options.
blueswir15824d652009-03-28 06:44:27 +00001685
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001686This option is now deprecated in favor of using the @option{tls-creds}
1687argument.
1688
blueswir15824d652009-03-28 06:44:27 +00001689@item x509=@var{/path/to/certificate/dir}
1690
1691Valid if @option{tls} is specified. Require that x509 credentials are used
1692for negotiating the TLS session. The server will send its x509 certificate
1693to the client. It is recommended that a password be set on the VNC server
1694to provide authentication of the client when this is used. The path following
1695this option specifies where the x509 certificates are to be loaded from.
1696See the @ref{vnc_security} section for details on generating certificates.
1697
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001698This option is now deprecated in favour of using the @option{tls-creds}
1699argument.
1700
blueswir15824d652009-03-28 06:44:27 +00001701@item x509verify=@var{/path/to/certificate/dir}
1702
1703Valid if @option{tls} is specified. Require that x509 credentials are used
1704for negotiating the TLS session. The server will send its x509 certificate
1705to the client, and request that the client send its own x509 certificate.
1706The server will validate the client's certificate against the CA certificate,
1707and reject clients when validation fails. If the certificate authority is
1708trusted, this is a sufficient authentication mechanism. You may still wish
1709to set a password on the VNC server as a second authentication layer. The
1710path following this option specifies where the x509 certificates are to
1711be loaded from. See the @ref{vnc_security} section for details on generating
1712certificates.
1713
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001714This option is now deprecated in favour of using the @option{tls-creds}
1715argument.
1716
blueswir15824d652009-03-28 06:44:27 +00001717@item sasl
1718
1719Require that the client use SASL to authenticate with the VNC server.
1720The exact choice of authentication method used is controlled from the
1721system / user's SASL configuration file for the 'qemu' service. This
1722is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1723unprivileged user, an environment variable SASL_CONF_PATH can be used
1724to make it search alternate locations for the service config.
1725While some SASL auth methods can also provide data encryption (eg GSSAPI),
1726it is recommended that SASL always be combined with the 'tls' and
1727'x509' settings to enable use of SSL and server certificates. This
1728ensures a data encryption preventing compromise of authentication
1729credentials. See the @ref{vnc_security} section for details on using
1730SASL authentication.
1731
1732@item acl
1733
1734Turn on access control lists for checking of the x509 client certificate
1735and SASL party. For x509 certs, the ACL check is made against the
1736certificate's distinguished name. This is something that looks like
1737@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1738made against the username, which depending on the SASL plugin, may
1739include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1740When the @option{acl} flag is set, the initial access list will be
1741empty, with a @code{deny} policy. Thus no one will be allowed to
1742use the VNC server until the ACLs have been loaded. This can be
1743achieved using the @code{acl} monitor command.
1744
Corentin Chary6f9c78c2010-07-07 20:57:51 +02001745@item lossy
1746
1747Enable lossy compression methods (gradient, JPEG, ...). If this
1748option is set, VNC client may receive lossy framebuffer updates
1749depending on its encoding settings. Enabling this option can save
1750a lot of bandwidth at the expense of quality.
1751
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001752@item non-adaptive
1753
1754Disable adaptive encodings. Adaptive encodings are enabled by default.
1755An adaptive encoding will try to detect frequently updated screen regions,
1756and send updates in these regions using a lossy encoding (like JPEG).
Stefan Weil61cc8702011-04-13 22:45:22 +02001757This can be really helpful to save bandwidth when playing videos. Disabling
Michael Tokarev9d85d552014-04-07 13:34:58 +04001758adaptive encodings restores the original static behavior of encodings
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001759like Tight.
1760
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001761@item share=[allow-exclusive|force-shared|ignore]
1762
1763Set display sharing policy. 'allow-exclusive' allows clients to ask
1764for exclusive access. As suggested by the rfb spec this is
1765implemented by dropping other connections. Connecting multiple
1766clients in parallel requires all clients asking for a shared session
1767(vncviewer: -shared switch). This is the default. 'force-shared'
1768disables exclusive client access. Useful for shared desktop sessions,
1769where you don't want someone forgetting specify -shared disconnect
1770everybody else. 'ignore' completely ignores the shared flag and
1771allows everybody connect unconditionally. Doesn't conform to the rfb
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001772spec but is traditional QEMU behavior.
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001773
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001774@item key-delay-ms
1775
1776Set keyboard delay, for key down and key up events, in milliseconds.
Alexander Grafd3b0db62017-07-12 14:43:45 +02001777Default is 10. Keyboards are low-bandwidth devices, so this slowdown
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001778can help the device and guest to keep up and not lose events in case
1779events are arriving in bulk. Possible causes for the latter are flaky
1780network connections, or scripts for automated testing.
1781
blueswir15824d652009-03-28 06:44:27 +00001782@end table
1783ETEXI
1784
1785STEXI
1786@end table
1787ETEXI
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001788ARCHHEADING(, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001789
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001790ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001791STEXI
1792@table @option
1793ETEXI
1794
blueswir15824d652009-03-28 06:44:27 +00001795DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
Blue Swirlad960902010-03-29 19:23:52 +00001796 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1797 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001798STEXI
1799@item -win2k-hack
Stefan Weil6616b2a2010-02-05 23:52:05 +01001800@findex -win2k-hack
blueswir15824d652009-03-28 06:44:27 +00001801Use it when installing Windows 2000 to avoid a disk full bug. After
1802Windows 2000 is installed, you no longer need this option (this option
1803slows down the IDE transfers).
1804ETEXI
1805
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02001806HXCOMM Deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00001807DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001808
blueswir15824d652009-03-28 06:44:27 +00001809DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
Blue Swirlad960902010-03-29 19:23:52 +00001810 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1811 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001812STEXI
1813@item -no-fd-bootchk
Stefan Weil6616b2a2010-02-05 23:52:05 +01001814@findex -no-fd-bootchk
Markus Armbruster4eda32f2013-06-14 13:15:06 +02001815Disable boot signature checking for floppy disks in BIOS. May
blueswir15824d652009-03-28 06:44:27 +00001816be needed to boot from old floppy disks.
1817ETEXI
1818
blueswir15824d652009-03-28 06:44:27 +00001819DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
Shannon Zhaof5d8c8c2015-05-29 11:28:54 +01001820 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
blueswir15824d652009-03-28 06:44:27 +00001821STEXI
1822@item -no-acpi
Stefan Weil6616b2a2010-02-05 23:52:05 +01001823@findex -no-acpi
blueswir15824d652009-03-28 06:44:27 +00001824Disable ACPI (Advanced Configuration and Power Interface) support. Use
1825it if your guest OS complains about ACPI problems (PC target machine
1826only).
1827ETEXI
1828
blueswir15824d652009-03-28 06:44:27 +00001829DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
Blue Swirlad960902010-03-29 19:23:52 +00001830 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001831STEXI
1832@item -no-hpet
Stefan Weil6616b2a2010-02-05 23:52:05 +01001833@findex -no-hpet
blueswir15824d652009-03-28 06:44:27 +00001834Disable HPET support.
1835ETEXI
1836
blueswir15824d652009-03-28 06:44:27 +00001837DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
Michael Tokarev104bf022011-05-12 18:44:17 +04001838 "-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"
Blue Swirlad960902010-03-29 19:23:52 +00001839 " ACPI table description\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001840STEXI
1841@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}]...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001842@findex -acpitable
blueswir15824d652009-03-28 06:44:27 +00001843Add ACPI table with specified header fields and context from specified files.
Michael Tokarev104bf022011-05-12 18:44:17 +04001844For file=, take whole ACPI table from the specified files, including all
1845ACPI headers (possible overridden by other options).
1846For data=, only data
1847portion of the table is used, all header information is specified in the
1848command line.
Laszlo Ersekae123742016-01-18 15:12:13 +01001849If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1850fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1851to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1852spec.
blueswir15824d652009-03-28 06:44:27 +00001853ETEXI
1854
aliguorib6f6e3d2009-04-17 18:59:56 +00001855DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1856 "-smbios file=binary\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001857 " load SMBIOS entry from binary file\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001858 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1859 " [,uefi=on|off]\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001860 " specify SMBIOS type 0 fields\n"
aliguorib6f6e3d2009-04-17 18:59:56 +00001861 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1862 " [,uuid=uuid][,sku=str][,family=str]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001863 " specify SMBIOS type 1 fields\n"
1864 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1865 " [,asset=str][,location=str]\n"
1866 " specify SMBIOS type 2 fields\n"
1867 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1868 " [,sku=str]\n"
1869 " specify SMBIOS type 3 fields\n"
1870 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1871 " [,asset=str][,part=str]\n"
1872 " specify SMBIOS type 4 fields\n"
1873 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001874 " [,asset=str][,part=str][,speed=%d]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001875 " specify SMBIOS type 17 fields\n",
Wei Huangc30e1562015-09-07 10:39:29 +01001876 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
aliguorib6f6e3d2009-04-17 18:59:56 +00001877STEXI
1878@item -smbios file=@var{binary}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001879@findex -smbios
aliguorib6f6e3d2009-04-17 18:59:56 +00001880Load SMBIOS entry from binary file.
1881
Gabriel L. Somlo84351842014-05-19 10:09:54 -04001882@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
aliguorib6f6e3d2009-04-17 18:59:56 +00001883Specify SMBIOS type 0 fields
1884
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001885@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}]
aliguorib6f6e3d2009-04-17 18:59:56 +00001886Specify SMBIOS type 1 fields
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001887
1888@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}]
1889Specify SMBIOS type 2 fields
1890
1891@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1892Specify SMBIOS type 3 fields
1893
1894@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1895Specify SMBIOS type 4 fields
1896
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001897@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}]
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001898Specify SMBIOS type 17 fields
aliguorib6f6e3d2009-04-17 18:59:56 +00001899ETEXI
1900
blueswir15824d652009-03-28 06:44:27 +00001901STEXI
1902@end table
1903ETEXI
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001904DEFHEADING()
blueswir15824d652009-03-28 06:44:27 +00001905
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001906DEFHEADING(Network options:)
blueswir15824d652009-03-28 06:44:27 +00001907STEXI
1908@table @option
1909ETEXI
1910
Jan Kiszkaad196a92009-06-24 14:42:28 +02001911HXCOMM Legacy slirp options (now moved to -net user):
1912#ifdef CONFIG_SLIRP
Blue Swirlad960902010-03-29 19:23:52 +00001913DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1914DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1915DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001916#ifndef _WIN32
Blue Swirlad960902010-03-29 19:23:52 +00001917DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001918#endif
1919#endif
1920
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001921DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
blueswir15824d652009-03-28 06:44:27 +00001922#ifdef CONFIG_SLIRP
Samuel Thibault0b11c032016-03-20 12:29:54 +01001923 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1924 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1925 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001926 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n"
Klaus Stengel63d29602012-10-27 19:53:39 +02001927 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001928#ifndef _WIN32
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001929 "[,smb=dir[,smbserver=addr]]\n"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001930#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001931 " configure a user mode network backend with ID 'str',\n"
1932 " its DHCP server and optional services\n"
blueswir15824d652009-03-28 06:44:27 +00001933#endif
1934#ifdef _WIN32
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001935 "-netdev tap,id=str,ifname=name\n"
1936 " configure a host TAP network backend with ID 'str'\n"
blueswir15824d652009-03-28 06:44:27 +00001937#else
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001938 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001939 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001940 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001941 " [,poll-us=n]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001942 " configure a host TAP network backend with ID 'str'\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001943 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001944 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1945 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1946 " to deconfigure it\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001947 " use '[down]script=no' to disable script execution\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001948 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1949 " configure it\n"
blueswir15824d652009-03-28 06:44:27 +00001950 " use 'fd=h' to connect to an already opened TAP interface\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001951 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001952 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
Michael S. Tsirkinf157ed22011-02-01 14:25:40 +02001953 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001954 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1955 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001956 " use vhost=on to enable experimental in kernel accelerator\n"
mst@redhat.com5430a282011-02-01 22:13:42 +02001957 " (only has effect for virtio guests which use MSIX)\n"
1958 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001959 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001960 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
Jason Wangec396012013-02-22 22:57:52 +08001961 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001962 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
1963 " spent on busy polling for vhost net\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001964 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1965 " configure a host TAP network backend with ID 'str' that is\n"
1966 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1967 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
Mark McLoughlin0df0ff62009-06-18 18:21:34 +01001968#endif
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001969#ifdef __linux__
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001970 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1971 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1972 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1973 " [,rxcookie=rxcookie][,offset=offset]\n"
1974 " configure a network backend with ID 'str' connected to\n"
1975 " an Ethernet over L2TPv3 pseudowire.\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001976 " Linux kernel 3.3+ as well as most routers can talk\n"
Michael Tokarev2f47b402014-07-24 20:10:17 +04001977 " L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001978 " VM to a router and even VM to Host. It is a nearly-universal\n"
1979 " standard (RFC3391). Note - this implementation uses static\n"
1980 " pre-configured tunnels (same as the Linux kernel).\n"
1981 " use 'src=' to specify source address\n"
1982 " use 'dst=' to specify destination address\n"
1983 " use 'udp=on' to specify udp encapsulation\n"
Gonglei39526512014-08-14 14:35:48 +08001984 " use 'srcport=' to specify source udp port\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001985 " use 'dstport=' to specify destination udp port\n"
1986 " use 'ipv6=on' to force v6\n"
1987 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1988 " well as a weak security measure\n"
1989 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1990 " use 'txcookie=0x012345678' to specify a txcookie\n"
1991 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1992 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1993 " use 'pincounter=on' to work around broken counter handling in peer\n"
1994 " use 'offset=X' to add an extra offset between header and data\n"
1995#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001996 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1997 " configure a network backend to connect to another network\n"
1998 " using a socket connection\n"
1999 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2000 " configure a network backend to connect to a multicast maddr and port\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08002001 " use 'localaddr=addr' to specify the host address to send packets from\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002002 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2003 " configure a network backend to connect to another network\n"
2004 " using an UDP tunnel\n"
blueswir15824d652009-03-28 06:44:27 +00002005#ifdef CONFIG_VDE
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002006 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2007 " configure a network backend to connect to port 'n' of a vde switch\n"
2008 " running on host and listening for incoming connections on 'socketpath'.\n"
blueswir15824d652009-03-28 06:44:27 +00002009 " Use group 'groupname' and mode 'octalmode' to change default\n"
2010 " ownership and permissions for communication port.\n"
2011#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01002012#ifdef CONFIG_NETMAP
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002013 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
Vincenzo Maffione58952132013-11-06 11:44:06 +01002014 " attach to the existing netmap-enabled network interface 'name', or to a\n"
2015 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2016 " netmap device, defaults to '/dev/netmap')\n"
2017#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002018 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2019 " configure a vhost-user network, backed by a chardev 'dev'\n"
2020 "-netdev hubport,id=str,hubid=n\n"
2021 " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL)
2022DEF("net", HAS_ARG, QEMU_OPTION_net,
Thomas Huth0e60a822017-12-19 16:28:55 +01002023 "-net nic[,vlan=n][,netdev=nd][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
2024 " configure or create an on-board (or machine default) NIC and\n"
2025 " connect it either to VLAN 'n' or the netdev 'nd' (for pluggable\n"
2026 " NICs please use '-device devtype,netdev=nd' instead)\n"
aliguoribb9ea792009-04-21 19:56:28 +00002027 "-net dump[,vlan=n][,file=f][,len=n]\n"
2028 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07002029 "-net none use it alone to have zero network devices. If no -net option\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002030 " is provided, the default is '-net nic -net user'\n"
2031 "-net ["
Mark McLoughlina1ea4582009-10-08 19:58:26 +01002032#ifdef CONFIG_SLIRP
2033 "user|"
2034#endif
2035 "tap|"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002036 "bridge|"
Mark McLoughlina1ea4582009-10-08 19:58:26 +01002037#ifdef CONFIG_VDE
2038 "vde|"
2039#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01002040#ifdef CONFIG_NETMAP
2041 "netmap|"
2042#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002043 "socket][,vlan=n][,option][,option][,...]\n"
2044 " old way to initialize a host network interface\n"
2045 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002046STEXI
Thomas Huth0e60a822017-12-19 16:28:55 +01002047@item -net nic[,vlan=@var{n}][,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002048@findex -net
Thomas Huth0e60a822017-12-19 16:28:55 +01002049Configure or create an on-board (or machine default) Network Interface Card
2050(NIC) and connect it either to VLAN @var{n} (@var{n} = 0 is the default), or
2051to the netdev @var{nd}. The NIC is an e1000 by default on the PC
Markus Armbruster5607c382009-06-18 15:14:08 +02002052target. Optionally, the MAC address can be changed to @var{mac}, the
2053device address set to @var{addr} (PCI cards only),
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03002054and a @var{name} can be assigned for use in monitor commands.
2055Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2056that the card should have; this option currently only affects virtio cards; set
2057@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
Stefan Weil071c9392012-04-07 09:23:36 +02002058NIC is created. QEMU can emulate several different models of network card.
blueswir15824d652009-03-28 06:44:27 +00002059Valid values for @var{type} are
Jason Wang2ec40552017-11-16 20:20:06 +08002060@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
blueswir15824d652009-03-28 06:44:27 +00002061@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
2062@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
Peter Maydell585f6032012-10-04 16:22:01 +01002063Not all devices are supported on all targets. Use @code{-net nic,model=help}
blueswir15824d652009-03-28 06:44:27 +00002064for a list of available devices for your target.
2065
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002066@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01002067@findex -netdev
Jan Kiszkaad196a92009-06-24 14:42:28 +02002068@item -net user[,@var{option}][,@var{option}][,...]
blueswir15824d652009-03-28 06:44:27 +00002069Use the user mode network stack which requires no administrator
Jan Kiszkaad196a92009-06-24 14:42:28 +02002070privilege to run. Valid options are:
blueswir15824d652009-03-28 06:44:27 +00002071
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002072@table @option
Jan Kiszkaad196a92009-06-24 14:42:28 +02002073@item vlan=@var{n}
2074Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
2075
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002076@item id=@var{id}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002077@itemx name=@var{name}
Jan Kiszkaad196a92009-06-24 14:42:28 +02002078Assign symbolic name for use in monitor commands.
2079
Samuel Thibault0b11c032016-03-20 12:29:54 +01002080@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
2081be enabled. If neither is specified both protocols are enabled.
2082
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002083@item net=@var{addr}[/@var{mask}]
2084Set IP network address the guest will see. Optionally specify the netmask,
2085either in the form a.b.c.d or as number of valid top-most bits. Default is
Brad Hardsb0b36e52011-04-24 17:19:56 +1000208610.0.2.0/24.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002087
2088@item host=@var{addr}
2089Specify the guest-visible address of the host. Default is the 2nd IP in the
2090guest network, i.e. x.x.x.2.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002091
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002092@item ipv6-net=@var{addr}[/@var{int}]
2093Set IPv6 network address the guest will see (default is fec0::/64). The
2094network prefix is given in the usual hexadecimal IPv6 address
2095notation. The prefix size is optional, and is given as the number of
2096valid top-most bits (default is 64).
Yann Bordenave7aac5312016-03-15 10:31:22 +01002097
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002098@item ipv6-host=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002099Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2100the guest network, i.e. xxxx::2.
2101
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02002102@item restrict=on|off
Brad Hardscaef55e2011-06-09 07:50:43 +10002103If this option is enabled, the guest will be isolated, i.e. it will not be
Jan Kiszkaad196a92009-06-24 14:42:28 +02002104able to contact the host and no guest IP packets will be routed over the host
Brad Hardscaef55e2011-06-09 07:50:43 +10002105to the outside. This option does not affect any explicitly set forwarding rules.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002106
2107@item hostname=@var{name}
Klaus Stengel63d29602012-10-27 19:53:39 +02002108Specifies the client hostname reported by the built-in DHCP server.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002109
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002110@item dhcpstart=@var{addr}
2111Specify the first of the 16 IPs the built-in DHCP server can assign. Default
Brad Hardsb0b36e52011-04-24 17:19:56 +10002112is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002113
2114@item dns=@var{addr}
2115Specify the guest-visible address of the virtual nameserver. The address must
2116be different from the host address. Default is the 3rd IP in the guest network,
2117i.e. x.x.x.3.
2118
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002119@item ipv6-dns=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002120Specify the guest-visible address of the IPv6 virtual nameserver. The address
2121must be different from the host address. Default is the 3rd IP in the guest
2122network, i.e. xxxx::3.
2123
Klaus Stengel63d29602012-10-27 19:53:39 +02002124@item dnssearch=@var{domain}
2125Provides an entry for the domain-search list sent by the built-in
2126DHCP server. More than one domain suffix can be transmitted by specifying
2127this option multiple times. If supported, this will cause the guest to
2128automatically try to append the given domain suffix(es) in case a domain name
2129can not be resolved.
2130
2131Example:
2132@example
2133qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
2134@end example
2135
Jan Kiszkaad196a92009-06-24 14:42:28 +02002136@item tftp=@var{dir}
2137When using the user mode network stack, activate a built-in TFTP
2138server. The files in @var{dir} will be exposed as the root of a TFTP server.
2139The TFTP client on the guest must be configured in binary mode (use the command
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002140@code{bin} of the Unix TFTP client).
Jan Kiszkaad196a92009-06-24 14:42:28 +02002141
2142@item bootfile=@var{file}
2143When using the user mode network stack, broadcast @var{file} as the BOOTP
2144filename. In conjunction with @option{tftp}, this can be used to network boot
2145a guest from a local directory.
2146
2147Example (using pxelinux):
2148@example
Stefan Weil3804da92012-05-11 22:21:50 +02002149qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
Jan Kiszkaad196a92009-06-24 14:42:28 +02002150@end example
2151
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002152@item smb=@var{dir}[,smbserver=@var{addr}]
Jan Kiszkaad196a92009-06-24 14:42:28 +02002153When using the user mode network stack, activate a built-in SMB
2154server so that Windows OSes can access to the host files in @file{@var{dir}}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002155transparently. The IP address of the SMB server can be set to @var{addr}. By
2156default the 4th IP in the guest network is used, i.e. x.x.x.4.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002157
2158In the guest Windows OS, the line:
2159@example
216010.0.2.4 smbserver
2161@end example
2162must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2163or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2164
2165Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2166
Brade2d88302011-09-02 16:53:28 -04002167Note that a SAMBA server must be installed on the host OS.
2168QEMU was tested successfully with smbd versions from Red Hat 9,
2169Fedora Core 3 and OpenSUSE 11.x.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002170
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002171@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002172Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2173the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2174@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002175given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2176be bound to a specific host interface. If no connection type is set, TCP is
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002177used. This option can be given multiple times.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002178
2179For example, to redirect host X11 connection from screen 1 to guest
2180screen 0, use the following:
2181
2182@example
2183# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02002184qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02002185# this host xterm should open in the guest X11 server
2186xterm -display :1
2187@end example
2188
2189To redirect telnet connections from host port 5555 to telnet port on
2190the guest, use the following:
2191
2192@example
2193# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02002194qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02002195telnet localhost 5555
2196@end example
2197
2198Then when you use on the host @code{telnet localhost 5555}, you
2199connect to the guest telnet server.
2200
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002201@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002202@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002203Forward guest TCP connections to the IP address @var{server} on port @var{port}
Alexander Grafb412eb62012-06-03 09:45:01 +02002204to the character device @var{dev} or to a program executed by @var{cmd:command}
2205which gets spawned for each connection. This option can be given multiple times.
2206
Stefan Weil43ffe612012-07-20 23:26:02 +02002207You can either use a chardev directly and have that one used throughout QEMU's
Alexander Grafb412eb62012-06-03 09:45:01 +02002208lifetime, like in the following example:
2209
2210@example
2211# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2212# the guest accesses it
2213qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
2214@end example
2215
2216Or you can execute a command on every TCP connection established by the guest,
Stefan Weil43ffe612012-07-20 23:26:02 +02002217so that QEMU behaves similar to an inetd process for that virtual server:
Alexander Grafb412eb62012-06-03 09:45:01 +02002218
2219@example
2220# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2221# and connect the TCP stream to its stdin/stdout
2222qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2223@end example
Jan Kiszkaad196a92009-06-24 14:42:28 +02002224
2225@end table
2226
2227Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
2228processed and applied to -net user. Mixing them with the new configuration
2229syntax gives undefined results. Their use for new applications is discouraged
2230as they will be removed from future versions.
blueswir15824d652009-03-28 06:44:27 +00002231
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002232@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
2233@itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002234Connect the host TAP network interface @var{name} to VLAN @var{n}.
2235
2236Use the network script @var{file} to configure it and the network script
blueswir15824d652009-03-28 06:44:27 +00002237@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002238automatically provides one. The default network configure script is
2239@file{/etc/qemu-ifup} and the default network deconfigure script is
2240@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2241to disable script execution.
2242
2243If running QEMU as an unprivileged user, use the network helper
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002244@var{helper} to configure the TAP interface and attach it to the bridge.
2245The default network helper executable is @file{/path/to/qemu-bridge-helper}
2246and the default bridge device is @file{br0}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002247
2248@option{fd}=@var{h} can be used to specify the handle of an already
2249opened host TAP interface.
2250
2251Examples:
blueswir15824d652009-03-28 06:44:27 +00002252
2253@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002254#launch a QEMU instance with the default network script
Stefan Weil3804da92012-05-11 22:21:50 +02002255qemu-system-i386 linux.img -net nic -net tap
blueswir15824d652009-03-28 06:44:27 +00002256@end example
2257
blueswir15824d652009-03-28 06:44:27 +00002258@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002259#launch a QEMU instance with two NICs, each one connected
2260#to a TAP device
Stefan Weil3804da92012-05-11 22:21:50 +02002261qemu-system-i386 linux.img \
2262 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
2263 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
blueswir15824d652009-03-28 06:44:27 +00002264@end example
2265
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002266@example
2267#launch a QEMU instance with the default network helper to
2268#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02002269qemu-system-i386 linux.img \
Amos Kong420508f2013-10-23 04:49:28 +08002270 -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002271@end example
2272
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002273@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002274@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002275Connect a host TAP network interface to a host bridge device.
2276
2277Use the network helper @var{helper} to configure the TAP interface and
2278attach it to the bridge. The default network helper executable is
Amos Kong420508f2013-10-23 04:49:28 +08002279@file{/path/to/qemu-bridge-helper} and the default bridge
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002280device is @file{br0}.
2281
2282Examples:
2283
2284@example
2285#launch a QEMU instance with the default network helper to
2286#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02002287qemu-system-i386 linux.img -net bridge -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002288@end example
2289
2290@example
2291#launch a QEMU instance with the default network helper to
2292#connect a TAP device to bridge qemubr0
Stefan Weil3804da92012-05-11 22:21:50 +02002293qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002294@end example
2295
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002296@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002297@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
blueswir15824d652009-03-28 06:44:27 +00002298
2299Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
2300machine using a TCP socket connection. If @option{listen} is
2301specified, QEMU waits for incoming connections on @var{port}
2302(@var{host} is optional). @option{connect} is used to connect to
2303another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2304specifies an already opened TCP socket.
2305
2306Example:
2307@example
2308# launch a first QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002309qemu-system-i386 linux.img \
2310 -net nic,macaddr=52:54:00:12:34:56 \
2311 -net socket,listen=:1234
blueswir15824d652009-03-28 06:44:27 +00002312# connect the VLAN 0 of this instance to the VLAN 0
2313# of the first instance
Stefan Weil3804da92012-05-11 22:21:50 +02002314qemu-system-i386 linux.img \
2315 -net nic,macaddr=52:54:00:12:34:57 \
2316 -net socket,connect=127.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002317@end example
2318
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002319@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002320@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
blueswir15824d652009-03-28 06:44:27 +00002321
2322Create a VLAN @var{n} shared with another QEMU virtual
2323machines using a UDP multicast socket, effectively making a bus for
2324every QEMU with same multicast address @var{maddr} and @var{port}.
2325NOTES:
2326@enumerate
2327@item
2328Several QEMU can be running on different hosts and share same bus (assuming
2329correct multicast setup for these hosts).
2330@item
2331mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2332@url{http://user-mode-linux.sf.net}.
2333@item
2334Use @option{fd=h} to specify an already opened UDP multicast socket.
2335@end enumerate
2336
2337Example:
2338@example
2339# launch one QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002340qemu-system-i386 linux.img \
2341 -net nic,macaddr=52:54:00:12:34:56 \
2342 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002343# launch another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002344qemu-system-i386 linux.img \
2345 -net nic,macaddr=52:54:00:12:34:57 \
2346 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002347# launch yet another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002348qemu-system-i386 linux.img \
2349 -net nic,macaddr=52:54:00:12:34:58 \
2350 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002351@end example
2352
2353Example (User Mode Linux compat.):
2354@example
2355# launch QEMU instance (note mcast address selected
2356# is UML's default)
Stefan Weil3804da92012-05-11 22:21:50 +02002357qemu-system-i386 linux.img \
2358 -net nic,macaddr=52:54:00:12:34:56 \
2359 -net socket,mcast=239.192.168.1:1102
blueswir15824d652009-03-28 06:44:27 +00002360# launch UML
2361/path/to/linux ubd0=/path/to/root_fs eth0=mcast
2362@end example
2363
Mike Ryan3a75e742010-12-01 11:16:47 -08002364Example (send packets from host's 1.2.3.4):
2365@example
Stefan Weil3804da92012-05-11 22:21:50 +02002366qemu-system-i386 linux.img \
2367 -net nic,macaddr=52:54:00:12:34:56 \
2368 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
Mike Ryan3a75e742010-12-01 11:16:47 -08002369@end example
2370
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002371@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}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002372@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}]
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002373Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
2374protocol to transport Ethernet (and other Layer 2) data frames between
2375two systems. It is present in routers, firewalls and the Linux kernel
2376(from version 3.3 onwards).
2377
2378This transport allows a VM to communicate to another VM, router or firewall directly.
2379
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002380@table @option
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002381@item src=@var{srcaddr}
2382 source address (mandatory)
2383@item dst=@var{dstaddr}
2384 destination address (mandatory)
2385@item udp
2386 select udp encapsulation (default is ip).
2387@item srcport=@var{srcport}
2388 source udp port.
2389@item dstport=@var{dstport}
2390 destination udp port.
2391@item ipv6
2392 force v6, otherwise defaults to v4.
2393@item rxcookie=@var{rxcookie}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002394@itemx txcookie=@var{txcookie}
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002395 Cookies are a weak form of security in the l2tpv3 specification.
2396Their function is mostly to prevent misconfiguration. By default they are 32
2397bit.
2398@item cookie64
2399 Set cookie size to 64 bit instead of the default 32
2400@item counter=off
2401 Force a 'cut-down' L2TPv3 with no counter as in
2402draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2403@item pincounter=on
2404 Work around broken counter handling in peer. This may also help on
2405networks which have packet reorder.
2406@item offset=@var{offset}
2407 Add an extra offset between header and data
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002408@end table
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002409
2410For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2411on the remote Linux host 1.2.3.4:
2412@example
2413# Setup tunnel on linux host using raw ip as encapsulation
2414# on 1.2.3.4
2415ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2416 encap udp udp_sport 16384 udp_dport 16384
2417ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2418 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2419ifconfig vmtunnel0 mtu 1500
2420ifconfig vmtunnel0 up
2421brctl addif br-lan vmtunnel0
2422
2423
2424# on 4.3.2.1
2425# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2426
2427qemu-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
2428
2429
2430@end example
2431
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002432@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002433@itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
blueswir15824d652009-03-28 06:44:27 +00002434Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
2435listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2436and MODE @var{octalmode} to change default ownership and permissions for
Stefan Weilc1ba4e02011-09-05 18:13:03 +02002437communication port. This option is only available if QEMU has been compiled
blueswir15824d652009-03-28 06:44:27 +00002438with vde support enabled.
2439
2440Example:
2441@example
2442# launch vde switch
2443vde_switch -F -sock /tmp/myswitch
2444# launch QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002445qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
blueswir15824d652009-03-28 06:44:27 +00002446@end example
2447
Stefan Hajnoczi40e8c262013-02-26 11:07:16 +01002448@item -netdev hubport,id=@var{id},hubid=@var{hubid}
2449
2450Create a hub port on QEMU "vlan" @var{hubid}.
2451
2452The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
2453netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
2454required hub automatically.
2455
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002456@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002457
2458Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2459be a unix domain socket backed one. The vhost-user uses a specifically defined
2460protocol to pass vhost ioctl replacement messages to an application on the other
2461end of the socket. On non-MSIX guests, the feature can be forced with
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002462@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2463be created for multiqueue vhost-user.
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002464
2465Example:
2466@example
2467qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2468 -numa node,memdev=mem \
Vincenzo Maffione79cad2f2017-02-20 17:45:09 +01002469 -chardev socket,id=chr0,path=/path/to/socket \
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002470 -netdev type=vhost-user,id=net0,chardev=chr0 \
2471 -device virtio-net-pci,netdev=net0
2472@end example
2473
aliguoribb9ea792009-04-21 19:56:28 +00002474@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
2475Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
2476At most @var{len} bytes (64k by default) per packet are stored. The file format is
2477libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
Thomas Huthd3e0c032015-10-13 12:40:02 +02002478Note: For devices created with '-netdev', use '-object filter-dump,...' instead.
aliguoribb9ea792009-04-21 19:56:28 +00002479
blueswir15824d652009-03-28 06:44:27 +00002480@item -net none
2481Indicate that no network devices should be configured. It is used to
2482override the default configuration (@option{-net nic -net user}) which
2483is activated if no @option{-net} options are provided.
blueswir15824d652009-03-28 06:44:27 +00002484ETEXI
2485
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002486STEXI
2487@end table
2488ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002489DEFHEADING()
2490
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002491DEFHEADING(Character device options:)
Matthew Booth7273a2d2009-10-30 13:41:12 +00002492
2493DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
Lin Ma517b3d42016-08-17 01:13:52 +08002494 "-chardev help\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002495 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Corey Minyard5dd1f022014-10-02 11:17:37 -05002496 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002497 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n"
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002498 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002499 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n"
2500 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002501 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02002502 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002503 " [,logfile=PATH][,logappend=on|off]\n"
2504 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002505 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002506 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2507 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2508 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2509 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002510#ifdef _WIN32
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002511 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2512 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002513#else
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002514 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2515 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002516#endif
2517#ifdef CONFIG_BRLAPI
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002518 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002519#endif
2520#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2521 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002522 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2523 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002524#endif
2525#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002526 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2527 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002528#endif
Alon Levycbcc6332011-01-19 10:49:50 +02002529#if defined(CONFIG_SPICE)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002530 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2531 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
Alon Levycbcc6332011-01-19 10:49:50 +02002532#endif
Blue Swirlad960902010-03-29 19:23:52 +00002533 , QEMU_ARCH_ALL
Matthew Booth7273a2d2009-10-30 13:41:12 +00002534)
2535
2536STEXI
Markus Armbrusterdddba062017-10-02 16:03:06 +02002537
2538The general form of a character device option is:
2539@table @option
Jan Kiszka97331282010-04-06 16:55:54 +02002540@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002541@findex -chardev
Matthew Booth7273a2d2009-10-30 13:41:12 +00002542Backend is one of:
2543@option{null},
2544@option{socket},
2545@option{udp},
2546@option{msmouse},
2547@option{vc},
Markus Armbruster4f573782013-07-26 16:44:32 +02002548@option{ringbuf},
Matthew Booth7273a2d2009-10-30 13:41:12 +00002549@option{file},
2550@option{pipe},
2551@option{console},
2552@option{serial},
2553@option{pty},
2554@option{stdio},
2555@option{braille},
2556@option{tty},
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002557@option{parallel},
Alon Levycbcc6332011-01-19 10:49:50 +02002558@option{parport},
2559@option{spicevmc}.
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002560@option{spiceport}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002561The specific backend will determine the applicable options.
2562
Markus Armbrusterdddba062017-10-02 16:03:06 +02002563Use @code{-chardev help} to print all available chardev backend types.
Lin Ma517b3d42016-08-17 01:13:52 +08002564
Matthew Booth7273a2d2009-10-30 13:41:12 +00002565All devices must have an id, which can be any string up to 127 characters long.
2566It is used to uniquely identify this device in other command line directives.
2567
Jan Kiszka97331282010-04-06 16:55:54 +02002568A character device may be used in multiplexing mode by multiple front-ends.
Peter Maydella40db1b2016-02-16 17:28:58 +00002569Specify @option{mux=on} to enable this mode.
2570A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2571backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2572If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2573create a multiplexer with your specified ID, and you can then configure multiple
2574front ends to use that chardev ID for their input/output. Up to four different
2575front ends can be connected to a single multiplexed chardev. (Without
2576multiplexing enabled, a chardev can only be used by a single front end.)
2577For instance you could use this to allow a single stdio chardev to be used by
2578two serial ports and the QEMU monitor:
2579
2580@example
2581-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002582-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002583-serial chardev:char0 \
2584-serial chardev:char0
2585@end example
2586
2587You can have more than one multiplexer in a system configuration; for instance
2588you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2589multiplexed between the QEMU monitor and a parallel port:
2590
2591@example
2592-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002593-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002594-parallel chardev:char0 \
2595-chardev tcp,...,mux=on,id=char1 \
2596-serial chardev:char1 \
2597-serial chardev:char1
2598@end example
2599
2600When you're using a multiplexed character device, some escape sequences are
2601interpreted in the input. @xref{mux_keys, Keys in the character backend
2602multiplexer}.
2603
2604Note that some other command line options may implicitly create multiplexed
2605character backends; for instance @option{-serial mon:stdio} creates a
2606multiplexed stdio backend connected to the serial port and the QEMU monitor,
2607and @option{-nographic} also multiplexes the console and the monitor to
2608stdio.
2609
2610There is currently no support for multiplexing in the other direction
2611(where a single QEMU front end takes input and output from multiple chardevs).
Jan Kiszka97331282010-04-06 16:55:54 +02002612
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002613Every backend supports the @option{logfile} option, which supplies the path
2614to a file to record all data transmitted via the backend. The @option{logappend}
2615option controls whether the log file will be truncated or appended to when
2616opened.
2617
Markus Armbrusterdddba062017-10-02 16:03:06 +02002618@end table
Matthew Booth7273a2d2009-10-30 13:41:12 +00002619
Markus Armbrusterdddba062017-10-02 16:03:06 +02002620The available backends are:
2621
2622@table @option
Matthew Booth7273a2d2009-10-30 13:41:12 +00002623@item -chardev null ,id=@var{id}
2624A void device. This device will not emit any data, and will drop any data it
2625receives. The null backend does not take any options.
2626
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002627@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002628
2629Create a two-way stream socket, which can be either a TCP or a unix socket. A
2630unix socket will be created if @option{path} is specified. Behaviour is
2631undefined if TCP options are specified for a unix socket.
2632
2633@option{server} specifies that the socket shall be a listening socket.
2634
2635@option{nowait} specifies that QEMU should not block waiting for a client to
2636connect to a listening socket.
2637
2638@option{telnet} specifies that traffic on the socket should interpret telnet
2639escape sequences.
2640
Corey Minyard5dd1f022014-10-02 11:17:37 -05002641@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2642the remote end goes away. qemu will delay this many seconds and then attempt
2643to reconnect. Zero disables reconnecting, and is the default.
2644
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002645@option{tls-creds} requests enablement of the TLS protocol for encryption,
2646and specifies the id of the TLS credentials to use for the handshake. The
2647credentials must be previously created with the @option{-object tls-creds}
2648argument.
2649
Matthew Booth7273a2d2009-10-30 13:41:12 +00002650TCP and unix socket options are given below:
2651
2652@table @option
2653
Aurelien Jarno8d533562010-03-27 11:52:05 +01002654@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002655
2656@option{host} for a listening socket specifies the local address to be bound.
2657For a connecting socket species the remote host to connect to. @option{host} is
2658optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2659
2660@option{port} for a listening socket specifies the local port to be bound. For a
2661connecting socket specifies the port on the remote host to connect to.
2662@option{port} can be given as either a port number or a service name.
2663@option{port} is required.
2664
2665@option{to} is only relevant to listening sockets. If it is specified, and
2666@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2667to and including @option{to} until it succeeds. @option{to} must be specified
2668as a port number.
2669
2670@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2671If neither is specified the socket may use either protocol.
2672
2673@option{nodelay} disables the Nagle algorithm.
2674
2675@item unix options: path=@var{path}
2676
2677@option{path} specifies the local path of the unix socket. @option{path} is
2678required.
2679
2680@end table
2681
2682@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2683
2684Sends all traffic from the guest to a remote host over UDP.
2685
2686@option{host} specifies the remote host to connect to. If not specified it
2687defaults to @code{localhost}.
2688
2689@option{port} specifies the port on the remote host to connect to. @option{port}
2690is required.
2691
2692@option{localaddr} specifies the local address to bind to. If not specified it
2693defaults to @code{0.0.0.0}.
2694
2695@option{localport} specifies the local port to bind to. If not specified any
2696available local port will be used.
2697
2698@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2699If neither is specified the device may use either protocol.
2700
2701@item -chardev msmouse ,id=@var{id}
2702
2703Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2704take any options.
2705
2706@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2707
2708Connect to a QEMU text console. @option{vc} may optionally be given a specific
2709size.
2710
2711@option{width} and @option{height} specify the width and height respectively of
2712the console, in pixels.
2713
2714@option{cols} and @option{rows} specify that the console be sized to fit a text
2715console with the given dimensions.
2716
Markus Armbruster4f573782013-07-26 16:44:32 +02002717@item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
Lei Li51767e72013-01-25 00:03:19 +08002718
Markus Armbruster3949e592013-02-06 21:27:24 +01002719Create a ring buffer with fixed size @option{size}.
Stefan Hajnoczie69f7d22016-09-19 11:56:26 +01002720@var{size} must be a power of two and defaults to @code{64K}.
Lei Li51767e72013-01-25 00:03:19 +08002721
Matthew Booth7273a2d2009-10-30 13:41:12 +00002722@item -chardev file ,id=@var{id} ,path=@var{path}
2723
2724Log all traffic received from the guest to a file.
2725
2726@option{path} specifies the path of the file to be opened. This file will be
2727created if it does not already exist, and overwritten if it does. @option{path}
2728is required.
2729
2730@item -chardev pipe ,id=@var{id} ,path=@var{path}
2731
2732Create a two-way connection to the guest. The behaviour differs slightly between
2733Windows hosts and other hosts:
2734
2735On Windows, a single duplex pipe will be created at
2736@file{\\.pipe\@option{path}}.
2737
2738On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2739@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2740received by the guest. Data written by the guest can be read from
2741@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2742be present.
2743
2744@option{path} forms part of the pipe path as described above. @option{path} is
2745required.
2746
2747@item -chardev console ,id=@var{id}
2748
2749Send traffic from the guest to QEMU's standard output. @option{console} does not
2750take any options.
2751
2752@option{console} is only available on Windows hosts.
2753
2754@item -chardev serial ,id=@var{id} ,path=@option{path}
2755
2756Send traffic from the guest to a serial device on the host.
2757
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01002758On Unix hosts serial will actually accept any tty device,
2759not only serial lines.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002760
2761@option{path} specifies the name of the serial device to open.
2762
2763@item -chardev pty ,id=@var{id}
2764
2765Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2766not take any options.
2767
2768@option{pty} is not available on Windows hosts.
2769
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002770@item -chardev stdio ,id=@var{id} [,signal=on|off]
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002771Connect to standard input and standard output of the QEMU process.
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002772
2773@option{signal} controls if signals are enabled on the terminal, that includes
2774exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2775default, use @option{signal=off} to disable it.
2776
Matthew Booth7273a2d2009-10-30 13:41:12 +00002777@item -chardev braille ,id=@var{id}
2778
2779Connect to a local BrlAPI server. @option{braille} does not take any options.
2780
2781@item -chardev tty ,id=@var{id} ,path=@var{path}
2782
Matthew Booth7273a2d2009-10-30 13:41:12 +00002783@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
Markus Armbrusterd037d6b2013-02-13 15:54:15 +01002784DragonFlyBSD hosts. It is an alias for @option{serial}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002785
2786@option{path} specifies the path to the tty. @option{path} is required.
2787
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002788@item -chardev parallel ,id=@var{id} ,path=@var{path}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002789@itemx -chardev parport ,id=@var{id} ,path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002790
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002791@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002792
2793Connect to a local parallel port.
2794
2795@option{path} specifies the path to the parallel port device. @option{path} is
2796required.
2797
Alon Levycbcc6332011-01-19 10:49:50 +02002798@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2799
Stefan Hajnoczi3a846902011-10-06 11:24:12 +01002800@option{spicevmc} is only available when spice support is built in.
2801
Alon Levycbcc6332011-01-19 10:49:50 +02002802@option{debug} debug level for spicevmc
2803
2804@option{name} name of spice channel to connect to
2805
2806Connect to a spice virtual machine channel, such as vdiport.
Alon Levycbcc6332011-01-19 10:49:50 +02002807
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002808@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2809
2810@option{spiceport} is only available when spice support is built in.
2811
2812@option{debug} debug level for spicevmc
2813
2814@option{name} name of spice port to connect to
2815
2816Connect to a spice port, allowing a Spice client to handle the traffic
2817identified by a name (preferably a fqdn).
Matthew Booth7273a2d2009-10-30 13:41:12 +00002818ETEXI
2819
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002820STEXI
2821@end table
2822ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002823DEFHEADING()
2824
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002825DEFHEADING(Bluetooth(R) options:)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002826STEXI
2827@table @option
2828ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002829
blueswir15824d652009-03-28 06:44:27 +00002830DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
blueswir15824d652009-03-28 06:44:27 +00002831 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2832 "-bt hci,host[:id]\n" \
2833 " use host's HCI with the given name\n" \
2834 "-bt hci[,vlan=n]\n" \
2835 " emulate a standard HCI in virtual scatternet 'n'\n" \
2836 "-bt vhci[,vlan=n]\n" \
2837 " add host computer to virtual scatternet 'n' using VHCI\n" \
2838 "-bt device:dev[,vlan=n]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00002839 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2840 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002841STEXI
blueswir15824d652009-03-28 06:44:27 +00002842@item -bt hci[...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002843@findex -bt
blueswir15824d652009-03-28 06:44:27 +00002844Defines the function of the corresponding Bluetooth HCI. -bt options
2845are matched with the HCIs present in the chosen machine type. For
2846example when emulating a machine with only one HCI built into it, only
2847the first @code{-bt hci[...]} option is valid and defines the HCI's
2848logic. The Transport Layer is decided by the machine type. Currently
2849the machines @code{n800} and @code{n810} have one HCI and all other
2850machines have none.
2851
2852@anchor{bt-hcis}
2853The following three types are recognized:
2854
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002855@table @option
blueswir15824d652009-03-28 06:44:27 +00002856@item -bt hci,null
2857(default) The corresponding Bluetooth HCI assumes no internal logic
2858and will not respond to any HCI commands or emit events.
2859
2860@item -bt hci,host[:@var{id}]
2861(@code{bluez} only) The corresponding HCI passes commands / events
2862to / from the physical HCI identified by the name @var{id} (default:
2863@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2864capable systems like Linux.
2865
2866@item -bt hci[,vlan=@var{n}]
2867Add a virtual, standard HCI that will participate in the Bluetooth
2868scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2869VLANs, devices inside a bluetooth network @var{n} can only communicate
2870with other devices in the same network (scatternet).
2871@end table
2872
2873@item -bt vhci[,vlan=@var{n}]
2874(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2875to the host bluetooth stack instead of to the emulated target. This
2876allows the host and target machines to participate in a common scatternet
2877and communicate. Requires the Linux @code{vhci} driver installed. Can
2878be used as following:
2879
2880@example
Stefan Weil3804da92012-05-11 22:21:50 +02002881qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
blueswir15824d652009-03-28 06:44:27 +00002882@end example
2883
2884@item -bt device:@var{dev}[,vlan=@var{n}]
2885Emulate a bluetooth device @var{dev} and place it in network @var{n}
2886(default @code{0}). QEMU can only emulate one type of bluetooth devices
2887currently:
2888
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002889@table @option
blueswir15824d652009-03-28 06:44:27 +00002890@item keyboard
2891Virtual wireless keyboard implementing the HIDP bluetooth profile.
2892@end table
blueswir15824d652009-03-28 06:44:27 +00002893ETEXI
2894
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002895STEXI
2896@end table
2897ETEXI
blueswir15824d652009-03-28 06:44:27 +00002898DEFHEADING()
2899
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002900#ifdef CONFIG_TPM
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002901DEFHEADING(TPM device options:)
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002902
2903DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
Stefan Berger92dcc232013-02-27 12:47:54 -05002904 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2905 " use path to provide path to a character device; default is /dev/tpm0\n"
2906 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
Amarnath Vallurif4ede812017-09-29 14:10:20 +03002907 " not provided it will be searched for in /sys/class/misc/tpm?/device\n"
2908 "-tpmdev emulator,id=id,chardev=dev\n"
2909 " configure the TPM device using chardev backend\n",
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002910 QEMU_ARCH_ALL)
2911STEXI
2912
2913The general form of a TPM device option is:
2914@table @option
2915
2916@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2917@findex -tpmdev
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002918
2919The specific backend type will determine the applicable options.
Corey Bryant28c4fa32013-03-20 12:34:49 -04002920The @code{-tpmdev} option creates the TPM backend and requires a
2921@code{-device} option that specifies the TPM frontend interface model.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002922
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002923Use @code{-tpmdev help} to print all available TPM backend types.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002924
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002925@end table
2926
2927The available backends are:
2928
2929@table @option
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002930
Stefan Berger92dcc232013-02-27 12:47:54 -05002931@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
Stefan Berger4549a8b2013-02-27 12:47:53 -05002932
2933(Linux-host only) Enable access to the host's TPM using the passthrough
2934driver.
2935
2936@option{path} specifies the path to the host's TPM device, i.e., on
2937a Linux host this would be @code{/dev/tpm0}.
2938@option{path} is optional and by default @code{/dev/tpm0} is used.
2939
Stefan Berger92dcc232013-02-27 12:47:54 -05002940@option{cancel-path} specifies the path to the host TPM device's sysfs
2941entry allowing for cancellation of an ongoing TPM command.
2942@option{cancel-path} is optional and by default QEMU will search for the
2943sysfs entry to use.
2944
Stefan Berger4549a8b2013-02-27 12:47:53 -05002945Some notes about using the host's TPM with the passthrough driver:
2946
2947The TPM device accessed by the passthrough driver must not be
2948used by any other application on the host.
2949
2950Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2951the VM's firmware (BIOS/UEFI) will not be able to initialize the
2952TPM again and may therefore not show a TPM-specific menu that would
2953otherwise allow the user to configure the TPM, e.g., allow the user to
2954enable/disable or activate/deactivate the TPM.
2955Further, if TPM ownership is released from within a VM then the host's TPM
2956will get disabled and deactivated. To enable and activate the
2957TPM again afterwards, the host has to be rebooted and the user is
2958required to enter the firmware's menu to enable and activate the TPM.
2959If the TPM is left disabled and/or deactivated most TPM commands will fail.
2960
2961To create a passthrough TPM use the following two options:
2962@example
2963-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2964@end example
2965Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2966@code{tpmdev=tpm0} in the device option.
2967
Amarnath Vallurif4ede812017-09-29 14:10:20 +03002968@item -tpmdev emulator, id=@var{id}, chardev=@var{dev}
2969
2970(Linux-host only) Enable access to a TPM emulator using Unix domain socket based
2971chardev backend.
2972
2973@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
2974
2975To create a TPM emulator backend device with chardev socket backend:
2976@example
2977
2978-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2979
2980@end example
2981
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002982ETEXI
2983
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002984STEXI
2985@end table
2986ETEXI
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002987DEFHEADING()
2988
2989#endif
2990
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002991DEFHEADING(Linux/Multiboot boot specific:)
blueswir15824d652009-03-28 06:44:27 +00002992STEXI
Alexander Graf7677f052009-06-28 16:55:55 +02002993
2994When using these options, you can use a given Linux or Multiboot
2995kernel without installing it in the disk image. It can be useful
blueswir15824d652009-03-28 06:44:27 +00002996for easier testing of various kernels.
2997
2998@table @option
2999ETEXI
3000
3001DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
Blue Swirlad960902010-03-29 19:23:52 +00003002 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003003STEXI
3004@item -kernel @var{bzImage}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003005@findex -kernel
Alexander Graf7677f052009-06-28 16:55:55 +02003006Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3007or in multiboot format.
blueswir15824d652009-03-28 06:44:27 +00003008ETEXI
3009
3010DEF("append", HAS_ARG, QEMU_OPTION_append, \
Blue Swirlad960902010-03-29 19:23:52 +00003011 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003012STEXI
3013@item -append @var{cmdline}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003014@findex -append
blueswir15824d652009-03-28 06:44:27 +00003015Use @var{cmdline} as kernel command line
3016ETEXI
3017
3018DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
Blue Swirlad960902010-03-29 19:23:52 +00003019 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003020STEXI
3021@item -initrd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003022@findex -initrd
blueswir15824d652009-03-28 06:44:27 +00003023Use @var{file} as initial ram disk.
Alexander Graf7677f052009-06-28 16:55:55 +02003024
3025@item -initrd "@var{file1} arg=foo,@var{file2}"
3026
3027This syntax is only available with multiboot.
3028
3029Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3030first module.
blueswir15824d652009-03-28 06:44:27 +00003031ETEXI
3032
Grant Likely412beee2012-03-02 11:56:38 +00003033DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
Peter A. G. Crosthwaite379b5c72012-03-04 21:03:54 +10003034 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
Grant Likely412beee2012-03-02 11:56:38 +00003035STEXI
3036@item -dtb @var{file}
3037@findex -dtb
3038Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3039on boot.
3040ETEXI
3041
blueswir15824d652009-03-28 06:44:27 +00003042STEXI
3043@end table
3044ETEXI
blueswir15824d652009-03-28 06:44:27 +00003045DEFHEADING()
3046
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003047DEFHEADING(Debug/Expert options:)
blueswir15824d652009-03-28 06:44:27 +00003048STEXI
3049@table @option
3050ETEXI
3051
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003052DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3053 "-fw_cfg [name=]<name>,file=<file>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003054 " add named fw_cfg entry with contents from file\n"
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003055 "-fw_cfg [name=]<name>,string=<str>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003056 " add named fw_cfg entry with contents from string\n",
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003057 QEMU_ARCH_ALL)
3058STEXI
Markus Armbruster63d31452016-04-18 18:29:50 +02003059
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003060@item -fw_cfg [name=]@var{name},file=@var{file}
3061@findex -fw_cfg
Markus Armbruster63d31452016-04-18 18:29:50 +02003062Add named fw_cfg entry with contents from file @var{file}.
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003063
3064@item -fw_cfg [name=]@var{name},string=@var{str}
Markus Armbruster63d31452016-04-18 18:29:50 +02003065Add named fw_cfg entry with contents from string @var{str}.
3066
3067The terminating NUL character of the contents of @var{str} will not be
3068included as part of the fw_cfg item data. To insert contents with
3069embedded NUL characters, you have to use the @var{file} parameter.
3070
3071The fw_cfg entries are passed by QEMU through to the guest.
3072
3073Example:
3074@example
3075 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3076@end example
3077creates an fw_cfg entry named opt/com.mycompany/blob with contents
3078from ./my_blob.bin.
3079
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003080ETEXI
3081
blueswir15824d652009-03-28 06:44:27 +00003082DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
Blue Swirlad960902010-03-29 19:23:52 +00003083 "-serial dev redirect the serial port to char device 'dev'\n",
3084 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003085STEXI
3086@item -serial @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003087@findex -serial
blueswir15824d652009-03-28 06:44:27 +00003088Redirect the virtual serial port to host character device
3089@var{dev}. The default device is @code{vc} in graphical mode and
3090@code{stdio} in non graphical mode.
3091
3092This option can be used several times to simulate up to 4 serial
3093ports.
3094
3095Use @code{-serial none} to disable all serial ports.
3096
3097Available character devices are:
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003098@table @option
Kevin Wolf4e257e52009-10-09 10:58:36 +02003099@item vc[:@var{W}x@var{H}]
blueswir15824d652009-03-28 06:44:27 +00003100Virtual console. Optionally, a width and height can be given in pixel with
3101@example
3102vc:800x600
3103@end example
3104It is also possible to specify width or height in characters:
3105@example
3106vc:80Cx24C
3107@end example
3108@item pty
3109[Linux only] Pseudo TTY (a new PTY is automatically allocated)
3110@item none
3111No device is allocated.
3112@item null
3113void device
Ingo van Lil88e020e2013-12-20 14:44:53 +01003114@item chardev:@var{id}
3115Use a named character device defined with the @code{-chardev} option.
blueswir15824d652009-03-28 06:44:27 +00003116@item /dev/XXX
3117[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3118parameters are set according to the emulated ones.
3119@item /dev/parport@var{N}
3120[Linux only, parallel port only] Use host parallel port
3121@var{N}. Currently SPP and EPP parallel port features can be used.
3122@item file:@var{filename}
3123Write output to @var{filename}. No character can be read.
3124@item stdio
3125[Unix only] standard input/output
3126@item pipe:@var{filename}
3127name pipe @var{filename}
3128@item COM@var{n}
3129[Windows only] Use host serial port @var{n}
3130@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3131This implements UDP Net Console.
3132When @var{remote_host} or @var{src_ip} are not specified
3133they default to @code{0.0.0.0}.
3134When not using a specified @var{src_port} a random port is automatically chosen.
blueswir15824d652009-03-28 06:44:27 +00003135
3136If you just want a simple readonly console you can use @code{netcat} or
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003137@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3138@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
blueswir15824d652009-03-28 06:44:27 +00003139will appear in the netconsole session.
3140
3141If you plan to send characters back via netconsole or you want to stop
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003142and start QEMU a lot of times, you should have QEMU use the same
blueswir15824d652009-03-28 06:44:27 +00003143source port each time by using something like @code{-serial
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003144udp::4555@@:4556} to QEMU. Another approach is to use a patched
blueswir15824d652009-03-28 06:44:27 +00003145version of netcat which can listen to a TCP port and send and receive
3146characters via udp. If you have a patched version of netcat which
3147activates telnet remote echo and single char transfer, then you can
Marc-André Lureaubd1caa32016-12-22 18:56:38 +04003148use the following options to set up a netcat redirector to allow
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003149telnet on port 5555 to access the QEMU port.
blueswir15824d652009-03-28 06:44:27 +00003150@table @code
Stefan Weil071c9392012-04-07 09:23:36 +02003151@item QEMU Options:
blueswir15824d652009-03-28 06:44:27 +00003152-serial udp::4555@@:4556
3153@item netcat options:
3154-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3155@item telnet options:
3156localhost 5555
3157@end table
3158
Corey Minyard5dd1f022014-10-02 11:17:37 -05003159@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003160The TCP Net Console has two modes of operation. It can send the serial
3161I/O to a location or wait for a connection from a location. By default
3162the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3163the @var{server} option QEMU will wait for a client socket application
3164to connect to the port before continuing, unless the @code{nowait}
3165option was specified. The @code{nodelay} option disables the Nagle buffering
Corey Minyard5dd1f022014-10-02 11:17:37 -05003166algorithm. The @code{reconnect} option only applies if @var{noserver} is
3167set, if the connection goes down it will attempt to reconnect at the
3168given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
blueswir15824d652009-03-28 06:44:27 +00003169one TCP connection at a time is accepted. You can use @code{telnet} to
3170connect to the corresponding character device.
3171@table @code
3172@item Example to send tcp console to 192.168.0.2 port 4444
3173-serial tcp:192.168.0.2:4444
3174@item Example to listen and wait on port 4444 for connection
3175-serial tcp::4444,server
3176@item Example to not wait and listen on ip 192.168.0.100 port 4444
3177-serial tcp:192.168.0.100:4444,server,nowait
3178@end table
3179
3180@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3181The telnet protocol is used instead of raw tcp sockets. The options
3182work the same as if you had specified @code{-serial tcp}. The
3183difference is that the port acts like a telnet server or client using
3184telnet option negotiation. This will also allow you to send the
3185MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3186sequence. Typically in unix telnet you do it with Control-] and then
3187type "send break" followed by pressing the enter key.
3188
Corey Minyard5dd1f022014-10-02 11:17:37 -05003189@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003190A unix domain socket is used instead of a tcp socket. The option works the
3191same as if you had specified @code{-serial tcp} except the unix domain socket
3192@var{path} is used for connections.
3193
3194@item mon:@var{dev_string}
3195This is a special option to allow the monitor to be multiplexed onto
3196another serial port. The monitor is accessed with key sequence of
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +04003197@key{Control-a} and then pressing @key{c}.
blueswir15824d652009-03-28 06:44:27 +00003198@var{dev_string} should be any one of the serial devices specified
3199above. An example to multiplex the monitor onto a telnet server
3200listening on port 4444 would be:
3201@table @code
3202@item -serial mon:telnet::4444,server,nowait
3203@end table
Michael Tokarevbe022d62013-07-11 12:55:50 +04003204When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3205QEMU any more but will be passed to the guest instead.
blueswir15824d652009-03-28 06:44:27 +00003206
3207@item braille
3208Braille device. This will use BrlAPI to display the braille output on a real
3209or fake device.
3210
Kevin Wolfbe8b28a2009-10-09 10:58:37 +02003211@item msmouse
3212Three button serial mouse. Configure the guest to use Microsoft protocol.
blueswir15824d652009-03-28 06:44:27 +00003213@end table
3214ETEXI
3215
3216DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
Blue Swirlad960902010-03-29 19:23:52 +00003217 "-parallel dev redirect the parallel port to char device 'dev'\n",
3218 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003219STEXI
3220@item -parallel @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003221@findex -parallel
blueswir15824d652009-03-28 06:44:27 +00003222Redirect the virtual parallel port to host device @var{dev} (same
3223devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3224be used to use hardware devices connected on the corresponding host
3225parallel port.
3226
3227This option can be used several times to simulate up to 3 parallel
3228ports.
3229
3230Use @code{-parallel none} to disable all parallel ports.
3231ETEXI
3232
3233DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
Blue Swirlad960902010-03-29 19:23:52 +00003234 "-monitor dev redirect the monitor to char device 'dev'\n",
3235 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003236STEXI
Gerd Hoffmann4e307fc2009-12-08 13:11:37 +01003237@item -monitor @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003238@findex -monitor
blueswir15824d652009-03-28 06:44:27 +00003239Redirect the monitor to host device @var{dev} (same devices as the
3240serial port).
3241The default device is @code{vc} in graphical mode and @code{stdio} in
3242non graphical mode.
Luiz Capitulino70e098a2013-05-16 12:02:55 -04003243Use @code{-monitor none} to disable the default monitor.
blueswir15824d652009-03-28 06:44:27 +00003244ETEXI
Gerd Hoffmann6ca55822009-12-08 13:11:52 +01003245DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
Blue Swirlad960902010-03-29 19:23:52 +00003246 "-qmp dev like -monitor but opens in 'control' mode\n",
3247 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003248STEXI
3249@item -qmp @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003250@findex -qmp
Stefan Weil95d5f082010-01-20 22:25:27 +01003251Like -monitor but opens in 'control' mode.
3252ETEXI
Max Reitz4821cd42014-11-17 13:31:04 +01003253DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3254 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3255 QEMU_ARCH_ALL)
3256STEXI
3257@item -qmp-pretty @var{dev}
3258@findex -qmp-pretty
3259Like -qmp but uses pretty JSON formatting.
3260ETEXI
blueswir15824d652009-03-28 06:44:27 +00003261
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003262DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003263 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003264STEXI
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003265@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003266@findex -mon
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003267Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3268easing human reading and debugging.
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003269ETEXI
3270
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003271DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
Blue Swirlad960902010-03-29 19:23:52 +00003272 "-debugcon dev redirect the debug console to char device 'dev'\n",
3273 QEMU_ARCH_ALL)
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003274STEXI
3275@item -debugcon @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003276@findex -debugcon
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003277Redirect the debug console to host device @var{dev} (same devices as the
3278serial port). The debug console is an I/O port which is typically port
32790xe9; writing to that I/O port sends output to this device.
3280The default device is @code{vc} in graphical mode and @code{stdio} in
3281non graphical mode.
3282ETEXI
3283
blueswir15824d652009-03-28 06:44:27 +00003284DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
Blue Swirlad960902010-03-29 19:23:52 +00003285 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003286STEXI
3287@item -pidfile @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003288@findex -pidfile
blueswir15824d652009-03-28 06:44:27 +00003289Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3290from a script.
3291ETEXI
3292
aurel321b530a62009-04-05 20:08:59 +00003293DEF("singlestep", 0, QEMU_OPTION_singlestep, \
Blue Swirlad960902010-03-29 19:23:52 +00003294 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
aurel321b530a62009-04-05 20:08:59 +00003295STEXI
3296@item -singlestep
Stefan Weil6616b2a2010-02-05 23:52:05 +01003297@findex -singlestep
aurel321b530a62009-04-05 20:08:59 +00003298Run the emulation in single step mode.
3299ETEXI
3300
blueswir15824d652009-03-28 06:44:27 +00003301DEF("S", 0, QEMU_OPTION_S, \
Blue Swirlad960902010-03-29 19:23:52 +00003302 "-S freeze CPU at startup (use 'c' to start execution)\n",
3303 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003304STEXI
3305@item -S
Stefan Weil6616b2a2010-02-05 23:52:05 +01003306@findex -S
blueswir15824d652009-03-28 06:44:27 +00003307Do not start CPU at startup (you must type 'c' in the monitor).
3308ETEXI
3309
Satoru Moriya888a6bc2013-04-19 16:42:06 +02003310DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3311 "-realtime [mlock=on|off]\n"
3312 " run qemu with realtime features\n"
3313 " mlock=on|off controls mlock support (default: on)\n",
3314 QEMU_ARCH_ALL)
3315STEXI
3316@item -realtime mlock=on|off
3317@findex -realtime
3318Run qemu with realtime features.
3319mlocking qemu and guest memory can be enabled via @option{mlock=on}
3320(enabled by default).
3321ETEXI
3322
aliguori59030a82009-04-05 18:43:41 +00003323DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
Blue Swirlad960902010-03-29 19:23:52 +00003324 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003325STEXI
aliguori59030a82009-04-05 18:43:41 +00003326@item -gdb @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003327@findex -gdb
aliguori59030a82009-04-05 18:43:41 +00003328Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3329connections will likely be TCP-based, but also UDP, pseudo TTY, or even
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003330stdio are reasonable use case. The latter is allowing to start QEMU from
aliguori59030a82009-04-05 18:43:41 +00003331within gdb and establish the connection via a pipe:
3332@example
Stefan Weil3804da92012-05-11 22:21:50 +02003333(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
aliguori59030a82009-04-05 18:43:41 +00003334@end example
blueswir15824d652009-03-28 06:44:27 +00003335ETEXI
3336
aliguori59030a82009-04-05 18:43:41 +00003337DEF("s", 0, QEMU_OPTION_s, \
Blue Swirlad960902010-03-29 19:23:52 +00003338 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3339 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003340STEXI
aliguori59030a82009-04-05 18:43:41 +00003341@item -s
Stefan Weil6616b2a2010-02-05 23:52:05 +01003342@findex -s
aliguori59030a82009-04-05 18:43:41 +00003343Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3344(@pxref{gdb_usage}).
blueswir15824d652009-03-28 06:44:27 +00003345ETEXI
3346
3347DEF("d", HAS_ARG, QEMU_OPTION_d, \
Peter Maydell989b6972013-02-26 17:52:40 +00003348 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
Blue Swirlad960902010-03-29 19:23:52 +00003349 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003350STEXI
Peter Maydell989b6972013-02-26 17:52:40 +00003351@item -d @var{item1}[,...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003352@findex -d
Peter Maydell989b6972013-02-26 17:52:40 +00003353Enable logging of specified items. Use '-d help' for a list of log items.
blueswir15824d652009-03-28 06:44:27 +00003354ETEXI
3355
Matthew Fernandezc235d732011-06-07 16:32:40 +00003356DEF("D", HAS_ARG, QEMU_OPTION_D, \
Peter Maydell989b6972013-02-26 17:52:40 +00003357 "-D logfile output log to logfile (default stderr)\n",
Matthew Fernandezc235d732011-06-07 16:32:40 +00003358 QEMU_ARCH_ALL)
3359STEXI
Stefan Weil8bd383b2012-05-11 22:40:50 +02003360@item -D @var{logfile}
Matthew Fernandezc235d732011-06-07 16:32:40 +00003361@findex -D
Peter Maydell989b6972013-02-26 17:52:40 +00003362Output log in @var{logfile} instead of to stderr
Matthew Fernandezc235d732011-06-07 16:32:40 +00003363ETEXI
3364
Alex Bennée35145522016-03-15 14:30:20 +00003365DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3366 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3367 QEMU_ARCH_ALL)
3368STEXI
3369@item -dfilter @var{range1}[,...]
3370@findex -dfilter
3371Filter debug output to that relevant to a range of target addresses. The filter
3372spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3373@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3374addresses and sizes required. For example:
3375@example
3376 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3377@end example
3378Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3379the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3380block starting at 0xffffffc00005f000.
3381ETEXI
3382
blueswir15824d652009-03-28 06:44:27 +00003383DEF("L", HAS_ARG, QEMU_OPTION_L, \
Blue Swirlad960902010-03-29 19:23:52 +00003384 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3385 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003386STEXI
3387@item -L @var{path}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003388@findex -L
blueswir15824d652009-03-28 06:44:27 +00003389Set the directory for the BIOS, VGA BIOS and keymaps.
Richard W.M. Jones37146e72016-05-16 17:34:35 +01003390
3391To list all the data directories, use @code{-L help}.
blueswir15824d652009-03-28 06:44:27 +00003392ETEXI
3393
3394DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
Blue Swirlad960902010-03-29 19:23:52 +00003395 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003396STEXI
3397@item -bios @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003398@findex -bios
blueswir15824d652009-03-28 06:44:27 +00003399Set the filename for the BIOS.
3400ETEXI
3401
blueswir15824d652009-03-28 06:44:27 +00003402DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
Blue Swirlad960902010-03-29 19:23:52 +00003403 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003404STEXI
3405@item -enable-kvm
Stefan Weil6616b2a2010-02-05 23:52:05 +01003406@findex -enable-kvm
blueswir15824d652009-03-28 06:44:27 +00003407Enable KVM full virtualization support. This option is only available
3408if KVM support is enabled when compiling.
3409ETEXI
3410
Vincent Palatinb0cb0a62017-01-10 11:59:57 +01003411DEF("enable-hax", 0, QEMU_OPTION_enable_hax, \
3412 "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386)
3413STEXI
3414@item -enable-hax
3415@findex -enable-hax
3416Enable HAX (Hardware-based Acceleration eXecution) support. This option
3417is only available if HAX support is enabled when compiling. HAX is only
3418applicable to MAC and Windows platform, and thus does not conflict with
3419KVM.
3420ETEXI
3421
aliguorie37630c2009-04-22 15:19:10 +00003422DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
Blue Swirlad960902010-03-29 19:23:52 +00003423 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003424DEF("xen-create", 0, QEMU_OPTION_xen_create,
3425 "-xen-create create domain using xen hypercalls, bypassing xend\n"
Blue Swirlad960902010-03-29 19:23:52 +00003426 " warning: should not be used when xend is in use\n",
3427 QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003428DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3429 "-xen-attach attach to existing xen domain\n"
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003430 " xend will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00003431 QEMU_ARCH_ALL)
Paul Durrant1c599472017-03-22 09:39:15 +00003432DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3433 "-xen-domid-restrict restrict set of available xen operations\n"
3434 " to specified domain id. (Does not affect\n"
3435 " xenpv machine type).\n",
3436 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003437STEXI
3438@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003439@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01003440Specify xen guest domain @var{id} (XEN only).
3441@item -xen-create
Stefan Weil6616b2a2010-02-05 23:52:05 +01003442@findex -xen-create
Stefan Weil95d5f082010-01-20 22:25:27 +01003443Create domain using xen hypercalls, bypassing xend.
3444Warning: should not be used when xend is in use (XEN only).
3445@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01003446@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01003447Attach to existing xen domain.
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003448xend will use this when starting QEMU (XEN only).
Paul Durrant1c599472017-03-22 09:39:15 +00003449@findex -xen-domid-restrict
3450Restrict set of available xen operations to specified domain id (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003451ETEXI
aliguorie37630c2009-04-22 15:19:10 +00003452
blueswir15824d652009-03-28 06:44:27 +00003453DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00003454 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003455STEXI
3456@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01003457@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00003458Exit instead of rebooting.
3459ETEXI
3460
3461DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00003462 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003463STEXI
3464@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01003465@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00003466Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3467This allows for instance switching to monitor to commit changes to the
3468disk image.
3469ETEXI
3470
3471DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3472 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003473 " start right away with a saved state (loadvm in monitor)\n",
3474 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003475STEXI
3476@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003477@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00003478Start right away with a saved state (@code{loadvm} in monitor)
3479ETEXI
3480
3481#ifndef _WIN32
3482DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00003483 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003484#endif
3485STEXI
3486@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01003487@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00003488Daemonize the QEMU process after initialization. QEMU will not detach from
3489standard IO until it is ready to receive connections on any of its devices.
3490This option is a useful way for external programs to launch QEMU without having
3491to cope with initialization race conditions.
3492ETEXI
3493
3494DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00003495 "-option-rom rom load a file, rom, into the option ROM space\n",
3496 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003497STEXI
3498@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003499@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003500Load the contents of @var{file} as an option ROM.
3501This option is useful to load things like EtherBoot.
3502ETEXI
3503
Markus Armbrustere2180522014-10-06 16:19:07 +02003504HXCOMM Silently ignored for compatibility
3505DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003506
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003507HXCOMM Options deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00003508DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3509DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003510
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003511DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Paolo Bonzini78808142012-03-30 10:31:21 +00003512 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003513 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3514 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003515
blueswir15824d652009-03-28 06:44:27 +00003516STEXI
3517
Jan Kiszka68752042009-09-15 13:36:04 +02003518@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003519@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003520Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3521UTC or local time, respectively. @code{localtime} is required for correct date in
3522MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3523format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3524
Michael Tokarev9d85d552014-04-07 13:34:58 +04003525By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003526RTC as accurate reference clock inside the guest, specifically if the host
3527time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003528If you want to isolate the guest time from the host, you can set @option{clock}
3529to @code{rt} instead. To even prevent it from progressing during suspension,
3530you can set it to @code{vm}.
Jan Kiszka68752042009-09-15 13:36:04 +02003531
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003532Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3533specifically with Windows' ACPI HAL. This option will try to figure out how
3534many timer interrupts were not processed by the Windows guest and will
3535re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003536ETEXI
3537
3538DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003539 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003540 " enable virtual instruction counter with 2^N clock ticks per\n" \
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003541 " instruction, enable aligning the host and virtual clocks\n" \
3542 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003543STEXI
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003544@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003545@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003546Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003547instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003548then the virtual cpu speed will be automatically adjusted to keep virtual
3549time within a few seconds of real time.
3550
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003551When the virtual cpu is sleeping, the virtual time will advance at default
Pranith Kumar778d9f92016-02-26 10:16:51 -05003552speed unless @option{sleep=on|off} is specified.
3553With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003554instantly whenever the virtual cpu goes to sleep mode and will not advance
3555if no timer is enabled. This behavior give deterministic execution times from
3556the guest point of view.
3557
blueswir15824d652009-03-28 06:44:27 +00003558Note that while this option can give deterministic behavior, it does not
3559provide cycle accurate emulation. Modern CPUs contain superscalar out of
3560order cores with complex cache hierarchies. The number of instructions
3561executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003562
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01003563@option{align=on} will activate the delay algorithm which will try
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003564to synchronise the host clock and the virtual clock. The goal is to
3565have a guest running at the real frequency imposed by the shift option.
3566Whenever the guest clock is behind the host clock and if
Michael Tokarev82597612015-04-27 11:12:49 +03003567@option{align=on} is specified then we print a message to the user
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003568to inform about the delay.
3569Currently this option does not work when @option{shift} is @code{auto}.
3570Note: The sync algorithm will work for those shift values for which
3571the guest clock runs ahead of the host clock. Typically this happens
3572when the shift value is high (how high depends on the host machine).
Pavel Dovgalyuk4c27b852015-09-17 19:25:18 +03003573
3574When @option{rr} option is specified deterministic record/replay is enabled.
3575Replay log is written into @var{filename} file in record mode and
3576read from this file in replay mode.
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003577
3578Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3579at the start of execution recording. In replay mode this option is used
3580to load the initial VM state.
blueswir15824d652009-03-28 06:44:27 +00003581ETEXI
3582
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003583DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
Xu Wangd7933ef2015-06-11 17:32:05 +02003584 "-watchdog model\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003585 " enable virtual hardware watchdog [default=none]\n",
3586 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003587STEXI
3588@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003589@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003590Create a virtual hardware watchdog device. Once enabled (by a guest
3591action), the watchdog must be periodically polled by an agent inside
Xu Wangd7933ef2015-06-11 17:32:05 +02003592the guest or else the guest will be restarted. Choose a model for
3593which your guest has drivers.
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003594
Xu Wangd7933ef2015-06-11 17:32:05 +02003595The @var{model} is the model of hardware watchdog to emulate. Use
3596@code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003597watchdog can be enabled for a guest.
Xu Wangd7933ef2015-06-11 17:32:05 +02003598
3599The following models may be available:
3600@table @option
3601@item ib700
3602iBASE 700 is a very simple ISA watchdog with a single timer.
3603@item i6300esb
3604Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3605dual-timer watchdog.
Xu Wang188f24c2015-02-05 18:28:32 +08003606@item diag288
3607A virtual watchdog for s390x backed by the diagnose 288 hypercall
3608(currently KVM only).
Xu Wangd7933ef2015-06-11 17:32:05 +02003609@end table
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003610ETEXI
3611
3612DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
Markus Armbruster7ad92702017-10-02 16:03:07 +02003613 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003614 " action when watchdog fires [default=reset]\n",
3615 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003616STEXI
3617@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003618@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003619
3620The @var{action} controls what QEMU will do when the watchdog timer
3621expires.
3622The default is
3623@code{reset} (forcefully reset the guest).
3624Other possible actions are:
3625@code{shutdown} (attempt to gracefully shutdown the guest),
3626@code{poweroff} (forcefully poweroff the guest),
Markus Armbruster7ad92702017-10-02 16:03:07 +02003627@code{inject-nmi} (inject a NMI into the guest),
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003628@code{pause} (pause the guest),
3629@code{debug} (print a debug message and continue), or
3630@code{none} (do nothing).
3631
3632Note that the @code{shutdown} action requires that the guest responds
3633to ACPI signals, which it may not be able to do in the sort of
3634situations where the watchdog would have expired, and thus
3635@code{-watchdog-action shutdown} is not recommended for production use.
3636
3637Examples:
3638
3639@table @code
3640@item -watchdog i6300esb -watchdog-action pause
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003641@itemx -watchdog ib700
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003642@end table
3643ETEXI
3644
blueswir15824d652009-03-28 06:44:27 +00003645DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003646 "-echr chr set terminal escape character instead of ctrl-a\n",
3647 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003648STEXI
3649
Kevin Wolf4e257e52009-10-09 10:58:36 +02003650@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003651@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003652Change the escape character used for switching to the monitor when using
3653monitor and serial sharing. The default is @code{0x01} when using the
3654@code{-nographic} option. @code{0x01} is equal to pressing
3655@code{Control-a}. You can select a different character from the ascii
3656control keys where 1 through 26 map to Control-a through Control-z. For
3657instance you could use the either of the following to change the escape
3658character to Control-t.
3659@table @code
3660@item -echr 0x14
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003661@itemx -echr 20
blueswir15824d652009-03-28 06:44:27 +00003662@end table
3663ETEXI
3664
3665DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3666 "-virtioconsole c\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003667 " set virtio console\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003668STEXI
3669@item -virtioconsole @var{c}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003670@findex -virtioconsole
blueswir15824d652009-03-28 06:44:27 +00003671Set virtio console.
Amit Shah98b19252010-01-20 00:36:52 +05303672
3673This option is maintained for backward compatibility.
3674
3675Please use @code{-device virtconsole} for the new way of invocation.
blueswir15824d652009-03-28 06:44:27 +00003676ETEXI
3677
3678DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003679 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003680STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003681@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003682@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003683Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003684ETEXI
3685
3686DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003687 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003688STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003689@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003690@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003691Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003692ETEXI
3693
3694DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Michael Tokarev7c601802015-02-10 22:40:47 +03003695 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3696 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3697 "-incoming unix:socketpath\n" \
3698 " prepare for incoming migration, listen on\n" \
3699 " specified protocol and socket address\n" \
3700 "-incoming fd:fd\n" \
3701 "-incoming exec:cmdline\n" \
3702 " accept incoming migration on given file descriptor\n" \
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003703 " or from given external command\n" \
3704 "-incoming defer\n" \
3705 " wait for the URI to be specified via migrate_incoming\n",
Blue Swirlad960902010-03-29 19:23:52 +00003706 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003707STEXI
Michael Tokarev7c601802015-02-10 22:40:47 +03003708@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003709@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003710@findex -incoming
Michael Tokarev7c601802015-02-10 22:40:47 +03003711Prepare for incoming migration, listen on a given tcp port.
3712
3713@item -incoming unix:@var{socketpath}
3714Prepare for incoming migration, listen on a given unix socket.
3715
3716@item -incoming fd:@var{fd}
3717Accept incoming migration from a given filedescriptor.
3718
3719@item -incoming exec:@var{cmdline}
3720Accept incoming migration as an output from specified external command.
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003721
3722@item -incoming defer
3723Wait for the URI to be specified via migrate_incoming. The monitor can
3724be used to change settings (such as migration parameters) prior to issuing
3725the migrate_incoming to allow the migration to begin.
blueswir15824d652009-03-28 06:44:27 +00003726ETEXI
3727
Ashijeet Acharyad15c05f2017-01-16 17:01:51 +05303728DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3729 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3730STEXI
3731@item -only-migratable
3732@findex -only-migratable
3733Only allow migratable devices. Devices will not be allowed to enter an
3734unmigratable state.
3735ETEXI
3736
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003737DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003738 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003739STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003740@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003741@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003742Don't create default devices. Normally, QEMU sets the default devices like serial
3743port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3744CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3745default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003746ETEXI
3747
blueswir15824d652009-03-28 06:44:27 +00003748#ifndef _WIN32
3749DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003750 "-chroot dir chroot to dir just before starting the VM\n",
3751 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003752#endif
3753STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003754@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003755@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003756Immediately before starting guest execution, chroot to the specified
3757directory. Especially useful in combination with -runas.
3758ETEXI
3759
3760#ifndef _WIN32
3761DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Blue Swirlad960902010-03-29 19:23:52 +00003762 "-runas user change to user id user just before starting the VM\n",
3763 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003764#endif
3765STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003766@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003767@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003768Immediately before starting guest execution, drop root privileges, switching
3769to the specified user.
3770ETEXI
3771
blueswir15824d652009-03-28 06:44:27 +00003772DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3773 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003774 " set OpenBIOS nvram variables\n",
3775 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003776STEXI
3777@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003778@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003779Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3780ETEXI
blueswir15824d652009-03-28 06:44:27 +00003781DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003782 "-semihosting semihosting mode\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003783 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3784 QEMU_ARCH_MIPS)
Stefan Weil95d5f082010-01-20 22:25:27 +01003785STEXI
3786@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003787@findex -semihosting
Leon Alrae3b3c1692015-06-19 11:08:43 +01003788Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
Liviu Ionescua38bb072014-12-11 12:07:48 +00003789ETEXI
3790DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
Leon Alraea59d31a2015-06-19 14:17:45 +01003791 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3792 " semihosting configuration\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003793QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3794QEMU_ARCH_MIPS)
Liviu Ionescua38bb072014-12-11 12:07:48 +00003795STEXI
Leon Alraea59d31a2015-06-19 14:17:45 +01003796@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
Liviu Ionescua38bb072014-12-11 12:07:48 +00003797@findex -semihosting-config
Leon Alrae3b3c1692015-06-19 11:08:43 +01003798Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
Leon Alraea59d31a2015-06-19 14:17:45 +01003799@table @option
3800@item target=@code{native|gdb|auto}
3801Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3802or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3803during debug sessions and @code{native} otherwise.
3804@item arg=@var{str1},arg=@var{str2},...
3805Allows the user to pass input arguments, and can be used multiple times to build
3806up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3807command line is still supported for backward compatibility. If both the
3808@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3809specified, the former is passed to semihosting as it always takes precedence.
3810@end table
Stefan Weil95d5f082010-01-20 22:25:27 +01003811ETEXI
blueswir15824d652009-03-28 06:44:27 +00003812DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00003813 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003814STEXI
3815@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01003816@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003817Old param mode (ARM only).
3818ETEXI
3819
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003820DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003821 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003822 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003823 " Enable seccomp mode 2 system call filter (default 'off').\n" \
3824 " use 'obsolete' to allow obsolete system calls that are provided\n" \
3825 " by the kernel, but typically no longer used by modern\n" \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003826 " C library implementations.\n" \
3827 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \
3828 " its privileges by blacklisting all set*uid|gid system calls.\n" \
3829 " The value 'children' will deny set*uid|gid system calls for\n" \
Eduardo Otubo995a2262017-03-13 22:16:01 +01003830 " main QEMU process but will allow forks and execves to run unprivileged\n" \
3831 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003832 " blacklisting *fork and execve\n" \
3833 " use 'resourcecontrol' to disable process affinity and schedular priority\n",
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003834 QEMU_ARCH_ALL)
3835STEXI
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003836@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003837@findex -sandbox
3838Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3839disable it. The default is 'off'.
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003840@table @option
3841@item obsolete=@var{string}
3842Enable Obsolete system calls
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003843@item elevateprivileges=@var{string}
3844Disable set*uid|gid system calls
Eduardo Otubo995a2262017-03-13 22:16:01 +01003845@item spawn=@var{string}
3846Disable *fork and execve
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003847@item resourcecontrol=@var{string}
3848Disable process affinity and schedular priority
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003849@end table
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003850ETEXI
3851
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003852DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00003853 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003854STEXI
3855@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003856@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003857Read device configuration from @var{file}. This approach is useful when you want to spawn
3858QEMU process with many command line options but you don't want to exceed the command line
3859character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003860ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003861DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3862 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00003863 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003864STEXI
3865@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003866@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003867Write device configuration to @var{file}. The @var{file} can be either filename to save
3868command line and device configuration into file or dash @code{-}) character to print the
3869output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003870ETEXI
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003871HXCOMM Deprecated, same as -no-user-config
3872DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, "", QEMU_ARCH_ALL)
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003873DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3874 "-no-user-config\n"
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003875 " do not load default user-provided config files at startup\n",
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003876 QEMU_ARCH_ALL)
3877STEXI
3878@item -no-user-config
3879@findex -no-user-config
3880The @code{-no-user-config} option makes QEMU not load any of the user-provided
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003881config files on @var{sysconfdir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06003882ETEXI
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003883DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Paolo Bonzini10578a22016-01-07 16:55:26 +03003884 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
Lluís23d15e82011-08-31 20:31:31 +02003885 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003886 QEMU_ARCH_ALL)
3887STEXI
Lluís23d15e82011-08-31 20:31:31 +02003888HXCOMM This line is not accurate, as some sub-options are backend-specific but
3889HXCOMM HX does not support conditional compilation of text.
Denis V. Luneve370ad92016-06-17 17:44:08 +03003890@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003891@findex -trace
Denis V. Luneveeb2b8f2016-06-17 17:44:09 +03003892@include qemu-option-trace.texi
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003893ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003894
Markus Armbruster31e70d62013-02-13 19:49:37 +01003895HXCOMM Internal use
3896DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3897DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02003898
Paul Moore0f669982012-08-03 14:39:21 -04003899#ifdef __linux__
3900DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3901 "-enable-fips enable FIPS 140-2 compliance\n",
3902 QEMU_ARCH_ALL)
3903#endif
3904STEXI
3905@item -enable-fips
3906@findex -enable-fips
3907Enable FIPS 140-2 compliance mode.
3908ETEXI
3909
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003910HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003911DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003912
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003913HXCOMM Deprecated by kvm-pit driver properties
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003914DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003915 "", QEMU_ARCH_I386)
3916
Jan Kiszkae43d5942012-10-05 14:51:40 -03003917HXCOMM Deprecated by -machine kernel_irqchip=on|off property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003918DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
Jan Kiszkae43d5942012-10-05 14:51:40 -03003919
Jan Kiszka88eed342012-10-05 14:51:44 -03003920HXCOMM Deprecated (ignored)
3921DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
3922
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04003923DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3924 "-msg timestamp[=on|off]\n"
3925 " change the format of messages\n"
3926 " on|off controls leading timestamps (default:on)\n",
3927 QEMU_ARCH_ALL)
3928STEXI
3929@item -msg timestamp[=on|off]
3930@findex -msg
3931prepend a timestamp to each log message.(default:on)
3932ETEXI
3933
Amit Shahabfd9ce2014-06-20 18:56:08 +05303934DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3935 "-dump-vmstate <file>\n"
3936 " Output vmstate information in JSON format to file.\n"
3937 " Use the scripts/vmstate-static-checker.py file to\n"
3938 " check for possible regressions in migration code\n"
Laurent Vivier23820532015-09-04 21:30:04 +02003939 " by comparing two such vmstate dumps.\n",
Amit Shahabfd9ce2014-06-20 18:56:08 +05303940 QEMU_ARCH_ALL)
3941STEXI
3942@item -dump-vmstate @var{file}
3943@findex -dump-vmstate
3944Dump json-encoded vmstate information for current machine type to file
3945in @var{file}
3946ETEXI
3947
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003948STEXI
3949@end table
3950ETEXI
3951DEFHEADING()
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003952
3953DEFHEADING(Generic object creation:)
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003954STEXI
3955@table @option
3956ETEXI
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003957
3958DEF("object", HAS_ARG, QEMU_OPTION_object,
3959 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3960 " create a new object of type TYPENAME setting properties\n"
3961 " in the order they are specified. Note that the 'id'\n"
3962 " property must be set. These objects are placed in the\n"
3963 " '/objects' path.\n",
3964 QEMU_ARCH_ALL)
3965STEXI
3966@item -object @var{typename}[,@var{prop1}=@var{value1},...]
3967@findex -object
3968Create a new object of type @var{typename} setting properties
3969in the order they are specified. Note that the 'id'
3970property must be set. These objects are placed in the
3971'/objects' path.
3972
3973@table @option
3974
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003975@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave}
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003976
3977Creates a memory file backend object, which can be used to back
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003978the guest RAM with huge pages.
3979
3980The @option{id} parameter is a unique ID that will be used to reference this
3981memory region when configuring the @option{-numa} argument.
3982
3983The @option{size} option provides the size of the memory region, and accepts
3984common suffixes, eg @option{500M}.
3985
3986The @option{mem-path} provides the path to either a shared memory or huge page
3987filesystem mount.
3988
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003989The @option{share} boolean option determines whether the memory
3990region is marked as private to QEMU, or shared. The latter allows
3991a co-operating external process to access the QEMU memory region.
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003992
Eduardo Habkost11ae6ed2017-08-24 16:23:15 -03003993Setting the @option{discard-data} boolean option to @var{on}
3994indicates that file contents can be destroyed when QEMU exits,
3995to avoid unnecessarily flushing data to the backing file. Note
3996that @option{discard-data} is only an optimization, and QEMU
3997might not discard file contents if it aborts unexpectedly or is
3998terminated using SIGKILL.
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003999
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00004000The @option{merge} boolean option enables memory merge, also known as
4001MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
4002memory deduplication.
4003
4004Setting the @option{dump} boolean option to @var{off} excludes the memory from
4005core dumps. This feature is also known as MADV_DONTDUMP.
4006
4007The @option{prealloc} boolean option enables memory preallocation.
4008
4009The @option{host-nodes} option binds the memory range to a list of NUMA host
4010nodes.
4011
4012The @option{policy} option sets the NUMA policy to one of the following values:
4013
4014@table @option
4015@item @var{default}
4016default host policy
4017
4018@item @var{preferred}
4019prefer the given host node list for allocation
4020
4021@item @var{bind}
4022restrict memory allocation to the given host node list
4023
4024@item @var{interleave}
4025interleave memory allocations across the given host node list
4026@end table
4027
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004028@item -object rng-random,id=@var{id},filename=@var{/dev/random}
4029
4030Creates a random number generator backend which obtains entropy from
4031a device on the host. The @option{id} parameter is a unique ID that
4032will be used to reference this entropy backend from the @option{virtio-rng}
4033device. The @option{filename} parameter specifies which file to obtain
4034entropy from and if omitted defaults to @option{/dev/random}.
4035
4036@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4037
4038Creates a random number generator backend which obtains entropy from
4039an external daemon running on the host. The @option{id} parameter is
4040a unique ID that will be used to reference this entropy backend from
4041the @option{virtio-rng} device. The @option{chardev} parameter is
4042the unique ID of a character device backend that provides the connection
4043to the RNG daemon.
4044
Daniel P. Berrangee00adf62015-03-13 17:39:26 +00004045@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4046
4047Creates a TLS anonymous credentials object, which can be used to provide
4048TLS support on network backends. The @option{id} parameter is a unique
4049ID which network backends will use to access the credentials. The
4050@option{endpoint} is either @option{server} or @option{client} depending
4051on whether the QEMU network backend that uses the credentials will be
4052acting as a client or as a server. If @option{verify-peer} is enabled
4053(the default) then once the handshake is completed, the peer credentials
4054will be verified, though this is a no-op for anonymous credentials.
4055
4056The @var{dir} parameter tells QEMU where to find the credential
4057files. For server endpoints, this directory may contain a file
4058@var{dh-params.pem} providing diffie-hellman parameters to use
4059for the TLS server. If the file is missing, QEMU will generate
4060a set of DH parameters at startup. This is a computationally
4061expensive operation that consumes random pool entropy, so it is
4062recommended that a persistent set of parameters be generated
4063upfront and saved.
4064
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004065@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}
Daniel P. Berrange85bcbc72015-03-13 17:39:26 +00004066
4067Creates a TLS anonymous credentials object, which can be used to provide
4068TLS support on network backends. The @option{id} parameter is a unique
4069ID which network backends will use to access the credentials. The
4070@option{endpoint} is either @option{server} or @option{client} depending
4071on whether the QEMU network backend that uses the credentials will be
4072acting as a client or as a server. If @option{verify-peer} is enabled
4073(the default) then once the handshake is completed, the peer credentials
4074will be verified. With x509 certificates, this implies that the clients
4075must be provided with valid client certificates too.
4076
4077The @var{dir} parameter tells QEMU where to find the credential
4078files. For server endpoints, this directory may contain a file
4079@var{dh-params.pem} providing diffie-hellman parameters to use
4080for the TLS server. If the file is missing, QEMU will generate
4081a set of DH parameters at startup. This is a computationally
4082expensive operation that consumes random pool entropy, so it is
4083recommended that a persistent set of parameters be generated
4084upfront and saved.
4085
4086For x509 certificate credentials the directory will contain further files
4087providing the x509 certificates. The certificates must be stored
4088in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4089@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4090@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4091
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004092For the @var{server-key.pem} and @var{client-key.pem} files which
4093contain sensitive private keys, it is possible to use an encrypted
4094version by providing the @var{passwordid} parameter. This provides
4095the ID of a previously created @code{secret} object containing the
4096password for decryption.
4097
zhanghailiang338d3f42016-03-01 13:37:02 +08004098@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004099
4100Interval @var{t} can't be 0, this filter batches the packet delivery: all
4101packets arriving in a given interval on netdev @var{netdevid} are delayed
4102until the end of the interval. Interval is in microseconds.
zhanghailiang338d3f42016-03-01 13:37:02 +08004103@option{status} is optional that indicate whether the netfilter is
4104on (enabled) or off (disabled), the default status for netfilter will be 'on'.
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004105
4106queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4107
4108@option{all}: the filter is attached both to the receive and the transmit
4109 queue of the netdev (default).
4110
4111@option{rx}: the filter is attached to the receive queue of the netdev,
4112 where it will receive packets sent to the netdev.
4113
4114@option{tx}: the filter is attached to the transmit queue of the netdev,
4115 where it will receive packets sent by the netdev.
4116
Zhang Chene2521f02017-07-04 14:53:48 +08004117@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
Zhang Chenf6d3afb2016-03-15 15:41:33 +08004118
Zhang Chene2521f02017-07-04 14:53:48 +08004119filter-mirror on netdev @var{netdevid},mirror net packet to chardev@var{chardevid}, if it has the vnet_hdr_support flag, filter-mirror will mirror packet with vnet_hdr_len.
Zhang Chenf6d3afb2016-03-15 15:41:33 +08004120
Zhang Chen00d5c242017-07-04 14:53:49 +08004121@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
Zhang Chend46f75b2016-03-17 16:16:26 +08004122
4123filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
Zhang Chen00d5c242017-07-04 14:53:49 +08004124@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4125filter-redirector will redirect packet with vnet_hdr_len.
Zhang Chend46f75b2016-03-17 16:16:26 +08004126Create a filter-redirector we need to differ outdev id from indev id, id can not
4127be the same. we can just use indev or outdev, but at least one of indev or outdev
4128need to be specified.
4129
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004130@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support]
Zhang Chene6eee8a2016-09-27 10:22:32 +08004131
4132Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4133secondary from primary to keep secondary tcp connection,and rewrite
4134tcp packet to primary from secondary make tcp packet can be handled by
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004135client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
Zhang Chene6eee8a2016-09-27 10:22:32 +08004136
4137usage:
4138colo secondary:
4139-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4140-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4141-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4142
Changlong Xiec551cd52016-10-11 13:28:32 +08004143@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
Thomas Huthd3e0c032015-10-13 12:40:02 +02004144
4145Dump the network traffic on netdev @var{dev} to the file specified by
4146@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4147The file format is libpcap, so it can be analyzed with tools such as tcpdump
4148or Wireshark.
4149
Zhang Chenaa3a7032017-07-04 14:53:52 +08004150@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid}[,vnet_hdr_support]
Zhang Chen7dce4e62016-09-27 10:22:26 +08004151
4152Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4153secondary packet. If the packets are same, we will output primary
4154packet to outdev@var{chardevid}, else we will notify colo-frame
4155do checkpoint and send primary packet to outdev@var{chardevid}.
Zhang Chenaa3a7032017-07-04 14:53:52 +08004156if it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len.
Zhang Chen7dce4e62016-09-27 10:22:26 +08004157
4158we must use it with the help of filter-mirror and filter-redirector.
4159
4160@example
4161
4162primary:
4163-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4164-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4165-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4166-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4167-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4168-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4169-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4170-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4171-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4172-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4173-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4174-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4175
4176secondary:
4177-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4178-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4179-chardev socket,id=red0,host=3.3.3.3,port=9003
4180-chardev socket,id=red1,host=3.3.3.3,port=9004
4181-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4182-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4183
4184@end example
4185
4186If you want to know the detail of above command line, you can read
4187the colo-compare git log.
4188
Gonglei1653a5f2016-10-28 16:33:23 +08004189@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4190
4191Creates a cryptodev backend which executes crypto opreation from
4192the QEMU cipher APIS. The @var{id} parameter is
4193a unique ID that will be used to reference this cryptodev backend from
4194the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4195which specify the queue number of cryptodev backend, the default of
4196@var{queues} is 1.
4197
4198@example
4199
4200 # qemu-system-x86_64 \
4201 [...] \
4202 -object cryptodev-backend-builtin,id=cryptodev0 \
4203 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4204 [...]
4205@end example
4206
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004207@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4208@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4209
4210Defines a secret to store a password, encryption key, or some other sensitive
4211data. The sensitive data can either be passed directly via the @var{data}
4212parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4213parameter is insecure unless the sensitive data is encrypted.
4214
4215The sensitive data can be provided in raw format (the default), or base64.
4216When encoded as JSON, the raw format only supports valid UTF-8 characters,
4217so base64 is recommended for sending binary data. QEMU will convert from
4218which ever format is provided to the format it needs internally. eg, an
4219RBD password can be provided in raw format, even though it will be base64
4220encoded when passed onto the RBD sever.
4221
4222For added protection, it is possible to encrypt the data associated with
4223a secret using the AES-256-CBC cipher. Use of encryption is indicated
4224by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4225parameter provides the ID of a previously defined secret that contains
4226the AES-256 decryption key. This key should be 32-bytes long and be
4227base64 encoded. The @var{iv} parameter provides the random initialization
4228vector used for encryption of this particular secret and should be a
Daniel P. Berrange69c0b272016-04-04 10:33:55 +01004229base64 encrypted string of the 16-byte IV.
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004230
4231The simplest (insecure) usage is to provide the secret inline
4232
4233@example
4234
4235 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4236
4237@end example
4238
4239The simplest secure usage is to provide the secret via a file
4240
Eric Blakeb43671f2017-07-03 13:09:50 -05004241 # printf "letmein" > mypasswd.txt
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004242 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4243
4244For greater security, AES-256-CBC should be used. To illustrate usage,
4245consider the openssl command line tool which can encrypt the data. Note
4246that when encrypting, the plaintext must be padded to the cipher block
4247size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4248
4249First a master key needs to be created in base64 encoding:
4250
4251@example
4252 # openssl rand -base64 32 > key.b64
4253 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4254@end example
4255
4256Each secret to be encrypted needs to have a random initialization vector
4257generated. These do not need to be kept secret
4258
4259@example
4260 # openssl rand -base64 16 > iv.b64
4261 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4262@end example
4263
4264The secret to be defined can now be encrypted, in this case we're
4265telling openssl to base64 encode the result, but it could be left
4266as raw bytes if desired.
4267
4268@example
Eric Blakeb43671f2017-07-03 13:09:50 -05004269 # SECRET=$(printf "letmein" |
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004270 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4271@end example
4272
4273When launching QEMU, create a master secret pointing to @code{key.b64}
4274and specify that to be used to decrypt the user password. Pass the
4275contents of @code{iv.b64} to the second secret
4276
4277@example
4278 # $QEMU \
4279 -object secret,id=secmaster0,format=base64,file=key.b64 \
4280 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4281 data=$SECRET,iv=$(<iv.b64)
4282@end example
4283
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004284@end table
4285
4286ETEXI
4287
4288
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004289HXCOMM This is the last statement. Insert new options before this line!
4290STEXI
4291@end table
4292ETEXI