blob: 81b1e99d585a6bbf9e35956ac7f8df2e8b5796f4 [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"
Justin Terry (VM)d661d9a2018-01-22 13:07:46 -080034 " supported accelerators are kvm, xen, hax, hvf, whpx 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"
Brijesh Singhdb588192018-03-08 06:48:38 -060046 " s390-squash-mcss=on|off (deprecated) controls support for squashing into default css (default=off)\n"
47 " memory-encryption=@var{} memory encryption object to use (default=none)\n",
Jan Kiszka80f52a62011-07-23 12:39:46 +020048 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000049STEXI
Jan Kiszka80f52a62011-07-23 12:39:46 +020050@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
51@findex -machine
Peter Maydell585f6032012-10-04 16:22:01 +010052Select the emulated machine by @var{name}. Use @code{-machine help} to list
Daniel P. Berrange8bfce832017-07-25 15:10:41 +010053available machines.
54
55For architectures which aim to support live migration compatibility
56across releases, each release will introduce a new versioned machine
57type. For example, the 2.8.0 release introduced machine types
58``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures.
59
60To allow live migration of guests from QEMU version 2.8.0, to QEMU
61version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8''
62and ``pc-q35-2.8'' machines too. To allow users live migrating VMs
63to skip multiple intermediate releases when upgrading, new releases
64of QEMU will support machine types from many previous versions.
65
66Supported machine properties are:
Jan Kiszka80f52a62011-07-23 12:39:46 +020067@table @option
68@item accel=@var{accels1}[:@var{accels2}[:...]]
69This is used to enable an accelerator. Depending on the target architecture,
Justin Terry (VM)d661d9a2018-01-22 13:07:46 -080070kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
Thomas Huthbde4d922017-05-04 07:24:41 +020071more than one accelerator specified, the next one is used if the previous one
72fails to initialize.
Jan Kiszka6a48ffa2011-10-15 13:43:48 +020073@item kernel_irqchip=on|off
Matt Gingell32c18a22015-11-16 10:03:06 -080074Controls in-kernel irqchip support for the chosen accelerator when available.
Tiejun Chen79814172015-07-15 13:37:45 +080075@item gfx_passthru=on|off
76Enables IGD GFX passthrough support for the chosen machine when available.
Don Slutzd1048be2014-11-21 11:18:52 -050077@item vmport=on|off|auto
78Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
79value based on accel. For accel=xen the default is off otherwise the default
80is on.
Jan Kiszka39d69602012-01-25 18:14:15 +010081@item kvm_shadow_mem=size
82Defines the size of the KVM shadow MMU.
Jason Baronddb97f12012-08-02 15:44:16 -040083@item dump-guest-core=on|off
84Include guest memory in a core dump. The default is on.
Luiz Capitulino8490fc72012-09-05 16:50:16 -030085@item mem-merge=on|off
86Enables or disables memory merge support. This feature, when supported by
87the host, de-duplicates identical memory pages among VMs instances
88(enabled by default).
Tony Krowiak2eb1cd02015-03-12 13:53:51 +010089@item aes-key-wrap=on|off
90Enables or disables AES key wrapping support on s390-ccw hosts. This feature
91controls whether AES wrapping keys will be created to allow
92execution of AES cryptographic functions. The default is on.
93@item dea-key-wrap=on|off
94Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
95controls whether DEA wrapping keys will be created to allow
96execution of DEA cryptographic functions. The default is on.
Xiao Guangrong87252e12015-12-02 15:20:58 +080097@item nvdimm=on|off
98Enables or disables NVDIMM support. The default is off.
Xiao Feng Ren274250c2017-05-17 02:48:03 +020099@item s390-squash-mcss=on|off
100Enables or disables squashing subchannels into the default css.
101The default is off.
Halil Pasicd69969e2017-12-06 15:44:38 +0100102NOTE: This property is deprecated and will be removed in future releases.
103The ``s390-squash-mcss=on`` property has been obsoleted by allowing the
104cssid to be chosen freely. Instead of squashing subchannels into the
105default channel subsystem image for guests that do not support multiple
106channel subsystems, all devices can be put into the default channel
107subsystem image.
Peter Xu16f72442017-07-07 10:54:08 +0800108@item enforce-config-section=on|off
109If @option{enforce-config-section} is set to @var{on}, force migration
110code to send configuration section even if the machine-type sets the
111@option{migration.send-configuration} property to @var{off}.
112NOTE: this parameter is deprecated. Please use @option{-global}
113@option{migration.send-configuration}=@var{on|off} instead.
Brijesh Singhdb588192018-03-08 06:48:38 -0600114@item memory-encryption=@var{}
115Memory encryption object to use. The default is none.
Jan Kiszka80f52a62011-07-23 12:39:46 +0200116@end table
blueswir15824d652009-03-28 06:44:27 +0000117ETEXI
118
Jan Kiszka80f52a62011-07-23 12:39:46 +0200119HXCOMM Deprecated by -machine
120DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
121
blueswir15824d652009-03-28 06:44:27 +0000122DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
Peter Maydell585f6032012-10-04 16:22:01 +0100123 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000124STEXI
125@item -cpu @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100126@findex -cpu
Peter Maydell585f6032012-10-04 16:22:01 +0100127Select CPU model (@code{-cpu help} for list and additional feature selection)
blueswir15824d652009-03-28 06:44:27 +0000128ETEXI
129
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000130DEF("accel", HAS_ARG, QEMU_OPTION_accel,
131 "-accel [accel=]accelerator[,thread=single|multi]\n"
Justin Terry (VM)d661d9a2018-01-22 13:07:46 -0800132 " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
Eduardo Habkost0b3c5c82018-06-11 16:56:07 -0300133 " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000134STEXI
135@item -accel @var{name}[,prop=@var{value}[,...]]
136@findex -accel
137This is used to enable an accelerator. Depending on the target architecture,
Justin Terry (VM)d661d9a2018-01-22 13:07:46 -0800138kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
Thomas Huthbde4d922017-05-04 07:24:41 +0200139more than one accelerator specified, the next one is used if the previous one
140fails to initialize.
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000141@table @option
142@item thread=single|multi
143Controls number of TCG threads. When the TCG is multi-threaded there will be one
144thread per vCPU therefor taking advantage of additional host cores. The default
145is to enable multi-threading where both the back-end and front-ends support it and
146no incompatible TCG features have been enabled (e.g. icount/replay).
147@end table
148ETEXI
149
blueswir15824d652009-03-28 06:44:27 +0000150DEF("smp", HAS_ARG, QEMU_OPTION_smp,
Michael Tokarev12b7f572013-06-24 15:06:52 +0400151 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
Jes Sorensen6be68d72009-07-23 17:03:42 +0200152 " set the number of CPUs to 'n' [default=1]\n"
153 " maxcpus= maximum number of total cpus, including\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -0700154 " offline CPUs for hotplug, etc\n"
Andre Przywara58a04db2009-08-28 10:49:57 +0200155 " cores= number of CPU cores on one socket\n"
156 " threads= number of threads on one CPU core\n"
Blue Swirlad960902010-03-29 19:23:52 +0000157 " sockets= number of discrete sockets in the system\n",
158 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000159STEXI
Michael Tokarev12b7f572013-06-24 15:06:52 +0400160@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100161@findex -smp
blueswir15824d652009-03-28 06:44:27 +0000162Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
163CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
164to 4.
Andre Przywara58a04db2009-08-28 10:49:57 +0200165For the PC target, the number of @var{cores} per socket, the number
166of @var{threads} per cores and the total number of @var{sockets} can be
167specified. Missing values will be computed. If any on the three values is
168given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
169specifies the maximum number of hotpluggable CPUs.
blueswir15824d652009-03-28 06:44:27 +0000170ETEXI
171
aliguori268a3622009-04-21 22:30:27 +0000172DEF("numa", HAS_ARG, QEMU_OPTION_numa,
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200173 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
He Chen0f203432017-04-27 10:35:58 +0800174 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
Igor Mammedov2d19c652017-11-28 15:53:58 +0100175 "-numa dist,src=source,dst=destination,val=distance\n"
176 "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n",
177 QEMU_ARCH_ALL)
aliguori268a3622009-04-21 22:30:27 +0000178STEXI
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200179@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
180@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
He Chen0f203432017-04-27 10:35:58 +0800181@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
Igor Mammedov419fcde2017-05-10 13:30:01 +0200182@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 +0100183@findex -numa
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200184Define a NUMA node and assign RAM and VCPUs to it.
He Chen0f203432017-04-27 10:35:58 +0800185Set the NUMA distance from a source node to a destination node.
Paolo Bonzini7febe362014-05-14 17:43:17 +0800186
Igor Mammedov419fcde2017-05-10 13:30:01 +0200187Legacy VCPU assignment uses @samp{cpus} option where
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200188@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
189@samp{cpus} option represent a contiguous range of CPU indexes
190(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
191set of VCPUs can be represented by providing multiple @samp{cpus}
192options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
193split between them.
194
195For example, the following option assigns VCPUs 0, 1, 2 and 5 to
196a NUMA node:
197@example
198-numa node,cpus=0-2,cpus=5
199@end example
200
Igor Mammedov419fcde2017-05-10 13:30:01 +0200201@samp{cpu} option is a new alternative to @samp{cpus} option
202which uses @samp{socket-id|core-id|thread-id} properties to assign
203CPU objects to a @var{node} using topology layout properties of CPU.
204The set of properties is machine specific, and depends on used
205machine type/@samp{smp} options. It could be queried with
206@samp{hotpluggable-cpus} monitor command.
207@samp{node-id} property specifies @var{node} to which CPU object
208will be assigned, it's required for @var{node} to be declared
209with @samp{node} option before it's used with @samp{cpu} option.
210
211For example:
212@example
213-M pc \
214-smp 1,sockets=2,maxcpus=2 \
215-numa node,nodeid=0 -numa node,nodeid=1 \
216-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
217@end example
218
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200219@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
220assigns RAM from a given memory backend device to a node. If
221@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
222split equally between them.
223
224@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
225if one node uses @samp{memdev}, all of them have to use it.
226
He Chen0f203432017-04-27 10:35:58 +0800227@var{source} and @var{destination} are NUMA node IDs.
228@var{distance} is the NUMA distance from @var{source} to @var{destination}.
229The distance from a node to itself is always 10. If any pair of nodes is
230given a distance, then all pairs must be given distances. Although, when
231distances are only given in one direction for each pair of nodes, then
232the distances in the opposite directions are assumed to be the same. If,
233however, an asymmetrical pair of distances is given for even one node
234pair, then all node pairs must be provided distance values for both
235directions, even when they are symmetrical. When a node is unreachable
236from another node, set the pair's distance to 255.
237
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200238Note that the -@option{numa} option doesn't allocate any of the
239specified resources, it just assigns existing resources to NUMA
240nodes. This means that one still has to use the @option{-m},
241@option{-smp} options to allocate RAM and VCPUs respectively.
242
aliguori268a3622009-04-21 22:30:27 +0000243ETEXI
244
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100245DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
246 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
247 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
248STEXI
249@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
250@findex -add-fd
251
252Add a file descriptor to an fd set. Valid options are:
253
254@table @option
255@item fd=@var{fd}
256This option defines the file descriptor of which a duplicate is added to fd set.
257The file descriptor cannot be stdin, stdout, or stderr.
258@item set=@var{set}
259This option defines the ID of the fd set to add the file descriptor to.
260@item opaque=@var{opaque}
261This option defines a free-form string that can be used to describe @var{fd}.
262@end table
263
264You can open an image using pre-opened file descriptors from an fd set:
265@example
266qemu-system-i386
267-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
268-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
269-drive file=/dev/fdset/2,index=0,media=disk
270@end example
271ETEXI
272
273DEF("set", HAS_ARG, QEMU_OPTION_set,
274 "-set group.id.arg=value\n"
275 " set <arg> parameter for item <id> of type <group>\n"
276 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
277STEXI
278@item -set @var{group}.@var{id}.@var{arg}=@var{value}
279@findex -set
Michael Tokareve1f3b972016-10-16 17:21:37 +0300280Set parameter @var{arg} for item @var{id} of type @var{group}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100281ETEXI
282
283DEF("global", HAS_ARG, QEMU_OPTION_global,
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200284 "-global driver.property=value\n"
285 "-global driver=driver,property=property,value=value\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100286 " set a global default for a driver property\n",
287 QEMU_ARCH_ALL)
288STEXI
289@item -global @var{driver}.@var{prop}=@var{value}
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200290@itemx -global driver=@var{driver},property=@var{property},value=@var{value}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100291@findex -global
292Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
293
294@example
Markus Armbruster1c9f3b82017-05-09 11:41:15 +0200295qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100296@end example
297
Michael Tokareva295d242017-09-23 19:31:59 +0300298In particular, you can use this to set driver properties for devices which are
299created automatically by the machine model. To create a device which is not
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100300created automatically and set properties on it, use -@option{device}.
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200301
Markus Armbrusterae08fd52015-06-15 14:35:58 +0200302-global @var{driver}.@var{prop}=@var{value} is shorthand for -global
303driver=@var{driver},property=@var{prop},value=@var{value}. The
304longhand syntax works even when @var{driver} contains a dot.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100305ETEXI
306
307DEF("boot", HAS_ARG, QEMU_OPTION_boot,
308 "-boot [order=drives][,once=drives][,menu=on|off]\n"
Amos Kongc8a6ae82013-03-19 14:23:27 +0800309 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100310 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
311 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
312 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
313 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
314 QEMU_ARCH_ALL)
315STEXI
Amos Kongc8a6ae82013-03-19 14:23:27 +0800316@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 +0100317@findex -boot
318Specify boot order @var{drives} as a string of drive letters. Valid
Gongleid274e072015-07-03 17:50:57 +0800319drive letters depend on the target architecture. The x86 PC uses: a, b
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100320(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
321from network adapter 1-4), hard disk boot is the default. To apply a
322particular boot order only on the first startup, specify it via
Thomas Huthc0d9f7d2017-02-28 18:40:01 +0100323@option{once}. Note that the @option{order} or @option{once} parameter
324should not be used together with the @option{bootindex} property of
325devices, since the firmware implementations normally do not support both
326at the same time.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100327
328Interactive boot menus/prompts can be enabled via @option{menu=on} as far
329as firmware/BIOS supports them. The default is non-interactive boot.
330
331A splash picture could be passed to bios, enabling user to show it as logo,
332when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
333supports them. Currently Seabios for X86 system support it.
334limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
335format(true color). The resolution should be supported by the SVGA mode, so
336the recommended is 320x240, 640x480, 800x640.
337
338A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
339when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
340reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
341system support it.
342
Amos Kongc8a6ae82013-03-19 14:23:27 +0800343Do strict boot via @option{strict=on} as far as firmware/BIOS
344supports it. This only effects when boot priority is changed by
345bootindex options. The default is non-strict boot.
346
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100347@example
348# try to boot from network first, then from hard disk
349qemu-system-i386 -boot order=nc
350# boot from CD-ROM first, switch back to default order after reboot
351qemu-system-i386 -boot once=d
352# boot with a splash picture for 5 seconds.
353qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
354@end example
355
356Note: The legacy format '-boot @var{drives}' is still supported but its
357use is discouraged as it may be removed from future versions.
358ETEXI
359
360DEF("m", HAS_ARG, QEMU_OPTION_m,
Michael Tokarev89f3ea22016-11-10 17:51:32 +0300361 "-m [size=]megs[,slots=n,maxmem=size]\n"
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100362 " configure guest RAM\n"
Alexander Graf0daba1f2015-06-05 11:05:03 +0200363 " size: initial amount of guest memory\n"
Igor Mammedovc270fb92014-06-02 15:25:02 +0200364 " slots: number of hotplug slots (default: none)\n"
Matthew Rosatob6fe0122014-08-28 11:25:33 -0400365 " maxmem: maximum amount of guest memory (default: none)\n"
366 "NOTE: Some architectures might enforce a specific granularity\n",
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100367 QEMU_ARCH_ALL)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100368STEXI
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500369@item -m [size=]@var{megs}[,slots=n,maxmem=size]
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100370@findex -m
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500371Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
372Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
373megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
374could be used to set amount of hotpluggable memory slots and maximum amount of
375memory. Note that @var{maxmem} must be aligned to the page size.
376
377For example, the following command-line sets the guest startup RAM size to
3781GB, creates 3 slots to hotplug additional memory and sets the maximum
379memory the guest can reach to 4GB:
380
381@example
382qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
383@end example
384
385If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
386be enabled and the guest startup RAM will never increase.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100387ETEXI
388
389DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
390 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
391STEXI
392@item -mem-path @var{path}
393@findex -mem-path
394Allocate guest RAM from a temporarily created file in @var{path}.
395ETEXI
396
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100397DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
398 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
399 QEMU_ARCH_ALL)
400STEXI
401@item -mem-prealloc
402@findex -mem-prealloc
403Preallocate memory when using -mem-path.
404ETEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100405
406DEF("k", HAS_ARG, QEMU_OPTION_k,
407 "-k language use keyboard layout (for example 'fr' for French)\n",
408 QEMU_ARCH_ALL)
409STEXI
410@item -k @var{language}
411@findex -k
412Use keyboard layout @var{language} (for example @code{fr} for
413French). This option is only needed where it is not easy to get raw PC
Samuel Thibault32945472016-06-22 17:48:31 +0200414keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100415display). You don't normally need to use it on PC/Linux or PC/Windows
416hosts.
417
418The available layouts are:
419@example
420ar de-ch es fo fr-ca hu ja mk no pt-br sv
421da en-gb et fr fr-ch is lt nl pl ru th
422de en-us fi fr-be hr it lv nl-be pt sl tr
423@end example
424
425The default is @code{en-us}.
426ETEXI
427
428
429DEF("audio-help", 0, QEMU_OPTION_audio_help,
430 "-audio-help print list of audio drivers and their options\n",
431 QEMU_ARCH_ALL)
432STEXI
433@item -audio-help
434@findex -audio-help
435Will show the audio subsystem help: list of drivers, tunable
436parameters.
437ETEXI
438
439DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
440 "-soundhw c1,... enable audio support\n"
441 " and only specified sound cards (comma separated list)\n"
442 " use '-soundhw help' to get the list of supported cards\n"
443 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
444STEXI
445@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
446@findex -soundhw
447Enable audio and selected sound hardware. Use 'help' to print all
448available sound hardware.
449
450@example
451qemu-system-i386 -soundhw sb16,adlib disk.img
452qemu-system-i386 -soundhw es1370 disk.img
453qemu-system-i386 -soundhw ac97 disk.img
454qemu-system-i386 -soundhw hda disk.img
455qemu-system-i386 -soundhw all disk.img
456qemu-system-i386 -soundhw help
457@end example
458
459Note that Linux's i810_audio OSS kernel (for AC97) module might
460require manually specifying clocking.
461
462@example
463modprobe i810_audio clocking=48000
464@end example
465ETEXI
466
467DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100468 "-balloon virtio[,addr=str]\n"
Thomas Huth4060e672018-02-28 06:38:23 +0100469 " enable virtio balloon device (deprecated)\n", QEMU_ARCH_ALL)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100470STEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100471@item -balloon virtio[,addr=@var{addr}]
Thomas Huth4060e672018-02-28 06:38:23 +0100472@findex -balloon
473Enable virtio balloon device, optionally with PCI address @var{addr}. This
474option is deprecated, use @option{--device virtio-balloon} instead.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100475ETEXI
476
477DEF("device", HAS_ARG, QEMU_OPTION_device,
478 "-device driver[,prop[=value][,...]]\n"
479 " add device (based on driver)\n"
480 " prop=value,... sets driver properties\n"
481 " use '-device help' to print all possible drivers\n"
482 " use '-device driver,help' to print all possible properties\n",
483 QEMU_ARCH_ALL)
484STEXI
485@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
486@findex -device
487Add device @var{driver}. @var{prop}=@var{value} sets driver
488properties. Valid properties depend on the driver. To get help on
489possible drivers and properties, use @code{-device help} and
490@code{-device @var{driver},help}.
Corey Minyardf8490452015-12-17 12:50:10 -0600491
492Some drivers are:
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200493@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 -0600494
495Add an IPMI BMC. This is a simulation of a hardware management
496interface processor that normally sits on a system. It provides
497a watchdog and the ability to reset and power control the system.
498You need to connect this to an IPMI interface to make it useful
499
500The IPMI slave address to use for the BMC. The default is 0x20.
501This address is the BMC's address on the I2C network of management
502controllers. If you don't know what this means, it is safe to ignore
503it.
504
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200505@table @option
506@item bmc=@var{id}
507The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
508@item slave_addr=@var{val}
509Define slave address to use for the BMC. The default is 0x20.
510@item sdrfile=@var{file}
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200511file containing raw Sensor Data Records (SDR) data. The default is none.
512@item fruareasize=@var{val}
513size of a Field Replaceable Unit (FRU) area. The default is 1024.
514@item frudatafile=@var{file}
515file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200516@end table
517
Corey Minyardf8490452015-12-17 12:50:10 -0600518@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
519
520Add a connection to an external IPMI BMC simulator. Instead of
521locally emulating the BMC like the above item, instead connect
522to an external entity that provides the IPMI services.
523
524A connection is made to an external BMC simulator. If you do this, it
525is strongly recommended that you use the "reconnect=" chardev option
526to reconnect to the simulator if the connection is lost. Note that if
527this is not used carefully, it can be a security issue, as the
528interface has the ability to send resets, NMIs, and power off the VM.
529It's best if QEMU makes a connection to an external simulator running
530on a secure port on localhost, so neither the simulator nor QEMU is
531exposed to any outside network.
532
533See the "lanserv/README.vm" file in the OpenIPMI library for more
534details on the external interface.
535
536@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
537
538Add a KCS IPMI interafce on the ISA bus. This also adds a
539corresponding ACPI and SMBIOS entries, if appropriate.
540
541@table @option
542@item bmc=@var{id}
543The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
544@item ioport=@var{val}
545Define the I/O address of the interface. The default is 0xca0 for KCS.
546@item irq=@var{val}
547Define the interrupt to use. The default is 5. To disable interrupts,
548set this to 0.
549@end table
550
551@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
552
553Like the KCS interface, but defines a BT interface. The default port is
5540xe4 and the default interrupt is 5.
555
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100556ETEXI
557
558DEF("name", HAS_ARG, QEMU_OPTION_name,
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000559 "-name string1[,process=string2][,debug-threads=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100560 " set the name of the guest\n"
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000561 " string1 sets the window title and string2 the process name (on Linux)\n"
562 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
563 " NOTE: The thread names are for debugging and not a stable API.\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100564 QEMU_ARCH_ALL)
565STEXI
566@item -name @var{name}
567@findex -name
568Sets the @var{name} of the guest.
569This name will be displayed in the SDL window caption.
570The @var{name} will also be used for the VNC server.
571Also optionally set the top visible process name in Linux.
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000572Naming of individual threads can also be enabled on Linux to aid debugging.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100573ETEXI
574
575DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
576 "-uuid %08x-%04x-%04x-%04x-%012x\n"
577 " specify machine UUID\n", QEMU_ARCH_ALL)
578STEXI
579@item -uuid @var{uuid}
580@findex -uuid
581Set system UUID.
582ETEXI
583
584STEXI
585@end table
586ETEXI
587DEFHEADING()
588
Markus Armbrusterde6b4f92017-10-02 16:03:00 +0200589DEFHEADING(Block device options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100590STEXI
591@table @option
592ETEXI
593
blueswir15824d652009-03-28 06:44:27 +0000594DEF("fda", HAS_ARG, QEMU_OPTION_fda,
Blue Swirlad960902010-03-29 19:23:52 +0000595 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
596DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000597STEXI
598@item -fda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200599@itemx -fdb @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100600@findex -fda
601@findex -fdb
Markus Armbruster92a539d2015-03-17 17:02:20 +0100602Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
blueswir15824d652009-03-28 06:44:27 +0000603ETEXI
604
605DEF("hda", HAS_ARG, QEMU_OPTION_hda,
Blue Swirlad960902010-03-29 19:23:52 +0000606 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
607DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000608DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
Blue Swirlad960902010-03-29 19:23:52 +0000609 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
610DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000611STEXI
612@item -hda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200613@itemx -hdb @var{file}
614@itemx -hdc @var{file}
615@itemx -hdd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100616@findex -hda
617@findex -hdb
618@findex -hdc
619@findex -hdd
blueswir15824d652009-03-28 06:44:27 +0000620Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
621ETEXI
622
623DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
Blue Swirlad960902010-03-29 19:23:52 +0000624 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
625 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000626STEXI
627@item -cdrom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100628@findex -cdrom
blueswir15824d652009-03-28 06:44:27 +0000629Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
630@option{-cdrom} at the same time). You can use the host CD-ROM by
631using @file{/dev/cdrom} as filename (@pxref{host_drives}).
632ETEXI
633
Markus Armbruster42e5f392017-02-28 22:27:07 +0100634DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
635 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
636 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
637 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
638 " [,driver specific parameters...]\n"
639 " configure a block backend\n", QEMU_ARCH_ALL)
Kevin Wolfdfaca462016-09-22 16:53:24 +0200640STEXI
641@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
642@findex -blockdev
643
Kevin Wolf370e8322016-09-22 17:24:38 +0200644Define a new block driver node. Some of the options apply to all block drivers,
645other options are only accepted for a specific block driver. See below for a
646list of generic options and options for the most common block drivers.
647
648Options that expect a reference to another node (e.g. @code{file}) can be
649given in two ways. Either you specify the node name of an already existing node
650(file=@var{node-name}), or you define a new node inline, adding options
651for the referenced node after a dot (file.filename=@var{path},file.aio=native).
652
653A block driver node created with @option{-blockdev} can be used for a guest
654device by specifying its node name for the @code{drive} property in a
655@option{-device} argument that defines a block device.
Kevin Wolfdfaca462016-09-22 16:53:24 +0200656
657@table @option
658@item Valid options for any block driver node:
659
660@table @code
661@item driver
662Specifies the block driver to use for the given node.
663@item node-name
664This defines the name of the block driver node by which it will be referenced
665later. The name must be unique, i.e. it must not match the name of a different
666block driver node, or (if you use @option{-drive} as well) the ID of a drive.
667
668If no node name is specified, it is automatically generated. The generated node
669name is not intended to be predictable and changes between QEMU invocations.
670For the top level, an explicit node name must be specified.
671@item read-only
672Open the node read-only. Guest write attempts will fail.
673@item cache.direct
674The host page cache can be avoided with @option{cache.direct=on}. This will
675attempt to do disk IO directly to the guest's memory. QEMU may still perform an
676internal copy of the data.
677@item cache.no-flush
678In case you don't care about data integrity over host failures, you can use
679@option{cache.no-flush=on}. This option tells QEMU that it never needs to write
680any data to the disk but can instead keep things in cache. If anything goes
681wrong, like your host losing power, the disk storage getting disconnected
682accidentally, etc. your image will most probably be rendered unusable.
683@item discard=@var{discard}
684@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
685whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
686ignored or passed to the filesystem. Some machine types may not support
687discard requests.
688@item detect-zeroes=@var{detect-zeroes}
689@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
690conversion of plain zero writes by the OS to driver specific optimized
691zero write commands. You may even choose "unmap" if @var{discard} is set
692to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
693@end table
694
Kevin Wolf370e8322016-09-22 17:24:38 +0200695@item Driver-specific options for @code{file}
696
697This is the protocol-level block driver for accessing regular files.
698
699@table @code
700@item filename
701The path to the image file in the local filesystem
702@item aio
703Specifies the AIO backend (threads/native, default: threads)
Fam Zheng1878eaf2017-11-24 16:53:51 +0800704@item locking
705Specifies whether the image file is protected with Linux OFD / POSIX locks. The
706default is to use the Linux Open File Descriptor API if available, otherwise no
707lock is applied. (auto/on/off, default: auto)
Kevin Wolf370e8322016-09-22 17:24:38 +0200708@end table
709Example:
710@example
711-blockdev driver=file,node-name=disk,filename=disk.img
712@end example
713
714@item Driver-specific options for @code{raw}
715
716This is the image format block driver for raw images. It is usually
717stacked on top of a protocol level block driver such as @code{file}.
718
719@table @code
720@item file
721Reference to or definition of the data source block driver node
722(e.g. a @code{file} driver node)
723@end table
724Example 1:
725@example
726-blockdev driver=file,node-name=disk_file,filename=disk.img
727-blockdev driver=raw,node-name=disk,file=disk_file
728@end example
729Example 2:
730@example
731-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
732@end example
733
734@item Driver-specific options for @code{qcow2}
735
736This is the image format block driver for qcow2 images. It is usually
737stacked on top of a protocol level block driver such as @code{file}.
738
739@table @code
740@item file
741Reference to or definition of the data source block driver node
742(e.g. a @code{file} driver node)
743
744@item backing
745Reference to or definition of the backing file block device (default is taken
Max Reitz4f7be282018-02-24 16:40:33 +0100746from the image file). It is allowed to pass @code{null} here in order to disable
747the default backing file.
Kevin Wolf370e8322016-09-22 17:24:38 +0200748
749@item lazy-refcounts
750Whether to enable the lazy refcounts feature (on/off; default is taken from the
751image file)
752
753@item cache-size
754The maximum total size of the L2 table and refcount block caches in bytes
755(default: 1048576 bytes or 8 clusters, whichever is larger)
756
757@item l2-cache-size
758The maximum size of the L2 table cache in bytes
759(default: 4/5 of the total cache size)
760
761@item refcount-cache-size
762The maximum size of the refcount block cache in bytes
763(default: 1/5 of the total cache size)
764
765@item cache-clean-interval
766Clean unused entries in the L2 and refcount caches. The interval is in seconds.
767The default value is 0 and it disables this feature.
768
769@item pass-discard-request
770Whether discard requests to the qcow2 device should be forwarded to the data
771source (on/off; default: on if discard=unmap is specified, off otherwise)
772
773@item pass-discard-snapshot
774Whether discard requests for the data source should be issued when a snapshot
775operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
776default: on)
777
778@item pass-discard-other
779Whether discard requests for the data source should be issued on other
780occasions where a cluster gets freed (on/off; default: off)
781
782@item overlap-check
783Which overlap checks to perform for writes to the image
784(none/constant/cached/all; default: cached). For details or finer
785granularity control refer to the QAPI documentation of @code{blockdev-add}.
786@end table
787
788Example 1:
789@example
790-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
791-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
792@end example
793Example 2:
794@example
795-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
796@end example
797
798@item Driver-specific options for other drivers
799Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
800
Kevin Wolfdfaca462016-09-22 16:53:24 +0200801@end table
802
803ETEXI
Markus Armbruster42e5f392017-02-28 22:27:07 +0100804
blueswir15824d652009-03-28 06:44:27 +0000805DEF("drive", HAS_ARG, QEMU_OPTION_drive,
806 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100807 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
Kevin Wolfb0083262018-06-13 11:01:30 +0200808 " [,snapshot=on|off][,rerror=ignore|stop|report]\n"
Stefan Hajnoczid1db7602014-04-23 13:55:37 +0200809 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000810 " [,readonly=on|off][,copy-on-read=on|off]\n"
Peter Lieven2f7133b2014-07-28 21:53:02 +0200811 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
Benoît Canet3e9fab62013-09-02 14:14:40 +0200812 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
813 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
814 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
815 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
Benoît Canet2024c1d2013-09-02 14:14:41 +0200816 " [[,iops_size=is]]\n"
Alberto Garcia76f4afb2015-06-08 18:17:44 +0200817 " [[,group=g]]\n"
Blue Swirlad960902010-03-29 19:23:52 +0000818 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000819STEXI
820@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100821@findex -drive
blueswir15824d652009-03-28 06:44:27 +0000822
Kevin Wolfdfaca462016-09-22 16:53:24 +0200823Define a new drive. This includes creating a block driver node (the backend) as
824well as a guest device, and is mostly a shortcut for defining the corresponding
825@option{-blockdev} and @option{-device} options.
826
827@option{-drive} accepts all options that are accepted by @option{-blockdev}. In
828addition, it knows the following options:
blueswir15824d652009-03-28 06:44:27 +0000829
Kevin Wolfb3f046c2009-10-09 10:58:35 +0200830@table @option
blueswir15824d652009-03-28 06:44:27 +0000831@item file=@var{file}
832This option defines which disk image (@pxref{disk_images}) to use with
833this drive. If the filename contains comma, you must double it
834(for instance, "file=my,,file" to use file "my,file").
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +1100835
836Special files such as iSCSI devices can be specified using protocol
837specific URLs. See the section for "Device URL Syntax" for more information.
blueswir15824d652009-03-28 06:44:27 +0000838@item if=@var{interface}
839This option defines on which type on interface the drive is connected.
Craig Jellicked1fcd02017-03-17 08:49:55 -0700840Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
blueswir15824d652009-03-28 06:44:27 +0000841@item bus=@var{bus},unit=@var{unit}
842These options define where is connected the drive by defining the bus number and
843the unit id.
844@item index=@var{index}
845This option defines where is connected the drive by using an index in the list
846of available connectors of a given interface type.
847@item media=@var{media}
848This option defines the type of the media: disk or cdrom.
blueswir15824d652009-03-28 06:44:27 +0000849@item snapshot=@var{snapshot}
Michael Tokarev9d85d552014-04-07 13:34:58 +0400850@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
851(see @option{-snapshot}).
blueswir15824d652009-03-28 06:44:27 +0000852@item cache=@var{cache}
Kevin Wolfdfaca462016-09-22 16:53:24 +0200853@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
854and controls how the host cache is used to access block data. This is a
855shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
856options (as in @option{-blockdev}), and additionally @option{cache.writeback},
857which provides a default for the @option{write-cache} option of block guest
858devices (as in @option{-device}). The modes correspond to the following
859settings:
860
861@c Our texi2pod.pl script doesn't support @multitable, so fall back to using
862@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
863@c and the HTML output.
864@example
865@ │ cache.writeback cache.direct cache.no-flush
866─────────────┼─────────────────────────────────────────────────
867writeback │ on off off
868none │ on on off
869writethrough │ off off off
870directsync │ off on off
871unsafe │ on off on
872@end example
873
874The default mode is @option{cache=writeback}.
875
Christoph Hellwig5c6c3a62009-08-20 16:58:35 +0200876@item aio=@var{aio}
877@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
blueswir15824d652009-03-28 06:44:27 +0000878@item format=@var{format}
879Specify which disk @var{format} will be used rather than detecting
Michael Tokarevd33c8a72016-05-18 15:47:53 +0300880the format. Can be used to specify format=raw to avoid interpreting
blueswir15824d652009-03-28 06:44:27 +0000881an untrusted format header.
Luiz Capitulinoae73e592011-07-12 17:35:08 -0300882@item werror=@var{action},rerror=@var{action}
883Specify which @var{action} to take on write and read errors. Valid actions are:
884"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
885"report" (report the error to the guest), "enospc" (pause QEMU only if the
886host disk is full; report the error to the guest otherwise).
887The default setting is @option{werror=enospc} and @option{rerror=report}.
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000888@item copy-on-read=@var{copy-on-read}
889@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
890file sectors into the image file.
Stefan Hajnoczi01f9cfa2017-03-01 11:50:24 +0000891@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
892Specify bandwidth throttling limits in bytes per second, either for all request
893types or for reads or writes only. Small values can lead to timeouts or hangs
894inside the guest. A safe minimum for disks is 2 MB/s.
895@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
896Specify bursts in bytes per second, either for all request types or for reads
897or writes only. Bursts allow the guest I/O to spike above the limit
898temporarily.
899@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
900Specify request rate limits in requests per second, either for all request
901types or for reads or writes only.
902@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
903Specify bursts in requests per second, either for all request types or for reads
904or writes only. Bursts allow the guest I/O to spike above the limit
905temporarily.
906@item iops_size=@var{is}
907Let every @var{is} bytes of a request count as a new request for iops
908throttling purposes. Use this option to prevent guests from circumventing iops
909limits by sending fewer but larger requests.
910@item group=@var{g}
911Join a throttling quota group with given name @var{g}. All drives that are
912members of the same group are accounted for together. Use this option to
913prevent guests from circumventing throttling limits by using many small disks
914instead of a single larger disk.
blueswir15824d652009-03-28 06:44:27 +0000915@end table
916
Kevin Wolfdfaca462016-09-22 16:53:24 +0200917By default, the @option{cache.writeback=on} mode is used. It will report data
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100918writes as completed as soon as the data is present in the host page cache.
919This is safe as long as your guest OS makes sure to correctly flush disk caches
920where needed. If your guest OS does not handle volatile disk write caches
921correctly and your host crashes or loses power, then the guest may experience
922data corruption.
blueswir15824d652009-03-28 06:44:27 +0000923
Kevin Wolfdfaca462016-09-22 16:53:24 +0200924For such guests, you should consider using @option{cache.writeback=off}. This
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100925means that the host page cache will be used to read and write data, but write
926notification will be sent to the guest only after QEMU has made sure to flush
927each write to the disk. Be aware that this has a major impact on performance.
blueswir15824d652009-03-28 06:44:27 +0000928
Kevin Wolfdfaca462016-09-22 16:53:24 +0200929When using the @option{-snapshot} option, unsafe caching is always used.
Alexander Graf016f5cf2010-05-26 17:51:49 +0200930
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000931Copy-on-read avoids accessing the same backing file sectors repeatedly and is
932useful when the backing file is over a slow network. By default copy-on-read
933is off.
934
blueswir15824d652009-03-28 06:44:27 +0000935Instead of @option{-cdrom} you can use:
936@example
Stefan Weil3804da92012-05-11 22:21:50 +0200937qemu-system-i386 -drive file=file,index=2,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000938@end example
939
940Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
941use:
942@example
Stefan Weil3804da92012-05-11 22:21:50 +0200943qemu-system-i386 -drive file=file,index=0,media=disk
944qemu-system-i386 -drive file=file,index=1,media=disk
945qemu-system-i386 -drive file=file,index=2,media=disk
946qemu-system-i386 -drive file=file,index=3,media=disk
blueswir15824d652009-03-28 06:44:27 +0000947@end example
948
Corey Bryant587ed6b2012-10-18 15:19:34 -0400949You can open an image using pre-opened file descriptors from an fd set:
950@example
951qemu-system-i386
952-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
953-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
954-drive file=/dev/fdset/2,index=0,media=disk
955@end example
956
blueswir15824d652009-03-28 06:44:27 +0000957You can connect a CDROM to the slave of ide0:
958@example
Stefan Weil3804da92012-05-11 22:21:50 +0200959qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000960@end example
961
962If you don't specify the "file=" argument, you define an empty drive:
963@example
Stefan Weil3804da92012-05-11 22:21:50 +0200964qemu-system-i386 -drive if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000965@end example
966
blueswir15824d652009-03-28 06:44:27 +0000967Instead of @option{-fda}, @option{-fdb}, you can use:
968@example
Stefan Weil3804da92012-05-11 22:21:50 +0200969qemu-system-i386 -drive file=file,index=0,if=floppy
970qemu-system-i386 -drive file=file,index=1,if=floppy
blueswir15824d652009-03-28 06:44:27 +0000971@end example
972
973By default, @var{interface} is "ide" and @var{index} is automatically
974incremented:
975@example
Stefan Weil3804da92012-05-11 22:21:50 +0200976qemu-system-i386 -drive file=a -drive file=b"
blueswir15824d652009-03-28 06:44:27 +0000977@end example
978is interpreted like:
979@example
Stefan Weil3804da92012-05-11 22:21:50 +0200980qemu-system-i386 -hda a -hdb b
blueswir15824d652009-03-28 06:44:27 +0000981@end example
982ETEXI
983
984DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
Blue Swirlad960902010-03-29 19:23:52 +0000985 "-mtdblock file use 'file' as on-board Flash memory image\n",
986 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000987STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200988@item -mtdblock @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100989@findex -mtdblock
Kevin Wolf4e257e52009-10-09 10:58:36 +0200990Use @var{file} as on-board Flash memory image.
blueswir15824d652009-03-28 06:44:27 +0000991ETEXI
992
993DEF("sd", HAS_ARG, QEMU_OPTION_sd,
Blue Swirlad960902010-03-29 19:23:52 +0000994 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000995STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200996@item -sd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100997@findex -sd
Kevin Wolf4e257e52009-10-09 10:58:36 +0200998Use @var{file} as SecureDigital card image.
blueswir15824d652009-03-28 06:44:27 +0000999ETEXI
1000
1001DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
Blue Swirlad960902010-03-29 19:23:52 +00001002 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001003STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02001004@item -pflash @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001005@findex -pflash
Kevin Wolf4e257e52009-10-09 10:58:36 +02001006Use @var{file} as a parallel flash image.
blueswir15824d652009-03-28 06:44:27 +00001007ETEXI
1008
blueswir15824d652009-03-28 06:44:27 +00001009DEF("snapshot", 0, QEMU_OPTION_snapshot,
Blue Swirlad960902010-03-29 19:23:52 +00001010 "-snapshot write to temporary files instead of disk image files\n",
1011 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001012STEXI
1013@item -snapshot
Stefan Weil6616b2a2010-02-05 23:52:05 +01001014@findex -snapshot
blueswir15824d652009-03-28 06:44:27 +00001015Write to temporary files instead of disk image files. In this case,
1016the raw disk image you use is not written back. You can however force
1017the write back by pressing @key{C-a s} (@pxref{disk_images}).
1018ETEXI
1019
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301020DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301021 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001022 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
Pradeep Jagadeeshb8bbdb82017-02-28 10:31:46 +01001023 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1024 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1025 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1026 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1027 " [[,throttling.iops-size=is]]\n",
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301028 QEMU_ARCH_ALL)
1029
1030STEXI
1031
Tobias Schrammb96feb22017-06-29 15:11:50 +02001032@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 +05301033@findex -fsdev
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301034Define a new file system device. Valid options are:
1035@table @option
1036@item @var{fsdriver}
1037This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301038Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301039@item id=@var{id}
1040Specifies identifier for this device
1041@item path=@var{path}
1042Specifies the export path for the file system device. Files under
1043this path will be available to the 9p client on the guest.
1044@item security_model=@var{security_model}
1045Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301046Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301047In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001048credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301049to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301050attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301051file attributes. For "mapped-file" these attributes are stored in the
1052hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301053interact with other unix tools. "none" security model is same as
1054passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301055set file attributes like ownership. Security model is mandatory
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301056only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301057security model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301058@item writeout=@var{writeout}
1059This is an optional argument. The only supported value is "immediate".
1060This means that host page cache will be used to read and write data but
1061write notification will be sent to the guest only when the data has been
1062reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301063@item readonly
1064Enables exporting 9p share as a readonly mount for guests. By default
1065read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301066@item socket=@var{socket}
1067Enables proxy filesystem driver to use passed socket file for communicating
1068with virtfs-proxy-helper
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301069@item sock_fd=@var{sock_fd}
1070Enables proxy filesystem driver to use passed socket descriptor for
1071communicating with virtfs-proxy-helper. Usually a helper like libvirt
1072will create socketpair and pass one of the fds as sock_fd
Tobias Schrammb96feb22017-06-29 15:11:50 +02001073@item fmode=@var{fmode}
1074Specifies the default mode for newly created files on the host. Works only
1075with security models "mapped-xattr" and "mapped-file".
1076@item dmode=@var{dmode}
1077Specifies the default mode for newly created directories on the host. Works
1078only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301079@end table
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301080
1081-fsdev option is used along with -device driver "virtio-9p-pci".
1082@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
1083Options for virtio-9p-pci driver are:
1084@table @option
1085@item fsdev=@var{id}
1086Specifies the id value specified along with -fsdev option
1087@item mount_tag=@var{mount_tag}
1088Specifies the tag name to be used by the guest to mount this export point
1089@end table
1090
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301091ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301092
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301093DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301094 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001095 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n",
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301096 QEMU_ARCH_ALL)
1097
1098STEXI
1099
Tobias Schrammb96feb22017-06-29 15:11:50 +02001100@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 +05301101@findex -virtfs
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301102
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301103The general form of a Virtual File system pass-through options are:
1104@table @option
1105@item @var{fsdriver}
1106This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301107Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301108@item id=@var{id}
1109Specifies identifier for this device
1110@item path=@var{path}
1111Specifies the export path for the file system device. Files under
1112this path will be available to the 9p client on the guest.
1113@item security_model=@var{security_model}
1114Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301115Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301116In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001117credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301118to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301119attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301120file attributes. For "mapped-file" these attributes are stored in the
1121hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301122interact with other unix tools. "none" security model is same as
1123passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301124set file attributes like ownership. Security model is mandatory only
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301125for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301126model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301127@item writeout=@var{writeout}
1128This is an optional argument. The only supported value is "immediate".
1129This means that host page cache will be used to read and write data but
1130write notification will be sent to the guest only when the data has been
1131reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301132@item readonly
1133Enables exporting 9p share as a readonly mount for guests. By default
1134read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301135@item socket=@var{socket}
1136Enables proxy filesystem driver to use passed socket file for
1137communicating with virtfs-proxy-helper. Usually a helper like libvirt
1138will create socketpair and pass one of the fds as sock_fd
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301139@item sock_fd
1140Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1141descriptor for interfacing with virtfs-proxy-helper
Tobias Schrammb96feb22017-06-29 15:11:50 +02001142@item fmode=@var{fmode}
1143Specifies the default mode for newly created files on the host. Works only
1144with security models "mapped-xattr" and "mapped-file".
1145@item dmode=@var{dmode}
1146Specifies the default mode for newly created directories on the host. Works
1147only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301148@end table
1149ETEXI
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301150
Aneesh Kumar K.V9db221a2011-10-25 12:10:40 +05301151DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
1152 "-virtfs_synth Create synthetic file system image\n",
1153 QEMU_ARCH_ALL)
1154STEXI
1155@item -virtfs_synth
1156@findex -virtfs_synth
1157Create synthetic file system image
1158ETEXI
1159
Markus Armbruster61d70482017-10-02 16:03:03 +02001160DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1161 "-iscsi [user=user][,password=password]\n"
1162 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1163 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1164 " [,timeout=timeout]\n"
1165 " iSCSI session parameters\n", QEMU_ARCH_ALL)
1166
blueswir15824d652009-03-28 06:44:27 +00001167STEXI
Markus Armbruster44743142017-10-02 16:03:04 +02001168@item -iscsi
1169@findex -iscsi
1170Configure iSCSI session parameters.
1171ETEXI
1172
1173STEXI
blueswir15824d652009-03-28 06:44:27 +00001174@end table
1175ETEXI
blueswir15824d652009-03-28 06:44:27 +00001176DEFHEADING()
1177
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001178DEFHEADING(USB options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001179STEXI
1180@table @option
1181ETEXI
1182
1183DEF("usb", 0, QEMU_OPTION_usb,
Thomas Hutha358a3a2017-05-19 08:35:16 +02001184 "-usb enable the USB driver (if it is not used by default yet)\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001185 QEMU_ARCH_ALL)
1186STEXI
1187@item -usb
1188@findex -usb
Thomas Hutha358a3a2017-05-19 08:35:16 +02001189Enable the USB driver (if it is not used by default yet).
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001190ETEXI
1191
1192DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1193 "-usbdevice name add the host or guest USB device 'name'\n",
1194 QEMU_ARCH_ALL)
1195STEXI
1196
1197@item -usbdevice @var{devname}
1198@findex -usbdevice
Thomas Hutha358a3a2017-05-19 08:35:16 +02001199Add the USB device @var{devname}. Note that this option is deprecated,
1200please use @code{-device usb-...} instead. @xref{usb_devices}.
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001201
1202@table @option
1203
1204@item mouse
1205Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1206
1207@item tablet
1208Pointer device that uses absolute coordinates (like a touchscreen). This
1209means QEMU is able to report the mouse position without having to grab the
1210mouse. Also overrides the PS/2 mouse emulation when activated.
1211
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001212@item braille
1213Braille device. This will use BrlAPI to display the braille output on a real
1214or fake device.
1215
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001216@end table
1217ETEXI
1218
1219STEXI
1220@end table
1221ETEXI
1222DEFHEADING()
1223
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001224DEFHEADING(Display options:)
blueswir15824d652009-03-28 06:44:27 +00001225STEXI
1226@table @option
1227ETEXI
1228
Jes Sorensen1472a952011-03-16 13:33:31 +01001229DEF("display", HAS_ARG, QEMU_OPTION_display,
1230 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
Elie Tournier4867e472018-04-13 14:58:42 +01001231 " [,window_close=on|off][,gl=on|core|es|off]\n"
Robert Hof04ec5a2016-07-26 18:17:11 +08001232 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1233 "-display vnc=<display>[,<optargs>]\n"
1234 "-display curses\n"
1235 "-display none"
1236 " select display type\n"
1237 "The default display is equivalent to\n"
1238#if defined(CONFIG_GTK)
1239 "\t\"-display gtk\"\n"
1240#elif defined(CONFIG_SDL)
1241 "\t\"-display sdl\"\n"
1242#elif defined(CONFIG_COCOA)
1243 "\t\"-display cocoa\"\n"
1244#elif defined(CONFIG_VNC)
1245 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1246#else
1247 "\t\"-display none\"\n"
1248#endif
1249 , QEMU_ARCH_ALL)
Jes Sorensen1472a952011-03-16 13:33:31 +01001250STEXI
1251@item -display @var{type}
1252@findex -display
1253Select type of display to use. This option is a replacement for the
1254old style -sdl/-curses/... options. Valid values for @var{type} are
1255@table @option
1256@item sdl
1257Display video output via SDL (usually in a separate graphics
1258window; see the SDL documentation for other possibilities).
1259@item curses
1260Display video output via curses. For graphics device models which
1261support a text mode, QEMU can display this output using a
1262curses/ncurses interface. Nothing is displayed when the graphics
1263device is in graphical mode or if the graphics device does not support
1264a text mode. Generally only the VGA device models support text mode.
Jes Sorensen4171d322011-03-16 13:33:32 +01001265@item none
1266Do not display video output. The guest will still see an emulated
1267graphics card, but its output will not be displayed to the QEMU
1268user. This option differs from the -nographic option in that it
1269only affects what is done with video output; -nographic also changes
1270the destination of the serial and parallel port data.
Jan Kiszka881249c2014-03-12 08:33:50 +01001271@item gtk
1272Display video output in a GTK window. This interface provides drop-down
1273menus and other UI elements to configure and control the VM during
1274runtime.
Jes Sorensen3264ff12011-03-16 13:33:33 +01001275@item vnc
1276Start a VNC server on display <arg>
Jes Sorensen1472a952011-03-16 13:33:31 +01001277@end table
1278ETEXI
1279
blueswir15824d652009-03-28 06:44:27 +00001280DEF("nographic", 0, QEMU_OPTION_nographic,
Blue Swirlad960902010-03-29 19:23:52 +00001281 "-nographic disable graphical output and redirect serial I/Os to console\n",
1282 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001283STEXI
1284@item -nographic
Stefan Weil6616b2a2010-02-05 23:52:05 +01001285@findex -nographic
Colin Lorddc0a3e42016-08-12 15:30:48 -04001286Normally, if QEMU is compiled with graphical window support, it displays
1287output such as guest graphics, guest console, and the QEMU monitor in a
1288window. With this option, you can totally disable graphical output so
1289that QEMU is a simple command line application. The emulated serial port
1290is redirected on the console and muxed with the monitor (unless
1291redirected elsewhere explicitly). Therefore, you can still use QEMU to
1292debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1293switching between the console and monitor.
blueswir15824d652009-03-28 06:44:27 +00001294ETEXI
1295
blueswir15824d652009-03-28 06:44:27 +00001296DEF("curses", 0, QEMU_OPTION_curses,
Robert Hof04ec5a2016-07-26 18:17:11 +08001297 "-curses shorthand for -display curses\n",
Blue Swirlad960902010-03-29 19:23:52 +00001298 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001299STEXI
1300@item -curses
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001301@findex -curses
Colin Lorddc0a3e42016-08-12 15:30:48 -04001302Normally, if QEMU is compiled with graphical window support, it displays
1303output such as guest graphics, guest console, and the QEMU monitor in a
1304window. With this option, QEMU can display the VGA output when in text
1305mode using a curses/ncurses interface. Nothing is displayed in graphical
1306mode.
blueswir15824d652009-03-28 06:44:27 +00001307ETEXI
1308
blueswir15824d652009-03-28 06:44:27 +00001309DEF("no-frame", 0, QEMU_OPTION_no_frame,
Blue Swirlad960902010-03-29 19:23:52 +00001310 "-no-frame open SDL window without a frame and window decorations\n",
1311 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001312STEXI
1313@item -no-frame
Stefan Weil6616b2a2010-02-05 23:52:05 +01001314@findex -no-frame
blueswir15824d652009-03-28 06:44:27 +00001315Do not use decorations for SDL windows and start them using the whole
1316available screen space. This makes the using QEMU in a dedicated desktop
1317workspace more convenient.
1318ETEXI
1319
blueswir15824d652009-03-28 06:44:27 +00001320DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001321 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1322 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001323STEXI
1324@item -alt-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001325@findex -alt-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001326Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1327affects the special keys (for fullscreen, monitor-mode switching, etc).
blueswir15824d652009-03-28 06:44:27 +00001328ETEXI
1329
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001330DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001331 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1332 QEMU_ARCH_ALL)
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001333STEXI
1334@item -ctrl-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001335@findex -ctrl-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001336Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1337affects the special keys (for fullscreen, monitor-mode switching, etc).
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001338ETEXI
1339
blueswir15824d652009-03-28 06:44:27 +00001340DEF("no-quit", 0, QEMU_OPTION_no_quit,
Blue Swirlad960902010-03-29 19:23:52 +00001341 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001342STEXI
1343@item -no-quit
Stefan Weil6616b2a2010-02-05 23:52:05 +01001344@findex -no-quit
blueswir15824d652009-03-28 06:44:27 +00001345Disable SDL window close capability.
1346ETEXI
1347
blueswir15824d652009-03-28 06:44:27 +00001348DEF("sdl", 0, QEMU_OPTION_sdl,
Robert Hof04ec5a2016-07-26 18:17:11 +08001349 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001350STEXI
1351@item -sdl
Stefan Weil6616b2a2010-02-05 23:52:05 +01001352@findex -sdl
blueswir15824d652009-03-28 06:44:27 +00001353Enable SDL.
1354ETEXI
1355
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001356DEF("spice", HAS_ARG, QEMU_OPTION_spice,
Yonit Halperin27af7782012-08-21 13:54:20 +03001357 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1358 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1359 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
Marc-André Lureaufe4831b2015-01-13 17:57:51 +01001360 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001361 " [,tls-ciphers=<list>]\n"
1362 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1363 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1364 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1365 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1366 " [,jpeg-wan-compression=[auto|never|always]]\n"
1367 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1368 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
Hans de Goede5ad24e52013-06-08 15:37:27 +02001369 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1370 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
Marc-André Lureau7b525502017-02-12 15:21:18 +04001371 " [,gl=[on|off]][,rendernode=<file>]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001372 " enable spice\n"
1373 " at least one of {port, tls-port} is mandatory\n",
1374 QEMU_ARCH_ALL)
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001375STEXI
1376@item -spice @var{option}[,@var{option}[,...]]
1377@findex -spice
1378Enable the spice remote desktop protocol. Valid options are
1379
1380@table @option
1381
1382@item port=<nr>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001383Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001384
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001385@item addr=<addr>
1386Set the IP address spice is listening on. Default is any address.
1387
1388@item ipv4
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001389@itemx ipv6
1390@itemx unix
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001391Force using the specified IP version.
1392
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001393@item password=<secret>
1394Set the password you need to authenticate.
1395
Marc-André Lureau48b3ed02011-05-17 10:40:33 +02001396@item sasl
1397Require that the client use SASL to authenticate with the spice.
1398The exact choice of authentication method used is controlled from the
1399system / user's SASL configuration file for the 'qemu' service. This
1400is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1401unprivileged user, an environment variable SASL_CONF_PATH can be used
1402to make it search alternate locations for the service config.
1403While some SASL auth methods can also provide data encryption (eg GSSAPI),
1404it is recommended that SASL always be combined with the 'tls' and
1405'x509' settings to enable use of SSL and server certificates. This
1406ensures a data encryption preventing compromise of authentication
1407credentials.
1408
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001409@item disable-ticketing
1410Allow client connects without authentication.
1411
Hans de Goeded4970b02011-03-27 16:43:54 +02001412@item disable-copy-paste
1413Disable copy paste between the client and the guest.
1414
Hans de Goede5ad24e52013-06-08 15:37:27 +02001415@item disable-agent-file-xfer
1416Disable spice-vdagent based file-xfer between the client and the guest.
1417
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001418@item tls-port=<nr>
1419Set the TCP port spice is listening on for encrypted channels.
1420
1421@item x509-dir=<dir>
1422Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1423
1424@item x509-key-file=<file>
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001425@itemx x509-key-password=<file>
1426@itemx x509-cert-file=<file>
1427@itemx x509-cacert-file=<file>
1428@itemx x509-dh-key-file=<file>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001429The x509 file names can also be configured individually.
1430
1431@item tls-ciphers=<list>
1432Specify which ciphers to use.
1433
Alon Levyd70d6b32011-12-20 13:05:18 +02001434@item tls-channel=[main|display|cursor|inputs|record|playback]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001435@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
Gerd Hoffmann17b6dea2010-08-27 14:09:56 +02001436Force specific channel to be used with or without TLS encryption. The
1437options can be specified multiple times to configure multiple
1438channels. The special name "default" can be used to set the default
1439mode. For channels which are not explicitly forced into one mode the
1440spice client is allowed to pick tls/plaintext as he pleases.
1441
Yonit Halperin9f04e092010-07-14 13:26:34 +03001442@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1443Configure image compression (lossless).
1444Default is auto_glz.
1445
1446@item jpeg-wan-compression=[auto|never|always]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001447@itemx zlib-glz-wan-compression=[auto|never|always]
Yonit Halperin9f04e092010-07-14 13:26:34 +03001448Configure wan image compression (lossy for slow links).
1449Default is auto.
1450
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001451@item streaming-video=[off|all|filter]
Li Zhijian93ca5192016-08-01 12:06:59 +08001452Configure video stream detection. Default is off.
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001453
1454@item agent-mouse=[on|off]
1455Enable/disable passing mouse events via vdagent. Default is on.
1456
1457@item playback-compression=[on|off]
1458Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1459
Yonit Halperin8c957052012-08-21 11:51:59 +03001460@item seamless-migration=[on|off]
1461Enable/disable spice seamless migration. Default is off.
1462
Gerd Hoffmann474114b2015-10-13 15:39:34 +02001463@item gl=[on|off]
1464Enable/disable OpenGL context. Default is off.
1465
Marc-André Lureau7b525502017-02-12 15:21:18 +04001466@item rendernode=<file>
1467DRM render node for OpenGL rendering. If not specified, it will pick
1468the first available. (Since 2.9)
1469
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001470@end table
1471ETEXI
1472
blueswir15824d652009-03-28 06:44:27 +00001473DEF("portrait", 0, QEMU_OPTION_portrait,
Blue Swirlad960902010-03-29 19:23:52 +00001474 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1475 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001476STEXI
1477@item -portrait
Stefan Weil6616b2a2010-02-05 23:52:05 +01001478@findex -portrait
blueswir15824d652009-03-28 06:44:27 +00001479Rotate graphical output 90 deg left (only PXA LCD).
1480ETEXI
1481
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001482DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1483 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1484 QEMU_ARCH_ALL)
1485STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01001486@item -rotate @var{deg}
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001487@findex -rotate
1488Rotate graphical output some deg left (only PXA LCD).
1489ETEXI
1490
blueswir15824d652009-03-28 06:44:27 +00001491DEF("vga", HAS_ARG, QEMU_OPTION_vga,
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001492 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001493 " select video card type\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001494STEXI
malce4558dc2012-08-27 18:33:21 +04001495@item -vga @var{type}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001496@findex -vga
blueswir15824d652009-03-28 06:44:27 +00001497Select type of VGA card to emulate. Valid values for @var{type} are
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001498@table @option
blueswir15824d652009-03-28 06:44:27 +00001499@item cirrus
1500Cirrus Logic GD5446 Video card. All Windows versions starting from
1501Windows 95 should recognize and use this graphic card. For optimal
1502performances, use 16 bit color depth in the guest and the host OS.
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001503(This card was the default before QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001504@item std
1505Standard VGA card with Bochs VBE extensions. If your guest OS
1506supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1507to use high resolution modes (>= 1280x1024x16) then you should use
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001508this option. (This card is the default since QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001509@item vmware
1510VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1511recent XFree86/XOrg server or Windows guest with a driver for this
1512card.
Gerd Hoffmanna19cbfb2010-04-27 11:50:11 +02001513@item qxl
1514QXL paravirtual graphic card. It is VGA compatible (including VESA
15152.0 VBE support). Works best with qxl guest drivers installed though.
1516Recommended choice when using the spice protocol.
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001517@item tcx
1518(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1519sun4m machines and offers both 8-bit and 24-bit colour depths at a
1520fixed resolution of 1024x768.
1521@item cg3
1522(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1523for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1524resolutions aimed at people wishing to run older Solaris versions.
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001525@item virtio
1526Virtio VGA card.
blueswir15824d652009-03-28 06:44:27 +00001527@item none
1528Disable VGA card.
1529@end table
1530ETEXI
1531
1532DEF("full-screen", 0, QEMU_OPTION_full_screen,
Blue Swirlad960902010-03-29 19:23:52 +00001533 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001534STEXI
1535@item -full-screen
Stefan Weil6616b2a2010-02-05 23:52:05 +01001536@findex -full-screen
blueswir15824d652009-03-28 06:44:27 +00001537Start in full screen.
1538ETEXI
1539
blueswir15824d652009-03-28 06:44:27 +00001540DEF("g", 1, QEMU_OPTION_g ,
Blue Swirlad960902010-03-29 19:23:52 +00001541 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1542 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
blueswir15824d652009-03-28 06:44:27 +00001543STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01001544@item -g @var{width}x@var{height}[x@var{depth}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001545@findex -g
Stefan Weil95d5f082010-01-20 22:25:27 +01001546Set the initial graphical resolution and depth (PPC, SPARC only).
blueswir15824d652009-03-28 06:44:27 +00001547ETEXI
1548
1549DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
Robert Hof04ec5a2016-07-26 18:17:11 +08001550 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001551STEXI
1552@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001553@findex -vnc
Colin Lorddc0a3e42016-08-12 15:30:48 -04001554Normally, if QEMU is compiled with graphical window support, it displays
1555output such as guest graphics, guest console, and the QEMU monitor in a
1556window. With this option, you can have QEMU listen on VNC display
1557@var{display} and redirect the VGA display over the VNC session. It is
1558very useful to enable the usb tablet device when using this option
Thomas Hutha358a3a2017-05-19 08:35:16 +02001559(option @option{-device usb-tablet}). When using the VNC display, you
Colin Lorddc0a3e42016-08-12 15:30:48 -04001560must use the @option{-k} parameter to set the keyboard layout if you are
1561not using en-us. Valid syntax for the @var{display} is
blueswir15824d652009-03-28 06:44:27 +00001562
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001563@table @option
blueswir15824d652009-03-28 06:44:27 +00001564
Robert Ho99a9a522016-05-31 15:03:09 +08001565@item to=@var{L}
1566
1567With this option, QEMU will try next available VNC @var{display}s, until the
1568number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1569available, e.g. port 5900+@var{display} is already used by another
1570application. By default, to=0.
1571
blueswir15824d652009-03-28 06:44:27 +00001572@item @var{host}:@var{d}
1573
1574TCP connections will only be allowed from @var{host} on display @var{d}.
1575By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1576be omitted in which case the server will accept connections from any host.
1577
Kevin Wolf4e257e52009-10-09 10:58:36 +02001578@item unix:@var{path}
blueswir15824d652009-03-28 06:44:27 +00001579
1580Connections will be allowed over UNIX domain sockets where @var{path} is the
1581location of a unix socket to listen for connections on.
1582
1583@item none
1584
1585VNC is initialized but not started. The monitor @code{change} command
1586can be used to later start the VNC server.
1587
1588@end table
1589
1590Following the @var{display} value there may be one or more @var{option} flags
1591separated by commas. Valid options are
1592
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001593@table @option
blueswir15824d652009-03-28 06:44:27 +00001594
1595@item reverse
1596
1597Connect to a listening VNC client via a ``reverse'' connection. The
1598client is specified by the @var{display}. For reverse network
1599connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1600is a TCP port number, not a display number.
1601
Tim Hardeck7536ee42013-01-21 11:04:44 +01001602@item websocket
1603
1604Opens an additional TCP listening port dedicated to VNC Websocket connections.
Daniel P. Berrange275e0d62017-02-03 12:06:45 +00001605If a bare @var{websocket} option is given, the Websocket port is
16065700+@var{display}. An alternative port can be specified with the
1607syntax @code{websocket}=@var{port}.
1608
1609If @var{host} is specified connections will only be allowed from this host.
1610It is possible to control the websocket listen address independently, using
1611the syntax @code{websocket}=@var{host}:@var{port}.
1612
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001613If no TLS credentials are provided, the websocket connection runs in
1614unencrypted mode. If TLS credentials are provided, the websocket connection
1615requires encrypted client connections.
Tim Hardeck7536ee42013-01-21 11:04:44 +01001616
blueswir15824d652009-03-28 06:44:27 +00001617@item password
1618
1619Require that password based authentication is used for client connections.
Michal Novotny86ee5bc2012-07-16 15:54:38 +02001620
1621The password must be set separately using the @code{set_password} command in
1622the @ref{pcsys_monitor}. The syntax to change your password is:
1623@code{set_password <protocol> <password>} where <protocol> could be either
1624"vnc" or "spice".
1625
1626If you would like to change <protocol> password expiration, you should use
1627@code{expire_password <protocol> <expiration-time>} where expiration time could
1628be one of the following options: now, never, +seconds or UNIX time of
1629expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1630to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1631date and time).
1632
1633You can also use keywords "now" or "never" for the expiration time to
1634allow <protocol> password to expire immediately or never expire.
blueswir15824d652009-03-28 06:44:27 +00001635
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001636@item tls-creds=@var{ID}
1637
1638Provides the ID of a set of TLS credentials to use to secure the
1639VNC server. They will apply to both the normal VNC server socket
1640and the websocket socket (if enabled). Setting TLS credentials
1641will cause the VNC server socket to enable the VeNCrypt auth
1642mechanism. The credentials should have been previously created
1643using the @option{-object tls-creds} argument.
1644
1645The @option{tls-creds} parameter obsoletes the @option{tls},
1646@option{x509}, and @option{x509verify} options, and as such
1647it is not permitted to set both new and old type options at
1648the same time.
1649
blueswir15824d652009-03-28 06:44:27 +00001650@item tls
1651
1652Require that client use TLS when communicating with the VNC server. This
1653uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1654attack. It is recommended that this option be combined with either the
Kevin Wolf4e257e52009-10-09 10:58:36 +02001655@option{x509} or @option{x509verify} options.
blueswir15824d652009-03-28 06:44:27 +00001656
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001657This option is now deprecated in favor of using the @option{tls-creds}
1658argument.
1659
blueswir15824d652009-03-28 06:44:27 +00001660@item x509=@var{/path/to/certificate/dir}
1661
1662Valid if @option{tls} is specified. Require that x509 credentials are used
1663for negotiating the TLS session. The server will send its x509 certificate
1664to the client. It is recommended that a password be set on the VNC server
1665to provide authentication of the client when this is used. The path following
1666this option specifies where the x509 certificates are to be loaded from.
1667See the @ref{vnc_security} section for details on generating certificates.
1668
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001669This option is now deprecated in favour of using the @option{tls-creds}
1670argument.
1671
blueswir15824d652009-03-28 06:44:27 +00001672@item x509verify=@var{/path/to/certificate/dir}
1673
1674Valid if @option{tls} is specified. Require that x509 credentials are used
1675for negotiating the TLS session. The server will send its x509 certificate
1676to the client, and request that the client send its own x509 certificate.
1677The server will validate the client's certificate against the CA certificate,
1678and reject clients when validation fails. If the certificate authority is
1679trusted, this is a sufficient authentication mechanism. You may still wish
1680to set a password on the VNC server as a second authentication layer. The
1681path following this option specifies where the x509 certificates are to
1682be loaded from. See the @ref{vnc_security} section for details on generating
1683certificates.
1684
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001685This option is now deprecated in favour of using the @option{tls-creds}
1686argument.
1687
blueswir15824d652009-03-28 06:44:27 +00001688@item sasl
1689
1690Require that the client use SASL to authenticate with the VNC server.
1691The exact choice of authentication method used is controlled from the
1692system / user's SASL configuration file for the 'qemu' service. This
1693is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1694unprivileged user, an environment variable SASL_CONF_PATH can be used
1695to make it search alternate locations for the service config.
1696While some SASL auth methods can also provide data encryption (eg GSSAPI),
1697it is recommended that SASL always be combined with the 'tls' and
1698'x509' settings to enable use of SSL and server certificates. This
1699ensures a data encryption preventing compromise of authentication
1700credentials. See the @ref{vnc_security} section for details on using
1701SASL authentication.
1702
1703@item acl
1704
1705Turn on access control lists for checking of the x509 client certificate
1706and SASL party. For x509 certs, the ACL check is made against the
1707certificate's distinguished name. This is something that looks like
1708@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1709made against the username, which depending on the SASL plugin, may
1710include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1711When the @option{acl} flag is set, the initial access list will be
1712empty, with a @code{deny} policy. Thus no one will be allowed to
1713use the VNC server until the ACLs have been loaded. This can be
1714achieved using the @code{acl} monitor command.
1715
Corentin Chary6f9c78c2010-07-07 20:57:51 +02001716@item lossy
1717
1718Enable lossy compression methods (gradient, JPEG, ...). If this
1719option is set, VNC client may receive lossy framebuffer updates
1720depending on its encoding settings. Enabling this option can save
1721a lot of bandwidth at the expense of quality.
1722
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001723@item non-adaptive
1724
1725Disable adaptive encodings. Adaptive encodings are enabled by default.
1726An adaptive encoding will try to detect frequently updated screen regions,
1727and send updates in these regions using a lossy encoding (like JPEG).
Stefan Weil61cc8702011-04-13 22:45:22 +02001728This can be really helpful to save bandwidth when playing videos. Disabling
Michael Tokarev9d85d552014-04-07 13:34:58 +04001729adaptive encodings restores the original static behavior of encodings
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001730like Tight.
1731
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001732@item share=[allow-exclusive|force-shared|ignore]
1733
1734Set display sharing policy. 'allow-exclusive' allows clients to ask
1735for exclusive access. As suggested by the rfb spec this is
1736implemented by dropping other connections. Connecting multiple
1737clients in parallel requires all clients asking for a shared session
1738(vncviewer: -shared switch). This is the default. 'force-shared'
1739disables exclusive client access. Useful for shared desktop sessions,
1740where you don't want someone forgetting specify -shared disconnect
1741everybody else. 'ignore' completely ignores the shared flag and
1742allows everybody connect unconditionally. Doesn't conform to the rfb
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001743spec but is traditional QEMU behavior.
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001744
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001745@item key-delay-ms
1746
1747Set keyboard delay, for key down and key up events, in milliseconds.
Alexander Grafd3b0db62017-07-12 14:43:45 +02001748Default is 10. Keyboards are low-bandwidth devices, so this slowdown
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001749can help the device and guest to keep up and not lose events in case
1750events are arriving in bulk. Possible causes for the latter are flaky
1751network connections, or scripts for automated testing.
1752
blueswir15824d652009-03-28 06:44:27 +00001753@end table
1754ETEXI
1755
1756STEXI
1757@end table
1758ETEXI
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001759ARCHHEADING(, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001760
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001761ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001762STEXI
1763@table @option
1764ETEXI
1765
blueswir15824d652009-03-28 06:44:27 +00001766DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
Blue Swirlad960902010-03-29 19:23:52 +00001767 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1768 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001769STEXI
1770@item -win2k-hack
Stefan Weil6616b2a2010-02-05 23:52:05 +01001771@findex -win2k-hack
blueswir15824d652009-03-28 06:44:27 +00001772Use it when installing Windows 2000 to avoid a disk full bug. After
1773Windows 2000 is installed, you no longer need this option (this option
1774slows down the IDE transfers).
1775ETEXI
1776
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02001777HXCOMM Deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00001778DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001779
blueswir15824d652009-03-28 06:44:27 +00001780DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
Blue Swirlad960902010-03-29 19:23:52 +00001781 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1782 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001783STEXI
1784@item -no-fd-bootchk
Stefan Weil6616b2a2010-02-05 23:52:05 +01001785@findex -no-fd-bootchk
Markus Armbruster4eda32f2013-06-14 13:15:06 +02001786Disable boot signature checking for floppy disks in BIOS. May
blueswir15824d652009-03-28 06:44:27 +00001787be needed to boot from old floppy disks.
1788ETEXI
1789
blueswir15824d652009-03-28 06:44:27 +00001790DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
Shannon Zhaof5d8c8c2015-05-29 11:28:54 +01001791 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
blueswir15824d652009-03-28 06:44:27 +00001792STEXI
1793@item -no-acpi
Stefan Weil6616b2a2010-02-05 23:52:05 +01001794@findex -no-acpi
blueswir15824d652009-03-28 06:44:27 +00001795Disable ACPI (Advanced Configuration and Power Interface) support. Use
1796it if your guest OS complains about ACPI problems (PC target machine
1797only).
1798ETEXI
1799
blueswir15824d652009-03-28 06:44:27 +00001800DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
Blue Swirlad960902010-03-29 19:23:52 +00001801 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001802STEXI
1803@item -no-hpet
Stefan Weil6616b2a2010-02-05 23:52:05 +01001804@findex -no-hpet
blueswir15824d652009-03-28 06:44:27 +00001805Disable HPET support.
1806ETEXI
1807
blueswir15824d652009-03-28 06:44:27 +00001808DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
Michael Tokarev104bf022011-05-12 18:44:17 +04001809 "-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 +00001810 " ACPI table description\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001811STEXI
1812@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 +01001813@findex -acpitable
blueswir15824d652009-03-28 06:44:27 +00001814Add ACPI table with specified header fields and context from specified files.
Michael Tokarev104bf022011-05-12 18:44:17 +04001815For file=, take whole ACPI table from the specified files, including all
1816ACPI headers (possible overridden by other options).
1817For data=, only data
1818portion of the table is used, all header information is specified in the
1819command line.
Laszlo Ersekae123742016-01-18 15:12:13 +01001820If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1821fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1822to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1823spec.
blueswir15824d652009-03-28 06:44:27 +00001824ETEXI
1825
aliguorib6f6e3d2009-04-17 18:59:56 +00001826DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1827 "-smbios file=binary\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001828 " load SMBIOS entry from binary file\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001829 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1830 " [,uefi=on|off]\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001831 " specify SMBIOS type 0 fields\n"
aliguorib6f6e3d2009-04-17 18:59:56 +00001832 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1833 " [,uuid=uuid][,sku=str][,family=str]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001834 " specify SMBIOS type 1 fields\n"
1835 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1836 " [,asset=str][,location=str]\n"
1837 " specify SMBIOS type 2 fields\n"
1838 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1839 " [,sku=str]\n"
1840 " specify SMBIOS type 3 fields\n"
1841 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1842 " [,asset=str][,part=str]\n"
1843 " specify SMBIOS type 4 fields\n"
1844 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001845 " [,asset=str][,part=str][,speed=%d]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001846 " specify SMBIOS type 17 fields\n",
Wei Huangc30e1562015-09-07 10:39:29 +01001847 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
aliguorib6f6e3d2009-04-17 18:59:56 +00001848STEXI
1849@item -smbios file=@var{binary}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001850@findex -smbios
aliguorib6f6e3d2009-04-17 18:59:56 +00001851Load SMBIOS entry from binary file.
1852
Gabriel L. Somlo84351842014-05-19 10:09:54 -04001853@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 +00001854Specify SMBIOS type 0 fields
1855
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001856@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 +00001857Specify SMBIOS type 1 fields
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001858
1859@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}]
1860Specify SMBIOS type 2 fields
1861
1862@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1863Specify SMBIOS type 3 fields
1864
1865@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1866Specify SMBIOS type 4 fields
1867
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001868@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 -05001869Specify SMBIOS type 17 fields
aliguorib6f6e3d2009-04-17 18:59:56 +00001870ETEXI
1871
blueswir15824d652009-03-28 06:44:27 +00001872STEXI
1873@end table
1874ETEXI
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001875DEFHEADING()
blueswir15824d652009-03-28 06:44:27 +00001876
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001877DEFHEADING(Network options:)
blueswir15824d652009-03-28 06:44:27 +00001878STEXI
1879@table @option
1880ETEXI
1881
Jan Kiszkaad196a92009-06-24 14:42:28 +02001882HXCOMM Legacy slirp options (now moved to -net user):
1883#ifdef CONFIG_SLIRP
Blue Swirlad960902010-03-29 19:23:52 +00001884DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1885DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1886DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001887#ifndef _WIN32
Blue Swirlad960902010-03-29 19:23:52 +00001888DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001889#endif
1890#endif
1891
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001892DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
blueswir15824d652009-03-28 06:44:27 +00001893#ifdef CONFIG_SLIRP
Samuel Thibault0b11c032016-03-20 12:29:54 +01001894 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1895 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1896 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
Benjamin Drungf18d1372018-02-27 17:06:01 +01001897 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
1898 " [,tftp=dir][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001899#ifndef _WIN32
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001900 "[,smb=dir[,smbserver=addr]]\n"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001901#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001902 " configure a user mode network backend with ID 'str',\n"
1903 " its DHCP server and optional services\n"
blueswir15824d652009-03-28 06:44:27 +00001904#endif
1905#ifdef _WIN32
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001906 "-netdev tap,id=str,ifname=name\n"
1907 " configure a host TAP network backend with ID 'str'\n"
blueswir15824d652009-03-28 06:44:27 +00001908#else
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001909 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001910 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001911 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001912 " [,poll-us=n]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001913 " configure a host TAP network backend with ID 'str'\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001914 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001915 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1916 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1917 " to deconfigure it\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001918 " use '[down]script=no' to disable script execution\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001919 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1920 " configure it\n"
blueswir15824d652009-03-28 06:44:27 +00001921 " use 'fd=h' to connect to an already opened TAP interface\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001922 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001923 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
Michael S. Tsirkinf157ed22011-02-01 14:25:40 +02001924 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001925 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1926 " 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 +02001927 " use vhost=on to enable experimental in kernel accelerator\n"
mst@redhat.com5430a282011-02-01 22:13:42 +02001928 " (only has effect for virtio guests which use MSIX)\n"
1929 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001930 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001931 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
Jason Wangec396012013-02-22 22:57:52 +08001932 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001933 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
1934 " spent on busy polling for vhost net\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001935 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1936 " configure a host TAP network backend with ID 'str' that is\n"
1937 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1938 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
Mark McLoughlin0df0ff62009-06-18 18:21:34 +01001939#endif
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001940#ifdef __linux__
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001941 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1942 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1943 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1944 " [,rxcookie=rxcookie][,offset=offset]\n"
1945 " configure a network backend with ID 'str' connected to\n"
1946 " an Ethernet over L2TPv3 pseudowire.\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001947 " Linux kernel 3.3+ as well as most routers can talk\n"
Michael Tokarev2f47b402014-07-24 20:10:17 +04001948 " L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001949 " VM to a router and even VM to Host. It is a nearly-universal\n"
1950 " standard (RFC3391). Note - this implementation uses static\n"
1951 " pre-configured tunnels (same as the Linux kernel).\n"
1952 " use 'src=' to specify source address\n"
1953 " use 'dst=' to specify destination address\n"
1954 " use 'udp=on' to specify udp encapsulation\n"
Gonglei39526512014-08-14 14:35:48 +08001955 " use 'srcport=' to specify source udp port\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001956 " use 'dstport=' to specify destination udp port\n"
1957 " use 'ipv6=on' to force v6\n"
1958 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1959 " well as a weak security measure\n"
1960 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1961 " use 'txcookie=0x012345678' to specify a txcookie\n"
1962 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1963 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1964 " use 'pincounter=on' to work around broken counter handling in peer\n"
1965 " use 'offset=X' to add an extra offset between header and data\n"
1966#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001967 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1968 " configure a network backend to connect to another network\n"
1969 " using a socket connection\n"
1970 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1971 " configure a network backend to connect to a multicast maddr and port\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08001972 " use 'localaddr=addr' to specify the host address to send packets from\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001973 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
1974 " configure a network backend to connect to another network\n"
1975 " using an UDP tunnel\n"
blueswir15824d652009-03-28 06:44:27 +00001976#ifdef CONFIG_VDE
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001977 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1978 " configure a network backend to connect to port 'n' of a vde switch\n"
1979 " running on host and listening for incoming connections on 'socketpath'.\n"
blueswir15824d652009-03-28 06:44:27 +00001980 " Use group 'groupname' and mode 'octalmode' to change default\n"
1981 " ownership and permissions for communication port.\n"
1982#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001983#ifdef CONFIG_NETMAP
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001984 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
Vincenzo Maffione58952132013-11-06 11:44:06 +01001985 " attach to the existing netmap-enabled network interface 'name', or to a\n"
1986 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1987 " netmap device, defaults to '/dev/netmap')\n"
1988#endif
Thomas Huth253dc142018-02-21 11:18:32 +01001989#ifdef CONFIG_POSIX
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001990 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
1991 " configure a vhost-user network, backed by a chardev 'dev'\n"
Thomas Huth253dc142018-02-21 11:18:32 +01001992#endif
Thomas Huth18d65d22018-01-15 20:50:55 +01001993 "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
Thomas Huthaf1a5c32018-04-30 20:02:23 +02001994 " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
Thomas Huth78cd6f72018-02-21 11:18:36 +01001995DEF("nic", HAS_ARG, QEMU_OPTION_nic,
1996 "--nic [tap|bridge|"
1997#ifdef CONFIG_SLIRP
1998 "user|"
1999#endif
2000#ifdef __linux__
2001 "l2tpv3|"
2002#endif
2003#ifdef CONFIG_VDE
2004 "vde|"
2005#endif
2006#ifdef CONFIG_NETMAP
2007 "netmap|"
2008#endif
2009#ifdef CONFIG_POSIX
2010 "vhost-user|"
2011#endif
2012 "socket][,option][,...][mac=macaddr]\n"
2013 " initialize an on-board / default host NIC (using MAC address\n"
2014 " macaddr) and connect it to the given host network backend\n"
2015 "--nic none use it alone to have zero network devices (the default is to\n"
2016 " provided a 'user' network connection)\n",
2017 QEMU_ARCH_ALL)
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002018DEF("net", HAS_ARG, QEMU_OPTION_net,
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002019 "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
Thomas Huth0e60a822017-12-19 16:28:55 +01002020 " configure or create an on-board (or machine default) NIC and\n"
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002021 " connect it to hub 0 (please use -nic unless you need a hub)\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002022 "-net ["
Mark McLoughlina1ea4582009-10-08 19:58:26 +01002023#ifdef CONFIG_SLIRP
2024 "user|"
2025#endif
2026 "tap|"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002027 "bridge|"
Mark McLoughlina1ea4582009-10-08 19:58:26 +01002028#ifdef CONFIG_VDE
2029 "vde|"
2030#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01002031#ifdef CONFIG_NETMAP
2032 "netmap|"
2033#endif
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002034 "socket][,option][,option][,...]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002035 " old way to initialize a host network interface\n"
2036 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002037STEXI
Thomas Huthabbbb032018-03-12 13:20:50 +01002038@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2039@findex -nic
2040This option is a shortcut for configuring both the on-board (default) guest
2041NIC hardware and the host network backend in one go. The host backend options
2042are the same as with the corresponding @option{-netdev} options below.
2043The guest NIC model can be set with @option{model=@var{modelname}}.
2044Use @option{model=help} to list the available device types.
2045The hardware MAC address can be set with @option{mac=@var{macaddr}}.
2046
2047The following two example do exactly the same, to show how @option{-nic} can
2048be used to shorten the command line length (note that the e1000 is the default
2049on i386, so the @option{model=e1000} parameter could even be omitted here, too):
2050@example
2051qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2052qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2053@end example
2054
2055@item -nic none
2056Indicate that no network devices should be configured. It is used to override
2057the default configuration (default NIC with ``user'' host network backend)
2058which is activated if no other networking options are provided.
blueswir15824d652009-03-28 06:44:27 +00002059
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002060@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01002061@findex -netdev
Thomas Huthabbbb032018-03-12 13:20:50 +01002062Configure user mode host network backend which requires no administrator
Jan Kiszkaad196a92009-06-24 14:42:28 +02002063privilege to run. Valid options are:
blueswir15824d652009-03-28 06:44:27 +00002064
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002065@table @option
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002066@item id=@var{id}
Jan Kiszkaad196a92009-06-24 14:42:28 +02002067Assign symbolic name for use in monitor commands.
2068
Thomas Huthabbbb032018-03-12 13:20:50 +01002069@item ipv4=on|off and ipv6=on|off
2070Specify that either IPv4 or IPv6 must be enabled. If neither is specified
2071both protocols are enabled.
Samuel Thibault0b11c032016-03-20 12:29:54 +01002072
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002073@item net=@var{addr}[/@var{mask}]
2074Set IP network address the guest will see. Optionally specify the netmask,
2075either in the form a.b.c.d or as number of valid top-most bits. Default is
Brad Hardsb0b36e52011-04-24 17:19:56 +1000207610.0.2.0/24.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002077
2078@item host=@var{addr}
2079Specify the guest-visible address of the host. Default is the 2nd IP in the
2080guest network, i.e. x.x.x.2.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002081
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002082@item ipv6-net=@var{addr}[/@var{int}]
2083Set IPv6 network address the guest will see (default is fec0::/64). The
2084network prefix is given in the usual hexadecimal IPv6 address
2085notation. The prefix size is optional, and is given as the number of
2086valid top-most bits (default is 64).
Yann Bordenave7aac5312016-03-15 10:31:22 +01002087
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002088@item ipv6-host=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002089Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2090the guest network, i.e. xxxx::2.
2091
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02002092@item restrict=on|off
Brad Hardscaef55e2011-06-09 07:50:43 +10002093If this option is enabled, the guest will be isolated, i.e. it will not be
Jan Kiszkaad196a92009-06-24 14:42:28 +02002094able to contact the host and no guest IP packets will be routed over the host
Brad Hardscaef55e2011-06-09 07:50:43 +10002095to the outside. This option does not affect any explicitly set forwarding rules.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002096
2097@item hostname=@var{name}
Klaus Stengel63d29602012-10-27 19:53:39 +02002098Specifies the client hostname reported by the built-in DHCP server.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002099
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002100@item dhcpstart=@var{addr}
2101Specify the first of the 16 IPs the built-in DHCP server can assign. Default
Brad Hardsb0b36e52011-04-24 17:19:56 +10002102is 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 +02002103
2104@item dns=@var{addr}
2105Specify the guest-visible address of the virtual nameserver. The address must
2106be different from the host address. Default is the 3rd IP in the guest network,
2107i.e. x.x.x.3.
2108
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002109@item ipv6-dns=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002110Specify the guest-visible address of the IPv6 virtual nameserver. The address
2111must be different from the host address. Default is the 3rd IP in the guest
2112network, i.e. xxxx::3.
2113
Klaus Stengel63d29602012-10-27 19:53:39 +02002114@item dnssearch=@var{domain}
2115Provides an entry for the domain-search list sent by the built-in
2116DHCP server. More than one domain suffix can be transmitted by specifying
2117this option multiple times. If supported, this will cause the guest to
2118automatically try to append the given domain suffix(es) in case a domain name
2119can not be resolved.
2120
2121Example:
2122@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002123qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
Klaus Stengel63d29602012-10-27 19:53:39 +02002124@end example
2125
Benjamin Drungf18d1372018-02-27 17:06:01 +01002126@item domainname=@var{domain}
2127Specifies the client domain name reported by the built-in DHCP server.
2128
Jan Kiszkaad196a92009-06-24 14:42:28 +02002129@item tftp=@var{dir}
2130When using the user mode network stack, activate a built-in TFTP
2131server. The files in @var{dir} will be exposed as the root of a TFTP server.
2132The TFTP client on the guest must be configured in binary mode (use the command
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002133@code{bin} of the Unix TFTP client).
Jan Kiszkaad196a92009-06-24 14:42:28 +02002134
2135@item bootfile=@var{file}
2136When using the user mode network stack, broadcast @var{file} as the BOOTP
2137filename. In conjunction with @option{tftp}, this can be used to network boot
2138a guest from a local directory.
2139
2140Example (using pxelinux):
2141@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002142qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
2143 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
Jan Kiszkaad196a92009-06-24 14:42:28 +02002144@end example
2145
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002146@item smb=@var{dir}[,smbserver=@var{addr}]
Jan Kiszkaad196a92009-06-24 14:42:28 +02002147When using the user mode network stack, activate a built-in SMB
2148server so that Windows OSes can access to the host files in @file{@var{dir}}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002149transparently. The IP address of the SMB server can be set to @var{addr}. By
2150default the 4th IP in the guest network is used, i.e. x.x.x.4.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002151
2152In the guest Windows OS, the line:
2153@example
215410.0.2.4 smbserver
2155@end example
2156must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2157or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2158
2159Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2160
Brade2d88302011-09-02 16:53:28 -04002161Note that a SAMBA server must be installed on the host OS.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002162
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002163@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002164Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2165the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2166@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002167given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2168be bound to a specific host interface. If no connection type is set, TCP is
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002169used. This option can be given multiple times.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002170
2171For example, to redirect host X11 connection from screen 1 to guest
2172screen 0, use the following:
2173
2174@example
2175# on the host
Thomas Huthabbbb032018-03-12 13:20:50 +01002176qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
Jan Kiszkaad196a92009-06-24 14:42:28 +02002177# this host xterm should open in the guest X11 server
2178xterm -display :1
2179@end example
2180
2181To redirect telnet connections from host port 5555 to telnet port on
2182the guest, use the following:
2183
2184@example
2185# on the host
Thomas Huthabbbb032018-03-12 13:20:50 +01002186qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
Jan Kiszkaad196a92009-06-24 14:42:28 +02002187telnet localhost 5555
2188@end example
2189
2190Then when you use on the host @code{telnet localhost 5555}, you
2191connect to the guest telnet server.
2192
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002193@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002194@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002195Forward guest TCP connections to the IP address @var{server} on port @var{port}
Alexander Grafb412eb62012-06-03 09:45:01 +02002196to the character device @var{dev} or to a program executed by @var{cmd:command}
2197which gets spawned for each connection. This option can be given multiple times.
2198
Stefan Weil43ffe612012-07-20 23:26:02 +02002199You can either use a chardev directly and have that one used throughout QEMU's
Alexander Grafb412eb62012-06-03 09:45:01 +02002200lifetime, like in the following example:
2201
2202@example
2203# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2204# the guest accesses it
Thomas Huthabbbb032018-03-12 13:20:50 +01002205qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
Alexander Grafb412eb62012-06-03 09:45:01 +02002206@end example
2207
2208Or you can execute a command on every TCP connection established by the guest,
Stefan Weil43ffe612012-07-20 23:26:02 +02002209so that QEMU behaves similar to an inetd process for that virtual server:
Alexander Grafb412eb62012-06-03 09:45:01 +02002210
2211@example
2212# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2213# and connect the TCP stream to its stdin/stdout
Thomas Huthabbbb032018-03-12 13:20:50 +01002214qemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
Alexander Grafb412eb62012-06-03 09:45:01 +02002215@end example
Jan Kiszkaad196a92009-06-24 14:42:28 +02002216
2217@end table
2218
2219Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
2220processed and applied to -net user. Mixing them with the new configuration
2221syntax gives undefined results. Their use for new applications is discouraged
2222as they will be removed from future versions.
blueswir15824d652009-03-28 06:44:27 +00002223
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002224@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
Thomas Huthabbbb032018-03-12 13:20:50 +01002225Configure a host TAP network backend with ID @var{id}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002226
2227Use the network script @var{file} to configure it and the network script
blueswir15824d652009-03-28 06:44:27 +00002228@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002229automatically provides one. The default network configure script is
2230@file{/etc/qemu-ifup} and the default network deconfigure script is
2231@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2232to disable script execution.
2233
2234If running QEMU as an unprivileged user, use the network helper
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002235@var{helper} to configure the TAP interface and attach it to the bridge.
2236The default network helper executable is @file{/path/to/qemu-bridge-helper}
2237and the default bridge device is @file{br0}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002238
2239@option{fd}=@var{h} can be used to specify the handle of an already
2240opened host TAP interface.
2241
2242Examples:
blueswir15824d652009-03-28 06:44:27 +00002243
2244@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002245#launch a QEMU instance with the default network script
Thomas Huthabbbb032018-03-12 13:20:50 +01002246qemu-system-i386 linux.img -nic tap
blueswir15824d652009-03-28 06:44:27 +00002247@end example
2248
blueswir15824d652009-03-28 06:44:27 +00002249@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002250#launch a QEMU instance with two NICs, each one connected
2251#to a TAP device
Stefan Weil3804da92012-05-11 22:21:50 +02002252qemu-system-i386 linux.img \
Thomas Huth74f78b92018-01-15 08:40:17 +01002253 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2254 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
blueswir15824d652009-03-28 06:44:27 +00002255@end example
2256
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002257@example
2258#launch a QEMU instance with the default network helper to
2259#connect a TAP device to bridge br0
Thomas Huthabbbb032018-03-12 13:20:50 +01002260qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
2261 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002262@end example
2263
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002264@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002265Connect a host TAP network interface to a host bridge device.
2266
2267Use the network helper @var{helper} to configure the TAP interface and
2268attach it to the bridge. The default network helper executable is
Amos Kong420508f2013-10-23 04:49:28 +08002269@file{/path/to/qemu-bridge-helper} and the default bridge
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002270device is @file{br0}.
2271
2272Examples:
2273
2274@example
2275#launch a QEMU instance with the default network helper to
2276#connect a TAP device to bridge br0
Thomas Huthabbbb032018-03-12 13:20:50 +01002277qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002278@end example
2279
2280@example
2281#launch a QEMU instance with the default network helper to
2282#connect a TAP device to bridge qemubr0
Thomas Huthabbbb032018-03-12 13:20:50 +01002283qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002284@end example
2285
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002286@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
blueswir15824d652009-03-28 06:44:27 +00002287
Thomas Huthabbbb032018-03-12 13:20:50 +01002288This host network backend can be used to connect the guest's network to
2289another QEMU virtual machine using a TCP socket connection. If @option{listen}
2290is specified, QEMU waits for incoming connections on @var{port}
blueswir15824d652009-03-28 06:44:27 +00002291(@var{host} is optional). @option{connect} is used to connect to
2292another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2293specifies an already opened TCP socket.
2294
2295Example:
2296@example
2297# launch a first QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002298qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002299 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2300 -netdev socket,id=n1,listen=:1234
2301# connect the network of this instance to the network of the first instance
Stefan Weil3804da92012-05-11 22:21:50 +02002302qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002303 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2304 -netdev socket,id=n2,connect=127.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002305@end example
2306
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002307@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
blueswir15824d652009-03-28 06:44:27 +00002308
Thomas Huthabbbb032018-03-12 13:20:50 +01002309Configure a socket host network backend to share the guest's network traffic
2310with another QEMU virtual machines using a UDP multicast socket, effectively
2311making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
blueswir15824d652009-03-28 06:44:27 +00002312NOTES:
2313@enumerate
2314@item
2315Several QEMU can be running on different hosts and share same bus (assuming
2316correct multicast setup for these hosts).
2317@item
2318mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2319@url{http://user-mode-linux.sf.net}.
2320@item
2321Use @option{fd=h} to specify an already opened UDP multicast socket.
2322@end enumerate
2323
2324Example:
2325@example
2326# launch one QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002327qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002328 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2329 -netdev socket,id=n1,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002330# launch another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002331qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002332 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2333 -netdev socket,id=n2,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002334# launch yet another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002335qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002336 -device e1000,netdev=n3,macaddr=52:54:00:12:34:58 \
2337 -netdev socket,id=n3,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002338@end example
2339
2340Example (User Mode Linux compat.):
2341@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002342# launch QEMU instance (note mcast address selected is UML's default)
Stefan Weil3804da92012-05-11 22:21:50 +02002343qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002344 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2345 -netdev socket,id=n1,mcast=239.192.168.1:1102
blueswir15824d652009-03-28 06:44:27 +00002346# launch UML
2347/path/to/linux ubd0=/path/to/root_fs eth0=mcast
2348@end example
2349
Mike Ryan3a75e742010-12-01 11:16:47 -08002350Example (send packets from host's 1.2.3.4):
2351@example
Stefan Weil3804da92012-05-11 22:21:50 +02002352qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002353 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2354 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
Mike Ryan3a75e742010-12-01 11:16:47 -08002355@end example
2356
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002357@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}]
Thomas Huthabbbb032018-03-12 13:20:50 +01002358Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
2359popular protocol to transport Ethernet (and other Layer 2) data frames between
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002360two systems. It is present in routers, firewalls and the Linux kernel
2361(from version 3.3 onwards).
2362
2363This transport allows a VM to communicate to another VM, router or firewall directly.
2364
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002365@table @option
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002366@item src=@var{srcaddr}
2367 source address (mandatory)
2368@item dst=@var{dstaddr}
2369 destination address (mandatory)
2370@item udp
2371 select udp encapsulation (default is ip).
2372@item srcport=@var{srcport}
2373 source udp port.
2374@item dstport=@var{dstport}
2375 destination udp port.
2376@item ipv6
2377 force v6, otherwise defaults to v4.
2378@item rxcookie=@var{rxcookie}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002379@itemx txcookie=@var{txcookie}
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002380 Cookies are a weak form of security in the l2tpv3 specification.
2381Their function is mostly to prevent misconfiguration. By default they are 32
2382bit.
2383@item cookie64
2384 Set cookie size to 64 bit instead of the default 32
2385@item counter=off
2386 Force a 'cut-down' L2TPv3 with no counter as in
2387draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2388@item pincounter=on
2389 Work around broken counter handling in peer. This may also help on
2390networks which have packet reorder.
2391@item offset=@var{offset}
2392 Add an extra offset between header and data
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002393@end table
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002394
2395For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2396on the remote Linux host 1.2.3.4:
2397@example
2398# Setup tunnel on linux host using raw ip as encapsulation
2399# on 1.2.3.4
2400ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2401 encap udp udp_sport 16384 udp_dport 16384
2402ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2403 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2404ifconfig vmtunnel0 mtu 1500
2405ifconfig vmtunnel0 up
2406brctl addif br-lan vmtunnel0
2407
2408
2409# on 4.3.2.1
2410# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2411
Thomas Huthabbbb032018-03-12 13:20:50 +01002412qemu-system-i386 linux.img -device e1000,netdev=n1 \
2413 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002414
2415@end example
2416
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002417@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
Thomas Huthabbbb032018-03-12 13:20:50 +01002418Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
blueswir15824d652009-03-28 06:44:27 +00002419listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2420and MODE @var{octalmode} to change default ownership and permissions for
Stefan Weilc1ba4e02011-09-05 18:13:03 +02002421communication port. This option is only available if QEMU has been compiled
blueswir15824d652009-03-28 06:44:27 +00002422with vde support enabled.
2423
2424Example:
2425@example
2426# launch vde switch
2427vde_switch -F -sock /tmp/myswitch
2428# launch QEMU instance
Thomas Huthabbbb032018-03-12 13:20:50 +01002429qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
blueswir15824d652009-03-28 06:44:27 +00002430@end example
2431
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002432@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002433
2434Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2435be a unix domain socket backed one. The vhost-user uses a specifically defined
2436protocol to pass vhost ioctl replacement messages to an application on the other
2437end of the socket. On non-MSIX guests, the feature can be forced with
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002438@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2439be created for multiqueue vhost-user.
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002440
2441Example:
2442@example
2443qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2444 -numa node,memdev=mem \
Vincenzo Maffione79cad2f2017-02-20 17:45:09 +01002445 -chardev socket,id=chr0,path=/path/to/socket \
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002446 -netdev type=vhost-user,id=net0,chardev=chr0 \
2447 -device virtio-net-pci,netdev=net0
2448@end example
2449
Thomas Huthabbbb032018-03-12 13:20:50 +01002450@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
Thomas Huth78cd6f72018-02-21 11:18:36 +01002451
Thomas Huthabbbb032018-03-12 13:20:50 +01002452Create a hub port on the emulated hub with ID @var{hubid}.
Thomas Huth78cd6f72018-02-21 11:18:36 +01002453
Thomas Huthabbbb032018-03-12 13:20:50 +01002454The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002455single netdev. Alternatively, you can also connect the hubport to another
2456netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
Thomas Huthabbbb032018-03-12 13:20:50 +01002457
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002458@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
Thomas Huthabbbb032018-03-12 13:20:50 +01002459@findex -net
2460Legacy option to configure or create an on-board (or machine default) Network
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002461Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
2462the default hub), or to the netdev @var{nd}.
Thomas Huthabbbb032018-03-12 13:20:50 +01002463The NIC is an e1000 by default on the PC target. Optionally, the MAC address
2464can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
2465only), and a @var{name} can be assigned for use in monitor commands.
2466Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2467that the card should have; this option currently only affects virtio cards; set
2468@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2469NIC is created. QEMU can emulate several different models of network card.
2470Use @code{-net nic,model=help} for a list of available devices for your target.
2471
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002472@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
Thomas Huthabbbb032018-03-12 13:20:50 +01002473Configure a host network backend (with the options corresponding to the same
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002474@option{-netdev} option) and connect it to the emulated hub 0 (the default
2475hub). Use @var{name} to specify the name of the hub port.
blueswir15824d652009-03-28 06:44:27 +00002476ETEXI
2477
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002478STEXI
2479@end table
2480ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002481DEFHEADING()
2482
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002483DEFHEADING(Character device options:)
Matthew Booth7273a2d2009-10-30 13:41:12 +00002484
2485DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
Lin Ma517b3d42016-08-17 01:13:52 +08002486 "-chardev help\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002487 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Corey Minyard5dd1f022014-10-02 11:17:37 -05002488 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002489 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n"
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002490 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002491 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n"
2492 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002493 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02002494 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002495 " [,logfile=PATH][,logappend=on|off]\n"
2496 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002497 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002498 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2499 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2500 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2501 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002502#ifdef _WIN32
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002503 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2504 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002505#else
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002506 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2507 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002508#endif
2509#ifdef CONFIG_BRLAPI
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002510 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002511#endif
2512#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2513 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002514 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2515 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002516#endif
2517#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002518 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2519 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002520#endif
Alon Levycbcc6332011-01-19 10:49:50 +02002521#if defined(CONFIG_SPICE)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002522 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2523 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
Alon Levycbcc6332011-01-19 10:49:50 +02002524#endif
Blue Swirlad960902010-03-29 19:23:52 +00002525 , QEMU_ARCH_ALL
Matthew Booth7273a2d2009-10-30 13:41:12 +00002526)
2527
2528STEXI
Markus Armbrusterdddba062017-10-02 16:03:06 +02002529
2530The general form of a character device option is:
2531@table @option
Thomas Huth16fdc562018-01-30 10:36:21 +01002532@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002533@findex -chardev
Matthew Booth7273a2d2009-10-30 13:41:12 +00002534Backend is one of:
2535@option{null},
2536@option{socket},
2537@option{udp},
2538@option{msmouse},
2539@option{vc},
Markus Armbruster4f573782013-07-26 16:44:32 +02002540@option{ringbuf},
Matthew Booth7273a2d2009-10-30 13:41:12 +00002541@option{file},
2542@option{pipe},
2543@option{console},
2544@option{serial},
2545@option{pty},
2546@option{stdio},
2547@option{braille},
2548@option{tty},
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002549@option{parallel},
Alon Levycbcc6332011-01-19 10:49:50 +02002550@option{parport},
Thomas Huth16fdc562018-01-30 10:36:21 +01002551@option{spicevmc},
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002552@option{spiceport}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002553The specific backend will determine the applicable options.
2554
Markus Armbrusterdddba062017-10-02 16:03:06 +02002555Use @code{-chardev help} to print all available chardev backend types.
Lin Ma517b3d42016-08-17 01:13:52 +08002556
Matthew Booth7273a2d2009-10-30 13:41:12 +00002557All devices must have an id, which can be any string up to 127 characters long.
2558It is used to uniquely identify this device in other command line directives.
2559
Jan Kiszka97331282010-04-06 16:55:54 +02002560A character device may be used in multiplexing mode by multiple front-ends.
Peter Maydella40db1b2016-02-16 17:28:58 +00002561Specify @option{mux=on} to enable this mode.
2562A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2563backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2564If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2565create a multiplexer with your specified ID, and you can then configure multiple
2566front ends to use that chardev ID for their input/output. Up to four different
2567front ends can be connected to a single multiplexed chardev. (Without
2568multiplexing enabled, a chardev can only be used by a single front end.)
2569For instance you could use this to allow a single stdio chardev to be used by
2570two serial ports and the QEMU monitor:
2571
2572@example
2573-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002574-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002575-serial chardev:char0 \
2576-serial chardev:char0
2577@end example
2578
2579You can have more than one multiplexer in a system configuration; for instance
2580you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2581multiplexed between the QEMU monitor and a parallel port:
2582
2583@example
2584-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002585-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002586-parallel chardev:char0 \
2587-chardev tcp,...,mux=on,id=char1 \
2588-serial chardev:char1 \
2589-serial chardev:char1
2590@end example
2591
2592When you're using a multiplexed character device, some escape sequences are
2593interpreted in the input. @xref{mux_keys, Keys in the character backend
2594multiplexer}.
2595
2596Note that some other command line options may implicitly create multiplexed
2597character backends; for instance @option{-serial mon:stdio} creates a
2598multiplexed stdio backend connected to the serial port and the QEMU monitor,
2599and @option{-nographic} also multiplexes the console and the monitor to
2600stdio.
2601
2602There is currently no support for multiplexing in the other direction
2603(where a single QEMU front end takes input and output from multiple chardevs).
Jan Kiszka97331282010-04-06 16:55:54 +02002604
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002605Every backend supports the @option{logfile} option, which supplies the path
2606to a file to record all data transmitted via the backend. The @option{logappend}
2607option controls whether the log file will be truncated or appended to when
2608opened.
2609
Markus Armbrusterdddba062017-10-02 16:03:06 +02002610@end table
Matthew Booth7273a2d2009-10-30 13:41:12 +00002611
Markus Armbrusterdddba062017-10-02 16:03:06 +02002612The available backends are:
2613
2614@table @option
Thomas Huth16fdc562018-01-30 10:36:21 +01002615@item -chardev null,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002616A void device. This device will not emit any data, and will drop any data it
2617receives. The null backend does not take any options.
2618
Thomas Huth16fdc562018-01-30 10:36:21 +01002619@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 +00002620
2621Create a two-way stream socket, which can be either a TCP or a unix socket. A
2622unix socket will be created if @option{path} is specified. Behaviour is
2623undefined if TCP options are specified for a unix socket.
2624
2625@option{server} specifies that the socket shall be a listening socket.
2626
2627@option{nowait} specifies that QEMU should not block waiting for a client to
2628connect to a listening socket.
2629
2630@option{telnet} specifies that traffic on the socket should interpret telnet
2631escape sequences.
2632
Corey Minyard5dd1f022014-10-02 11:17:37 -05002633@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2634the remote end goes away. qemu will delay this many seconds and then attempt
2635to reconnect. Zero disables reconnecting, and is the default.
2636
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002637@option{tls-creds} requests enablement of the TLS protocol for encryption,
2638and specifies the id of the TLS credentials to use for the handshake. The
2639credentials must be previously created with the @option{-object tls-creds}
2640argument.
2641
Matthew Booth7273a2d2009-10-30 13:41:12 +00002642TCP and unix socket options are given below:
2643
2644@table @option
2645
Thomas Huth16fdc562018-01-30 10:36:21 +01002646@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002647
2648@option{host} for a listening socket specifies the local address to be bound.
2649For a connecting socket species the remote host to connect to. @option{host} is
2650optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2651
2652@option{port} for a listening socket specifies the local port to be bound. For a
2653connecting socket specifies the port on the remote host to connect to.
2654@option{port} can be given as either a port number or a service name.
2655@option{port} is required.
2656
2657@option{to} is only relevant to listening sockets. If it is specified, and
2658@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2659to and including @option{to} until it succeeds. @option{to} must be specified
2660as a port number.
2661
2662@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2663If neither is specified the socket may use either protocol.
2664
2665@option{nodelay} disables the Nagle algorithm.
2666
2667@item unix options: path=@var{path}
2668
2669@option{path} specifies the local path of the unix socket. @option{path} is
2670required.
2671
2672@end table
2673
Thomas Huth16fdc562018-01-30 10:36:21 +01002674@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002675
2676Sends all traffic from the guest to a remote host over UDP.
2677
2678@option{host} specifies the remote host to connect to. If not specified it
2679defaults to @code{localhost}.
2680
2681@option{port} specifies the port on the remote host to connect to. @option{port}
2682is required.
2683
2684@option{localaddr} specifies the local address to bind to. If not specified it
2685defaults to @code{0.0.0.0}.
2686
2687@option{localport} specifies the local port to bind to. If not specified any
2688available local port will be used.
2689
2690@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2691If neither is specified the device may use either protocol.
2692
Thomas Huth16fdc562018-01-30 10:36:21 +01002693@item -chardev msmouse,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002694
2695Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2696take any options.
2697
Thomas Huth16fdc562018-01-30 10:36:21 +01002698@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002699
2700Connect to a QEMU text console. @option{vc} may optionally be given a specific
2701size.
2702
2703@option{width} and @option{height} specify the width and height respectively of
2704the console, in pixels.
2705
2706@option{cols} and @option{rows} specify that the console be sized to fit a text
2707console with the given dimensions.
2708
Thomas Huth16fdc562018-01-30 10:36:21 +01002709@item -chardev ringbuf,id=@var{id}[,size=@var{size}]
Lei Li51767e72013-01-25 00:03:19 +08002710
Markus Armbruster3949e592013-02-06 21:27:24 +01002711Create a ring buffer with fixed size @option{size}.
Stefan Hajnoczie69f7d22016-09-19 11:56:26 +01002712@var{size} must be a power of two and defaults to @code{64K}.
Lei Li51767e72013-01-25 00:03:19 +08002713
Thomas Huth16fdc562018-01-30 10:36:21 +01002714@item -chardev file,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002715
2716Log all traffic received from the guest to a file.
2717
2718@option{path} specifies the path of the file to be opened. This file will be
2719created if it does not already exist, and overwritten if it does. @option{path}
2720is required.
2721
Thomas Huth16fdc562018-01-30 10:36:21 +01002722@item -chardev pipe,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002723
2724Create a two-way connection to the guest. The behaviour differs slightly between
2725Windows hosts and other hosts:
2726
2727On Windows, a single duplex pipe will be created at
2728@file{\\.pipe\@option{path}}.
2729
2730On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2731@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2732received by the guest. Data written by the guest can be read from
2733@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2734be present.
2735
2736@option{path} forms part of the pipe path as described above. @option{path} is
2737required.
2738
Thomas Huth16fdc562018-01-30 10:36:21 +01002739@item -chardev console,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002740
2741Send traffic from the guest to QEMU's standard output. @option{console} does not
2742take any options.
2743
2744@option{console} is only available on Windows hosts.
2745
Thomas Huth16fdc562018-01-30 10:36:21 +01002746@item -chardev serial,id=@var{id},path=@option{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002747
2748Send traffic from the guest to a serial device on the host.
2749
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01002750On Unix hosts serial will actually accept any tty device,
2751not only serial lines.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002752
2753@option{path} specifies the name of the serial device to open.
2754
Thomas Huth16fdc562018-01-30 10:36:21 +01002755@item -chardev pty,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002756
2757Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2758not take any options.
2759
2760@option{pty} is not available on Windows hosts.
2761
Thomas Huth16fdc562018-01-30 10:36:21 +01002762@item -chardev stdio,id=@var{id}[,signal=on|off]
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002763Connect to standard input and standard output of the QEMU process.
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002764
2765@option{signal} controls if signals are enabled on the terminal, that includes
2766exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2767default, use @option{signal=off} to disable it.
2768
Thomas Huth16fdc562018-01-30 10:36:21 +01002769@item -chardev braille,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002770
2771Connect to a local BrlAPI server. @option{braille} does not take any options.
2772
Thomas Huth16fdc562018-01-30 10:36:21 +01002773@item -chardev tty,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002774
Matthew Booth7273a2d2009-10-30 13:41:12 +00002775@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
Markus Armbrusterd037d6b2013-02-13 15:54:15 +01002776DragonFlyBSD hosts. It is an alias for @option{serial}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002777
2778@option{path} specifies the path to the tty. @option{path} is required.
2779
Thomas Huth16fdc562018-01-30 10:36:21 +01002780@item -chardev parallel,id=@var{id},path=@var{path}
2781@itemx -chardev parport,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002782
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002783@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002784
2785Connect to a local parallel port.
2786
2787@option{path} specifies the path to the parallel port device. @option{path} is
2788required.
2789
Thomas Huth16fdc562018-01-30 10:36:21 +01002790@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
Alon Levycbcc6332011-01-19 10:49:50 +02002791
Stefan Hajnoczi3a846902011-10-06 11:24:12 +01002792@option{spicevmc} is only available when spice support is built in.
2793
Alon Levycbcc6332011-01-19 10:49:50 +02002794@option{debug} debug level for spicevmc
2795
2796@option{name} name of spice channel to connect to
2797
2798Connect to a spice virtual machine channel, such as vdiport.
Alon Levycbcc6332011-01-19 10:49:50 +02002799
Thomas Huth16fdc562018-01-30 10:36:21 +01002800@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002801
2802@option{spiceport} is only available when spice support is built in.
2803
2804@option{debug} debug level for spicevmc
2805
2806@option{name} name of spice port to connect to
2807
2808Connect to a spice port, allowing a Spice client to handle the traffic
2809identified by a name (preferably a fqdn).
Matthew Booth7273a2d2009-10-30 13:41:12 +00002810ETEXI
2811
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002812STEXI
2813@end table
2814ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002815DEFHEADING()
2816
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002817DEFHEADING(Bluetooth(R) options:)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002818STEXI
2819@table @option
2820ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002821
blueswir15824d652009-03-28 06:44:27 +00002822DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
blueswir15824d652009-03-28 06:44:27 +00002823 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2824 "-bt hci,host[:id]\n" \
2825 " use host's HCI with the given name\n" \
2826 "-bt hci[,vlan=n]\n" \
2827 " emulate a standard HCI in virtual scatternet 'n'\n" \
2828 "-bt vhci[,vlan=n]\n" \
2829 " add host computer to virtual scatternet 'n' using VHCI\n" \
2830 "-bt device:dev[,vlan=n]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00002831 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2832 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002833STEXI
blueswir15824d652009-03-28 06:44:27 +00002834@item -bt hci[...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002835@findex -bt
blueswir15824d652009-03-28 06:44:27 +00002836Defines the function of the corresponding Bluetooth HCI. -bt options
2837are matched with the HCIs present in the chosen machine type. For
2838example when emulating a machine with only one HCI built into it, only
2839the first @code{-bt hci[...]} option is valid and defines the HCI's
2840logic. The Transport Layer is decided by the machine type. Currently
2841the machines @code{n800} and @code{n810} have one HCI and all other
2842machines have none.
2843
2844@anchor{bt-hcis}
2845The following three types are recognized:
2846
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002847@table @option
blueswir15824d652009-03-28 06:44:27 +00002848@item -bt hci,null
2849(default) The corresponding Bluetooth HCI assumes no internal logic
2850and will not respond to any HCI commands or emit events.
2851
2852@item -bt hci,host[:@var{id}]
2853(@code{bluez} only) The corresponding HCI passes commands / events
2854to / from the physical HCI identified by the name @var{id} (default:
2855@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2856capable systems like Linux.
2857
2858@item -bt hci[,vlan=@var{n}]
2859Add a virtual, standard HCI that will participate in the Bluetooth
2860scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2861VLANs, devices inside a bluetooth network @var{n} can only communicate
2862with other devices in the same network (scatternet).
2863@end table
2864
2865@item -bt vhci[,vlan=@var{n}]
2866(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2867to the host bluetooth stack instead of to the emulated target. This
2868allows the host and target machines to participate in a common scatternet
2869and communicate. Requires the Linux @code{vhci} driver installed. Can
2870be used as following:
2871
2872@example
Stefan Weil3804da92012-05-11 22:21:50 +02002873qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
blueswir15824d652009-03-28 06:44:27 +00002874@end example
2875
2876@item -bt device:@var{dev}[,vlan=@var{n}]
2877Emulate a bluetooth device @var{dev} and place it in network @var{n}
2878(default @code{0}). QEMU can only emulate one type of bluetooth devices
2879currently:
2880
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002881@table @option
blueswir15824d652009-03-28 06:44:27 +00002882@item keyboard
2883Virtual wireless keyboard implementing the HIDP bluetooth profile.
2884@end table
blueswir15824d652009-03-28 06:44:27 +00002885ETEXI
2886
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002887STEXI
2888@end table
2889ETEXI
blueswir15824d652009-03-28 06:44:27 +00002890DEFHEADING()
2891
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002892#ifdef CONFIG_TPM
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002893DEFHEADING(TPM device options:)
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002894
2895DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
Stefan Berger92dcc232013-02-27 12:47:54 -05002896 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2897 " use path to provide path to a character device; default is /dev/tpm0\n"
2898 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
Amarnath Vallurif4ede812017-09-29 14:10:20 +03002899 " not provided it will be searched for in /sys/class/misc/tpm?/device\n"
2900 "-tpmdev emulator,id=id,chardev=dev\n"
2901 " configure the TPM device using chardev backend\n",
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002902 QEMU_ARCH_ALL)
2903STEXI
2904
2905The general form of a TPM device option is:
2906@table @option
2907
Thomas Huth16fdc562018-01-30 10:36:21 +01002908@item -tpmdev @var{backend},id=@var{id}[,@var{options}]
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002909@findex -tpmdev
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002910
2911The specific backend type will determine the applicable options.
Corey Bryant28c4fa32013-03-20 12:34:49 -04002912The @code{-tpmdev} option creates the TPM backend and requires a
2913@code{-device} option that specifies the TPM frontend interface model.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002914
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002915Use @code{-tpmdev help} to print all available TPM backend types.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002916
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002917@end table
2918
2919The available backends are:
2920
2921@table @option
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002922
Thomas Huth16fdc562018-01-30 10:36:21 +01002923@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
Stefan Berger4549a8b2013-02-27 12:47:53 -05002924
2925(Linux-host only) Enable access to the host's TPM using the passthrough
2926driver.
2927
2928@option{path} specifies the path to the host's TPM device, i.e., on
2929a Linux host this would be @code{/dev/tpm0}.
2930@option{path} is optional and by default @code{/dev/tpm0} is used.
2931
Stefan Berger92dcc232013-02-27 12:47:54 -05002932@option{cancel-path} specifies the path to the host TPM device's sysfs
2933entry allowing for cancellation of an ongoing TPM command.
2934@option{cancel-path} is optional and by default QEMU will search for the
2935sysfs entry to use.
2936
Stefan Berger4549a8b2013-02-27 12:47:53 -05002937Some notes about using the host's TPM with the passthrough driver:
2938
2939The TPM device accessed by the passthrough driver must not be
2940used by any other application on the host.
2941
2942Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2943the VM's firmware (BIOS/UEFI) will not be able to initialize the
2944TPM again and may therefore not show a TPM-specific menu that would
2945otherwise allow the user to configure the TPM, e.g., allow the user to
2946enable/disable or activate/deactivate the TPM.
2947Further, if TPM ownership is released from within a VM then the host's TPM
2948will get disabled and deactivated. To enable and activate the
2949TPM again afterwards, the host has to be rebooted and the user is
2950required to enter the firmware's menu to enable and activate the TPM.
2951If the TPM is left disabled and/or deactivated most TPM commands will fail.
2952
2953To create a passthrough TPM use the following two options:
2954@example
2955-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2956@end example
2957Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2958@code{tpmdev=tpm0} in the device option.
2959
Thomas Huth16fdc562018-01-30 10:36:21 +01002960@item -tpmdev emulator,id=@var{id},chardev=@var{dev}
Amarnath Vallurif4ede812017-09-29 14:10:20 +03002961
2962(Linux-host only) Enable access to a TPM emulator using Unix domain socket based
2963chardev backend.
2964
2965@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
2966
2967To create a TPM emulator backend device with chardev socket backend:
2968@example
2969
2970-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2971
2972@end example
2973
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002974ETEXI
2975
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002976STEXI
2977@end table
2978ETEXI
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002979DEFHEADING()
2980
2981#endif
2982
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002983DEFHEADING(Linux/Multiboot boot specific:)
blueswir15824d652009-03-28 06:44:27 +00002984STEXI
Alexander Graf7677f052009-06-28 16:55:55 +02002985
2986When using these options, you can use a given Linux or Multiboot
2987kernel without installing it in the disk image. It can be useful
blueswir15824d652009-03-28 06:44:27 +00002988for easier testing of various kernels.
2989
2990@table @option
2991ETEXI
2992
2993DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
Blue Swirlad960902010-03-29 19:23:52 +00002994 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002995STEXI
2996@item -kernel @var{bzImage}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002997@findex -kernel
Alexander Graf7677f052009-06-28 16:55:55 +02002998Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2999or in multiboot format.
blueswir15824d652009-03-28 06:44:27 +00003000ETEXI
3001
3002DEF("append", HAS_ARG, QEMU_OPTION_append, \
Blue Swirlad960902010-03-29 19:23:52 +00003003 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003004STEXI
3005@item -append @var{cmdline}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003006@findex -append
blueswir15824d652009-03-28 06:44:27 +00003007Use @var{cmdline} as kernel command line
3008ETEXI
3009
3010DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
Blue Swirlad960902010-03-29 19:23:52 +00003011 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003012STEXI
3013@item -initrd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003014@findex -initrd
blueswir15824d652009-03-28 06:44:27 +00003015Use @var{file} as initial ram disk.
Alexander Graf7677f052009-06-28 16:55:55 +02003016
3017@item -initrd "@var{file1} arg=foo,@var{file2}"
3018
3019This syntax is only available with multiboot.
3020
3021Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3022first module.
blueswir15824d652009-03-28 06:44:27 +00003023ETEXI
3024
Grant Likely412beee2012-03-02 11:56:38 +00003025DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
Peter A. G. Crosthwaite379b5c72012-03-04 21:03:54 +10003026 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
Grant Likely412beee2012-03-02 11:56:38 +00003027STEXI
3028@item -dtb @var{file}
3029@findex -dtb
3030Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3031on boot.
3032ETEXI
3033
blueswir15824d652009-03-28 06:44:27 +00003034STEXI
3035@end table
3036ETEXI
blueswir15824d652009-03-28 06:44:27 +00003037DEFHEADING()
3038
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003039DEFHEADING(Debug/Expert options:)
blueswir15824d652009-03-28 06:44:27 +00003040STEXI
3041@table @option
3042ETEXI
3043
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003044DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3045 "-fw_cfg [name=]<name>,file=<file>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003046 " add named fw_cfg entry with contents from file\n"
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003047 "-fw_cfg [name=]<name>,string=<str>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003048 " add named fw_cfg entry with contents from string\n",
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003049 QEMU_ARCH_ALL)
3050STEXI
Markus Armbruster63d31452016-04-18 18:29:50 +02003051
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003052@item -fw_cfg [name=]@var{name},file=@var{file}
3053@findex -fw_cfg
Markus Armbruster63d31452016-04-18 18:29:50 +02003054Add named fw_cfg entry with contents from file @var{file}.
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003055
3056@item -fw_cfg [name=]@var{name},string=@var{str}
Markus Armbruster63d31452016-04-18 18:29:50 +02003057Add named fw_cfg entry with contents from string @var{str}.
3058
3059The terminating NUL character of the contents of @var{str} will not be
3060included as part of the fw_cfg item data. To insert contents with
3061embedded NUL characters, you have to use the @var{file} parameter.
3062
3063The fw_cfg entries are passed by QEMU through to the guest.
3064
3065Example:
3066@example
3067 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3068@end example
3069creates an fw_cfg entry named opt/com.mycompany/blob with contents
3070from ./my_blob.bin.
3071
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003072ETEXI
3073
blueswir15824d652009-03-28 06:44:27 +00003074DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
Blue Swirlad960902010-03-29 19:23:52 +00003075 "-serial dev redirect the serial port to char device 'dev'\n",
3076 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003077STEXI
3078@item -serial @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003079@findex -serial
blueswir15824d652009-03-28 06:44:27 +00003080Redirect the virtual serial port to host character device
3081@var{dev}. The default device is @code{vc} in graphical mode and
3082@code{stdio} in non graphical mode.
3083
3084This option can be used several times to simulate up to 4 serial
3085ports.
3086
3087Use @code{-serial none} to disable all serial ports.
3088
3089Available character devices are:
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003090@table @option
Kevin Wolf4e257e52009-10-09 10:58:36 +02003091@item vc[:@var{W}x@var{H}]
blueswir15824d652009-03-28 06:44:27 +00003092Virtual console. Optionally, a width and height can be given in pixel with
3093@example
3094vc:800x600
3095@end example
3096It is also possible to specify width or height in characters:
3097@example
3098vc:80Cx24C
3099@end example
3100@item pty
3101[Linux only] Pseudo TTY (a new PTY is automatically allocated)
3102@item none
3103No device is allocated.
3104@item null
3105void device
Ingo van Lil88e020e2013-12-20 14:44:53 +01003106@item chardev:@var{id}
3107Use a named character device defined with the @code{-chardev} option.
blueswir15824d652009-03-28 06:44:27 +00003108@item /dev/XXX
3109[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3110parameters are set according to the emulated ones.
3111@item /dev/parport@var{N}
3112[Linux only, parallel port only] Use host parallel port
3113@var{N}. Currently SPP and EPP parallel port features can be used.
3114@item file:@var{filename}
3115Write output to @var{filename}. No character can be read.
3116@item stdio
3117[Unix only] standard input/output
3118@item pipe:@var{filename}
3119name pipe @var{filename}
3120@item COM@var{n}
3121[Windows only] Use host serial port @var{n}
3122@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3123This implements UDP Net Console.
3124When @var{remote_host} or @var{src_ip} are not specified
3125they default to @code{0.0.0.0}.
3126When not using a specified @var{src_port} a random port is automatically chosen.
blueswir15824d652009-03-28 06:44:27 +00003127
3128If you just want a simple readonly console you can use @code{netcat} or
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003129@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3130@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
blueswir15824d652009-03-28 06:44:27 +00003131will appear in the netconsole session.
3132
3133If you plan to send characters back via netconsole or you want to stop
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003134and start QEMU a lot of times, you should have QEMU use the same
blueswir15824d652009-03-28 06:44:27 +00003135source port each time by using something like @code{-serial
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003136udp::4555@@:4556} to QEMU. Another approach is to use a patched
blueswir15824d652009-03-28 06:44:27 +00003137version of netcat which can listen to a TCP port and send and receive
3138characters via udp. If you have a patched version of netcat which
3139activates telnet remote echo and single char transfer, then you can
Marc-André Lureaubd1caa32016-12-22 18:56:38 +04003140use the following options to set up a netcat redirector to allow
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003141telnet on port 5555 to access the QEMU port.
blueswir15824d652009-03-28 06:44:27 +00003142@table @code
Stefan Weil071c9392012-04-07 09:23:36 +02003143@item QEMU Options:
blueswir15824d652009-03-28 06:44:27 +00003144-serial udp::4555@@:4556
3145@item netcat options:
3146-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3147@item telnet options:
3148localhost 5555
3149@end table
3150
Corey Minyard5dd1f022014-10-02 11:17:37 -05003151@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003152The TCP Net Console has two modes of operation. It can send the serial
3153I/O to a location or wait for a connection from a location. By default
3154the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3155the @var{server} option QEMU will wait for a client socket application
3156to connect to the port before continuing, unless the @code{nowait}
3157option was specified. The @code{nodelay} option disables the Nagle buffering
Corey Minyard5dd1f022014-10-02 11:17:37 -05003158algorithm. The @code{reconnect} option only applies if @var{noserver} is
3159set, if the connection goes down it will attempt to reconnect at the
3160given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
blueswir15824d652009-03-28 06:44:27 +00003161one TCP connection at a time is accepted. You can use @code{telnet} to
3162connect to the corresponding character device.
3163@table @code
3164@item Example to send tcp console to 192.168.0.2 port 4444
3165-serial tcp:192.168.0.2:4444
3166@item Example to listen and wait on port 4444 for connection
3167-serial tcp::4444,server
3168@item Example to not wait and listen on ip 192.168.0.100 port 4444
3169-serial tcp:192.168.0.100:4444,server,nowait
3170@end table
3171
3172@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3173The telnet protocol is used instead of raw tcp sockets. The options
3174work the same as if you had specified @code{-serial tcp}. The
3175difference is that the port acts like a telnet server or client using
3176telnet option negotiation. This will also allow you to send the
3177MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3178sequence. Typically in unix telnet you do it with Control-] and then
3179type "send break" followed by pressing the enter key.
3180
Corey Minyard5dd1f022014-10-02 11:17:37 -05003181@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003182A unix domain socket is used instead of a tcp socket. The option works the
3183same as if you had specified @code{-serial tcp} except the unix domain socket
3184@var{path} is used for connections.
3185
3186@item mon:@var{dev_string}
3187This is a special option to allow the monitor to be multiplexed onto
3188another serial port. The monitor is accessed with key sequence of
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +04003189@key{Control-a} and then pressing @key{c}.
blueswir15824d652009-03-28 06:44:27 +00003190@var{dev_string} should be any one of the serial devices specified
3191above. An example to multiplex the monitor onto a telnet server
3192listening on port 4444 would be:
3193@table @code
3194@item -serial mon:telnet::4444,server,nowait
3195@end table
Michael Tokarevbe022d62013-07-11 12:55:50 +04003196When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3197QEMU any more but will be passed to the guest instead.
blueswir15824d652009-03-28 06:44:27 +00003198
3199@item braille
3200Braille device. This will use BrlAPI to display the braille output on a real
3201or fake device.
3202
Kevin Wolfbe8b28a2009-10-09 10:58:37 +02003203@item msmouse
3204Three button serial mouse. Configure the guest to use Microsoft protocol.
blueswir15824d652009-03-28 06:44:27 +00003205@end table
3206ETEXI
3207
3208DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
Blue Swirlad960902010-03-29 19:23:52 +00003209 "-parallel dev redirect the parallel port to char device 'dev'\n",
3210 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003211STEXI
3212@item -parallel @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003213@findex -parallel
blueswir15824d652009-03-28 06:44:27 +00003214Redirect the virtual parallel port to host device @var{dev} (same
3215devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3216be used to use hardware devices connected on the corresponding host
3217parallel port.
3218
3219This option can be used several times to simulate up to 3 parallel
3220ports.
3221
3222Use @code{-parallel none} to disable all parallel ports.
3223ETEXI
3224
3225DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
Blue Swirlad960902010-03-29 19:23:52 +00003226 "-monitor dev redirect the monitor to char device 'dev'\n",
3227 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003228STEXI
Gerd Hoffmann4e307fc2009-12-08 13:11:37 +01003229@item -monitor @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003230@findex -monitor
blueswir15824d652009-03-28 06:44:27 +00003231Redirect the monitor to host device @var{dev} (same devices as the
3232serial port).
3233The default device is @code{vc} in graphical mode and @code{stdio} in
3234non graphical mode.
Luiz Capitulino70e098a2013-05-16 12:02:55 -04003235Use @code{-monitor none} to disable the default monitor.
blueswir15824d652009-03-28 06:44:27 +00003236ETEXI
Gerd Hoffmann6ca55822009-12-08 13:11:52 +01003237DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
Blue Swirlad960902010-03-29 19:23:52 +00003238 "-qmp dev like -monitor but opens in 'control' mode\n",
3239 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003240STEXI
3241@item -qmp @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003242@findex -qmp
Stefan Weil95d5f082010-01-20 22:25:27 +01003243Like -monitor but opens in 'control' mode.
3244ETEXI
Max Reitz4821cd42014-11-17 13:31:04 +01003245DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3246 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3247 QEMU_ARCH_ALL)
3248STEXI
3249@item -qmp-pretty @var{dev}
3250@findex -qmp-pretty
3251Like -qmp but uses pretty JSON formatting.
3252ETEXI
blueswir15824d652009-03-28 06:44:27 +00003253
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003254DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003255 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003256STEXI
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003257@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003258@findex -mon
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003259Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3260easing human reading and debugging.
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003261ETEXI
3262
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003263DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
Blue Swirlad960902010-03-29 19:23:52 +00003264 "-debugcon dev redirect the debug console to char device 'dev'\n",
3265 QEMU_ARCH_ALL)
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003266STEXI
3267@item -debugcon @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003268@findex -debugcon
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003269Redirect the debug console to host device @var{dev} (same devices as the
3270serial port). The debug console is an I/O port which is typically port
32710xe9; writing to that I/O port sends output to this device.
3272The default device is @code{vc} in graphical mode and @code{stdio} in
3273non graphical mode.
3274ETEXI
3275
blueswir15824d652009-03-28 06:44:27 +00003276DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
Blue Swirlad960902010-03-29 19:23:52 +00003277 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003278STEXI
3279@item -pidfile @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003280@findex -pidfile
blueswir15824d652009-03-28 06:44:27 +00003281Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3282from a script.
3283ETEXI
3284
aurel321b530a62009-04-05 20:08:59 +00003285DEF("singlestep", 0, QEMU_OPTION_singlestep, \
Blue Swirlad960902010-03-29 19:23:52 +00003286 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
aurel321b530a62009-04-05 20:08:59 +00003287STEXI
3288@item -singlestep
Stefan Weil6616b2a2010-02-05 23:52:05 +01003289@findex -singlestep
aurel321b530a62009-04-05 20:08:59 +00003290Run the emulation in single step mode.
3291ETEXI
3292
Igor Mammedov047f7032018-05-11 19:24:43 +02003293DEF("preconfig", 0, QEMU_OPTION_preconfig, \
3294 "--preconfig pause QEMU before machine is initialized\n",
3295 QEMU_ARCH_ALL)
3296STEXI
3297@item --preconfig
3298@findex --preconfig
3299Pause QEMU for interactive configuration before the machine is created,
3300which allows querying and configuring properties that will affect
3301machine initialization. Use the QMP command 'exit-preconfig' to exit
3302the preconfig state and move to the next state (ie. run guest if -S
3303isn't used or pause the second time if -S is used).
3304ETEXI
3305
blueswir15824d652009-03-28 06:44:27 +00003306DEF("S", 0, QEMU_OPTION_S, \
Blue Swirlad960902010-03-29 19:23:52 +00003307 "-S freeze CPU at startup (use 'c' to start execution)\n",
3308 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003309STEXI
3310@item -S
Stefan Weil6616b2a2010-02-05 23:52:05 +01003311@findex -S
blueswir15824d652009-03-28 06:44:27 +00003312Do not start CPU at startup (you must type 'c' in the monitor).
3313ETEXI
3314
Satoru Moriya888a6bc2013-04-19 16:42:06 +02003315DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3316 "-realtime [mlock=on|off]\n"
3317 " run qemu with realtime features\n"
3318 " mlock=on|off controls mlock support (default: on)\n",
3319 QEMU_ARCH_ALL)
3320STEXI
3321@item -realtime mlock=on|off
3322@findex -realtime
3323Run qemu with realtime features.
3324mlocking qemu and guest memory can be enabled via @option{mlock=on}
3325(enabled by default).
3326ETEXI
3327
Michael S. Tsirkin6f131f12018-06-22 22:22:05 +03003328DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
3329 "--overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
3330 " run qemu with overcommit hints\n"
3331 " mem-lock=on|off controls memory lock support (default: off)\n"
3332 " cpu-pm=on|off controls cpu power management (default: off)\n",
3333 QEMU_ARCH_ALL)
3334STEXI
3335@item -overcommit mem-lock=on|off
3336@item -overcommit cpu-pm=on|off
3337@findex -overcommit
3338Run qemu with hints about host resource overcommit. The default is
3339to assume that host overcommits all resources.
3340
3341Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
3342by default). This works when host memory is not overcommitted and reduces the
3343worst-case latency for guest. This is equivalent to @option{realtime}.
3344
3345Guest ability to manage power state of host cpus (increasing latency for other
3346processes on the same host cpu, but decreasing latency for guest) can be
3347enabled via @option{cpu-pm=on} (disabled by default). This works best when
3348host CPU is not overcommitted. When used, host estimates of CPU cycle and power
3349utilization will be incorrect, not taking into account guest idle time.
3350ETEXI
3351
aliguori59030a82009-04-05 18:43:41 +00003352DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
Blue Swirlad960902010-03-29 19:23:52 +00003353 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003354STEXI
aliguori59030a82009-04-05 18:43:41 +00003355@item -gdb @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003356@findex -gdb
aliguori59030a82009-04-05 18:43:41 +00003357Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3358connections will likely be TCP-based, but also UDP, pseudo TTY, or even
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003359stdio are reasonable use case. The latter is allowing to start QEMU from
aliguori59030a82009-04-05 18:43:41 +00003360within gdb and establish the connection via a pipe:
3361@example
Stefan Weil3804da92012-05-11 22:21:50 +02003362(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
aliguori59030a82009-04-05 18:43:41 +00003363@end example
blueswir15824d652009-03-28 06:44:27 +00003364ETEXI
3365
aliguori59030a82009-04-05 18:43:41 +00003366DEF("s", 0, QEMU_OPTION_s, \
Blue Swirlad960902010-03-29 19:23:52 +00003367 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3368 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003369STEXI
aliguori59030a82009-04-05 18:43:41 +00003370@item -s
Stefan Weil6616b2a2010-02-05 23:52:05 +01003371@findex -s
aliguori59030a82009-04-05 18:43:41 +00003372Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3373(@pxref{gdb_usage}).
blueswir15824d652009-03-28 06:44:27 +00003374ETEXI
3375
3376DEF("d", HAS_ARG, QEMU_OPTION_d, \
Peter Maydell989b6972013-02-26 17:52:40 +00003377 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
Blue Swirlad960902010-03-29 19:23:52 +00003378 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003379STEXI
Peter Maydell989b6972013-02-26 17:52:40 +00003380@item -d @var{item1}[,...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003381@findex -d
Peter Maydell989b6972013-02-26 17:52:40 +00003382Enable logging of specified items. Use '-d help' for a list of log items.
blueswir15824d652009-03-28 06:44:27 +00003383ETEXI
3384
Matthew Fernandezc235d732011-06-07 16:32:40 +00003385DEF("D", HAS_ARG, QEMU_OPTION_D, \
Peter Maydell989b6972013-02-26 17:52:40 +00003386 "-D logfile output log to logfile (default stderr)\n",
Matthew Fernandezc235d732011-06-07 16:32:40 +00003387 QEMU_ARCH_ALL)
3388STEXI
Stefan Weil8bd383b2012-05-11 22:40:50 +02003389@item -D @var{logfile}
Matthew Fernandezc235d732011-06-07 16:32:40 +00003390@findex -D
Peter Maydell989b6972013-02-26 17:52:40 +00003391Output log in @var{logfile} instead of to stderr
Matthew Fernandezc235d732011-06-07 16:32:40 +00003392ETEXI
3393
Alex Bennée35145522016-03-15 14:30:20 +00003394DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3395 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3396 QEMU_ARCH_ALL)
3397STEXI
3398@item -dfilter @var{range1}[,...]
3399@findex -dfilter
3400Filter debug output to that relevant to a range of target addresses. The filter
3401spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3402@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3403addresses and sizes required. For example:
3404@example
3405 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3406@end example
3407Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3408the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3409block starting at 0xffffffc00005f000.
3410ETEXI
3411
blueswir15824d652009-03-28 06:44:27 +00003412DEF("L", HAS_ARG, QEMU_OPTION_L, \
Blue Swirlad960902010-03-29 19:23:52 +00003413 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3414 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003415STEXI
3416@item -L @var{path}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003417@findex -L
blueswir15824d652009-03-28 06:44:27 +00003418Set the directory for the BIOS, VGA BIOS and keymaps.
Richard W.M. Jones37146e72016-05-16 17:34:35 +01003419
3420To list all the data directories, use @code{-L help}.
blueswir15824d652009-03-28 06:44:27 +00003421ETEXI
3422
3423DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
Blue Swirlad960902010-03-29 19:23:52 +00003424 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003425STEXI
3426@item -bios @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003427@findex -bios
blueswir15824d652009-03-28 06:44:27 +00003428Set the filename for the BIOS.
3429ETEXI
3430
blueswir15824d652009-03-28 06:44:27 +00003431DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
Blue Swirlad960902010-03-29 19:23:52 +00003432 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003433STEXI
3434@item -enable-kvm
Stefan Weil6616b2a2010-02-05 23:52:05 +01003435@findex -enable-kvm
blueswir15824d652009-03-28 06:44:27 +00003436Enable KVM full virtualization support. This option is only available
3437if KVM support is enabled when compiling.
3438ETEXI
3439
Vincent Palatinb0cb0a62017-01-10 11:59:57 +01003440DEF("enable-hax", 0, QEMU_OPTION_enable_hax, \
3441 "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386)
3442STEXI
3443@item -enable-hax
3444@findex -enable-hax
3445Enable HAX (Hardware-based Acceleration eXecution) support. This option
3446is only available if HAX support is enabled when compiling. HAX is only
3447applicable to MAC and Windows platform, and thus does not conflict with
Thomas Huthc44df2f2018-06-25 20:22:13 +02003448KVM. This option is deprecated, use @option{-accel hax} instead.
Vincent Palatinb0cb0a62017-01-10 11:59:57 +01003449ETEXI
3450
aliguorie37630c2009-04-22 15:19:10 +00003451DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
Blue Swirlad960902010-03-29 19:23:52 +00003452 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003453DEF("xen-create", 0, QEMU_OPTION_xen_create,
3454 "-xen-create create domain using xen hypercalls, bypassing xend\n"
Blue Swirlad960902010-03-29 19:23:52 +00003455 " warning: should not be used when xend is in use\n",
3456 QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003457DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3458 "-xen-attach attach to existing xen domain\n"
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003459 " xend will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00003460 QEMU_ARCH_ALL)
Paul Durrant1c599472017-03-22 09:39:15 +00003461DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3462 "-xen-domid-restrict restrict set of available xen operations\n"
3463 " to specified domain id. (Does not affect\n"
3464 " xenpv machine type).\n",
3465 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003466STEXI
3467@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003468@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01003469Specify xen guest domain @var{id} (XEN only).
3470@item -xen-create
Stefan Weil6616b2a2010-02-05 23:52:05 +01003471@findex -xen-create
Stefan Weil95d5f082010-01-20 22:25:27 +01003472Create domain using xen hypercalls, bypassing xend.
3473Warning: should not be used when xend is in use (XEN only).
3474@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01003475@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01003476Attach to existing xen domain.
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003477xend will use this when starting QEMU (XEN only).
Paul Durrant1c599472017-03-22 09:39:15 +00003478@findex -xen-domid-restrict
3479Restrict set of available xen operations to specified domain id (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003480ETEXI
aliguorie37630c2009-04-22 15:19:10 +00003481
blueswir15824d652009-03-28 06:44:27 +00003482DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00003483 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003484STEXI
3485@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01003486@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00003487Exit instead of rebooting.
3488ETEXI
3489
3490DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00003491 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003492STEXI
3493@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01003494@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00003495Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3496This allows for instance switching to monitor to commit changes to the
3497disk image.
3498ETEXI
3499
3500DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3501 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003502 " start right away with a saved state (loadvm in monitor)\n",
3503 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003504STEXI
3505@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003506@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00003507Start right away with a saved state (@code{loadvm} in monitor)
3508ETEXI
3509
3510#ifndef _WIN32
3511DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00003512 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003513#endif
3514STEXI
3515@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01003516@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00003517Daemonize the QEMU process after initialization. QEMU will not detach from
3518standard IO until it is ready to receive connections on any of its devices.
3519This option is a useful way for external programs to launch QEMU without having
3520to cope with initialization race conditions.
3521ETEXI
3522
3523DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00003524 "-option-rom rom load a file, rom, into the option ROM space\n",
3525 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003526STEXI
3527@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003528@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003529Load the contents of @var{file} as an option ROM.
3530This option is useful to load things like EtherBoot.
3531ETEXI
3532
Markus Armbrustere2180522014-10-06 16:19:07 +02003533HXCOMM Silently ignored for compatibility
3534DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003535
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003536HXCOMM Options deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00003537DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3538DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003539
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003540DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Paolo Bonzini78808142012-03-30 10:31:21 +00003541 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003542 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3543 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003544
blueswir15824d652009-03-28 06:44:27 +00003545STEXI
3546
Jan Kiszka68752042009-09-15 13:36:04 +02003547@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003548@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003549Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3550UTC or local time, respectively. @code{localtime} is required for correct date in
3551MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3552format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3553
Michael Tokarev9d85d552014-04-07 13:34:58 +04003554By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003555RTC as accurate reference clock inside the guest, specifically if the host
3556time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003557If you want to isolate the guest time from the host, you can set @option{clock}
3558to @code{rt} instead. To even prevent it from progressing during suspension,
3559you can set it to @code{vm}.
Jan Kiszka68752042009-09-15 13:36:04 +02003560
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003561Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3562specifically with Windows' ACPI HAL. This option will try to figure out how
3563many timer interrupts were not processed by the Windows guest and will
3564re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003565ETEXI
3566
3567DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003568 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003569 " enable virtual instruction counter with 2^N clock ticks per\n" \
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003570 " instruction, enable aligning the host and virtual clocks\n" \
3571 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003572STEXI
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003573@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003574@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003575Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003576instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003577then the virtual cpu speed will be automatically adjusted to keep virtual
3578time within a few seconds of real time.
3579
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003580When the virtual cpu is sleeping, the virtual time will advance at default
Pranith Kumar778d9f92016-02-26 10:16:51 -05003581speed unless @option{sleep=on|off} is specified.
3582With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003583instantly whenever the virtual cpu goes to sleep mode and will not advance
3584if no timer is enabled. This behavior give deterministic execution times from
3585the guest point of view.
3586
blueswir15824d652009-03-28 06:44:27 +00003587Note that while this option can give deterministic behavior, it does not
3588provide cycle accurate emulation. Modern CPUs contain superscalar out of
3589order cores with complex cache hierarchies. The number of instructions
3590executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003591
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01003592@option{align=on} will activate the delay algorithm which will try
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003593to synchronise the host clock and the virtual clock. The goal is to
3594have a guest running at the real frequency imposed by the shift option.
3595Whenever the guest clock is behind the host clock and if
Michael Tokarev82597612015-04-27 11:12:49 +03003596@option{align=on} is specified then we print a message to the user
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003597to inform about the delay.
3598Currently this option does not work when @option{shift} is @code{auto}.
3599Note: The sync algorithm will work for those shift values for which
3600the guest clock runs ahead of the host clock. Typically this happens
3601when the shift value is high (how high depends on the host machine).
Pavel Dovgalyuk4c27b852015-09-17 19:25:18 +03003602
3603When @option{rr} option is specified deterministic record/replay is enabled.
3604Replay log is written into @var{filename} file in record mode and
3605read from this file in replay mode.
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003606
3607Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3608at the start of execution recording. In replay mode this option is used
3609to load the initial VM state.
blueswir15824d652009-03-28 06:44:27 +00003610ETEXI
3611
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003612DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
Xu Wangd7933ef2015-06-11 17:32:05 +02003613 "-watchdog model\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003614 " enable virtual hardware watchdog [default=none]\n",
3615 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003616STEXI
3617@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003618@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003619Create a virtual hardware watchdog device. Once enabled (by a guest
3620action), the watchdog must be periodically polled by an agent inside
Xu Wangd7933ef2015-06-11 17:32:05 +02003621the guest or else the guest will be restarted. Choose a model for
3622which your guest has drivers.
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003623
Xu Wangd7933ef2015-06-11 17:32:05 +02003624The @var{model} is the model of hardware watchdog to emulate. Use
3625@code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003626watchdog can be enabled for a guest.
Xu Wangd7933ef2015-06-11 17:32:05 +02003627
3628The following models may be available:
3629@table @option
3630@item ib700
3631iBASE 700 is a very simple ISA watchdog with a single timer.
3632@item i6300esb
3633Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3634dual-timer watchdog.
Xu Wang188f24c2015-02-05 18:28:32 +08003635@item diag288
3636A virtual watchdog for s390x backed by the diagnose 288 hypercall
3637(currently KVM only).
Xu Wangd7933ef2015-06-11 17:32:05 +02003638@end table
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003639ETEXI
3640
3641DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
Markus Armbruster7ad92702017-10-02 16:03:07 +02003642 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003643 " action when watchdog fires [default=reset]\n",
3644 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003645STEXI
3646@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003647@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003648
3649The @var{action} controls what QEMU will do when the watchdog timer
3650expires.
3651The default is
3652@code{reset} (forcefully reset the guest).
3653Other possible actions are:
3654@code{shutdown} (attempt to gracefully shutdown the guest),
3655@code{poweroff} (forcefully poweroff the guest),
Markus Armbruster7ad92702017-10-02 16:03:07 +02003656@code{inject-nmi} (inject a NMI into the guest),
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003657@code{pause} (pause the guest),
3658@code{debug} (print a debug message and continue), or
3659@code{none} (do nothing).
3660
3661Note that the @code{shutdown} action requires that the guest responds
3662to ACPI signals, which it may not be able to do in the sort of
3663situations where the watchdog would have expired, and thus
3664@code{-watchdog-action shutdown} is not recommended for production use.
3665
3666Examples:
3667
3668@table @code
3669@item -watchdog i6300esb -watchdog-action pause
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003670@itemx -watchdog ib700
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003671@end table
3672ETEXI
3673
blueswir15824d652009-03-28 06:44:27 +00003674DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003675 "-echr chr set terminal escape character instead of ctrl-a\n",
3676 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003677STEXI
3678
Kevin Wolf4e257e52009-10-09 10:58:36 +02003679@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003680@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003681Change the escape character used for switching to the monitor when using
3682monitor and serial sharing. The default is @code{0x01} when using the
3683@code{-nographic} option. @code{0x01} is equal to pressing
3684@code{Control-a}. You can select a different character from the ascii
3685control keys where 1 through 26 map to Control-a through Control-z. For
3686instance you could use the either of the following to change the escape
3687character to Control-t.
3688@table @code
3689@item -echr 0x14
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003690@itemx -echr 20
blueswir15824d652009-03-28 06:44:27 +00003691@end table
3692ETEXI
3693
3694DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3695 "-virtioconsole c\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003696 " set virtio console\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003697STEXI
3698@item -virtioconsole @var{c}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003699@findex -virtioconsole
blueswir15824d652009-03-28 06:44:27 +00003700Set virtio console.
Thomas Huth45401292018-05-04 17:13:10 +02003701This option is deprecated, please use @option{-device virtconsole} instead.
blueswir15824d652009-03-28 06:44:27 +00003702ETEXI
3703
3704DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003705 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003706STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003707@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003708@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003709Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003710ETEXI
3711
3712DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003713 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003714STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003715@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003716@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003717Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003718ETEXI
3719
3720DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Michael Tokarev7c601802015-02-10 22:40:47 +03003721 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3722 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3723 "-incoming unix:socketpath\n" \
3724 " prepare for incoming migration, listen on\n" \
3725 " specified protocol and socket address\n" \
3726 "-incoming fd:fd\n" \
3727 "-incoming exec:cmdline\n" \
3728 " accept incoming migration on given file descriptor\n" \
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003729 " or from given external command\n" \
3730 "-incoming defer\n" \
3731 " wait for the URI to be specified via migrate_incoming\n",
Blue Swirlad960902010-03-29 19:23:52 +00003732 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003733STEXI
Michael Tokarev7c601802015-02-10 22:40:47 +03003734@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003735@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003736@findex -incoming
Michael Tokarev7c601802015-02-10 22:40:47 +03003737Prepare for incoming migration, listen on a given tcp port.
3738
3739@item -incoming unix:@var{socketpath}
3740Prepare for incoming migration, listen on a given unix socket.
3741
3742@item -incoming fd:@var{fd}
3743Accept incoming migration from a given filedescriptor.
3744
3745@item -incoming exec:@var{cmdline}
3746Accept incoming migration as an output from specified external command.
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003747
3748@item -incoming defer
3749Wait for the URI to be specified via migrate_incoming. The monitor can
3750be used to change settings (such as migration parameters) prior to issuing
3751the migrate_incoming to allow the migration to begin.
blueswir15824d652009-03-28 06:44:27 +00003752ETEXI
3753
Ashijeet Acharyad15c05f2017-01-16 17:01:51 +05303754DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3755 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3756STEXI
3757@item -only-migratable
3758@findex -only-migratable
3759Only allow migratable devices. Devices will not be allowed to enter an
3760unmigratable state.
3761ETEXI
3762
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003763DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003764 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003765STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003766@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003767@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003768Don't create default devices. Normally, QEMU sets the default devices like serial
3769port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3770CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3771default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003772ETEXI
3773
blueswir15824d652009-03-28 06:44:27 +00003774#ifndef _WIN32
3775DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003776 "-chroot dir chroot to dir just before starting the VM\n",
3777 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003778#endif
3779STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003780@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003781@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003782Immediately before starting guest execution, chroot to the specified
3783directory. Especially useful in combination with -runas.
3784ETEXI
3785
3786#ifndef _WIN32
3787DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Ian Jackson2c42f1e2017-09-15 18:10:44 +01003788 "-runas user change to user id user just before starting the VM\n" \
3789 " user can be numeric uid:gid instead\n",
Blue Swirlad960902010-03-29 19:23:52 +00003790 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003791#endif
3792STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003793@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003794@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003795Immediately before starting guest execution, drop root privileges, switching
3796to the specified user.
3797ETEXI
3798
blueswir15824d652009-03-28 06:44:27 +00003799DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3800 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003801 " set OpenBIOS nvram variables\n",
3802 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003803STEXI
3804@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003805@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003806Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3807ETEXI
blueswir15824d652009-03-28 06:44:27 +00003808DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003809 "-semihosting semihosting mode\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003810 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3811 QEMU_ARCH_MIPS)
Stefan Weil95d5f082010-01-20 22:25:27 +01003812STEXI
3813@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003814@findex -semihosting
Leon Alrae3b3c1692015-06-19 11:08:43 +01003815Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
Liviu Ionescua38bb072014-12-11 12:07:48 +00003816ETEXI
3817DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
Leon Alraea59d31a2015-06-19 14:17:45 +01003818 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3819 " semihosting configuration\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003820QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3821QEMU_ARCH_MIPS)
Liviu Ionescua38bb072014-12-11 12:07:48 +00003822STEXI
Leon Alraea59d31a2015-06-19 14:17:45 +01003823@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
Liviu Ionescua38bb072014-12-11 12:07:48 +00003824@findex -semihosting-config
Leon Alrae3b3c1692015-06-19 11:08:43 +01003825Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
Leon Alraea59d31a2015-06-19 14:17:45 +01003826@table @option
3827@item target=@code{native|gdb|auto}
3828Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3829or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3830during debug sessions and @code{native} otherwise.
3831@item arg=@var{str1},arg=@var{str2},...
3832Allows the user to pass input arguments, and can be used multiple times to build
3833up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3834command line is still supported for backward compatibility. If both the
3835@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3836specified, the former is passed to semihosting as it always takes precedence.
3837@end table
Stefan Weil95d5f082010-01-20 22:25:27 +01003838ETEXI
blueswir15824d652009-03-28 06:44:27 +00003839DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00003840 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003841STEXI
3842@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01003843@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003844Old param mode (ARM only).
3845ETEXI
3846
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003847DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003848 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003849 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003850 " Enable seccomp mode 2 system call filter (default 'off').\n" \
3851 " use 'obsolete' to allow obsolete system calls that are provided\n" \
3852 " by the kernel, but typically no longer used by modern\n" \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003853 " C library implementations.\n" \
3854 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \
3855 " its privileges by blacklisting all set*uid|gid system calls.\n" \
3856 " The value 'children' will deny set*uid|gid system calls for\n" \
Eduardo Otubo995a2262017-03-13 22:16:01 +01003857 " main QEMU process but will allow forks and execves to run unprivileged\n" \
3858 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003859 " blacklisting *fork and execve\n" \
3860 " use 'resourcecontrol' to disable process affinity and schedular priority\n",
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003861 QEMU_ARCH_ALL)
3862STEXI
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003863@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003864@findex -sandbox
3865Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3866disable it. The default is 'off'.
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003867@table @option
3868@item obsolete=@var{string}
3869Enable Obsolete system calls
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003870@item elevateprivileges=@var{string}
3871Disable set*uid|gid system calls
Eduardo Otubo995a2262017-03-13 22:16:01 +01003872@item spawn=@var{string}
3873Disable *fork and execve
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003874@item resourcecontrol=@var{string}
3875Disable process affinity and schedular priority
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003876@end table
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003877ETEXI
3878
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003879DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00003880 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003881STEXI
3882@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003883@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003884Read device configuration from @var{file}. This approach is useful when you want to spawn
3885QEMU process with many command line options but you don't want to exceed the command line
3886character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003887ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003888DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3889 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00003890 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003891STEXI
3892@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003893@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003894Write device configuration to @var{file}. The @var{file} can be either filename to save
3895command line and device configuration into file or dash @code{-}) character to print the
3896output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003897ETEXI
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003898HXCOMM Deprecated, same as -no-user-config
3899DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, "", QEMU_ARCH_ALL)
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003900DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3901 "-no-user-config\n"
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003902 " do not load default user-provided config files at startup\n",
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003903 QEMU_ARCH_ALL)
3904STEXI
3905@item -no-user-config
3906@findex -no-user-config
3907The @code{-no-user-config} option makes QEMU not load any of the user-provided
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003908config files on @var{sysconfdir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06003909ETEXI
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003910DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Paolo Bonzini10578a22016-01-07 16:55:26 +03003911 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
Lluís23d15e82011-08-31 20:31:31 +02003912 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003913 QEMU_ARCH_ALL)
3914STEXI
Lluís23d15e82011-08-31 20:31:31 +02003915HXCOMM This line is not accurate, as some sub-options are backend-specific but
3916HXCOMM HX does not support conditional compilation of text.
Denis V. Luneve370ad92016-06-17 17:44:08 +03003917@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003918@findex -trace
Denis V. Luneveeb2b8f2016-06-17 17:44:09 +03003919@include qemu-option-trace.texi
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003920ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003921
Markus Armbruster31e70d62013-02-13 19:49:37 +01003922HXCOMM Internal use
3923DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3924DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02003925
Paul Moore0f669982012-08-03 14:39:21 -04003926#ifdef __linux__
3927DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3928 "-enable-fips enable FIPS 140-2 compliance\n",
3929 QEMU_ARCH_ALL)
3930#endif
3931STEXI
3932@item -enable-fips
3933@findex -enable-fips
3934Enable FIPS 140-2 compliance mode.
3935ETEXI
3936
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003937HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003938DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003939
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04003940DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3941 "-msg timestamp[=on|off]\n"
3942 " change the format of messages\n"
3943 " on|off controls leading timestamps (default:on)\n",
3944 QEMU_ARCH_ALL)
3945STEXI
3946@item -msg timestamp[=on|off]
3947@findex -msg
3948prepend a timestamp to each log message.(default:on)
3949ETEXI
3950
Amit Shahabfd9ce2014-06-20 18:56:08 +05303951DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3952 "-dump-vmstate <file>\n"
3953 " Output vmstate information in JSON format to file.\n"
3954 " Use the scripts/vmstate-static-checker.py file to\n"
3955 " check for possible regressions in migration code\n"
Laurent Vivier23820532015-09-04 21:30:04 +02003956 " by comparing two such vmstate dumps.\n",
Amit Shahabfd9ce2014-06-20 18:56:08 +05303957 QEMU_ARCH_ALL)
3958STEXI
3959@item -dump-vmstate @var{file}
3960@findex -dump-vmstate
3961Dump json-encoded vmstate information for current machine type to file
3962in @var{file}
3963ETEXI
3964
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003965STEXI
3966@end table
3967ETEXI
3968DEFHEADING()
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003969
3970DEFHEADING(Generic object creation:)
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003971STEXI
3972@table @option
3973ETEXI
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003974
3975DEF("object", HAS_ARG, QEMU_OPTION_object,
3976 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3977 " create a new object of type TYPENAME setting properties\n"
3978 " in the order they are specified. Note that the 'id'\n"
3979 " property must be set. These objects are placed in the\n"
3980 " '/objects' path.\n",
3981 QEMU_ARCH_ALL)
3982STEXI
3983@item -object @var{typename}[,@var{prop1}=@var{value1},...]
3984@findex -object
3985Create a new object of type @var{typename} setting properties
3986in the order they are specified. Note that the 'id'
3987property must be set. These objects are placed in the
3988'/objects' path.
3989
3990@table @option
3991
Haozhong Zhang98376842017-12-11 15:28:04 +08003992@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},align=@var{align}
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003993
3994Creates a memory file backend object, which can be used to back
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003995the guest RAM with huge pages.
3996
3997The @option{id} parameter is a unique ID that will be used to reference this
3998memory region when configuring the @option{-numa} argument.
3999
4000The @option{size} option provides the size of the memory region, and accepts
4001common suffixes, eg @option{500M}.
4002
4003The @option{mem-path} provides the path to either a shared memory or huge page
4004filesystem mount.
4005
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004006The @option{share} boolean option determines whether the memory
4007region is marked as private to QEMU, or shared. The latter allows
4008a co-operating external process to access the QEMU memory region.
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00004009
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02004010The @option{share} is also required for pvrdma devices due to
4011limitations in the RDMA API provided by Linux.
4012
4013Setting share=on might affect the ability to configure NUMA
4014bindings for the memory backend under some circumstances, see
4015Documentation/vm/numa_memory_policy.txt on the Linux kernel
4016source tree for additional details.
4017
Eduardo Habkost11ae6ed2017-08-24 16:23:15 -03004018Setting the @option{discard-data} boolean option to @var{on}
4019indicates that file contents can be destroyed when QEMU exits,
4020to avoid unnecessarily flushing data to the backing file. Note
4021that @option{discard-data} is only an optimization, and QEMU
4022might not discard file contents if it aborts unexpectedly or is
4023terminated using SIGKILL.
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004024
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00004025The @option{merge} boolean option enables memory merge, also known as
4026MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
4027memory deduplication.
4028
4029Setting the @option{dump} boolean option to @var{off} excludes the memory from
4030core dumps. This feature is also known as MADV_DONTDUMP.
4031
4032The @option{prealloc} boolean option enables memory preallocation.
4033
4034The @option{host-nodes} option binds the memory range to a list of NUMA host
4035nodes.
4036
4037The @option{policy} option sets the NUMA policy to one of the following values:
4038
4039@table @option
4040@item @var{default}
4041default host policy
4042
4043@item @var{preferred}
4044prefer the given host node list for allocation
4045
4046@item @var{bind}
4047restrict memory allocation to the given host node list
4048
4049@item @var{interleave}
4050interleave memory allocations across the given host node list
4051@end table
4052
Haozhong Zhang98376842017-12-11 15:28:04 +08004053The @option{align} option specifies the base address alignment when
4054QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg
4055@option{2M}. Some backend store specified by @option{mem-path}
4056requires an alignment different than the default one used by QEMU, eg
4057the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
4058such cases, users can specify the required alignment via this option.
4059
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02004060@item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave}
Stefan Hajnoczicd194912017-11-28 16:15:29 +00004061
4062Creates a memory backend object, which can be used to back the guest RAM.
4063Memory backend objects offer more control than the @option{-m} option that is
4064traditionally used to define guest RAM. Please refer to
4065@option{memory-backend-file} for a description of the options.
4066
Marc-André Lureaudbb9e0f2018-02-01 14:27:54 +01004067@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size}
4068
4069Creates an anonymous memory file backend object, which allows QEMU to
4070share the memory with an external process (e.g. when using
4071vhost-user). The memory is allocated with memfd and optional
4072sealing. (Linux only)
4073
4074The @option{seal} option creates a sealed-file, that will block
4075further resizing the memory ('on' by default).
4076
4077The @option{hugetlb} option specify the file to be created resides in
4078the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with
4079the @option{hugetlb} option, the @option{hugetlbsize} option specify
4080the hugetlb page size on systems that support multiple hugetlb page
4081sizes (it must be a power of 2 value supported by the system).
4082
4083In some versions of Linux, the @option{hugetlb} option is incompatible
4084with the @option{seal} option (requires at least Linux 4.16).
4085
4086Please refer to @option{memory-backend-file} for a description of the
4087other options.
4088
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004089@item -object rng-random,id=@var{id},filename=@var{/dev/random}
4090
4091Creates a random number generator backend which obtains entropy from
4092a device on the host. The @option{id} parameter is a unique ID that
4093will be used to reference this entropy backend from the @option{virtio-rng}
4094device. The @option{filename} parameter specifies which file to obtain
4095entropy from and if omitted defaults to @option{/dev/random}.
4096
4097@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4098
4099Creates a random number generator backend which obtains entropy from
4100an external daemon running on the host. The @option{id} parameter is
4101a unique ID that will be used to reference this entropy backend from
4102the @option{virtio-rng} device. The @option{chardev} parameter is
4103the unique ID of a character device backend that provides the connection
4104to the RNG daemon.
4105
Daniel P. Berrangee00adf62015-03-13 17:39:26 +00004106@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4107
4108Creates a TLS anonymous credentials object, which can be used to provide
4109TLS support on network backends. The @option{id} parameter is a unique
4110ID which network backends will use to access the credentials. The
4111@option{endpoint} is either @option{server} or @option{client} depending
4112on whether the QEMU network backend that uses the credentials will be
4113acting as a client or as a server. If @option{verify-peer} is enabled
4114(the default) then once the handshake is completed, the peer credentials
4115will be verified, though this is a no-op for anonymous credentials.
4116
4117The @var{dir} parameter tells QEMU where to find the credential
4118files. For server endpoints, this directory may contain a file
4119@var{dh-params.pem} providing diffie-hellman parameters to use
4120for the TLS server. If the file is missing, QEMU will generate
4121a set of DH parameters at startup. This is a computationally
4122expensive operation that consumes random pool entropy, so it is
4123recommended that a persistent set of parameters be generated
4124upfront and saved.
4125
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004126@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id}
Daniel P. Berrange85bcbc72015-03-13 17:39:26 +00004127
4128Creates a TLS anonymous credentials object, which can be used to provide
4129TLS support on network backends. The @option{id} parameter is a unique
4130ID which network backends will use to access the credentials. The
4131@option{endpoint} is either @option{server} or @option{client} depending
4132on whether the QEMU network backend that uses the credentials will be
4133acting as a client or as a server. If @option{verify-peer} is enabled
4134(the default) then once the handshake is completed, the peer credentials
4135will be verified. With x509 certificates, this implies that the clients
4136must be provided with valid client certificates too.
4137
4138The @var{dir} parameter tells QEMU where to find the credential
4139files. For server endpoints, this directory may contain a file
4140@var{dh-params.pem} providing diffie-hellman parameters to use
4141for the TLS server. If the file is missing, QEMU will generate
4142a set of DH parameters at startup. This is a computationally
4143expensive operation that consumes random pool entropy, so it is
4144recommended that a persistent set of parameters be generated
4145upfront and saved.
4146
4147For x509 certificate credentials the directory will contain further files
4148providing the x509 certificates. The certificates must be stored
4149in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4150@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4151@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4152
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004153For the @var{server-key.pem} and @var{client-key.pem} files which
4154contain sensitive private keys, it is possible to use an encrypted
4155version by providing the @var{passwordid} parameter. This provides
4156the ID of a previously created @code{secret} object containing the
4157password for decryption.
4158
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004159The @var{priority} parameter allows to override the global default
4160priority used by gnutls. This can be useful if the system administrator
4161needs to use a weaker set of crypto priorities for QEMU without
4162potentially forcing the weakness onto all applications. Or conversely
4163if one wants wants a stronger default for QEMU than for all other
4164applications, they can do this through this parameter. Its format is
4165a gnutls priority string as described at
4166@url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
4167
zhanghailiang338d3f42016-03-01 13:37:02 +08004168@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 +08004169
4170Interval @var{t} can't be 0, this filter batches the packet delivery: all
4171packets arriving in a given interval on netdev @var{netdevid} are delayed
4172until the end of the interval. Interval is in microseconds.
zhanghailiang338d3f42016-03-01 13:37:02 +08004173@option{status} is optional that indicate whether the netfilter is
4174on (enabled) or off (disabled), the default status for netfilter will be 'on'.
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004175
4176queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4177
4178@option{all}: the filter is attached both to the receive and the transmit
4179 queue of the netdev (default).
4180
4181@option{rx}: the filter is attached to the receive queue of the netdev,
4182 where it will receive packets sent to the netdev.
4183
4184@option{tx}: the filter is attached to the transmit queue of the netdev,
4185 where it will receive packets sent by the netdev.
4186
Zhang Chene2521f02017-07-04 14:53:48 +08004187@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 +08004188
Zhang Chene2521f02017-07-04 14:53:48 +08004189filter-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 +08004190
Zhang Chen00d5c242017-07-04 14:53:49 +08004191@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 +08004192
4193filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
Zhang Chen00d5c242017-07-04 14:53:49 +08004194@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4195filter-redirector will redirect packet with vnet_hdr_len.
Zhang Chend46f75b2016-03-17 16:16:26 +08004196Create a filter-redirector we need to differ outdev id from indev id, id can not
4197be the same. we can just use indev or outdev, but at least one of indev or outdev
4198need to be specified.
4199
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004200@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 +08004201
4202Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4203secondary from primary to keep secondary tcp connection,and rewrite
4204tcp packet to primary from secondary make tcp packet can be handled by
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004205client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
Zhang Chene6eee8a2016-09-27 10:22:32 +08004206
4207usage:
4208colo secondary:
4209-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4210-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4211-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4212
Changlong Xiec551cd52016-10-11 13:28:32 +08004213@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
Thomas Huthd3e0c032015-10-13 12:40:02 +02004214
4215Dump the network traffic on netdev @var{dev} to the file specified by
4216@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4217The file format is libpcap, so it can be analyzed with tools such as tcpdump
4218or Wireshark.
4219
Zhang Chenaa3a7032017-07-04 14:53:52 +08004220@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 +08004221
4222Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4223secondary packet. If the packets are same, we will output primary
4224packet to outdev@var{chardevid}, else we will notify colo-frame
4225do checkpoint and send primary packet to outdev@var{chardevid}.
Zhang Chenaa3a7032017-07-04 14:53:52 +08004226if it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len.
Zhang Chen7dce4e62016-09-27 10:22:26 +08004227
4228we must use it with the help of filter-mirror and filter-redirector.
4229
4230@example
4231
4232primary:
4233-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4234-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4235-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4236-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4237-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4238-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4239-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4240-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4241-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4242-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4243-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4244-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4245
4246secondary:
4247-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4248-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4249-chardev socket,id=red0,host=3.3.3.3,port=9003
4250-chardev socket,id=red1,host=3.3.3.3,port=9004
4251-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4252-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4253
4254@end example
4255
4256If you want to know the detail of above command line, you can read
4257the colo-compare git log.
4258
Gonglei1653a5f2016-10-28 16:33:23 +08004259@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4260
4261Creates a cryptodev backend which executes crypto opreation from
4262the QEMU cipher APIS. The @var{id} parameter is
4263a unique ID that will be used to reference this cryptodev backend from
4264the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4265which specify the queue number of cryptodev backend, the default of
4266@var{queues} is 1.
4267
4268@example
4269
4270 # qemu-system-x86_64 \
4271 [...] \
4272 -object cryptodev-backend-builtin,id=cryptodev0 \
4273 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4274 [...]
4275@end example
4276
Gonglei042cea22018-03-01 21:46:28 +08004277@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}]
4278
4279Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}.
4280The @var{id} parameter is a unique ID that will be used to reference this
4281cryptodev backend from the @option{virtio-crypto} device.
4282The chardev should be a unix domain socket backed one. The vhost-user uses
4283a specifically defined protocol to pass vhost ioctl replacement messages
4284to an application on the other end of the socket.
4285The @var{queues} parameter is optional, which specify the queue number
4286of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1.
4287
4288@example
4289
4290 # qemu-system-x86_64 \
4291 [...] \
4292 -chardev socket,id=chardev0,path=/path/to/socket \
4293 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4294 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4295 [...]
4296@end example
4297
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004298@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4299@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4300
4301Defines a secret to store a password, encryption key, or some other sensitive
4302data. The sensitive data can either be passed directly via the @var{data}
4303parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4304parameter is insecure unless the sensitive data is encrypted.
4305
4306The sensitive data can be provided in raw format (the default), or base64.
4307When encoded as JSON, the raw format only supports valid UTF-8 characters,
4308so base64 is recommended for sending binary data. QEMU will convert from
4309which ever format is provided to the format it needs internally. eg, an
4310RBD password can be provided in raw format, even though it will be base64
4311encoded when passed onto the RBD sever.
4312
4313For added protection, it is possible to encrypt the data associated with
4314a secret using the AES-256-CBC cipher. Use of encryption is indicated
4315by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4316parameter provides the ID of a previously defined secret that contains
4317the AES-256 decryption key. This key should be 32-bytes long and be
4318base64 encoded. The @var{iv} parameter provides the random initialization
4319vector used for encryption of this particular secret and should be a
Daniel P. Berrange69c0b272016-04-04 10:33:55 +01004320base64 encrypted string of the 16-byte IV.
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004321
4322The simplest (insecure) usage is to provide the secret inline
4323
4324@example
4325
4326 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4327
4328@end example
4329
4330The simplest secure usage is to provide the secret via a file
4331
Eric Blakeb43671f2017-07-03 13:09:50 -05004332 # printf "letmein" > mypasswd.txt
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004333 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4334
4335For greater security, AES-256-CBC should be used. To illustrate usage,
4336consider the openssl command line tool which can encrypt the data. Note
4337that when encrypting, the plaintext must be padded to the cipher block
4338size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4339
4340First a master key needs to be created in base64 encoding:
4341
4342@example
4343 # openssl rand -base64 32 > key.b64
4344 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4345@end example
4346
4347Each secret to be encrypted needs to have a random initialization vector
4348generated. These do not need to be kept secret
4349
4350@example
4351 # openssl rand -base64 16 > iv.b64
4352 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4353@end example
4354
4355The secret to be defined can now be encrypted, in this case we're
4356telling openssl to base64 encode the result, but it could be left
4357as raw bytes if desired.
4358
4359@example
Eric Blakeb43671f2017-07-03 13:09:50 -05004360 # SECRET=$(printf "letmein" |
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004361 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4362@end example
4363
4364When launching QEMU, create a master secret pointing to @code{key.b64}
4365and specify that to be used to decrypt the user password. Pass the
4366contents of @code{iv.b64} to the second secret
4367
4368@example
4369 # $QEMU \
4370 -object secret,id=secmaster0,format=base64,file=key.b64 \
4371 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4372 data=$SECRET,iv=$(<iv.b64)
4373@end example
4374
Brijesh Singha9b49422018-03-08 06:48:41 -06004375@item -object sev-guest,id=@var{id},cbitpos=@var{cbitpos},reduced-phys-bits=@var{val},[sev-device=@var{string},policy=@var{policy},handle=@var{handle},dh-cert-file=@var{file},session-file=@var{file}]
4376
4377Create a Secure Encrypted Virtualization (SEV) guest object, which can be used
4378to provide the guest memory encryption support on AMD processors.
4379
4380When memory encryption is enabled, one of the physical address bit (aka the
4381C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos}
4382is used to provide the C-bit position. The C-bit position is Host family dependent
4383hence user must provide this value. On EPYC, the value should be 47.
4384
4385When memory encryption is enabled, we loose certain bits in physical address space.
4386The @option{reduced-phys-bits} is used to provide the number of bits we loose in
4387physical address space. Similar to C-bit, the value is Host family dependent.
4388On EPYC, the value should be 5.
4389
4390The @option{sev-device} provides the device file to use for communicating with
4391the SEV firmware running inside AMD Secure Processor. The default device is
4392'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are
4393created by CCP driver.
4394
4395The @option{policy} provides the guest policy to be enforced by the SEV firmware
4396and restrict what configuration and operational commands can be performed on this
4397guest by the hypervisor. The policy should be provided by the guest owner and is
4398bound to the guest and cannot be changed throughout the lifetime of the guest.
4399The default is 0.
4400
4401If guest @option{policy} allows sharing the key with another SEV guest then
4402@option{handle} can be use to provide handle of the guest from which to share
4403the key.
4404
4405The @option{dh-cert-file} and @option{session-file} provides the guest owner's
4406Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters
4407are used for establishing a cryptographic session with the guest owner to
4408negotiate keys used for attestation. The file must be encoded in base64.
4409
4410e.g to launch a SEV guest
4411@example
4412 # $QEMU \
4413 ......
4414 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4415 -machine ...,memory-encryption=sev0
4416 .....
4417
4418@end example
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004419@end table
4420
4421ETEXI
4422
4423
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004424HXCOMM This is the last statement. Insert new options before this line!
4425STEXI
4426@end table
4427ETEXI