blob: 521511ec1308491b31fd0e036b6fab0ae7bbc6d5 [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 " memory-encryption=@var{} memory encryption object to use (default=none)\n",
Jan Kiszka80f52a62011-07-23 12:39:46 +020047 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000048STEXI
Jan Kiszka80f52a62011-07-23 12:39:46 +020049@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
50@findex -machine
Peter Maydell585f6032012-10-04 16:22:01 +010051Select the emulated machine by @var{name}. Use @code{-machine help} to list
Daniel P. Berrange8bfce832017-07-25 15:10:41 +010052available machines.
53
54For architectures which aim to support live migration compatibility
55across releases, each release will introduce a new versioned machine
56type. For example, the 2.8.0 release introduced machine types
57``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures.
58
59To allow live migration of guests from QEMU version 2.8.0, to QEMU
60version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8''
61and ``pc-q35-2.8'' machines too. To allow users live migrating VMs
62to skip multiple intermediate releases when upgrading, new releases
63of QEMU will support machine types from many previous versions.
64
65Supported machine properties are:
Jan Kiszka80f52a62011-07-23 12:39:46 +020066@table @option
67@item accel=@var{accels1}[:@var{accels2}[:...]]
68This is used to enable an accelerator. Depending on the target architecture,
Justin Terry (VM)d661d9a2018-01-22 13:07:46 -080069kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
Thomas Huthbde4d922017-05-04 07:24:41 +020070more than one accelerator specified, the next one is used if the previous one
71fails to initialize.
Jan Kiszka6a48ffa2011-10-15 13:43:48 +020072@item kernel_irqchip=on|off
Matt Gingell32c18a22015-11-16 10:03:06 -080073Controls in-kernel irqchip support for the chosen accelerator when available.
Tiejun Chen79814172015-07-15 13:37:45 +080074@item gfx_passthru=on|off
75Enables IGD GFX passthrough support for the chosen machine when available.
Don Slutzd1048be2014-11-21 11:18:52 -050076@item vmport=on|off|auto
77Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
78value based on accel. For accel=xen the default is off otherwise the default
79is on.
Jan Kiszka39d69602012-01-25 18:14:15 +010080@item kvm_shadow_mem=size
81Defines the size of the KVM shadow MMU.
Jason Baronddb97f12012-08-02 15:44:16 -040082@item dump-guest-core=on|off
83Include guest memory in a core dump. The default is on.
Luiz Capitulino8490fc72012-09-05 16:50:16 -030084@item mem-merge=on|off
85Enables or disables memory merge support. This feature, when supported by
86the host, de-duplicates identical memory pages among VMs instances
87(enabled by default).
Tony Krowiak2eb1cd02015-03-12 13:53:51 +010088@item aes-key-wrap=on|off
89Enables or disables AES key wrapping support on s390-ccw hosts. This feature
90controls whether AES wrapping keys will be created to allow
91execution of AES cryptographic functions. The default is on.
92@item dea-key-wrap=on|off
93Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
94controls whether DEA wrapping keys will be created to allow
95execution of DEA cryptographic functions. The default is on.
Xiao Guangrong87252e12015-12-02 15:20:58 +080096@item nvdimm=on|off
97Enables or disables NVDIMM support. The default is off.
Peter Xu16f72442017-07-07 10:54:08 +080098@item enforce-config-section=on|off
99If @option{enforce-config-section} is set to @var{on}, force migration
100code to send configuration section even if the machine-type sets the
101@option{migration.send-configuration} property to @var{off}.
102NOTE: this parameter is deprecated. Please use @option{-global}
103@option{migration.send-configuration}=@var{on|off} instead.
Brijesh Singhdb588192018-03-08 06:48:38 -0600104@item memory-encryption=@var{}
105Memory encryption object to use. The default is none.
Jan Kiszka80f52a62011-07-23 12:39:46 +0200106@end table
blueswir15824d652009-03-28 06:44:27 +0000107ETEXI
108
Jan Kiszka80f52a62011-07-23 12:39:46 +0200109HXCOMM Deprecated by -machine
110DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
111
blueswir15824d652009-03-28 06:44:27 +0000112DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
Peter Maydell585f6032012-10-04 16:22:01 +0100113 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000114STEXI
115@item -cpu @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100116@findex -cpu
Peter Maydell585f6032012-10-04 16:22:01 +0100117Select CPU model (@code{-cpu help} for list and additional feature selection)
blueswir15824d652009-03-28 06:44:27 +0000118ETEXI
119
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000120DEF("accel", HAS_ARG, QEMU_OPTION_accel,
121 "-accel [accel=]accelerator[,thread=single|multi]\n"
Justin Terry (VM)d661d9a2018-01-22 13:07:46 -0800122 " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
Eduardo Habkost0b3c5c82018-06-11 16:56:07 -0300123 " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000124STEXI
125@item -accel @var{name}[,prop=@var{value}[,...]]
126@findex -accel
127This is used to enable an accelerator. Depending on the target architecture,
Justin Terry (VM)d661d9a2018-01-22 13:07:46 -0800128kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
Thomas Huthbde4d922017-05-04 07:24:41 +0200129more than one accelerator specified, the next one is used if the previous one
130fails to initialize.
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000131@table @option
132@item thread=single|multi
133Controls number of TCG threads. When the TCG is multi-threaded there will be one
134thread per vCPU therefor taking advantage of additional host cores. The default
135is to enable multi-threading where both the back-end and front-ends support it and
136no incompatible TCG features have been enabled (e.g. icount/replay).
137@end table
138ETEXI
139
blueswir15824d652009-03-28 06:44:27 +0000140DEF("smp", HAS_ARG, QEMU_OPTION_smp,
Michael Tokarev12b7f572013-06-24 15:06:52 +0400141 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
Jes Sorensen6be68d72009-07-23 17:03:42 +0200142 " set the number of CPUs to 'n' [default=1]\n"
143 " maxcpus= maximum number of total cpus, including\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -0700144 " offline CPUs for hotplug, etc\n"
Andre Przywara58a04db2009-08-28 10:49:57 +0200145 " cores= number of CPU cores on one socket\n"
146 " threads= number of threads on one CPU core\n"
Blue Swirlad960902010-03-29 19:23:52 +0000147 " sockets= number of discrete sockets in the system\n",
148 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000149STEXI
Michael Tokarev12b7f572013-06-24 15:06:52 +0400150@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100151@findex -smp
blueswir15824d652009-03-28 06:44:27 +0000152Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
153CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
154to 4.
Andre Przywara58a04db2009-08-28 10:49:57 +0200155For the PC target, the number of @var{cores} per socket, the number
156of @var{threads} per cores and the total number of @var{sockets} can be
157specified. Missing values will be computed. If any on the three values is
158given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
159specifies the maximum number of hotpluggable CPUs.
blueswir15824d652009-03-28 06:44:27 +0000160ETEXI
161
aliguori268a3622009-04-21 22:30:27 +0000162DEF("numa", HAS_ARG, QEMU_OPTION_numa,
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200163 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
He Chen0f203432017-04-27 10:35:58 +0800164 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
Igor Mammedov2d19c652017-11-28 15:53:58 +0100165 "-numa dist,src=source,dst=destination,val=distance\n"
166 "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n",
167 QEMU_ARCH_ALL)
aliguori268a3622009-04-21 22:30:27 +0000168STEXI
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200169@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
170@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
He Chen0f203432017-04-27 10:35:58 +0800171@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
Igor Mammedov419fcde2017-05-10 13:30:01 +0200172@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 +0100173@findex -numa
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200174Define a NUMA node and assign RAM and VCPUs to it.
He Chen0f203432017-04-27 10:35:58 +0800175Set the NUMA distance from a source node to a destination node.
Paolo Bonzini7febe362014-05-14 17:43:17 +0800176
Igor Mammedov419fcde2017-05-10 13:30:01 +0200177Legacy VCPU assignment uses @samp{cpus} option where
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200178@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
179@samp{cpus} option represent a contiguous range of CPU indexes
180(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
181set of VCPUs can be represented by providing multiple @samp{cpus}
182options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
183split between them.
184
185For example, the following option assigns VCPUs 0, 1, 2 and 5 to
186a NUMA node:
187@example
188-numa node,cpus=0-2,cpus=5
189@end example
190
Igor Mammedov419fcde2017-05-10 13:30:01 +0200191@samp{cpu} option is a new alternative to @samp{cpus} option
192which uses @samp{socket-id|core-id|thread-id} properties to assign
193CPU objects to a @var{node} using topology layout properties of CPU.
194The set of properties is machine specific, and depends on used
195machine type/@samp{smp} options. It could be queried with
196@samp{hotpluggable-cpus} monitor command.
197@samp{node-id} property specifies @var{node} to which CPU object
198will be assigned, it's required for @var{node} to be declared
199with @samp{node} option before it's used with @samp{cpu} option.
200
201For example:
202@example
203-M pc \
204-smp 1,sockets=2,maxcpus=2 \
205-numa node,nodeid=0 -numa node,nodeid=1 \
206-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
207@end example
208
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200209@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
210assigns RAM from a given memory backend device to a node. If
211@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
212split equally between them.
213
214@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
215if one node uses @samp{memdev}, all of them have to use it.
216
He Chen0f203432017-04-27 10:35:58 +0800217@var{source} and @var{destination} are NUMA node IDs.
218@var{distance} is the NUMA distance from @var{source} to @var{destination}.
219The distance from a node to itself is always 10. If any pair of nodes is
220given a distance, then all pairs must be given distances. Although, when
221distances are only given in one direction for each pair of nodes, then
222the distances in the opposite directions are assumed to be the same. If,
223however, an asymmetrical pair of distances is given for even one node
224pair, then all node pairs must be provided distance values for both
225directions, even when they are symmetrical. When a node is unreachable
226from another node, set the pair's distance to 255.
227
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200228Note that the -@option{numa} option doesn't allocate any of the
229specified resources, it just assigns existing resources to NUMA
230nodes. This means that one still has to use the @option{-m},
231@option{-smp} options to allocate RAM and VCPUs respectively.
232
aliguori268a3622009-04-21 22:30:27 +0000233ETEXI
234
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100235DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
236 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
237 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
238STEXI
239@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
240@findex -add-fd
241
242Add a file descriptor to an fd set. Valid options are:
243
244@table @option
245@item fd=@var{fd}
246This option defines the file descriptor of which a duplicate is added to fd set.
247The file descriptor cannot be stdin, stdout, or stderr.
248@item set=@var{set}
249This option defines the ID of the fd set to add the file descriptor to.
250@item opaque=@var{opaque}
251This option defines a free-form string that can be used to describe @var{fd}.
252@end table
253
254You can open an image using pre-opened file descriptors from an fd set:
255@example
256qemu-system-i386
257-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
258-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
259-drive file=/dev/fdset/2,index=0,media=disk
260@end example
261ETEXI
262
263DEF("set", HAS_ARG, QEMU_OPTION_set,
264 "-set group.id.arg=value\n"
265 " set <arg> parameter for item <id> of type <group>\n"
266 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
267STEXI
268@item -set @var{group}.@var{id}.@var{arg}=@var{value}
269@findex -set
Michael Tokareve1f3b972016-10-16 17:21:37 +0300270Set parameter @var{arg} for item @var{id} of type @var{group}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100271ETEXI
272
273DEF("global", HAS_ARG, QEMU_OPTION_global,
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200274 "-global driver.property=value\n"
275 "-global driver=driver,property=property,value=value\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100276 " set a global default for a driver property\n",
277 QEMU_ARCH_ALL)
278STEXI
279@item -global @var{driver}.@var{prop}=@var{value}
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200280@itemx -global driver=@var{driver},property=@var{property},value=@var{value}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100281@findex -global
282Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
283
284@example
Markus Armbruster1c9f3b82017-05-09 11:41:15 +0200285qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100286@end example
287
Michael Tokareva295d242017-09-23 19:31:59 +0300288In particular, you can use this to set driver properties for devices which are
289created automatically by the machine model. To create a device which is not
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100290created automatically and set properties on it, use -@option{device}.
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200291
Markus Armbrusterae08fd52015-06-15 14:35:58 +0200292-global @var{driver}.@var{prop}=@var{value} is shorthand for -global
293driver=@var{driver},property=@var{prop},value=@var{value}. The
294longhand syntax works even when @var{driver} contains a dot.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100295ETEXI
296
297DEF("boot", HAS_ARG, QEMU_OPTION_boot,
298 "-boot [order=drives][,once=drives][,menu=on|off]\n"
Amos Kongc8a6ae82013-03-19 14:23:27 +0800299 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100300 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
301 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
302 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
303 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
304 QEMU_ARCH_ALL)
305STEXI
Amos Kongc8a6ae82013-03-19 14:23:27 +0800306@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 +0100307@findex -boot
308Specify boot order @var{drives} as a string of drive letters. Valid
Gongleid274e072015-07-03 17:50:57 +0800309drive letters depend on the target architecture. The x86 PC uses: a, b
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100310(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
311from network adapter 1-4), hard disk boot is the default. To apply a
312particular boot order only on the first startup, specify it via
Thomas Huthc0d9f7d2017-02-28 18:40:01 +0100313@option{once}. Note that the @option{order} or @option{once} parameter
314should not be used together with the @option{bootindex} property of
315devices, since the firmware implementations normally do not support both
316at the same time.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100317
318Interactive boot menus/prompts can be enabled via @option{menu=on} as far
319as firmware/BIOS supports them. The default is non-interactive boot.
320
321A splash picture could be passed to bios, enabling user to show it as logo,
322when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
323supports them. Currently Seabios for X86 system support it.
324limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
325format(true color). The resolution should be supported by the SVGA mode, so
326the recommended is 320x240, 640x480, 800x640.
327
328A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
329when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
330reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
331system support it.
332
Amos Kongc8a6ae82013-03-19 14:23:27 +0800333Do strict boot via @option{strict=on} as far as firmware/BIOS
334supports it. This only effects when boot priority is changed by
335bootindex options. The default is non-strict boot.
336
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100337@example
338# try to boot from network first, then from hard disk
339qemu-system-i386 -boot order=nc
340# boot from CD-ROM first, switch back to default order after reboot
341qemu-system-i386 -boot once=d
342# boot with a splash picture for 5 seconds.
343qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
344@end example
345
346Note: The legacy format '-boot @var{drives}' is still supported but its
347use is discouraged as it may be removed from future versions.
348ETEXI
349
350DEF("m", HAS_ARG, QEMU_OPTION_m,
Michael Tokarev89f3ea22016-11-10 17:51:32 +0300351 "-m [size=]megs[,slots=n,maxmem=size]\n"
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100352 " configure guest RAM\n"
Alexander Graf0daba1f2015-06-05 11:05:03 +0200353 " size: initial amount of guest memory\n"
Igor Mammedovc270fb92014-06-02 15:25:02 +0200354 " slots: number of hotplug slots (default: none)\n"
Matthew Rosatob6fe0122014-08-28 11:25:33 -0400355 " maxmem: maximum amount of guest memory (default: none)\n"
356 "NOTE: Some architectures might enforce a specific granularity\n",
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100357 QEMU_ARCH_ALL)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100358STEXI
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500359@item -m [size=]@var{megs}[,slots=n,maxmem=size]
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100360@findex -m
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500361Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
362Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
363megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
364could be used to set amount of hotpluggable memory slots and maximum amount of
365memory. Note that @var{maxmem} must be aligned to the page size.
366
367For example, the following command-line sets the guest startup RAM size to
3681GB, creates 3 slots to hotplug additional memory and sets the maximum
369memory the guest can reach to 4GB:
370
371@example
372qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
373@end example
374
375If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
376be enabled and the guest startup RAM will never increase.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100377ETEXI
378
379DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
380 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
381STEXI
382@item -mem-path @var{path}
383@findex -mem-path
384Allocate guest RAM from a temporarily created file in @var{path}.
385ETEXI
386
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100387DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
388 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
389 QEMU_ARCH_ALL)
390STEXI
391@item -mem-prealloc
392@findex -mem-prealloc
393Preallocate memory when using -mem-path.
394ETEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100395
396DEF("k", HAS_ARG, QEMU_OPTION_k,
397 "-k language use keyboard layout (for example 'fr' for French)\n",
398 QEMU_ARCH_ALL)
399STEXI
400@item -k @var{language}
401@findex -k
402Use keyboard layout @var{language} (for example @code{fr} for
403French). This option is only needed where it is not easy to get raw PC
Samuel Thibault32945472016-06-22 17:48:31 +0200404keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100405display). You don't normally need to use it on PC/Linux or PC/Windows
406hosts.
407
408The available layouts are:
409@example
410ar de-ch es fo fr-ca hu ja mk no pt-br sv
411da en-gb et fr fr-ch is lt nl pl ru th
412de en-us fi fr-be hr it lv nl-be pt sl tr
413@end example
414
415The default is @code{en-us}.
416ETEXI
417
418
419DEF("audio-help", 0, QEMU_OPTION_audio_help,
420 "-audio-help print list of audio drivers and their options\n",
421 QEMU_ARCH_ALL)
422STEXI
423@item -audio-help
424@findex -audio-help
425Will show the audio subsystem help: list of drivers, tunable
426parameters.
427ETEXI
428
429DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
430 "-soundhw c1,... enable audio support\n"
431 " and only specified sound cards (comma separated list)\n"
432 " use '-soundhw help' to get the list of supported cards\n"
433 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
434STEXI
435@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
436@findex -soundhw
437Enable audio and selected sound hardware. Use 'help' to print all
438available sound hardware.
439
440@example
441qemu-system-i386 -soundhw sb16,adlib disk.img
442qemu-system-i386 -soundhw es1370 disk.img
443qemu-system-i386 -soundhw ac97 disk.img
444qemu-system-i386 -soundhw hda disk.img
445qemu-system-i386 -soundhw all disk.img
446qemu-system-i386 -soundhw help
447@end example
448
449Note that Linux's i810_audio OSS kernel (for AC97) module might
450require manually specifying clocking.
451
452@example
453modprobe i810_audio clocking=48000
454@end example
455ETEXI
456
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100457DEF("device", HAS_ARG, QEMU_OPTION_device,
458 "-device driver[,prop[=value][,...]]\n"
459 " add device (based on driver)\n"
460 " prop=value,... sets driver properties\n"
461 " use '-device help' to print all possible drivers\n"
462 " use '-device driver,help' to print all possible properties\n",
463 QEMU_ARCH_ALL)
464STEXI
465@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
466@findex -device
467Add device @var{driver}. @var{prop}=@var{value} sets driver
468properties. Valid properties depend on the driver. To get help on
469possible drivers and properties, use @code{-device help} and
470@code{-device @var{driver},help}.
Corey Minyardf8490452015-12-17 12:50:10 -0600471
472Some drivers are:
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200473@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 -0600474
475Add an IPMI BMC. This is a simulation of a hardware management
476interface processor that normally sits on a system. It provides
477a watchdog and the ability to reset and power control the system.
478You need to connect this to an IPMI interface to make it useful
479
480The IPMI slave address to use for the BMC. The default is 0x20.
481This address is the BMC's address on the I2C network of management
482controllers. If you don't know what this means, it is safe to ignore
483it.
484
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200485@table @option
486@item bmc=@var{id}
487The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
488@item slave_addr=@var{val}
489Define slave address to use for the BMC. The default is 0x20.
490@item sdrfile=@var{file}
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200491file containing raw Sensor Data Records (SDR) data. The default is none.
492@item fruareasize=@var{val}
493size of a Field Replaceable Unit (FRU) area. The default is 1024.
494@item frudatafile=@var{file}
495file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200496@end table
497
Corey Minyardf8490452015-12-17 12:50:10 -0600498@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
499
500Add a connection to an external IPMI BMC simulator. Instead of
501locally emulating the BMC like the above item, instead connect
502to an external entity that provides the IPMI services.
503
504A connection is made to an external BMC simulator. If you do this, it
505is strongly recommended that you use the "reconnect=" chardev option
506to reconnect to the simulator if the connection is lost. Note that if
507this is not used carefully, it can be a security issue, as the
508interface has the ability to send resets, NMIs, and power off the VM.
509It's best if QEMU makes a connection to an external simulator running
510on a secure port on localhost, so neither the simulator nor QEMU is
511exposed to any outside network.
512
513See the "lanserv/README.vm" file in the OpenIPMI library for more
514details on the external interface.
515
516@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
517
518Add a KCS IPMI interafce on the ISA bus. This also adds a
519corresponding ACPI and SMBIOS entries, if appropriate.
520
521@table @option
522@item bmc=@var{id}
523The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
524@item ioport=@var{val}
525Define the I/O address of the interface. The default is 0xca0 for KCS.
526@item irq=@var{val}
527Define the interrupt to use. The default is 5. To disable interrupts,
528set this to 0.
529@end table
530
531@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
532
533Like the KCS interface, but defines a BT interface. The default port is
5340xe4 and the default interrupt is 5.
535
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100536ETEXI
537
538DEF("name", HAS_ARG, QEMU_OPTION_name,
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000539 "-name string1[,process=string2][,debug-threads=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100540 " set the name of the guest\n"
Roman Bolshakov479a5742018-12-17 23:26:01 +0300541 " string1 sets the window title and string2 the process name\n"
542 " When debug-threads is enabled, individual threads are given a separate name\n"
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000543 " NOTE: The thread names are for debugging and not a stable API.\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100544 QEMU_ARCH_ALL)
545STEXI
546@item -name @var{name}
547@findex -name
548Sets the @var{name} of the guest.
549This name will be displayed in the SDL window caption.
550The @var{name} will also be used for the VNC server.
551Also optionally set the top visible process name in Linux.
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000552Naming of individual threads can also be enabled on Linux to aid debugging.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100553ETEXI
554
555DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
556 "-uuid %08x-%04x-%04x-%04x-%012x\n"
557 " specify machine UUID\n", QEMU_ARCH_ALL)
558STEXI
559@item -uuid @var{uuid}
560@findex -uuid
561Set system UUID.
562ETEXI
563
564STEXI
565@end table
566ETEXI
567DEFHEADING()
568
Markus Armbrusterde6b4f92017-10-02 16:03:00 +0200569DEFHEADING(Block device options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100570STEXI
571@table @option
572ETEXI
573
blueswir15824d652009-03-28 06:44:27 +0000574DEF("fda", HAS_ARG, QEMU_OPTION_fda,
Blue Swirlad960902010-03-29 19:23:52 +0000575 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
576DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000577STEXI
578@item -fda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200579@itemx -fdb @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100580@findex -fda
581@findex -fdb
Markus Armbruster92a539d2015-03-17 17:02:20 +0100582Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
blueswir15824d652009-03-28 06:44:27 +0000583ETEXI
584
585DEF("hda", HAS_ARG, QEMU_OPTION_hda,
Blue Swirlad960902010-03-29 19:23:52 +0000586 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
587DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000588DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
Blue Swirlad960902010-03-29 19:23:52 +0000589 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
590DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000591STEXI
592@item -hda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200593@itemx -hdb @var{file}
594@itemx -hdc @var{file}
595@itemx -hdd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100596@findex -hda
597@findex -hdb
598@findex -hdc
599@findex -hdd
blueswir15824d652009-03-28 06:44:27 +0000600Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
601ETEXI
602
603DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
Blue Swirlad960902010-03-29 19:23:52 +0000604 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
605 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000606STEXI
607@item -cdrom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100608@findex -cdrom
blueswir15824d652009-03-28 06:44:27 +0000609Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
610@option{-cdrom} at the same time). You can use the host CD-ROM by
611using @file{/dev/cdrom} as filename (@pxref{host_drives}).
612ETEXI
613
Markus Armbruster42e5f392017-02-28 22:27:07 +0100614DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
615 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
616 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
617 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
618 " [,driver specific parameters...]\n"
619 " configure a block backend\n", QEMU_ARCH_ALL)
Kevin Wolfdfaca462016-09-22 16:53:24 +0200620STEXI
621@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
622@findex -blockdev
623
Kevin Wolf370e8322016-09-22 17:24:38 +0200624Define a new block driver node. Some of the options apply to all block drivers,
625other options are only accepted for a specific block driver. See below for a
626list of generic options and options for the most common block drivers.
627
628Options that expect a reference to another node (e.g. @code{file}) can be
629given in two ways. Either you specify the node name of an already existing node
630(file=@var{node-name}), or you define a new node inline, adding options
631for the referenced node after a dot (file.filename=@var{path},file.aio=native).
632
633A block driver node created with @option{-blockdev} can be used for a guest
634device by specifying its node name for the @code{drive} property in a
635@option{-device} argument that defines a block device.
Kevin Wolfdfaca462016-09-22 16:53:24 +0200636
637@table @option
638@item Valid options for any block driver node:
639
640@table @code
641@item driver
642Specifies the block driver to use for the given node.
643@item node-name
644This defines the name of the block driver node by which it will be referenced
645later. The name must be unique, i.e. it must not match the name of a different
646block driver node, or (if you use @option{-drive} as well) the ID of a drive.
647
648If no node name is specified, it is automatically generated. The generated node
649name is not intended to be predictable and changes between QEMU invocations.
650For the top level, an explicit node name must be specified.
651@item read-only
652Open the node read-only. Guest write attempts will fail.
653@item cache.direct
654The host page cache can be avoided with @option{cache.direct=on}. This will
655attempt to do disk IO directly to the guest's memory. QEMU may still perform an
656internal copy of the data.
657@item cache.no-flush
658In case you don't care about data integrity over host failures, you can use
659@option{cache.no-flush=on}. This option tells QEMU that it never needs to write
660any data to the disk but can instead keep things in cache. If anything goes
661wrong, like your host losing power, the disk storage getting disconnected
662accidentally, etc. your image will most probably be rendered unusable.
663@item discard=@var{discard}
664@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
665whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
666ignored or passed to the filesystem. Some machine types may not support
667discard requests.
668@item detect-zeroes=@var{detect-zeroes}
669@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
670conversion of plain zero writes by the OS to driver specific optimized
671zero write commands. You may even choose "unmap" if @var{discard} is set
672to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
673@end table
674
Kevin Wolf370e8322016-09-22 17:24:38 +0200675@item Driver-specific options for @code{file}
676
677This is the protocol-level block driver for accessing regular files.
678
679@table @code
680@item filename
681The path to the image file in the local filesystem
682@item aio
683Specifies the AIO backend (threads/native, default: threads)
Fam Zheng1878eaf2017-11-24 16:53:51 +0800684@item locking
685Specifies whether the image file is protected with Linux OFD / POSIX locks. The
686default is to use the Linux Open File Descriptor API if available, otherwise no
687lock is applied. (auto/on/off, default: auto)
Kevin Wolf370e8322016-09-22 17:24:38 +0200688@end table
689Example:
690@example
691-blockdev driver=file,node-name=disk,filename=disk.img
692@end example
693
694@item Driver-specific options for @code{raw}
695
696This is the image format block driver for raw images. It is usually
697stacked on top of a protocol level block driver such as @code{file}.
698
699@table @code
700@item file
701Reference to or definition of the data source block driver node
702(e.g. a @code{file} driver node)
703@end table
704Example 1:
705@example
706-blockdev driver=file,node-name=disk_file,filename=disk.img
707-blockdev driver=raw,node-name=disk,file=disk_file
708@end example
709Example 2:
710@example
711-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
712@end example
713
714@item Driver-specific options for @code{qcow2}
715
716This is the image format block driver for qcow2 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
724@item backing
725Reference to or definition of the backing file block device (default is taken
Max Reitz4f7be282018-02-24 16:40:33 +0100726from the image file). It is allowed to pass @code{null} here in order to disable
727the default backing file.
Kevin Wolf370e8322016-09-22 17:24:38 +0200728
729@item lazy-refcounts
730Whether to enable the lazy refcounts feature (on/off; default is taken from the
731image file)
732
733@item cache-size
734The maximum total size of the L2 table and refcount block caches in bytes
Leonid Bloch40fb2152018-09-26 19:04:39 +0300735(default: the sum of l2-cache-size and refcount-cache-size)
Kevin Wolf370e8322016-09-22 17:24:38 +0200736
737@item l2-cache-size
738The maximum size of the L2 table cache in bytes
Leonid Bloch80668d02018-09-26 19:04:44 +0300739(default: if cache-size is not specified - 32M on Linux platforms, and 8M on
740non-Linux platforms; otherwise, as large as possible within the cache-size,
741while permitting the requested or the minimal refcount cache size)
Kevin Wolf370e8322016-09-22 17:24:38 +0200742
743@item refcount-cache-size
744The maximum size of the refcount block cache in bytes
Leonid Bloch40fb2152018-09-26 19:04:39 +0300745(default: 4 times the cluster size; or if cache-size is specified, the part of
746it which is not used for the L2 cache)
Kevin Wolf370e8322016-09-22 17:24:38 +0200747
748@item cache-clean-interval
749Clean unused entries in the L2 and refcount caches. The interval is in seconds.
Leonid Bloche3a7b452018-09-29 12:54:54 +0300750The default value is 600 on supporting platforms, and 0 on other platforms.
751Setting it to 0 disables this feature.
Kevin Wolf370e8322016-09-22 17:24:38 +0200752
753@item pass-discard-request
754Whether discard requests to the qcow2 device should be forwarded to the data
755source (on/off; default: on if discard=unmap is specified, off otherwise)
756
757@item pass-discard-snapshot
758Whether discard requests for the data source should be issued when a snapshot
759operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
760default: on)
761
762@item pass-discard-other
763Whether discard requests for the data source should be issued on other
764occasions where a cluster gets freed (on/off; default: off)
765
766@item overlap-check
767Which overlap checks to perform for writes to the image
768(none/constant/cached/all; default: cached). For details or finer
769granularity control refer to the QAPI documentation of @code{blockdev-add}.
770@end table
771
772Example 1:
773@example
774-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
775-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
776@end example
777Example 2:
778@example
779-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
780@end example
781
782@item Driver-specific options for other drivers
783Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
784
Kevin Wolfdfaca462016-09-22 16:53:24 +0200785@end table
786
787ETEXI
Markus Armbruster42e5f392017-02-28 22:27:07 +0100788
blueswir15824d652009-03-28 06:44:27 +0000789DEF("drive", HAS_ARG, QEMU_OPTION_drive,
790 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100791 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
Kevin Wolf572023f2018-06-13 11:01:30 +0200792 " [,snapshot=on|off][,rerror=ignore|stop|report]\n"
Stefan Hajnoczid1db7602014-04-23 13:55:37 +0200793 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000794 " [,readonly=on|off][,copy-on-read=on|off]\n"
Peter Lieven2f7133b2014-07-28 21:53:02 +0200795 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
Benoît Canet3e9fab62013-09-02 14:14:40 +0200796 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
797 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
798 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
799 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
Benoît Canet2024c1d2013-09-02 14:14:41 +0200800 " [[,iops_size=is]]\n"
Alberto Garcia76f4afb2015-06-08 18:17:44 +0200801 " [[,group=g]]\n"
Blue Swirlad960902010-03-29 19:23:52 +0000802 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000803STEXI
804@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100805@findex -drive
blueswir15824d652009-03-28 06:44:27 +0000806
Kevin Wolfdfaca462016-09-22 16:53:24 +0200807Define a new drive. This includes creating a block driver node (the backend) as
808well as a guest device, and is mostly a shortcut for defining the corresponding
809@option{-blockdev} and @option{-device} options.
810
811@option{-drive} accepts all options that are accepted by @option{-blockdev}. In
812addition, it knows the following options:
blueswir15824d652009-03-28 06:44:27 +0000813
Kevin Wolfb3f046c2009-10-09 10:58:35 +0200814@table @option
blueswir15824d652009-03-28 06:44:27 +0000815@item file=@var{file}
816This option defines which disk image (@pxref{disk_images}) to use with
817this drive. If the filename contains comma, you must double it
818(for instance, "file=my,,file" to use file "my,file").
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +1100819
820Special files such as iSCSI devices can be specified using protocol
821specific URLs. See the section for "Device URL Syntax" for more information.
blueswir15824d652009-03-28 06:44:27 +0000822@item if=@var{interface}
823This option defines on which type on interface the drive is connected.
Craig Jellicked1fcd02017-03-17 08:49:55 -0700824Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
blueswir15824d652009-03-28 06:44:27 +0000825@item bus=@var{bus},unit=@var{unit}
826These options define where is connected the drive by defining the bus number and
827the unit id.
828@item index=@var{index}
829This option defines where is connected the drive by using an index in the list
830of available connectors of a given interface type.
831@item media=@var{media}
832This option defines the type of the media: disk or cdrom.
blueswir15824d652009-03-28 06:44:27 +0000833@item snapshot=@var{snapshot}
Michael Tokarev9d85d552014-04-07 13:34:58 +0400834@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
835(see @option{-snapshot}).
blueswir15824d652009-03-28 06:44:27 +0000836@item cache=@var{cache}
Kevin Wolfdfaca462016-09-22 16:53:24 +0200837@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
838and controls how the host cache is used to access block data. This is a
839shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
840options (as in @option{-blockdev}), and additionally @option{cache.writeback},
841which provides a default for the @option{write-cache} option of block guest
842devices (as in @option{-device}). The modes correspond to the following
843settings:
844
845@c Our texi2pod.pl script doesn't support @multitable, so fall back to using
846@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
847@c and the HTML output.
848@example
849@ │ cache.writeback cache.direct cache.no-flush
850─────────────┼─────────────────────────────────────────────────
851writeback │ on off off
852none │ on on off
853writethrough │ off off off
854directsync │ off on off
855unsafe │ on off on
856@end example
857
858The default mode is @option{cache=writeback}.
859
Christoph Hellwig5c6c3a62009-08-20 16:58:35 +0200860@item aio=@var{aio}
861@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
blueswir15824d652009-03-28 06:44:27 +0000862@item format=@var{format}
863Specify which disk @var{format} will be used rather than detecting
Michael Tokarevd33c8a72016-05-18 15:47:53 +0300864the format. Can be used to specify format=raw to avoid interpreting
blueswir15824d652009-03-28 06:44:27 +0000865an untrusted format header.
Luiz Capitulinoae73e592011-07-12 17:35:08 -0300866@item werror=@var{action},rerror=@var{action}
867Specify which @var{action} to take on write and read errors. Valid actions are:
868"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
869"report" (report the error to the guest), "enospc" (pause QEMU only if the
870host disk is full; report the error to the guest otherwise).
871The default setting is @option{werror=enospc} and @option{rerror=report}.
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000872@item copy-on-read=@var{copy-on-read}
873@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
874file sectors into the image file.
Stefan Hajnoczi01f9cfa2017-03-01 11:50:24 +0000875@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
876Specify bandwidth throttling limits in bytes per second, either for all request
877types or for reads or writes only. Small values can lead to timeouts or hangs
878inside the guest. A safe minimum for disks is 2 MB/s.
879@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
880Specify bursts in bytes per second, either for all request types or for reads
881or writes only. Bursts allow the guest I/O to spike above the limit
882temporarily.
883@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
884Specify request rate limits in requests per second, either for all request
885types or for reads or writes only.
886@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
887Specify bursts in requests per second, either for all request types or for reads
888or writes only. Bursts allow the guest I/O to spike above the limit
889temporarily.
890@item iops_size=@var{is}
891Let every @var{is} bytes of a request count as a new request for iops
892throttling purposes. Use this option to prevent guests from circumventing iops
893limits by sending fewer but larger requests.
894@item group=@var{g}
895Join a throttling quota group with given name @var{g}. All drives that are
896members of the same group are accounted for together. Use this option to
897prevent guests from circumventing throttling limits by using many small disks
898instead of a single larger disk.
blueswir15824d652009-03-28 06:44:27 +0000899@end table
900
Kevin Wolfdfaca462016-09-22 16:53:24 +0200901By default, the @option{cache.writeback=on} mode is used. It will report data
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100902writes as completed as soon as the data is present in the host page cache.
903This is safe as long as your guest OS makes sure to correctly flush disk caches
904where needed. If your guest OS does not handle volatile disk write caches
905correctly and your host crashes or loses power, then the guest may experience
906data corruption.
blueswir15824d652009-03-28 06:44:27 +0000907
Kevin Wolfdfaca462016-09-22 16:53:24 +0200908For such guests, you should consider using @option{cache.writeback=off}. This
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100909means that the host page cache will be used to read and write data, but write
910notification will be sent to the guest only after QEMU has made sure to flush
911each write to the disk. Be aware that this has a major impact on performance.
blueswir15824d652009-03-28 06:44:27 +0000912
Kevin Wolfdfaca462016-09-22 16:53:24 +0200913When using the @option{-snapshot} option, unsafe caching is always used.
Alexander Graf016f5cf2010-05-26 17:51:49 +0200914
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000915Copy-on-read avoids accessing the same backing file sectors repeatedly and is
916useful when the backing file is over a slow network. By default copy-on-read
917is off.
918
blueswir15824d652009-03-28 06:44:27 +0000919Instead of @option{-cdrom} you can use:
920@example
Stefan Weil3804da92012-05-11 22:21:50 +0200921qemu-system-i386 -drive file=file,index=2,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000922@end example
923
924Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
925use:
926@example
Stefan Weil3804da92012-05-11 22:21:50 +0200927qemu-system-i386 -drive file=file,index=0,media=disk
928qemu-system-i386 -drive file=file,index=1,media=disk
929qemu-system-i386 -drive file=file,index=2,media=disk
930qemu-system-i386 -drive file=file,index=3,media=disk
blueswir15824d652009-03-28 06:44:27 +0000931@end example
932
Corey Bryant587ed6b2012-10-18 15:19:34 -0400933You can open an image using pre-opened file descriptors from an fd set:
934@example
935qemu-system-i386
936-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
937-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
938-drive file=/dev/fdset/2,index=0,media=disk
939@end example
940
blueswir15824d652009-03-28 06:44:27 +0000941You can connect a CDROM to the slave of ide0:
942@example
Stefan Weil3804da92012-05-11 22:21:50 +0200943qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000944@end example
945
946If you don't specify the "file=" argument, you define an empty drive:
947@example
Stefan Weil3804da92012-05-11 22:21:50 +0200948qemu-system-i386 -drive if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000949@end example
950
blueswir15824d652009-03-28 06:44:27 +0000951Instead of @option{-fda}, @option{-fdb}, you can use:
952@example
Stefan Weil3804da92012-05-11 22:21:50 +0200953qemu-system-i386 -drive file=file,index=0,if=floppy
954qemu-system-i386 -drive file=file,index=1,if=floppy
blueswir15824d652009-03-28 06:44:27 +0000955@end example
956
957By default, @var{interface} is "ide" and @var{index} is automatically
958incremented:
959@example
Stefan Weil3804da92012-05-11 22:21:50 +0200960qemu-system-i386 -drive file=a -drive file=b"
blueswir15824d652009-03-28 06:44:27 +0000961@end example
962is interpreted like:
963@example
Stefan Weil3804da92012-05-11 22:21:50 +0200964qemu-system-i386 -hda a -hdb b
blueswir15824d652009-03-28 06:44:27 +0000965@end example
966ETEXI
967
968DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
Blue Swirlad960902010-03-29 19:23:52 +0000969 "-mtdblock file use 'file' as on-board Flash memory image\n",
970 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000971STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200972@item -mtdblock @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100973@findex -mtdblock
Kevin Wolf4e257e52009-10-09 10:58:36 +0200974Use @var{file} as on-board Flash memory image.
blueswir15824d652009-03-28 06:44:27 +0000975ETEXI
976
977DEF("sd", HAS_ARG, QEMU_OPTION_sd,
Blue Swirlad960902010-03-29 19:23:52 +0000978 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000979STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200980@item -sd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100981@findex -sd
Kevin Wolf4e257e52009-10-09 10:58:36 +0200982Use @var{file} as SecureDigital card image.
blueswir15824d652009-03-28 06:44:27 +0000983ETEXI
984
985DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
Blue Swirlad960902010-03-29 19:23:52 +0000986 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000987STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200988@item -pflash @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100989@findex -pflash
Kevin Wolf4e257e52009-10-09 10:58:36 +0200990Use @var{file} as a parallel flash image.
blueswir15824d652009-03-28 06:44:27 +0000991ETEXI
992
blueswir15824d652009-03-28 06:44:27 +0000993DEF("snapshot", 0, QEMU_OPTION_snapshot,
Blue Swirlad960902010-03-29 19:23:52 +0000994 "-snapshot write to temporary files instead of disk image files\n",
995 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000996STEXI
997@item -snapshot
Stefan Weil6616b2a2010-02-05 23:52:05 +0100998@findex -snapshot
blueswir15824d652009-03-28 06:44:27 +0000999Write to temporary files instead of disk image files. In this case,
1000the raw disk image you use is not written back. You can however force
1001the write back by pressing @key{C-a s} (@pxref{disk_images}).
1002ETEXI
1003
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301004DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301005 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001006 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
Pradeep Jagadeeshb8bbdb82017-02-28 10:31:46 +01001007 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1008 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1009 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1010 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1011 " [[,throttling.iops-size=is]]\n",
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301012 QEMU_ARCH_ALL)
1013
1014STEXI
1015
Tobias Schrammb96feb22017-06-29 15:11:50 +02001016@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 +05301017@findex -fsdev
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301018Define a new file system device. Valid options are:
1019@table @option
1020@item @var{fsdriver}
1021This option specifies the fs driver backend to use.
Greg Kurz93aee842018-12-12 14:18:10 +01001022Currently "local" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301023@item id=@var{id}
1024Specifies identifier for this device
1025@item path=@var{path}
1026Specifies the export path for the file system device. Files under
1027this path will be available to the 9p client on the guest.
1028@item security_model=@var{security_model}
1029Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301030Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301031In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001032credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301033to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301034attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301035file attributes. For "mapped-file" these attributes are stored in the
1036hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301037interact with other unix tools. "none" security model is same as
1038passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301039set file attributes like ownership. Security model is mandatory
Greg Kurz93aee842018-12-12 14:18:10 +01001040only for local fsdriver. Other fsdrivers (like proxy) don't take
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301041security model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301042@item writeout=@var{writeout}
1043This is an optional argument. The only supported value is "immediate".
1044This means that host page cache will be used to read and write data but
1045write notification will be sent to the guest only when the data has been
1046reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301047@item readonly
1048Enables exporting 9p share as a readonly mount for guests. By default
1049read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301050@item socket=@var{socket}
1051Enables proxy filesystem driver to use passed socket file for communicating
1052with virtfs-proxy-helper
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301053@item sock_fd=@var{sock_fd}
1054Enables proxy filesystem driver to use passed socket descriptor for
1055communicating with virtfs-proxy-helper. Usually a helper like libvirt
1056will create socketpair and pass one of the fds as sock_fd
Tobias Schrammb96feb22017-06-29 15:11:50 +02001057@item fmode=@var{fmode}
1058Specifies the default mode for newly created files on the host. Works only
1059with security models "mapped-xattr" and "mapped-file".
1060@item dmode=@var{dmode}
1061Specifies the default mode for newly created directories on the host. Works
1062only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301063@end table
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301064
1065-fsdev option is used along with -device driver "virtio-9p-pci".
1066@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
1067Options for virtio-9p-pci driver are:
1068@table @option
1069@item fsdev=@var{id}
1070Specifies the id value specified along with -fsdev option
1071@item mount_tag=@var{mount_tag}
1072Specifies the tag name to be used by the guest to mount this export point
1073@end table
1074
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301075ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301076
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301077DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301078 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001079 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n",
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301080 QEMU_ARCH_ALL)
1081
1082STEXI
1083
Tobias Schrammb96feb22017-06-29 15:11:50 +02001084@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 +05301085@findex -virtfs
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301086
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301087The general form of a Virtual File system pass-through options are:
1088@table @option
1089@item @var{fsdriver}
1090This option specifies the fs driver backend to use.
Greg Kurz93aee842018-12-12 14:18:10 +01001091Currently "local" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301092@item id=@var{id}
1093Specifies identifier for this device
1094@item path=@var{path}
1095Specifies the export path for the file system device. Files under
1096this path will be available to the 9p client on the guest.
1097@item security_model=@var{security_model}
1098Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301099Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301100In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001101credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301102to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301103attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301104file attributes. For "mapped-file" these attributes are stored in the
1105hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301106interact with other unix tools. "none" security model is same as
1107passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301108set file attributes like ownership. Security model is mandatory only
Greg Kurz93aee842018-12-12 14:18:10 +01001109for local fsdriver. Other fsdrivers (like proxy) don't take security
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301110model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301111@item writeout=@var{writeout}
1112This is an optional argument. The only supported value is "immediate".
1113This means that host page cache will be used to read and write data but
1114write notification will be sent to the guest only when the data has been
1115reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301116@item readonly
1117Enables exporting 9p share as a readonly mount for guests. By default
1118read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301119@item socket=@var{socket}
1120Enables proxy filesystem driver to use passed socket file for
1121communicating with virtfs-proxy-helper. Usually a helper like libvirt
1122will create socketpair and pass one of the fds as sock_fd
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301123@item sock_fd
1124Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1125descriptor for interfacing with virtfs-proxy-helper
Tobias Schrammb96feb22017-06-29 15:11:50 +02001126@item fmode=@var{fmode}
1127Specifies the default mode for newly created files on the host. Works only
1128with security models "mapped-xattr" and "mapped-file".
1129@item dmode=@var{dmode}
1130Specifies the default mode for newly created directories on the host. Works
1131only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301132@end table
1133ETEXI
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301134
Aneesh Kumar K.V9db221a2011-10-25 12:10:40 +05301135DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
1136 "-virtfs_synth Create synthetic file system image\n",
1137 QEMU_ARCH_ALL)
1138STEXI
1139@item -virtfs_synth
1140@findex -virtfs_synth
1141Create synthetic file system image
1142ETEXI
1143
Markus Armbruster61d70482017-10-02 16:03:03 +02001144DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1145 "-iscsi [user=user][,password=password]\n"
1146 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1147 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1148 " [,timeout=timeout]\n"
1149 " iSCSI session parameters\n", QEMU_ARCH_ALL)
1150
blueswir15824d652009-03-28 06:44:27 +00001151STEXI
Markus Armbruster44743142017-10-02 16:03:04 +02001152@item -iscsi
1153@findex -iscsi
1154Configure iSCSI session parameters.
1155ETEXI
1156
1157STEXI
blueswir15824d652009-03-28 06:44:27 +00001158@end table
1159ETEXI
blueswir15824d652009-03-28 06:44:27 +00001160DEFHEADING()
1161
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001162DEFHEADING(USB options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001163STEXI
1164@table @option
1165ETEXI
1166
1167DEF("usb", 0, QEMU_OPTION_usb,
Thomas Hutha358a3a2017-05-19 08:35:16 +02001168 "-usb enable the USB driver (if it is not used by default yet)\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001169 QEMU_ARCH_ALL)
1170STEXI
1171@item -usb
1172@findex -usb
Thomas Hutha358a3a2017-05-19 08:35:16 +02001173Enable the USB driver (if it is not used by default yet).
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001174ETEXI
1175
1176DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1177 "-usbdevice name add the host or guest USB device 'name'\n",
1178 QEMU_ARCH_ALL)
1179STEXI
1180
1181@item -usbdevice @var{devname}
1182@findex -usbdevice
Thomas Hutha358a3a2017-05-19 08:35:16 +02001183Add the USB device @var{devname}. Note that this option is deprecated,
1184please use @code{-device usb-...} instead. @xref{usb_devices}.
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001185
1186@table @option
1187
1188@item mouse
1189Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1190
1191@item tablet
1192Pointer device that uses absolute coordinates (like a touchscreen). This
1193means QEMU is able to report the mouse position without having to grab the
1194mouse. Also overrides the PS/2 mouse emulation when activated.
1195
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001196@item braille
1197Braille device. This will use BrlAPI to display the braille output on a real
1198or fake device.
1199
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001200@end table
1201ETEXI
1202
1203STEXI
1204@end table
1205ETEXI
1206DEFHEADING()
1207
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001208DEFHEADING(Display options:)
blueswir15824d652009-03-28 06:44:27 +00001209STEXI
1210@table @option
1211ETEXI
1212
Jes Sorensen1472a952011-03-16 13:33:31 +01001213DEF("display", HAS_ARG, QEMU_OPTION_display,
1214 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
Elie Tournier4867e472018-04-13 14:58:42 +01001215 " [,window_close=on|off][,gl=on|core|es|off]\n"
Robert Hof04ec5a2016-07-26 18:17:11 +08001216 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1217 "-display vnc=<display>[,<optargs>]\n"
1218 "-display curses\n"
Erik Skultety144aaa92018-11-16 11:14:44 +01001219 "-display none\n"
1220 "-display egl-headless[,rendernode=<file>]"
Robert Hof04ec5a2016-07-26 18:17:11 +08001221 " select display type\n"
1222 "The default display is equivalent to\n"
1223#if defined(CONFIG_GTK)
1224 "\t\"-display gtk\"\n"
1225#elif defined(CONFIG_SDL)
1226 "\t\"-display sdl\"\n"
1227#elif defined(CONFIG_COCOA)
1228 "\t\"-display cocoa\"\n"
1229#elif defined(CONFIG_VNC)
1230 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1231#else
1232 "\t\"-display none\"\n"
1233#endif
1234 , QEMU_ARCH_ALL)
Jes Sorensen1472a952011-03-16 13:33:31 +01001235STEXI
1236@item -display @var{type}
1237@findex -display
1238Select type of display to use. This option is a replacement for the
1239old style -sdl/-curses/... options. Valid values for @var{type} are
1240@table @option
1241@item sdl
1242Display video output via SDL (usually in a separate graphics
1243window; see the SDL documentation for other possibilities).
1244@item curses
1245Display video output via curses. For graphics device models which
1246support a text mode, QEMU can display this output using a
1247curses/ncurses interface. Nothing is displayed when the graphics
1248device is in graphical mode or if the graphics device does not support
1249a text mode. Generally only the VGA device models support text mode.
Jes Sorensen4171d322011-03-16 13:33:32 +01001250@item none
1251Do not display video output. The guest will still see an emulated
1252graphics card, but its output will not be displayed to the QEMU
1253user. This option differs from the -nographic option in that it
1254only affects what is done with video output; -nographic also changes
1255the destination of the serial and parallel port data.
Jan Kiszka881249c2014-03-12 08:33:50 +01001256@item gtk
1257Display video output in a GTK window. This interface provides drop-down
1258menus and other UI elements to configure and control the VM during
1259runtime.
Jes Sorensen3264ff12011-03-16 13:33:33 +01001260@item vnc
1261Start a VNC server on display <arg>
Erik Skultety144aaa92018-11-16 11:14:44 +01001262@item egl-headless
1263Offload all OpenGL operations to a local DRI device. For any graphical display,
1264this display needs to be paired with either VNC or SPICE displays.
Jes Sorensen1472a952011-03-16 13:33:31 +01001265@end table
1266ETEXI
1267
blueswir15824d652009-03-28 06:44:27 +00001268DEF("nographic", 0, QEMU_OPTION_nographic,
Blue Swirlad960902010-03-29 19:23:52 +00001269 "-nographic disable graphical output and redirect serial I/Os to console\n",
1270 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001271STEXI
1272@item -nographic
Stefan Weil6616b2a2010-02-05 23:52:05 +01001273@findex -nographic
Colin Lorddc0a3e42016-08-12 15:30:48 -04001274Normally, if QEMU is compiled with graphical window support, it displays
1275output such as guest graphics, guest console, and the QEMU monitor in a
1276window. With this option, you can totally disable graphical output so
1277that QEMU is a simple command line application. The emulated serial port
1278is redirected on the console and muxed with the monitor (unless
1279redirected elsewhere explicitly). Therefore, you can still use QEMU to
1280debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1281switching between the console and monitor.
blueswir15824d652009-03-28 06:44:27 +00001282ETEXI
1283
blueswir15824d652009-03-28 06:44:27 +00001284DEF("curses", 0, QEMU_OPTION_curses,
Robert Hof04ec5a2016-07-26 18:17:11 +08001285 "-curses shorthand for -display curses\n",
Blue Swirlad960902010-03-29 19:23:52 +00001286 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001287STEXI
1288@item -curses
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001289@findex -curses
Colin Lorddc0a3e42016-08-12 15:30:48 -04001290Normally, if QEMU is compiled with graphical window support, it displays
1291output such as guest graphics, guest console, and the QEMU monitor in a
1292window. With this option, QEMU can display the VGA output when in text
1293mode using a curses/ncurses interface. Nothing is displayed in graphical
1294mode.
blueswir15824d652009-03-28 06:44:27 +00001295ETEXI
1296
blueswir15824d652009-03-28 06:44:27 +00001297DEF("no-frame", 0, QEMU_OPTION_no_frame,
Blue Swirlad960902010-03-29 19:23:52 +00001298 "-no-frame open SDL window without a frame and window decorations\n",
1299 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001300STEXI
1301@item -no-frame
Stefan Weil6616b2a2010-02-05 23:52:05 +01001302@findex -no-frame
blueswir15824d652009-03-28 06:44:27 +00001303Do not use decorations for SDL windows and start them using the whole
1304available screen space. This makes the using QEMU in a dedicated desktop
1305workspace more convenient.
1306ETEXI
1307
blueswir15824d652009-03-28 06:44:27 +00001308DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001309 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1310 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001311STEXI
1312@item -alt-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001313@findex -alt-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001314Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1315affects the special keys (for fullscreen, monitor-mode switching, etc).
blueswir15824d652009-03-28 06:44:27 +00001316ETEXI
1317
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001318DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001319 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1320 QEMU_ARCH_ALL)
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001321STEXI
1322@item -ctrl-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001323@findex -ctrl-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001324Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1325affects the special keys (for fullscreen, monitor-mode switching, etc).
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001326ETEXI
1327
blueswir15824d652009-03-28 06:44:27 +00001328DEF("no-quit", 0, QEMU_OPTION_no_quit,
Blue Swirlad960902010-03-29 19:23:52 +00001329 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001330STEXI
1331@item -no-quit
Stefan Weil6616b2a2010-02-05 23:52:05 +01001332@findex -no-quit
blueswir15824d652009-03-28 06:44:27 +00001333Disable SDL window close capability.
1334ETEXI
1335
blueswir15824d652009-03-28 06:44:27 +00001336DEF("sdl", 0, QEMU_OPTION_sdl,
Robert Hof04ec5a2016-07-26 18:17:11 +08001337 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001338STEXI
1339@item -sdl
Stefan Weil6616b2a2010-02-05 23:52:05 +01001340@findex -sdl
blueswir15824d652009-03-28 06:44:27 +00001341Enable SDL.
1342ETEXI
1343
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001344DEF("spice", HAS_ARG, QEMU_OPTION_spice,
Yonit Halperin27af7782012-08-21 13:54:20 +03001345 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1346 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1347 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
Marc-André Lureaufe4831b2015-01-13 17:57:51 +01001348 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001349 " [,tls-ciphers=<list>]\n"
1350 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1351 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1352 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1353 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1354 " [,jpeg-wan-compression=[auto|never|always]]\n"
1355 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1356 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
Hans de Goede5ad24e52013-06-08 15:37:27 +02001357 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1358 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
Marc-André Lureau7b525502017-02-12 15:21:18 +04001359 " [,gl=[on|off]][,rendernode=<file>]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001360 " enable spice\n"
1361 " at least one of {port, tls-port} is mandatory\n",
1362 QEMU_ARCH_ALL)
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001363STEXI
1364@item -spice @var{option}[,@var{option}[,...]]
1365@findex -spice
1366Enable the spice remote desktop protocol. Valid options are
1367
1368@table @option
1369
1370@item port=<nr>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001371Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001372
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001373@item addr=<addr>
1374Set the IP address spice is listening on. Default is any address.
1375
1376@item ipv4
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001377@itemx ipv6
1378@itemx unix
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001379Force using the specified IP version.
1380
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001381@item password=<secret>
1382Set the password you need to authenticate.
1383
Marc-André Lureau48b3ed02011-05-17 10:40:33 +02001384@item sasl
1385Require that the client use SASL to authenticate with the spice.
1386The exact choice of authentication method used is controlled from the
1387system / user's SASL configuration file for the 'qemu' service. This
1388is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1389unprivileged user, an environment variable SASL_CONF_PATH can be used
1390to make it search alternate locations for the service config.
1391While some SASL auth methods can also provide data encryption (eg GSSAPI),
1392it is recommended that SASL always be combined with the 'tls' and
1393'x509' settings to enable use of SSL and server certificates. This
1394ensures a data encryption preventing compromise of authentication
1395credentials.
1396
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001397@item disable-ticketing
1398Allow client connects without authentication.
1399
Hans de Goeded4970b02011-03-27 16:43:54 +02001400@item disable-copy-paste
1401Disable copy paste between the client and the guest.
1402
Hans de Goede5ad24e52013-06-08 15:37:27 +02001403@item disable-agent-file-xfer
1404Disable spice-vdagent based file-xfer between the client and the guest.
1405
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001406@item tls-port=<nr>
1407Set the TCP port spice is listening on for encrypted channels.
1408
1409@item x509-dir=<dir>
1410Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1411
1412@item x509-key-file=<file>
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001413@itemx x509-key-password=<file>
1414@itemx x509-cert-file=<file>
1415@itemx x509-cacert-file=<file>
1416@itemx x509-dh-key-file=<file>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001417The x509 file names can also be configured individually.
1418
1419@item tls-ciphers=<list>
1420Specify which ciphers to use.
1421
Alon Levyd70d6b32011-12-20 13:05:18 +02001422@item tls-channel=[main|display|cursor|inputs|record|playback]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001423@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
Gerd Hoffmann17b6dea2010-08-27 14:09:56 +02001424Force specific channel to be used with or without TLS encryption. The
1425options can be specified multiple times to configure multiple
1426channels. The special name "default" can be used to set the default
1427mode. For channels which are not explicitly forced into one mode the
1428spice client is allowed to pick tls/plaintext as he pleases.
1429
Yonit Halperin9f04e092010-07-14 13:26:34 +03001430@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1431Configure image compression (lossless).
1432Default is auto_glz.
1433
1434@item jpeg-wan-compression=[auto|never|always]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001435@itemx zlib-glz-wan-compression=[auto|never|always]
Yonit Halperin9f04e092010-07-14 13:26:34 +03001436Configure wan image compression (lossy for slow links).
1437Default is auto.
1438
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001439@item streaming-video=[off|all|filter]
Li Zhijian93ca5192016-08-01 12:06:59 +08001440Configure video stream detection. Default is off.
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001441
1442@item agent-mouse=[on|off]
1443Enable/disable passing mouse events via vdagent. Default is on.
1444
1445@item playback-compression=[on|off]
1446Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1447
Yonit Halperin8c957052012-08-21 11:51:59 +03001448@item seamless-migration=[on|off]
1449Enable/disable spice seamless migration. Default is off.
1450
Gerd Hoffmann474114b2015-10-13 15:39:34 +02001451@item gl=[on|off]
1452Enable/disable OpenGL context. Default is off.
1453
Marc-André Lureau7b525502017-02-12 15:21:18 +04001454@item rendernode=<file>
1455DRM render node for OpenGL rendering. If not specified, it will pick
1456the first available. (Since 2.9)
1457
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001458@end table
1459ETEXI
1460
blueswir15824d652009-03-28 06:44:27 +00001461DEF("portrait", 0, QEMU_OPTION_portrait,
Blue Swirlad960902010-03-29 19:23:52 +00001462 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1463 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001464STEXI
1465@item -portrait
Stefan Weil6616b2a2010-02-05 23:52:05 +01001466@findex -portrait
blueswir15824d652009-03-28 06:44:27 +00001467Rotate graphical output 90 deg left (only PXA LCD).
1468ETEXI
1469
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001470DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1471 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1472 QEMU_ARCH_ALL)
1473STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01001474@item -rotate @var{deg}
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001475@findex -rotate
1476Rotate graphical output some deg left (only PXA LCD).
1477ETEXI
1478
blueswir15824d652009-03-28 06:44:27 +00001479DEF("vga", HAS_ARG, QEMU_OPTION_vga,
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001480 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001481 " select video card type\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001482STEXI
malce4558dc2012-08-27 18:33:21 +04001483@item -vga @var{type}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001484@findex -vga
blueswir15824d652009-03-28 06:44:27 +00001485Select type of VGA card to emulate. Valid values for @var{type} are
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001486@table @option
blueswir15824d652009-03-28 06:44:27 +00001487@item cirrus
1488Cirrus Logic GD5446 Video card. All Windows versions starting from
1489Windows 95 should recognize and use this graphic card. For optimal
1490performances, use 16 bit color depth in the guest and the host OS.
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001491(This card was the default before QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001492@item std
1493Standard VGA card with Bochs VBE extensions. If your guest OS
1494supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1495to use high resolution modes (>= 1280x1024x16) then you should use
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001496this option. (This card is the default since QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001497@item vmware
1498VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1499recent XFree86/XOrg server or Windows guest with a driver for this
1500card.
Gerd Hoffmanna19cbfb2010-04-27 11:50:11 +02001501@item qxl
1502QXL paravirtual graphic card. It is VGA compatible (including VESA
15032.0 VBE support). Works best with qxl guest drivers installed though.
1504Recommended choice when using the spice protocol.
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001505@item tcx
1506(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1507sun4m machines and offers both 8-bit and 24-bit colour depths at a
1508fixed resolution of 1024x768.
1509@item cg3
1510(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1511for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1512resolutions aimed at people wishing to run older Solaris versions.
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001513@item virtio
1514Virtio VGA card.
blueswir15824d652009-03-28 06:44:27 +00001515@item none
1516Disable VGA card.
1517@end table
1518ETEXI
1519
1520DEF("full-screen", 0, QEMU_OPTION_full_screen,
Blue Swirlad960902010-03-29 19:23:52 +00001521 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001522STEXI
1523@item -full-screen
Stefan Weil6616b2a2010-02-05 23:52:05 +01001524@findex -full-screen
blueswir15824d652009-03-28 06:44:27 +00001525Start in full screen.
1526ETEXI
1527
blueswir15824d652009-03-28 06:44:27 +00001528DEF("g", 1, QEMU_OPTION_g ,
Blue Swirlad960902010-03-29 19:23:52 +00001529 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1530 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
blueswir15824d652009-03-28 06:44:27 +00001531STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01001532@item -g @var{width}x@var{height}[x@var{depth}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001533@findex -g
Stefan Weil95d5f082010-01-20 22:25:27 +01001534Set the initial graphical resolution and depth (PPC, SPARC only).
blueswir15824d652009-03-28 06:44:27 +00001535ETEXI
1536
1537DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
Robert Hof04ec5a2016-07-26 18:17:11 +08001538 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001539STEXI
1540@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001541@findex -vnc
Colin Lorddc0a3e42016-08-12 15:30:48 -04001542Normally, if QEMU is compiled with graphical window support, it displays
1543output such as guest graphics, guest console, and the QEMU monitor in a
1544window. With this option, you can have QEMU listen on VNC display
1545@var{display} and redirect the VGA display over the VNC session. It is
1546very useful to enable the usb tablet device when using this option
Thomas Hutha358a3a2017-05-19 08:35:16 +02001547(option @option{-device usb-tablet}). When using the VNC display, you
Colin Lorddc0a3e42016-08-12 15:30:48 -04001548must use the @option{-k} parameter to set the keyboard layout if you are
1549not using en-us. Valid syntax for the @var{display} is
blueswir15824d652009-03-28 06:44:27 +00001550
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001551@table @option
blueswir15824d652009-03-28 06:44:27 +00001552
Robert Ho99a9a522016-05-31 15:03:09 +08001553@item to=@var{L}
1554
1555With this option, QEMU will try next available VNC @var{display}s, until the
1556number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1557available, e.g. port 5900+@var{display} is already used by another
1558application. By default, to=0.
1559
blueswir15824d652009-03-28 06:44:27 +00001560@item @var{host}:@var{d}
1561
1562TCP connections will only be allowed from @var{host} on display @var{d}.
1563By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1564be omitted in which case the server will accept connections from any host.
1565
Kevin Wolf4e257e52009-10-09 10:58:36 +02001566@item unix:@var{path}
blueswir15824d652009-03-28 06:44:27 +00001567
1568Connections will be allowed over UNIX domain sockets where @var{path} is the
1569location of a unix socket to listen for connections on.
1570
1571@item none
1572
1573VNC is initialized but not started. The monitor @code{change} command
1574can be used to later start the VNC server.
1575
1576@end table
1577
1578Following the @var{display} value there may be one or more @var{option} flags
1579separated by commas. Valid options are
1580
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001581@table @option
blueswir15824d652009-03-28 06:44:27 +00001582
1583@item reverse
1584
1585Connect to a listening VNC client via a ``reverse'' connection. The
1586client is specified by the @var{display}. For reverse network
1587connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1588is a TCP port number, not a display number.
1589
Tim Hardeck7536ee42013-01-21 11:04:44 +01001590@item websocket
1591
1592Opens an additional TCP listening port dedicated to VNC Websocket connections.
Daniel P. Berrange275e0d62017-02-03 12:06:45 +00001593If a bare @var{websocket} option is given, the Websocket port is
15945700+@var{display}. An alternative port can be specified with the
1595syntax @code{websocket}=@var{port}.
1596
1597If @var{host} is specified connections will only be allowed from this host.
1598It is possible to control the websocket listen address independently, using
1599the syntax @code{websocket}=@var{host}:@var{port}.
1600
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001601If no TLS credentials are provided, the websocket connection runs in
1602unencrypted mode. If TLS credentials are provided, the websocket connection
1603requires encrypted client connections.
Tim Hardeck7536ee42013-01-21 11:04:44 +01001604
blueswir15824d652009-03-28 06:44:27 +00001605@item password
1606
1607Require that password based authentication is used for client connections.
Michal Novotny86ee5bc2012-07-16 15:54:38 +02001608
1609The password must be set separately using the @code{set_password} command in
1610the @ref{pcsys_monitor}. The syntax to change your password is:
1611@code{set_password <protocol> <password>} where <protocol> could be either
1612"vnc" or "spice".
1613
1614If you would like to change <protocol> password expiration, you should use
1615@code{expire_password <protocol> <expiration-time>} where expiration time could
1616be one of the following options: now, never, +seconds or UNIX time of
1617expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1618to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1619date and time).
1620
1621You can also use keywords "now" or "never" for the expiration time to
1622allow <protocol> password to expire immediately or never expire.
blueswir15824d652009-03-28 06:44:27 +00001623
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001624@item tls-creds=@var{ID}
1625
1626Provides the ID of a set of TLS credentials to use to secure the
1627VNC server. They will apply to both the normal VNC server socket
1628and the websocket socket (if enabled). Setting TLS credentials
1629will cause the VNC server socket to enable the VeNCrypt auth
1630mechanism. The credentials should have been previously created
1631using the @option{-object tls-creds} argument.
1632
blueswir15824d652009-03-28 06:44:27 +00001633@item sasl
1634
1635Require that the client use SASL to authenticate with the VNC server.
1636The exact choice of authentication method used is controlled from the
1637system / user's SASL configuration file for the 'qemu' service. This
1638is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1639unprivileged user, an environment variable SASL_CONF_PATH can be used
1640to make it search alternate locations for the service config.
1641While some SASL auth methods can also provide data encryption (eg GSSAPI),
1642it is recommended that SASL always be combined with the 'tls' and
1643'x509' settings to enable use of SSL and server certificates. This
1644ensures a data encryption preventing compromise of authentication
1645credentials. See the @ref{vnc_security} section for details on using
1646SASL authentication.
1647
1648@item acl
1649
1650Turn on access control lists for checking of the x509 client certificate
1651and SASL party. For x509 certs, the ACL check is made against the
1652certificate's distinguished name. This is something that looks like
1653@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1654made against the username, which depending on the SASL plugin, may
1655include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1656When the @option{acl} flag is set, the initial access list will be
1657empty, with a @code{deny} policy. Thus no one will be allowed to
1658use the VNC server until the ACLs have been loaded. This can be
1659achieved using the @code{acl} monitor command.
1660
Corentin Chary6f9c78c2010-07-07 20:57:51 +02001661@item lossy
1662
1663Enable lossy compression methods (gradient, JPEG, ...). If this
1664option is set, VNC client may receive lossy framebuffer updates
1665depending on its encoding settings. Enabling this option can save
1666a lot of bandwidth at the expense of quality.
1667
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001668@item non-adaptive
1669
1670Disable adaptive encodings. Adaptive encodings are enabled by default.
1671An adaptive encoding will try to detect frequently updated screen regions,
1672and send updates in these regions using a lossy encoding (like JPEG).
Stefan Weil61cc8702011-04-13 22:45:22 +02001673This can be really helpful to save bandwidth when playing videos. Disabling
Michael Tokarev9d85d552014-04-07 13:34:58 +04001674adaptive encodings restores the original static behavior of encodings
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001675like Tight.
1676
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001677@item share=[allow-exclusive|force-shared|ignore]
1678
1679Set display sharing policy. 'allow-exclusive' allows clients to ask
1680for exclusive access. As suggested by the rfb spec this is
1681implemented by dropping other connections. Connecting multiple
1682clients in parallel requires all clients asking for a shared session
1683(vncviewer: -shared switch). This is the default. 'force-shared'
1684disables exclusive client access. Useful for shared desktop sessions,
1685where you don't want someone forgetting specify -shared disconnect
1686everybody else. 'ignore' completely ignores the shared flag and
1687allows everybody connect unconditionally. Doesn't conform to the rfb
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001688spec but is traditional QEMU behavior.
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001689
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001690@item key-delay-ms
1691
1692Set keyboard delay, for key down and key up events, in milliseconds.
Alexander Grafd3b0db62017-07-12 14:43:45 +02001693Default is 10. Keyboards are low-bandwidth devices, so this slowdown
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001694can help the device and guest to keep up and not lose events in case
1695events are arriving in bulk. Possible causes for the latter are flaky
1696network connections, or scripts for automated testing.
1697
blueswir15824d652009-03-28 06:44:27 +00001698@end table
1699ETEXI
1700
1701STEXI
1702@end table
1703ETEXI
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001704ARCHHEADING(, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001705
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001706ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001707STEXI
1708@table @option
1709ETEXI
1710
blueswir15824d652009-03-28 06:44:27 +00001711DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
Blue Swirlad960902010-03-29 19:23:52 +00001712 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1713 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001714STEXI
1715@item -win2k-hack
Stefan Weil6616b2a2010-02-05 23:52:05 +01001716@findex -win2k-hack
blueswir15824d652009-03-28 06:44:27 +00001717Use it when installing Windows 2000 to avoid a disk full bug. After
1718Windows 2000 is installed, you no longer need this option (this option
1719slows down the IDE transfers).
1720ETEXI
1721
blueswir15824d652009-03-28 06:44:27 +00001722DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
Blue Swirlad960902010-03-29 19:23:52 +00001723 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1724 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001725STEXI
1726@item -no-fd-bootchk
Stefan Weil6616b2a2010-02-05 23:52:05 +01001727@findex -no-fd-bootchk
Markus Armbruster4eda32f2013-06-14 13:15:06 +02001728Disable boot signature checking for floppy disks in BIOS. May
blueswir15824d652009-03-28 06:44:27 +00001729be needed to boot from old floppy disks.
1730ETEXI
1731
blueswir15824d652009-03-28 06:44:27 +00001732DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
Shannon Zhaof5d8c8c2015-05-29 11:28:54 +01001733 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
blueswir15824d652009-03-28 06:44:27 +00001734STEXI
1735@item -no-acpi
Stefan Weil6616b2a2010-02-05 23:52:05 +01001736@findex -no-acpi
blueswir15824d652009-03-28 06:44:27 +00001737Disable ACPI (Advanced Configuration and Power Interface) support. Use
1738it if your guest OS complains about ACPI problems (PC target machine
1739only).
1740ETEXI
1741
blueswir15824d652009-03-28 06:44:27 +00001742DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
Blue Swirlad960902010-03-29 19:23:52 +00001743 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001744STEXI
1745@item -no-hpet
Stefan Weil6616b2a2010-02-05 23:52:05 +01001746@findex -no-hpet
blueswir15824d652009-03-28 06:44:27 +00001747Disable HPET support.
1748ETEXI
1749
blueswir15824d652009-03-28 06:44:27 +00001750DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
Michael Tokarev104bf022011-05-12 18:44:17 +04001751 "-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 +00001752 " ACPI table description\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001753STEXI
1754@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 +01001755@findex -acpitable
blueswir15824d652009-03-28 06:44:27 +00001756Add ACPI table with specified header fields and context from specified files.
Michael Tokarev104bf022011-05-12 18:44:17 +04001757For file=, take whole ACPI table from the specified files, including all
1758ACPI headers (possible overridden by other options).
1759For data=, only data
1760portion of the table is used, all header information is specified in the
1761command line.
Laszlo Ersekae123742016-01-18 15:12:13 +01001762If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1763fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1764to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1765spec.
blueswir15824d652009-03-28 06:44:27 +00001766ETEXI
1767
aliguorib6f6e3d2009-04-17 18:59:56 +00001768DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1769 "-smbios file=binary\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001770 " load SMBIOS entry from binary file\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001771 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1772 " [,uefi=on|off]\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001773 " specify SMBIOS type 0 fields\n"
aliguorib6f6e3d2009-04-17 18:59:56 +00001774 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1775 " [,uuid=uuid][,sku=str][,family=str]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001776 " specify SMBIOS type 1 fields\n"
1777 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1778 " [,asset=str][,location=str]\n"
1779 " specify SMBIOS type 2 fields\n"
1780 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1781 " [,sku=str]\n"
1782 " specify SMBIOS type 3 fields\n"
1783 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1784 " [,asset=str][,part=str]\n"
1785 " specify SMBIOS type 4 fields\n"
1786 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001787 " [,asset=str][,part=str][,speed=%d]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001788 " specify SMBIOS type 17 fields\n",
Wei Huangc30e1562015-09-07 10:39:29 +01001789 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
aliguorib6f6e3d2009-04-17 18:59:56 +00001790STEXI
1791@item -smbios file=@var{binary}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001792@findex -smbios
aliguorib6f6e3d2009-04-17 18:59:56 +00001793Load SMBIOS entry from binary file.
1794
Gabriel L. Somlo84351842014-05-19 10:09:54 -04001795@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 +00001796Specify SMBIOS type 0 fields
1797
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001798@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 +00001799Specify SMBIOS type 1 fields
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001800
1801@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}]
1802Specify SMBIOS type 2 fields
1803
1804@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1805Specify SMBIOS type 3 fields
1806
1807@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1808Specify SMBIOS type 4 fields
1809
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001810@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 -05001811Specify SMBIOS type 17 fields
aliguorib6f6e3d2009-04-17 18:59:56 +00001812ETEXI
1813
blueswir15824d652009-03-28 06:44:27 +00001814STEXI
1815@end table
1816ETEXI
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001817DEFHEADING()
blueswir15824d652009-03-28 06:44:27 +00001818
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001819DEFHEADING(Network options:)
blueswir15824d652009-03-28 06:44:27 +00001820STEXI
1821@table @option
1822ETEXI
1823
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001824DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
blueswir15824d652009-03-28 06:44:27 +00001825#ifdef CONFIG_SLIRP
Samuel Thibault0b11c032016-03-20 12:29:54 +01001826 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1827 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1828 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
Benjamin Drungf18d1372018-02-27 17:06:01 +01001829 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
Fam Zheng0fca92b2018-09-14 15:26:16 +08001830 " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001831#ifndef _WIN32
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001832 "[,smb=dir[,smbserver=addr]]\n"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001833#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001834 " configure a user mode network backend with ID 'str',\n"
1835 " its DHCP server and optional services\n"
blueswir15824d652009-03-28 06:44:27 +00001836#endif
1837#ifdef _WIN32
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001838 "-netdev tap,id=str,ifname=name\n"
1839 " configure a host TAP network backend with ID 'str'\n"
blueswir15824d652009-03-28 06:44:27 +00001840#else
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001841 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001842 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001843 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001844 " [,poll-us=n]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001845 " configure a host TAP network backend with ID 'str'\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001846 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001847 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1848 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1849 " to deconfigure it\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001850 " use '[down]script=no' to disable script execution\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001851 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1852 " configure it\n"
blueswir15824d652009-03-28 06:44:27 +00001853 " use 'fd=h' to connect to an already opened TAP interface\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001854 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001855 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
Michael S. Tsirkinf157ed22011-02-01 14:25:40 +02001856 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001857 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1858 " 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 +02001859 " use vhost=on to enable experimental in kernel accelerator\n"
mst@redhat.com5430a282011-02-01 22:13:42 +02001860 " (only has effect for virtio guests which use MSIX)\n"
1861 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001862 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001863 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
Jason Wangec396012013-02-22 22:57:52 +08001864 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001865 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
1866 " spent on busy polling for vhost net\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001867 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1868 " configure a host TAP network backend with ID 'str' that is\n"
1869 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1870 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
Mark McLoughlin0df0ff62009-06-18 18:21:34 +01001871#endif
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001872#ifdef __linux__
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001873 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1874 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1875 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1876 " [,rxcookie=rxcookie][,offset=offset]\n"
1877 " configure a network backend with ID 'str' connected to\n"
1878 " an Ethernet over L2TPv3 pseudowire.\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001879 " Linux kernel 3.3+ as well as most routers can talk\n"
Michael Tokarev2f47b402014-07-24 20:10:17 +04001880 " L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001881 " VM to a router and even VM to Host. It is a nearly-universal\n"
1882 " standard (RFC3391). Note - this implementation uses static\n"
1883 " pre-configured tunnels (same as the Linux kernel).\n"
1884 " use 'src=' to specify source address\n"
1885 " use 'dst=' to specify destination address\n"
1886 " use 'udp=on' to specify udp encapsulation\n"
Gonglei39526512014-08-14 14:35:48 +08001887 " use 'srcport=' to specify source udp port\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001888 " use 'dstport=' to specify destination udp port\n"
1889 " use 'ipv6=on' to force v6\n"
1890 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1891 " well as a weak security measure\n"
1892 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1893 " use 'txcookie=0x012345678' to specify a txcookie\n"
1894 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1895 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1896 " use 'pincounter=on' to work around broken counter handling in peer\n"
1897 " use 'offset=X' to add an extra offset between header and data\n"
1898#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001899 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1900 " configure a network backend to connect to another network\n"
1901 " using a socket connection\n"
1902 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1903 " configure a network backend to connect to a multicast maddr and port\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08001904 " use 'localaddr=addr' to specify the host address to send packets from\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001905 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
1906 " configure a network backend to connect to another network\n"
1907 " using an UDP tunnel\n"
blueswir15824d652009-03-28 06:44:27 +00001908#ifdef CONFIG_VDE
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001909 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1910 " configure a network backend to connect to port 'n' of a vde switch\n"
1911 " running on host and listening for incoming connections on 'socketpath'.\n"
blueswir15824d652009-03-28 06:44:27 +00001912 " Use group 'groupname' and mode 'octalmode' to change default\n"
1913 " ownership and permissions for communication port.\n"
1914#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001915#ifdef CONFIG_NETMAP
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001916 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
Vincenzo Maffione58952132013-11-06 11:44:06 +01001917 " attach to the existing netmap-enabled network interface 'name', or to a\n"
1918 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1919 " netmap device, defaults to '/dev/netmap')\n"
1920#endif
Thomas Huth253dc142018-02-21 11:18:32 +01001921#ifdef CONFIG_POSIX
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001922 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
1923 " configure a vhost-user network, backed by a chardev 'dev'\n"
Thomas Huth253dc142018-02-21 11:18:32 +01001924#endif
Thomas Huth18d65d22018-01-15 20:50:55 +01001925 "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
Thomas Huthaf1a5c32018-04-30 20:02:23 +02001926 " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
Thomas Huth78cd6f72018-02-21 11:18:36 +01001927DEF("nic", HAS_ARG, QEMU_OPTION_nic,
BALATON Zoltandfaa7d52018-07-16 21:12:08 +02001928 "-nic [tap|bridge|"
Thomas Huth78cd6f72018-02-21 11:18:36 +01001929#ifdef CONFIG_SLIRP
1930 "user|"
1931#endif
1932#ifdef __linux__
1933 "l2tpv3|"
1934#endif
1935#ifdef CONFIG_VDE
1936 "vde|"
1937#endif
1938#ifdef CONFIG_NETMAP
1939 "netmap|"
1940#endif
1941#ifdef CONFIG_POSIX
1942 "vhost-user|"
1943#endif
1944 "socket][,option][,...][mac=macaddr]\n"
1945 " initialize an on-board / default host NIC (using MAC address\n"
1946 " macaddr) and connect it to the given host network backend\n"
BALATON Zoltandfaa7d52018-07-16 21:12:08 +02001947 "-nic none use it alone to have zero network devices (the default is to\n"
Thomas Huth78cd6f72018-02-21 11:18:36 +01001948 " provided a 'user' network connection)\n",
1949 QEMU_ARCH_ALL)
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001950DEF("net", HAS_ARG, QEMU_OPTION_net,
Thomas Huthaf1a5c32018-04-30 20:02:23 +02001951 "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
Thomas Huth0e60a822017-12-19 16:28:55 +01001952 " configure or create an on-board (or machine default) NIC and\n"
Thomas Huthaf1a5c32018-04-30 20:02:23 +02001953 " connect it to hub 0 (please use -nic unless you need a hub)\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001954 "-net ["
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001955#ifdef CONFIG_SLIRP
1956 "user|"
1957#endif
1958 "tap|"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001959 "bridge|"
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001960#ifdef CONFIG_VDE
1961 "vde|"
1962#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001963#ifdef CONFIG_NETMAP
1964 "netmap|"
1965#endif
Thomas Huthaf1a5c32018-04-30 20:02:23 +02001966 "socket][,option][,option][,...]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001967 " old way to initialize a host network interface\n"
1968 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001969STEXI
Thomas Huthabbbb032018-03-12 13:20:50 +01001970@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
1971@findex -nic
1972This option is a shortcut for configuring both the on-board (default) guest
1973NIC hardware and the host network backend in one go. The host backend options
1974are the same as with the corresponding @option{-netdev} options below.
1975The guest NIC model can be set with @option{model=@var{modelname}}.
1976Use @option{model=help} to list the available device types.
1977The hardware MAC address can be set with @option{mac=@var{macaddr}}.
1978
1979The following two example do exactly the same, to show how @option{-nic} can
1980be used to shorten the command line length (note that the e1000 is the default
1981on i386, so the @option{model=e1000} parameter could even be omitted here, too):
1982@example
1983qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
1984qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
1985@end example
1986
1987@item -nic none
1988Indicate that no network devices should be configured. It is used to override
1989the default configuration (default NIC with ``user'' host network backend)
1990which is activated if no other networking options are provided.
blueswir15824d652009-03-28 06:44:27 +00001991
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001992@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001993@findex -netdev
Thomas Huthabbbb032018-03-12 13:20:50 +01001994Configure user mode host network backend which requires no administrator
Jan Kiszkaad196a92009-06-24 14:42:28 +02001995privilege to run. Valid options are:
blueswir15824d652009-03-28 06:44:27 +00001996
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001997@table @option
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001998@item id=@var{id}
Jan Kiszkaad196a92009-06-24 14:42:28 +02001999Assign symbolic name for use in monitor commands.
2000
Thomas Huthabbbb032018-03-12 13:20:50 +01002001@item ipv4=on|off and ipv6=on|off
2002Specify that either IPv4 or IPv6 must be enabled. If neither is specified
2003both protocols are enabled.
Samuel Thibault0b11c032016-03-20 12:29:54 +01002004
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002005@item net=@var{addr}[/@var{mask}]
2006Set IP network address the guest will see. Optionally specify the netmask,
2007either in the form a.b.c.d or as number of valid top-most bits. Default is
Brad Hardsb0b36e52011-04-24 17:19:56 +1000200810.0.2.0/24.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002009
2010@item host=@var{addr}
2011Specify the guest-visible address of the host. Default is the 2nd IP in the
2012guest network, i.e. x.x.x.2.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002013
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002014@item ipv6-net=@var{addr}[/@var{int}]
2015Set IPv6 network address the guest will see (default is fec0::/64). The
2016network prefix is given in the usual hexadecimal IPv6 address
2017notation. The prefix size is optional, and is given as the number of
2018valid top-most bits (default is 64).
Yann Bordenave7aac5312016-03-15 10:31:22 +01002019
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002020@item ipv6-host=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002021Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2022the guest network, i.e. xxxx::2.
2023
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02002024@item restrict=on|off
Brad Hardscaef55e2011-06-09 07:50:43 +10002025If this option is enabled, the guest will be isolated, i.e. it will not be
Jan Kiszkaad196a92009-06-24 14:42:28 +02002026able to contact the host and no guest IP packets will be routed over the host
Brad Hardscaef55e2011-06-09 07:50:43 +10002027to the outside. This option does not affect any explicitly set forwarding rules.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002028
2029@item hostname=@var{name}
Klaus Stengel63d29602012-10-27 19:53:39 +02002030Specifies the client hostname reported by the built-in DHCP server.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002031
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002032@item dhcpstart=@var{addr}
2033Specify the first of the 16 IPs the built-in DHCP server can assign. Default
Brad Hardsb0b36e52011-04-24 17:19:56 +10002034is 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 +02002035
2036@item dns=@var{addr}
2037Specify the guest-visible address of the virtual nameserver. The address must
2038be different from the host address. Default is the 3rd IP in the guest network,
2039i.e. x.x.x.3.
2040
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002041@item ipv6-dns=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002042Specify the guest-visible address of the IPv6 virtual nameserver. The address
2043must be different from the host address. Default is the 3rd IP in the guest
2044network, i.e. xxxx::3.
2045
Klaus Stengel63d29602012-10-27 19:53:39 +02002046@item dnssearch=@var{domain}
2047Provides an entry for the domain-search list sent by the built-in
2048DHCP server. More than one domain suffix can be transmitted by specifying
2049this option multiple times. If supported, this will cause the guest to
2050automatically try to append the given domain suffix(es) in case a domain name
2051can not be resolved.
2052
2053Example:
2054@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002055qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
Klaus Stengel63d29602012-10-27 19:53:39 +02002056@end example
2057
Benjamin Drungf18d1372018-02-27 17:06:01 +01002058@item domainname=@var{domain}
2059Specifies the client domain name reported by the built-in DHCP server.
2060
Jan Kiszkaad196a92009-06-24 14:42:28 +02002061@item tftp=@var{dir}
2062When using the user mode network stack, activate a built-in TFTP
2063server. The files in @var{dir} will be exposed as the root of a TFTP server.
2064The TFTP client on the guest must be configured in binary mode (use the command
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002065@code{bin} of the Unix TFTP client).
Jan Kiszkaad196a92009-06-24 14:42:28 +02002066
Fam Zheng0fca92b2018-09-14 15:26:16 +08002067@item tftp-server-name=@var{name}
2068In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option
206966). This can be used to advise the guest to load boot files or configurations
2070from a different server than the host address.
2071
Jan Kiszkaad196a92009-06-24 14:42:28 +02002072@item bootfile=@var{file}
2073When using the user mode network stack, broadcast @var{file} as the BOOTP
2074filename. In conjunction with @option{tftp}, this can be used to network boot
2075a guest from a local directory.
2076
2077Example (using pxelinux):
2078@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002079qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
2080 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
Jan Kiszkaad196a92009-06-24 14:42:28 +02002081@end example
2082
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002083@item smb=@var{dir}[,smbserver=@var{addr}]
Jan Kiszkaad196a92009-06-24 14:42:28 +02002084When using the user mode network stack, activate a built-in SMB
2085server so that Windows OSes can access to the host files in @file{@var{dir}}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002086transparently. The IP address of the SMB server can be set to @var{addr}. By
2087default the 4th IP in the guest network is used, i.e. x.x.x.4.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002088
2089In the guest Windows OS, the line:
2090@example
209110.0.2.4 smbserver
2092@end example
2093must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2094or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2095
2096Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2097
Brade2d88302011-09-02 16:53:28 -04002098Note that a SAMBA server must be installed on the host OS.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002099
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002100@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002101Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2102the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2103@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002104given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2105be bound to a specific host interface. If no connection type is set, TCP is
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002106used. This option can be given multiple times.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002107
2108For example, to redirect host X11 connection from screen 1 to guest
2109screen 0, use the following:
2110
2111@example
2112# on the host
Thomas Huthabbbb032018-03-12 13:20:50 +01002113qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
Jan Kiszkaad196a92009-06-24 14:42:28 +02002114# this host xterm should open in the guest X11 server
2115xterm -display :1
2116@end example
2117
2118To redirect telnet connections from host port 5555 to telnet port on
2119the guest, use the following:
2120
2121@example
2122# on the host
Thomas Huthabbbb032018-03-12 13:20:50 +01002123qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
Jan Kiszkaad196a92009-06-24 14:42:28 +02002124telnet localhost 5555
2125@end example
2126
2127Then when you use on the host @code{telnet localhost 5555}, you
2128connect to the guest telnet server.
2129
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002130@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002131@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002132Forward guest TCP connections to the IP address @var{server} on port @var{port}
Alexander Grafb412eb62012-06-03 09:45:01 +02002133to the character device @var{dev} or to a program executed by @var{cmd:command}
2134which gets spawned for each connection. This option can be given multiple times.
2135
Stefan Weil43ffe612012-07-20 23:26:02 +02002136You can either use a chardev directly and have that one used throughout QEMU's
Alexander Grafb412eb62012-06-03 09:45:01 +02002137lifetime, like in the following example:
2138
2139@example
2140# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2141# the guest accesses it
Thomas Huthabbbb032018-03-12 13:20:50 +01002142qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
Alexander Grafb412eb62012-06-03 09:45:01 +02002143@end example
2144
2145Or you can execute a command on every TCP connection established by the guest,
Stefan Weil43ffe612012-07-20 23:26:02 +02002146so that QEMU behaves similar to an inetd process for that virtual server:
Alexander Grafb412eb62012-06-03 09:45:01 +02002147
2148@example
2149# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2150# and connect the TCP stream to its stdin/stdout
Thomas Huthabbbb032018-03-12 13:20:50 +01002151qemu-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 +02002152@end example
Jan Kiszkaad196a92009-06-24 14:42:28 +02002153
2154@end table
2155
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002156@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 +01002157Configure a host TAP network backend with ID @var{id}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002158
2159Use the network script @var{file} to configure it and the network script
blueswir15824d652009-03-28 06:44:27 +00002160@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002161automatically provides one. The default network configure script is
2162@file{/etc/qemu-ifup} and the default network deconfigure script is
2163@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2164to disable script execution.
2165
2166If running QEMU as an unprivileged user, use the network helper
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002167@var{helper} to configure the TAP interface and attach it to the bridge.
2168The default network helper executable is @file{/path/to/qemu-bridge-helper}
2169and the default bridge device is @file{br0}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002170
2171@option{fd}=@var{h} can be used to specify the handle of an already
2172opened host TAP interface.
2173
2174Examples:
blueswir15824d652009-03-28 06:44:27 +00002175
2176@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002177#launch a QEMU instance with the default network script
Thomas Huthabbbb032018-03-12 13:20:50 +01002178qemu-system-i386 linux.img -nic tap
blueswir15824d652009-03-28 06:44:27 +00002179@end example
2180
blueswir15824d652009-03-28 06:44:27 +00002181@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002182#launch a QEMU instance with two NICs, each one connected
2183#to a TAP device
Stefan Weil3804da92012-05-11 22:21:50 +02002184qemu-system-i386 linux.img \
Thomas Huth74f78b92018-01-15 08:40:17 +01002185 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2186 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
blueswir15824d652009-03-28 06:44:27 +00002187@end example
2188
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002189@example
2190#launch a QEMU instance with the default network helper to
2191#connect a TAP device to bridge br0
Thomas Huthabbbb032018-03-12 13:20:50 +01002192qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
2193 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002194@end example
2195
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002196@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002197Connect a host TAP network interface to a host bridge device.
2198
2199Use the network helper @var{helper} to configure the TAP interface and
2200attach it to the bridge. The default network helper executable is
Amos Kong420508f2013-10-23 04:49:28 +08002201@file{/path/to/qemu-bridge-helper} and the default bridge
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002202device is @file{br0}.
2203
2204Examples:
2205
2206@example
2207#launch a QEMU instance with the default network helper to
2208#connect a TAP device to bridge br0
Thomas Huthabbbb032018-03-12 13:20:50 +01002209qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002210@end example
2211
2212@example
2213#launch a QEMU instance with the default network helper to
2214#connect a TAP device to bridge qemubr0
Thomas Huthabbbb032018-03-12 13:20:50 +01002215qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002216@end example
2217
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002218@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 +00002219
Thomas Huthabbbb032018-03-12 13:20:50 +01002220This host network backend can be used to connect the guest's network to
2221another QEMU virtual machine using a TCP socket connection. If @option{listen}
2222is specified, QEMU waits for incoming connections on @var{port}
blueswir15824d652009-03-28 06:44:27 +00002223(@var{host} is optional). @option{connect} is used to connect to
2224another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2225specifies an already opened TCP socket.
2226
2227Example:
2228@example
2229# launch a first QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002230qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002231 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2232 -netdev socket,id=n1,listen=:1234
2233# connect the network of this instance to the network of the first instance
Stefan Weil3804da92012-05-11 22:21:50 +02002234qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002235 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2236 -netdev socket,id=n2,connect=127.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002237@end example
2238
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002239@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
blueswir15824d652009-03-28 06:44:27 +00002240
Thomas Huthabbbb032018-03-12 13:20:50 +01002241Configure a socket host network backend to share the guest's network traffic
2242with another QEMU virtual machines using a UDP multicast socket, effectively
2243making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
blueswir15824d652009-03-28 06:44:27 +00002244NOTES:
2245@enumerate
2246@item
2247Several QEMU can be running on different hosts and share same bus (assuming
2248correct multicast setup for these hosts).
2249@item
2250mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2251@url{http://user-mode-linux.sf.net}.
2252@item
2253Use @option{fd=h} to specify an already opened UDP multicast socket.
2254@end enumerate
2255
2256Example:
2257@example
2258# launch one QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002259qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002260 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2261 -netdev socket,id=n1,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002262# launch another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002263qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002264 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2265 -netdev socket,id=n2,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002266# launch yet another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002267qemu-system-i386 linux.img \
Thomas Huth37a44422018-08-13 13:51:44 +02002268 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
Thomas Huthabbbb032018-03-12 13:20:50 +01002269 -netdev socket,id=n3,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002270@end example
2271
2272Example (User Mode Linux compat.):
2273@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002274# launch QEMU instance (note mcast address selected is UML's default)
Stefan Weil3804da92012-05-11 22:21:50 +02002275qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002276 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2277 -netdev socket,id=n1,mcast=239.192.168.1:1102
blueswir15824d652009-03-28 06:44:27 +00002278# launch UML
2279/path/to/linux ubd0=/path/to/root_fs eth0=mcast
2280@end example
2281
Mike Ryan3a75e742010-12-01 11:16:47 -08002282Example (send packets from host's 1.2.3.4):
2283@example
Stefan Weil3804da92012-05-11 22:21:50 +02002284qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002285 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2286 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
Mike Ryan3a75e742010-12-01 11:16:47 -08002287@end example
2288
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002289@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 +01002290Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
2291popular protocol to transport Ethernet (and other Layer 2) data frames between
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002292two systems. It is present in routers, firewalls and the Linux kernel
2293(from version 3.3 onwards).
2294
2295This transport allows a VM to communicate to another VM, router or firewall directly.
2296
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002297@table @option
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002298@item src=@var{srcaddr}
2299 source address (mandatory)
2300@item dst=@var{dstaddr}
2301 destination address (mandatory)
2302@item udp
2303 select udp encapsulation (default is ip).
2304@item srcport=@var{srcport}
2305 source udp port.
2306@item dstport=@var{dstport}
2307 destination udp port.
2308@item ipv6
2309 force v6, otherwise defaults to v4.
2310@item rxcookie=@var{rxcookie}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002311@itemx txcookie=@var{txcookie}
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002312 Cookies are a weak form of security in the l2tpv3 specification.
2313Their function is mostly to prevent misconfiguration. By default they are 32
2314bit.
2315@item cookie64
2316 Set cookie size to 64 bit instead of the default 32
2317@item counter=off
2318 Force a 'cut-down' L2TPv3 with no counter as in
2319draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2320@item pincounter=on
2321 Work around broken counter handling in peer. This may also help on
2322networks which have packet reorder.
2323@item offset=@var{offset}
2324 Add an extra offset between header and data
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002325@end table
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002326
2327For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2328on the remote Linux host 1.2.3.4:
2329@example
2330# Setup tunnel on linux host using raw ip as encapsulation
2331# on 1.2.3.4
2332ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2333 encap udp udp_sport 16384 udp_dport 16384
2334ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2335 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2336ifconfig vmtunnel0 mtu 1500
2337ifconfig vmtunnel0 up
2338brctl addif br-lan vmtunnel0
2339
2340
2341# on 4.3.2.1
2342# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2343
Thomas Huthabbbb032018-03-12 13:20:50 +01002344qemu-system-i386 linux.img -device e1000,netdev=n1 \
2345 -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 +01002346
2347@end example
2348
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002349@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 +01002350Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
blueswir15824d652009-03-28 06:44:27 +00002351listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2352and MODE @var{octalmode} to change default ownership and permissions for
Stefan Weilc1ba4e02011-09-05 18:13:03 +02002353communication port. This option is only available if QEMU has been compiled
blueswir15824d652009-03-28 06:44:27 +00002354with vde support enabled.
2355
2356Example:
2357@example
2358# launch vde switch
2359vde_switch -F -sock /tmp/myswitch
2360# launch QEMU instance
Thomas Huthabbbb032018-03-12 13:20:50 +01002361qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
blueswir15824d652009-03-28 06:44:27 +00002362@end example
2363
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002364@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002365
2366Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2367be a unix domain socket backed one. The vhost-user uses a specifically defined
2368protocol to pass vhost ioctl replacement messages to an application on the other
2369end of the socket. On non-MSIX guests, the feature can be forced with
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002370@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2371be created for multiqueue vhost-user.
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002372
2373Example:
2374@example
2375qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2376 -numa node,memdev=mem \
Vincenzo Maffione79cad2f2017-02-20 17:45:09 +01002377 -chardev socket,id=chr0,path=/path/to/socket \
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002378 -netdev type=vhost-user,id=net0,chardev=chr0 \
2379 -device virtio-net-pci,netdev=net0
2380@end example
2381
Thomas Huthabbbb032018-03-12 13:20:50 +01002382@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
Thomas Huth78cd6f72018-02-21 11:18:36 +01002383
Thomas Huthabbbb032018-03-12 13:20:50 +01002384Create a hub port on the emulated hub with ID @var{hubid}.
Thomas Huth78cd6f72018-02-21 11:18:36 +01002385
Thomas Huthabbbb032018-03-12 13:20:50 +01002386The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002387single netdev. Alternatively, you can also connect the hubport to another
2388netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
Thomas Huthabbbb032018-03-12 13:20:50 +01002389
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002390@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 +01002391@findex -net
2392Legacy option to configure or create an on-board (or machine default) Network
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002393Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
2394the default hub), or to the netdev @var{nd}.
Thomas Huthabbbb032018-03-12 13:20:50 +01002395The NIC is an e1000 by default on the PC target. Optionally, the MAC address
2396can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
2397only), and a @var{name} can be assigned for use in monitor commands.
2398Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2399that the card should have; this option currently only affects virtio cards; set
2400@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2401NIC is created. QEMU can emulate several different models of network card.
2402Use @code{-net nic,model=help} for a list of available devices for your target.
2403
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002404@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
Thomas Huthabbbb032018-03-12 13:20:50 +01002405Configure a host network backend (with the options corresponding to the same
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002406@option{-netdev} option) and connect it to the emulated hub 0 (the default
2407hub). Use @var{name} to specify the name of the hub port.
blueswir15824d652009-03-28 06:44:27 +00002408ETEXI
2409
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002410STEXI
2411@end table
2412ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002413DEFHEADING()
2414
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002415DEFHEADING(Character device options:)
Matthew Booth7273a2d2009-10-30 13:41:12 +00002416
2417DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
Lin Ma517b3d42016-08-17 01:13:52 +08002418 "-chardev help\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002419 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Corey Minyard5dd1f022014-10-02 11:17:37 -05002420 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
Julia Suvorova981b06e2018-10-19 01:35:00 +03002421 " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n"
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002422 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
Julia Suvorova981b06e2018-10-19 01:35:00 +03002423 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002424 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002425 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02002426 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002427 " [,logfile=PATH][,logappend=on|off]\n"
2428 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002429 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002430 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2431 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2432 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2433 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002434#ifdef _WIN32
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002435 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2436 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002437#else
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002438 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2439 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002440#endif
2441#ifdef CONFIG_BRLAPI
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002442 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002443#endif
2444#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2445 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002446 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2447 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002448#endif
2449#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002450 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2451 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002452#endif
Alon Levycbcc6332011-01-19 10:49:50 +02002453#if defined(CONFIG_SPICE)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002454 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2455 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
Alon Levycbcc6332011-01-19 10:49:50 +02002456#endif
Blue Swirlad960902010-03-29 19:23:52 +00002457 , QEMU_ARCH_ALL
Matthew Booth7273a2d2009-10-30 13:41:12 +00002458)
2459
2460STEXI
Markus Armbrusterdddba062017-10-02 16:03:06 +02002461
2462The general form of a character device option is:
2463@table @option
Thomas Huth16fdc562018-01-30 10:36:21 +01002464@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002465@findex -chardev
Matthew Booth7273a2d2009-10-30 13:41:12 +00002466Backend is one of:
2467@option{null},
2468@option{socket},
2469@option{udp},
2470@option{msmouse},
2471@option{vc},
Markus Armbruster4f573782013-07-26 16:44:32 +02002472@option{ringbuf},
Matthew Booth7273a2d2009-10-30 13:41:12 +00002473@option{file},
2474@option{pipe},
2475@option{console},
2476@option{serial},
2477@option{pty},
2478@option{stdio},
2479@option{braille},
2480@option{tty},
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002481@option{parallel},
Alon Levycbcc6332011-01-19 10:49:50 +02002482@option{parport},
Thomas Huth16fdc562018-01-30 10:36:21 +01002483@option{spicevmc},
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002484@option{spiceport}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002485The specific backend will determine the applicable options.
2486
Markus Armbrusterdddba062017-10-02 16:03:06 +02002487Use @code{-chardev help} to print all available chardev backend types.
Lin Ma517b3d42016-08-17 01:13:52 +08002488
Matthew Booth7273a2d2009-10-30 13:41:12 +00002489All devices must have an id, which can be any string up to 127 characters long.
2490It is used to uniquely identify this device in other command line directives.
2491
Jan Kiszka97331282010-04-06 16:55:54 +02002492A character device may be used in multiplexing mode by multiple front-ends.
Peter Maydella40db1b2016-02-16 17:28:58 +00002493Specify @option{mux=on} to enable this mode.
2494A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2495backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2496If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2497create a multiplexer with your specified ID, and you can then configure multiple
2498front ends to use that chardev ID for their input/output. Up to four different
2499front ends can be connected to a single multiplexed chardev. (Without
2500multiplexing enabled, a chardev can only be used by a single front end.)
2501For instance you could use this to allow a single stdio chardev to be used by
2502two serial ports and the QEMU monitor:
2503
2504@example
2505-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002506-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002507-serial chardev:char0 \
2508-serial chardev:char0
2509@end example
2510
2511You can have more than one multiplexer in a system configuration; for instance
2512you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2513multiplexed between the QEMU monitor and a parallel port:
2514
2515@example
2516-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002517-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002518-parallel chardev:char0 \
2519-chardev tcp,...,mux=on,id=char1 \
2520-serial chardev:char1 \
2521-serial chardev:char1
2522@end example
2523
2524When you're using a multiplexed character device, some escape sequences are
2525interpreted in the input. @xref{mux_keys, Keys in the character backend
2526multiplexer}.
2527
2528Note that some other command line options may implicitly create multiplexed
2529character backends; for instance @option{-serial mon:stdio} creates a
2530multiplexed stdio backend connected to the serial port and the QEMU monitor,
2531and @option{-nographic} also multiplexes the console and the monitor to
2532stdio.
2533
2534There is currently no support for multiplexing in the other direction
2535(where a single QEMU front end takes input and output from multiple chardevs).
Jan Kiszka97331282010-04-06 16:55:54 +02002536
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002537Every backend supports the @option{logfile} option, which supplies the path
2538to a file to record all data transmitted via the backend. The @option{logappend}
2539option controls whether the log file will be truncated or appended to when
2540opened.
2541
Markus Armbrusterdddba062017-10-02 16:03:06 +02002542@end table
Matthew Booth7273a2d2009-10-30 13:41:12 +00002543
Markus Armbrusterdddba062017-10-02 16:03:06 +02002544The available backends are:
2545
2546@table @option
Thomas Huth16fdc562018-01-30 10:36:21 +01002547@item -chardev null,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002548A void device. This device will not emit any data, and will drop any data it
2549receives. The null backend does not take any options.
2550
Julia Suvorova981b06e2018-10-19 01:35:00 +03002551@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002552
2553Create a two-way stream socket, which can be either a TCP or a unix socket. A
2554unix socket will be created if @option{path} is specified. Behaviour is
2555undefined if TCP options are specified for a unix socket.
2556
2557@option{server} specifies that the socket shall be a listening socket.
2558
2559@option{nowait} specifies that QEMU should not block waiting for a client to
2560connect to a listening socket.
2561
2562@option{telnet} specifies that traffic on the socket should interpret telnet
2563escape sequences.
2564
Julia Suvorova981b06e2018-10-19 01:35:00 +03002565@option{websocket} specifies that the socket uses WebSocket protocol for
2566communication.
2567
Corey Minyard5dd1f022014-10-02 11:17:37 -05002568@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2569the remote end goes away. qemu will delay this many seconds and then attempt
2570to reconnect. Zero disables reconnecting, and is the default.
2571
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002572@option{tls-creds} requests enablement of the TLS protocol for encryption,
2573and specifies the id of the TLS credentials to use for the handshake. The
2574credentials must be previously created with the @option{-object tls-creds}
2575argument.
2576
Matthew Booth7273a2d2009-10-30 13:41:12 +00002577TCP and unix socket options are given below:
2578
2579@table @option
2580
Thomas Huth16fdc562018-01-30 10:36:21 +01002581@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002582
2583@option{host} for a listening socket specifies the local address to be bound.
2584For a connecting socket species the remote host to connect to. @option{host} is
2585optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2586
2587@option{port} for a listening socket specifies the local port to be bound. For a
2588connecting socket specifies the port on the remote host to connect to.
2589@option{port} can be given as either a port number or a service name.
2590@option{port} is required.
2591
2592@option{to} is only relevant to listening sockets. If it is specified, and
2593@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2594to and including @option{to} until it succeeds. @option{to} must be specified
2595as a port number.
2596
2597@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2598If neither is specified the socket may use either protocol.
2599
2600@option{nodelay} disables the Nagle algorithm.
2601
2602@item unix options: path=@var{path}
2603
2604@option{path} specifies the local path of the unix socket. @option{path} is
2605required.
2606
2607@end table
2608
Thomas Huth16fdc562018-01-30 10:36:21 +01002609@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 +00002610
2611Sends all traffic from the guest to a remote host over UDP.
2612
2613@option{host} specifies the remote host to connect to. If not specified it
2614defaults to @code{localhost}.
2615
2616@option{port} specifies the port on the remote host to connect to. @option{port}
2617is required.
2618
2619@option{localaddr} specifies the local address to bind to. If not specified it
2620defaults to @code{0.0.0.0}.
2621
2622@option{localport} specifies the local port to bind to. If not specified any
2623available local port will be used.
2624
2625@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2626If neither is specified the device may use either protocol.
2627
Thomas Huth16fdc562018-01-30 10:36:21 +01002628@item -chardev msmouse,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002629
2630Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2631take any options.
2632
Thomas Huth16fdc562018-01-30 10:36:21 +01002633@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 +00002634
2635Connect to a QEMU text console. @option{vc} may optionally be given a specific
2636size.
2637
2638@option{width} and @option{height} specify the width and height respectively of
2639the console, in pixels.
2640
2641@option{cols} and @option{rows} specify that the console be sized to fit a text
2642console with the given dimensions.
2643
Thomas Huth16fdc562018-01-30 10:36:21 +01002644@item -chardev ringbuf,id=@var{id}[,size=@var{size}]
Lei Li51767e72013-01-25 00:03:19 +08002645
Markus Armbruster3949e592013-02-06 21:27:24 +01002646Create a ring buffer with fixed size @option{size}.
Stefan Hajnoczie69f7d22016-09-19 11:56:26 +01002647@var{size} must be a power of two and defaults to @code{64K}.
Lei Li51767e72013-01-25 00:03:19 +08002648
Thomas Huth16fdc562018-01-30 10:36:21 +01002649@item -chardev file,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002650
2651Log all traffic received from the guest to a file.
2652
2653@option{path} specifies the path of the file to be opened. This file will be
2654created if it does not already exist, and overwritten if it does. @option{path}
2655is required.
2656
Thomas Huth16fdc562018-01-30 10:36:21 +01002657@item -chardev pipe,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002658
2659Create a two-way connection to the guest. The behaviour differs slightly between
2660Windows hosts and other hosts:
2661
2662On Windows, a single duplex pipe will be created at
2663@file{\\.pipe\@option{path}}.
2664
2665On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2666@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2667received by the guest. Data written by the guest can be read from
2668@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2669be present.
2670
2671@option{path} forms part of the pipe path as described above. @option{path} is
2672required.
2673
Thomas Huth16fdc562018-01-30 10:36:21 +01002674@item -chardev console,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002675
2676Send traffic from the guest to QEMU's standard output. @option{console} does not
2677take any options.
2678
2679@option{console} is only available on Windows hosts.
2680
Thomas Huth16fdc562018-01-30 10:36:21 +01002681@item -chardev serial,id=@var{id},path=@option{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002682
2683Send traffic from the guest to a serial device on the host.
2684
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01002685On Unix hosts serial will actually accept any tty device,
2686not only serial lines.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002687
2688@option{path} specifies the name of the serial device to open.
2689
Thomas Huth16fdc562018-01-30 10:36:21 +01002690@item -chardev pty,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002691
2692Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2693not take any options.
2694
2695@option{pty} is not available on Windows hosts.
2696
Thomas Huth16fdc562018-01-30 10:36:21 +01002697@item -chardev stdio,id=@var{id}[,signal=on|off]
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002698Connect to standard input and standard output of the QEMU process.
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002699
2700@option{signal} controls if signals are enabled on the terminal, that includes
2701exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2702default, use @option{signal=off} to disable it.
2703
Thomas Huth16fdc562018-01-30 10:36:21 +01002704@item -chardev braille,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002705
2706Connect to a local BrlAPI server. @option{braille} does not take any options.
2707
Thomas Huth16fdc562018-01-30 10:36:21 +01002708@item -chardev tty,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002709
Matthew Booth7273a2d2009-10-30 13:41:12 +00002710@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
Markus Armbrusterd037d6b2013-02-13 15:54:15 +01002711DragonFlyBSD hosts. It is an alias for @option{serial}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002712
2713@option{path} specifies the path to the tty. @option{path} is required.
2714
Thomas Huth16fdc562018-01-30 10:36:21 +01002715@item -chardev parallel,id=@var{id},path=@var{path}
2716@itemx -chardev parport,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002717
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002718@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002719
2720Connect to a local parallel port.
2721
2722@option{path} specifies the path to the parallel port device. @option{path} is
2723required.
2724
Thomas Huth16fdc562018-01-30 10:36:21 +01002725@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
Alon Levycbcc6332011-01-19 10:49:50 +02002726
Stefan Hajnoczi3a846902011-10-06 11:24:12 +01002727@option{spicevmc} is only available when spice support is built in.
2728
Alon Levycbcc6332011-01-19 10:49:50 +02002729@option{debug} debug level for spicevmc
2730
2731@option{name} name of spice channel to connect to
2732
2733Connect to a spice virtual machine channel, such as vdiport.
Alon Levycbcc6332011-01-19 10:49:50 +02002734
Thomas Huth16fdc562018-01-30 10:36:21 +01002735@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002736
2737@option{spiceport} is only available when spice support is built in.
2738
2739@option{debug} debug level for spicevmc
2740
2741@option{name} name of spice port to connect to
2742
2743Connect to a spice port, allowing a Spice client to handle the traffic
2744identified by a name (preferably a fqdn).
Matthew Booth7273a2d2009-10-30 13:41:12 +00002745ETEXI
2746
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002747STEXI
2748@end table
2749ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002750DEFHEADING()
2751
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002752DEFHEADING(Bluetooth(R) options:)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002753STEXI
2754@table @option
2755ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002756
blueswir15824d652009-03-28 06:44:27 +00002757DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
blueswir15824d652009-03-28 06:44:27 +00002758 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2759 "-bt hci,host[:id]\n" \
2760 " use host's HCI with the given name\n" \
2761 "-bt hci[,vlan=n]\n" \
2762 " emulate a standard HCI in virtual scatternet 'n'\n" \
2763 "-bt vhci[,vlan=n]\n" \
2764 " add host computer to virtual scatternet 'n' using VHCI\n" \
2765 "-bt device:dev[,vlan=n]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00002766 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2767 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002768STEXI
blueswir15824d652009-03-28 06:44:27 +00002769@item -bt hci[...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002770@findex -bt
blueswir15824d652009-03-28 06:44:27 +00002771Defines the function of the corresponding Bluetooth HCI. -bt options
2772are matched with the HCIs present in the chosen machine type. For
2773example when emulating a machine with only one HCI built into it, only
2774the first @code{-bt hci[...]} option is valid and defines the HCI's
2775logic. The Transport Layer is decided by the machine type. Currently
2776the machines @code{n800} and @code{n810} have one HCI and all other
2777machines have none.
2778
Thomas Huthc0188e62018-11-12 11:00:30 +01002779Note: This option and the whole bluetooth subsystem is considered as deprecated.
2780If you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where
2781you describe your usecase.
2782
blueswir15824d652009-03-28 06:44:27 +00002783@anchor{bt-hcis}
2784The following three types are recognized:
2785
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002786@table @option
blueswir15824d652009-03-28 06:44:27 +00002787@item -bt hci,null
2788(default) The corresponding Bluetooth HCI assumes no internal logic
2789and will not respond to any HCI commands or emit events.
2790
2791@item -bt hci,host[:@var{id}]
2792(@code{bluez} only) The corresponding HCI passes commands / events
2793to / from the physical HCI identified by the name @var{id} (default:
2794@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2795capable systems like Linux.
2796
2797@item -bt hci[,vlan=@var{n}]
2798Add a virtual, standard HCI that will participate in the Bluetooth
2799scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2800VLANs, devices inside a bluetooth network @var{n} can only communicate
2801with other devices in the same network (scatternet).
2802@end table
2803
2804@item -bt vhci[,vlan=@var{n}]
2805(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2806to the host bluetooth stack instead of to the emulated target. This
2807allows the host and target machines to participate in a common scatternet
2808and communicate. Requires the Linux @code{vhci} driver installed. Can
2809be used as following:
2810
2811@example
Stefan Weil3804da92012-05-11 22:21:50 +02002812qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
blueswir15824d652009-03-28 06:44:27 +00002813@end example
2814
2815@item -bt device:@var{dev}[,vlan=@var{n}]
2816Emulate a bluetooth device @var{dev} and place it in network @var{n}
2817(default @code{0}). QEMU can only emulate one type of bluetooth devices
2818currently:
2819
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002820@table @option
blueswir15824d652009-03-28 06:44:27 +00002821@item keyboard
2822Virtual wireless keyboard implementing the HIDP bluetooth profile.
2823@end table
blueswir15824d652009-03-28 06:44:27 +00002824ETEXI
2825
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002826STEXI
2827@end table
2828ETEXI
blueswir15824d652009-03-28 06:44:27 +00002829DEFHEADING()
2830
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002831#ifdef CONFIG_TPM
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002832DEFHEADING(TPM device options:)
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002833
2834DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
Stefan Berger92dcc232013-02-27 12:47:54 -05002835 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2836 " use path to provide path to a character device; default is /dev/tpm0\n"
2837 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
Amarnath Vallurif4ede812017-09-29 14:10:20 +03002838 " not provided it will be searched for in /sys/class/misc/tpm?/device\n"
2839 "-tpmdev emulator,id=id,chardev=dev\n"
2840 " configure the TPM device using chardev backend\n",
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002841 QEMU_ARCH_ALL)
2842STEXI
2843
2844The general form of a TPM device option is:
2845@table @option
2846
Thomas Huth16fdc562018-01-30 10:36:21 +01002847@item -tpmdev @var{backend},id=@var{id}[,@var{options}]
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002848@findex -tpmdev
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002849
2850The specific backend type will determine the applicable options.
Corey Bryant28c4fa32013-03-20 12:34:49 -04002851The @code{-tpmdev} option creates the TPM backend and requires a
2852@code{-device} option that specifies the TPM frontend interface model.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002853
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002854Use @code{-tpmdev help} to print all available TPM backend types.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002855
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002856@end table
2857
2858The available backends are:
2859
2860@table @option
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002861
Thomas Huth16fdc562018-01-30 10:36:21 +01002862@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
Stefan Berger4549a8b2013-02-27 12:47:53 -05002863
2864(Linux-host only) Enable access to the host's TPM using the passthrough
2865driver.
2866
2867@option{path} specifies the path to the host's TPM device, i.e., on
2868a Linux host this would be @code{/dev/tpm0}.
2869@option{path} is optional and by default @code{/dev/tpm0} is used.
2870
Stefan Berger92dcc232013-02-27 12:47:54 -05002871@option{cancel-path} specifies the path to the host TPM device's sysfs
2872entry allowing for cancellation of an ongoing TPM command.
2873@option{cancel-path} is optional and by default QEMU will search for the
2874sysfs entry to use.
2875
Stefan Berger4549a8b2013-02-27 12:47:53 -05002876Some notes about using the host's TPM with the passthrough driver:
2877
2878The TPM device accessed by the passthrough driver must not be
2879used by any other application on the host.
2880
2881Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2882the VM's firmware (BIOS/UEFI) will not be able to initialize the
2883TPM again and may therefore not show a TPM-specific menu that would
2884otherwise allow the user to configure the TPM, e.g., allow the user to
2885enable/disable or activate/deactivate the TPM.
2886Further, if TPM ownership is released from within a VM then the host's TPM
2887will get disabled and deactivated. To enable and activate the
2888TPM again afterwards, the host has to be rebooted and the user is
2889required to enter the firmware's menu to enable and activate the TPM.
2890If the TPM is left disabled and/or deactivated most TPM commands will fail.
2891
2892To create a passthrough TPM use the following two options:
2893@example
2894-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2895@end example
2896Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2897@code{tpmdev=tpm0} in the device option.
2898
Thomas Huth16fdc562018-01-30 10:36:21 +01002899@item -tpmdev emulator,id=@var{id},chardev=@var{dev}
Amarnath Vallurif4ede812017-09-29 14:10:20 +03002900
2901(Linux-host only) Enable access to a TPM emulator using Unix domain socket based
2902chardev backend.
2903
2904@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
2905
2906To create a TPM emulator backend device with chardev socket backend:
2907@example
2908
2909-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2910
2911@end example
2912
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002913ETEXI
2914
Markus Armbruster2252aaf2017-10-02 16:03:05 +02002915STEXI
2916@end table
2917ETEXI
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002918DEFHEADING()
2919
2920#endif
2921
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002922DEFHEADING(Linux/Multiboot boot specific:)
blueswir15824d652009-03-28 06:44:27 +00002923STEXI
Alexander Graf7677f052009-06-28 16:55:55 +02002924
2925When using these options, you can use a given Linux or Multiboot
2926kernel without installing it in the disk image. It can be useful
blueswir15824d652009-03-28 06:44:27 +00002927for easier testing of various kernels.
2928
2929@table @option
2930ETEXI
2931
2932DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
Blue Swirlad960902010-03-29 19:23:52 +00002933 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002934STEXI
2935@item -kernel @var{bzImage}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002936@findex -kernel
Alexander Graf7677f052009-06-28 16:55:55 +02002937Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2938or in multiboot format.
blueswir15824d652009-03-28 06:44:27 +00002939ETEXI
2940
2941DEF("append", HAS_ARG, QEMU_OPTION_append, \
Blue Swirlad960902010-03-29 19:23:52 +00002942 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002943STEXI
2944@item -append @var{cmdline}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002945@findex -append
blueswir15824d652009-03-28 06:44:27 +00002946Use @var{cmdline} as kernel command line
2947ETEXI
2948
2949DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
Blue Swirlad960902010-03-29 19:23:52 +00002950 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002951STEXI
2952@item -initrd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002953@findex -initrd
blueswir15824d652009-03-28 06:44:27 +00002954Use @var{file} as initial ram disk.
Alexander Graf7677f052009-06-28 16:55:55 +02002955
2956@item -initrd "@var{file1} arg=foo,@var{file2}"
2957
2958This syntax is only available with multiboot.
2959
2960Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2961first module.
blueswir15824d652009-03-28 06:44:27 +00002962ETEXI
2963
Grant Likely412beee2012-03-02 11:56:38 +00002964DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
Peter A. G. Crosthwaite379b5c72012-03-04 21:03:54 +10002965 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
Grant Likely412beee2012-03-02 11:56:38 +00002966STEXI
2967@item -dtb @var{file}
2968@findex -dtb
2969Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
2970on boot.
2971ETEXI
2972
blueswir15824d652009-03-28 06:44:27 +00002973STEXI
2974@end table
2975ETEXI
blueswir15824d652009-03-28 06:44:27 +00002976DEFHEADING()
2977
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002978DEFHEADING(Debug/Expert options:)
blueswir15824d652009-03-28 06:44:27 +00002979STEXI
2980@table @option
2981ETEXI
2982
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04002983DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
2984 "-fw_cfg [name=]<name>,file=<file>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02002985 " add named fw_cfg entry with contents from file\n"
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04002986 "-fw_cfg [name=]<name>,string=<str>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02002987 " add named fw_cfg entry with contents from string\n",
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04002988 QEMU_ARCH_ALL)
2989STEXI
Markus Armbruster63d31452016-04-18 18:29:50 +02002990
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04002991@item -fw_cfg [name=]@var{name},file=@var{file}
2992@findex -fw_cfg
Markus Armbruster63d31452016-04-18 18:29:50 +02002993Add named fw_cfg entry with contents from file @var{file}.
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04002994
2995@item -fw_cfg [name=]@var{name},string=@var{str}
Markus Armbruster63d31452016-04-18 18:29:50 +02002996Add named fw_cfg entry with contents from string @var{str}.
2997
2998The terminating NUL character of the contents of @var{str} will not be
2999included as part of the fw_cfg item data. To insert contents with
3000embedded NUL characters, you have to use the @var{file} parameter.
3001
3002The fw_cfg entries are passed by QEMU through to the guest.
3003
3004Example:
3005@example
3006 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3007@end example
3008creates an fw_cfg entry named opt/com.mycompany/blob with contents
3009from ./my_blob.bin.
3010
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003011ETEXI
3012
blueswir15824d652009-03-28 06:44:27 +00003013DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
Blue Swirlad960902010-03-29 19:23:52 +00003014 "-serial dev redirect the serial port to char device 'dev'\n",
3015 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003016STEXI
3017@item -serial @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003018@findex -serial
blueswir15824d652009-03-28 06:44:27 +00003019Redirect the virtual serial port to host character device
3020@var{dev}. The default device is @code{vc} in graphical mode and
3021@code{stdio} in non graphical mode.
3022
3023This option can be used several times to simulate up to 4 serial
3024ports.
3025
3026Use @code{-serial none} to disable all serial ports.
3027
3028Available character devices are:
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003029@table @option
Kevin Wolf4e257e52009-10-09 10:58:36 +02003030@item vc[:@var{W}x@var{H}]
blueswir15824d652009-03-28 06:44:27 +00003031Virtual console. Optionally, a width and height can be given in pixel with
3032@example
3033vc:800x600
3034@end example
3035It is also possible to specify width or height in characters:
3036@example
3037vc:80Cx24C
3038@end example
3039@item pty
3040[Linux only] Pseudo TTY (a new PTY is automatically allocated)
3041@item none
3042No device is allocated.
3043@item null
3044void device
Ingo van Lil88e020e2013-12-20 14:44:53 +01003045@item chardev:@var{id}
3046Use a named character device defined with the @code{-chardev} option.
blueswir15824d652009-03-28 06:44:27 +00003047@item /dev/XXX
3048[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3049parameters are set according to the emulated ones.
3050@item /dev/parport@var{N}
3051[Linux only, parallel port only] Use host parallel port
3052@var{N}. Currently SPP and EPP parallel port features can be used.
3053@item file:@var{filename}
3054Write output to @var{filename}. No character can be read.
3055@item stdio
3056[Unix only] standard input/output
3057@item pipe:@var{filename}
3058name pipe @var{filename}
3059@item COM@var{n}
3060[Windows only] Use host serial port @var{n}
3061@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3062This implements UDP Net Console.
3063When @var{remote_host} or @var{src_ip} are not specified
3064they default to @code{0.0.0.0}.
3065When not using a specified @var{src_port} a random port is automatically chosen.
blueswir15824d652009-03-28 06:44:27 +00003066
3067If you just want a simple readonly console you can use @code{netcat} or
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003068@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3069@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
blueswir15824d652009-03-28 06:44:27 +00003070will appear in the netconsole session.
3071
3072If you plan to send characters back via netconsole or you want to stop
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003073and start QEMU a lot of times, you should have QEMU use the same
blueswir15824d652009-03-28 06:44:27 +00003074source port each time by using something like @code{-serial
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003075udp::4555@@:4556} to QEMU. Another approach is to use a patched
blueswir15824d652009-03-28 06:44:27 +00003076version of netcat which can listen to a TCP port and send and receive
3077characters via udp. If you have a patched version of netcat which
3078activates telnet remote echo and single char transfer, then you can
Marc-André Lureaubd1caa32016-12-22 18:56:38 +04003079use the following options to set up a netcat redirector to allow
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003080telnet on port 5555 to access the QEMU port.
blueswir15824d652009-03-28 06:44:27 +00003081@table @code
Stefan Weil071c9392012-04-07 09:23:36 +02003082@item QEMU Options:
blueswir15824d652009-03-28 06:44:27 +00003083-serial udp::4555@@:4556
3084@item netcat options:
3085-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3086@item telnet options:
3087localhost 5555
3088@end table
3089
Corey Minyard5dd1f022014-10-02 11:17:37 -05003090@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003091The TCP Net Console has two modes of operation. It can send the serial
3092I/O to a location or wait for a connection from a location. By default
3093the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3094the @var{server} option QEMU will wait for a client socket application
3095to connect to the port before continuing, unless the @code{nowait}
3096option was specified. The @code{nodelay} option disables the Nagle buffering
Corey Minyard5dd1f022014-10-02 11:17:37 -05003097algorithm. The @code{reconnect} option only applies if @var{noserver} is
3098set, if the connection goes down it will attempt to reconnect at the
3099given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
blueswir15824d652009-03-28 06:44:27 +00003100one TCP connection at a time is accepted. You can use @code{telnet} to
3101connect to the corresponding character device.
3102@table @code
3103@item Example to send tcp console to 192.168.0.2 port 4444
3104-serial tcp:192.168.0.2:4444
3105@item Example to listen and wait on port 4444 for connection
3106-serial tcp::4444,server
3107@item Example to not wait and listen on ip 192.168.0.100 port 4444
3108-serial tcp:192.168.0.100:4444,server,nowait
3109@end table
3110
3111@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3112The telnet protocol is used instead of raw tcp sockets. The options
3113work the same as if you had specified @code{-serial tcp}. The
3114difference is that the port acts like a telnet server or client using
3115telnet option negotiation. This will also allow you to send the
3116MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3117sequence. Typically in unix telnet you do it with Control-] and then
3118type "send break" followed by pressing the enter key.
3119
Julia Suvorova981b06e2018-10-19 01:35:00 +03003120@item websocket:@var{host}:@var{port},server[,nowait][,nodelay]
3121The WebSocket protocol is used instead of raw tcp socket. The port acts as
3122a WebSocket server. Client mode is not supported.
3123
Corey Minyard5dd1f022014-10-02 11:17:37 -05003124@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003125A unix domain socket is used instead of a tcp socket. The option works the
3126same as if you had specified @code{-serial tcp} except the unix domain socket
3127@var{path} is used for connections.
3128
3129@item mon:@var{dev_string}
3130This is a special option to allow the monitor to be multiplexed onto
3131another serial port. The monitor is accessed with key sequence of
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +04003132@key{Control-a} and then pressing @key{c}.
blueswir15824d652009-03-28 06:44:27 +00003133@var{dev_string} should be any one of the serial devices specified
3134above. An example to multiplex the monitor onto a telnet server
3135listening on port 4444 would be:
3136@table @code
3137@item -serial mon:telnet::4444,server,nowait
3138@end table
Michael Tokarevbe022d62013-07-11 12:55:50 +04003139When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3140QEMU any more but will be passed to the guest instead.
blueswir15824d652009-03-28 06:44:27 +00003141
3142@item braille
3143Braille device. This will use BrlAPI to display the braille output on a real
3144or fake device.
3145
Kevin Wolfbe8b28a2009-10-09 10:58:37 +02003146@item msmouse
3147Three button serial mouse. Configure the guest to use Microsoft protocol.
blueswir15824d652009-03-28 06:44:27 +00003148@end table
3149ETEXI
3150
3151DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
Blue Swirlad960902010-03-29 19:23:52 +00003152 "-parallel dev redirect the parallel port to char device 'dev'\n",
3153 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003154STEXI
3155@item -parallel @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003156@findex -parallel
blueswir15824d652009-03-28 06:44:27 +00003157Redirect the virtual parallel port to host device @var{dev} (same
3158devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3159be used to use hardware devices connected on the corresponding host
3160parallel port.
3161
3162This option can be used several times to simulate up to 3 parallel
3163ports.
3164
3165Use @code{-parallel none} to disable all parallel ports.
3166ETEXI
3167
3168DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
Blue Swirlad960902010-03-29 19:23:52 +00003169 "-monitor dev redirect the monitor to char device 'dev'\n",
3170 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003171STEXI
Gerd Hoffmann4e307fc2009-12-08 13:11:37 +01003172@item -monitor @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003173@findex -monitor
blueswir15824d652009-03-28 06:44:27 +00003174Redirect the monitor to host device @var{dev} (same devices as the
3175serial port).
3176The default device is @code{vc} in graphical mode and @code{stdio} in
3177non graphical mode.
Luiz Capitulino70e098a2013-05-16 12:02:55 -04003178Use @code{-monitor none} to disable the default monitor.
blueswir15824d652009-03-28 06:44:27 +00003179ETEXI
Gerd Hoffmann6ca55822009-12-08 13:11:52 +01003180DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
Blue Swirlad960902010-03-29 19:23:52 +00003181 "-qmp dev like -monitor but opens in 'control' mode\n",
3182 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003183STEXI
3184@item -qmp @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003185@findex -qmp
Stefan Weil95d5f082010-01-20 22:25:27 +01003186Like -monitor but opens in 'control' mode.
3187ETEXI
Max Reitz4821cd42014-11-17 13:31:04 +01003188DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3189 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3190 QEMU_ARCH_ALL)
3191STEXI
3192@item -qmp-pretty @var{dev}
3193@findex -qmp-pretty
3194Like -qmp but uses pretty JSON formatting.
3195ETEXI
blueswir15824d652009-03-28 06:44:27 +00003196
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003197DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003198 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003199STEXI
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003200@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003201@findex -mon
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003202Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3203easing human reading and debugging.
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003204ETEXI
3205
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003206DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
Blue Swirlad960902010-03-29 19:23:52 +00003207 "-debugcon dev redirect the debug console to char device 'dev'\n",
3208 QEMU_ARCH_ALL)
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003209STEXI
3210@item -debugcon @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003211@findex -debugcon
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003212Redirect the debug console to host device @var{dev} (same devices as the
3213serial port). The debug console is an I/O port which is typically port
32140xe9; writing to that I/O port sends output to this device.
3215The default device is @code{vc} in graphical mode and @code{stdio} in
3216non graphical mode.
3217ETEXI
3218
blueswir15824d652009-03-28 06:44:27 +00003219DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
Blue Swirlad960902010-03-29 19:23:52 +00003220 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003221STEXI
3222@item -pidfile @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003223@findex -pidfile
blueswir15824d652009-03-28 06:44:27 +00003224Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3225from a script.
3226ETEXI
3227
aurel321b530a62009-04-05 20:08:59 +00003228DEF("singlestep", 0, QEMU_OPTION_singlestep, \
Blue Swirlad960902010-03-29 19:23:52 +00003229 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
aurel321b530a62009-04-05 20:08:59 +00003230STEXI
3231@item -singlestep
Stefan Weil6616b2a2010-02-05 23:52:05 +01003232@findex -singlestep
aurel321b530a62009-04-05 20:08:59 +00003233Run the emulation in single step mode.
3234ETEXI
3235
Igor Mammedov047f7032018-05-11 19:24:43 +02003236DEF("preconfig", 0, QEMU_OPTION_preconfig, \
Markus Armbruster361ac942018-07-05 11:14:02 +02003237 "--preconfig pause QEMU before machine is initialized (experimental)\n",
Igor Mammedov047f7032018-05-11 19:24:43 +02003238 QEMU_ARCH_ALL)
3239STEXI
3240@item --preconfig
3241@findex --preconfig
3242Pause QEMU for interactive configuration before the machine is created,
3243which allows querying and configuring properties that will affect
Markus Armbruster361ac942018-07-05 11:14:02 +02003244machine initialization. Use QMP command 'x-exit-preconfig' to exit
3245the preconfig state and move to the next state (i.e. run guest if -S
3246isn't used or pause the second time if -S is used). This option is
3247experimental.
Igor Mammedov047f7032018-05-11 19:24:43 +02003248ETEXI
3249
blueswir15824d652009-03-28 06:44:27 +00003250DEF("S", 0, QEMU_OPTION_S, \
Blue Swirlad960902010-03-29 19:23:52 +00003251 "-S freeze CPU at startup (use 'c' to start execution)\n",
3252 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003253STEXI
3254@item -S
Stefan Weil6616b2a2010-02-05 23:52:05 +01003255@findex -S
blueswir15824d652009-03-28 06:44:27 +00003256Do not start CPU at startup (you must type 'c' in the monitor).
3257ETEXI
3258
Satoru Moriya888a6bc2013-04-19 16:42:06 +02003259DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3260 "-realtime [mlock=on|off]\n"
3261 " run qemu with realtime features\n"
3262 " mlock=on|off controls mlock support (default: on)\n",
3263 QEMU_ARCH_ALL)
3264STEXI
3265@item -realtime mlock=on|off
3266@findex -realtime
3267Run qemu with realtime features.
3268mlocking qemu and guest memory can be enabled via @option{mlock=on}
3269(enabled by default).
3270ETEXI
3271
Michael S. Tsirkin6f131f12018-06-22 22:22:05 +03003272DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
BALATON Zoltandfaa7d52018-07-16 21:12:08 +02003273 "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
Michael S. Tsirkin6f131f12018-06-22 22:22:05 +03003274 " run qemu with overcommit hints\n"
3275 " mem-lock=on|off controls memory lock support (default: off)\n"
3276 " cpu-pm=on|off controls cpu power management (default: off)\n",
3277 QEMU_ARCH_ALL)
3278STEXI
3279@item -overcommit mem-lock=on|off
3280@item -overcommit cpu-pm=on|off
3281@findex -overcommit
3282Run qemu with hints about host resource overcommit. The default is
3283to assume that host overcommits all resources.
3284
3285Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
3286by default). This works when host memory is not overcommitted and reduces the
3287worst-case latency for guest. This is equivalent to @option{realtime}.
3288
3289Guest ability to manage power state of host cpus (increasing latency for other
3290processes on the same host cpu, but decreasing latency for guest) can be
3291enabled via @option{cpu-pm=on} (disabled by default). This works best when
3292host CPU is not overcommitted. When used, host estimates of CPU cycle and power
3293utilization will be incorrect, not taking into account guest idle time.
3294ETEXI
3295
aliguori59030a82009-04-05 18:43:41 +00003296DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
Blue Swirlad960902010-03-29 19:23:52 +00003297 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003298STEXI
aliguori59030a82009-04-05 18:43:41 +00003299@item -gdb @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003300@findex -gdb
aliguori59030a82009-04-05 18:43:41 +00003301Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3302connections will likely be TCP-based, but also UDP, pseudo TTY, or even
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003303stdio are reasonable use case. The latter is allowing to start QEMU from
aliguori59030a82009-04-05 18:43:41 +00003304within gdb and establish the connection via a pipe:
3305@example
Stefan Weil3804da92012-05-11 22:21:50 +02003306(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
aliguori59030a82009-04-05 18:43:41 +00003307@end example
blueswir15824d652009-03-28 06:44:27 +00003308ETEXI
3309
aliguori59030a82009-04-05 18:43:41 +00003310DEF("s", 0, QEMU_OPTION_s, \
Blue Swirlad960902010-03-29 19:23:52 +00003311 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3312 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003313STEXI
aliguori59030a82009-04-05 18:43:41 +00003314@item -s
Stefan Weil6616b2a2010-02-05 23:52:05 +01003315@findex -s
aliguori59030a82009-04-05 18:43:41 +00003316Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3317(@pxref{gdb_usage}).
blueswir15824d652009-03-28 06:44:27 +00003318ETEXI
3319
3320DEF("d", HAS_ARG, QEMU_OPTION_d, \
Peter Maydell989b6972013-02-26 17:52:40 +00003321 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
Blue Swirlad960902010-03-29 19:23:52 +00003322 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003323STEXI
Peter Maydell989b6972013-02-26 17:52:40 +00003324@item -d @var{item1}[,...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003325@findex -d
Peter Maydell989b6972013-02-26 17:52:40 +00003326Enable logging of specified items. Use '-d help' for a list of log items.
blueswir15824d652009-03-28 06:44:27 +00003327ETEXI
3328
Matthew Fernandezc235d732011-06-07 16:32:40 +00003329DEF("D", HAS_ARG, QEMU_OPTION_D, \
Peter Maydell989b6972013-02-26 17:52:40 +00003330 "-D logfile output log to logfile (default stderr)\n",
Matthew Fernandezc235d732011-06-07 16:32:40 +00003331 QEMU_ARCH_ALL)
3332STEXI
Stefan Weil8bd383b2012-05-11 22:40:50 +02003333@item -D @var{logfile}
Matthew Fernandezc235d732011-06-07 16:32:40 +00003334@findex -D
Peter Maydell989b6972013-02-26 17:52:40 +00003335Output log in @var{logfile} instead of to stderr
Matthew Fernandezc235d732011-06-07 16:32:40 +00003336ETEXI
3337
Alex Bennée35145522016-03-15 14:30:20 +00003338DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3339 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3340 QEMU_ARCH_ALL)
3341STEXI
3342@item -dfilter @var{range1}[,...]
3343@findex -dfilter
3344Filter debug output to that relevant to a range of target addresses. The filter
3345spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3346@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3347addresses and sizes required. For example:
3348@example
3349 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3350@end example
3351Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3352the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3353block starting at 0xffffffc00005f000.
3354ETEXI
3355
blueswir15824d652009-03-28 06:44:27 +00003356DEF("L", HAS_ARG, QEMU_OPTION_L, \
Blue Swirlad960902010-03-29 19:23:52 +00003357 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3358 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003359STEXI
3360@item -L @var{path}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003361@findex -L
blueswir15824d652009-03-28 06:44:27 +00003362Set the directory for the BIOS, VGA BIOS and keymaps.
Richard W.M. Jones37146e72016-05-16 17:34:35 +01003363
3364To list all the data directories, use @code{-L help}.
blueswir15824d652009-03-28 06:44:27 +00003365ETEXI
3366
3367DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
Blue Swirlad960902010-03-29 19:23:52 +00003368 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003369STEXI
3370@item -bios @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003371@findex -bios
blueswir15824d652009-03-28 06:44:27 +00003372Set the filename for the BIOS.
3373ETEXI
3374
blueswir15824d652009-03-28 06:44:27 +00003375DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
Blue Swirlad960902010-03-29 19:23:52 +00003376 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003377STEXI
3378@item -enable-kvm
Stefan Weil6616b2a2010-02-05 23:52:05 +01003379@findex -enable-kvm
blueswir15824d652009-03-28 06:44:27 +00003380Enable KVM full virtualization support. This option is only available
3381if KVM support is enabled when compiling.
3382ETEXI
3383
Vincent Palatinb0cb0a62017-01-10 11:59:57 +01003384DEF("enable-hax", 0, QEMU_OPTION_enable_hax, \
3385 "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386)
3386STEXI
3387@item -enable-hax
3388@findex -enable-hax
3389Enable HAX (Hardware-based Acceleration eXecution) support. This option
3390is only available if HAX support is enabled when compiling. HAX is only
3391applicable to MAC and Windows platform, and thus does not conflict with
Thomas Huthc44df2f2018-06-25 20:22:13 +02003392KVM. This option is deprecated, use @option{-accel hax} instead.
Vincent Palatinb0cb0a62017-01-10 11:59:57 +01003393ETEXI
3394
aliguorie37630c2009-04-22 15:19:10 +00003395DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
Blue Swirlad960902010-03-29 19:23:52 +00003396 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003397DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3398 "-xen-attach attach to existing xen domain\n"
Anthony PERARD1077bca2018-09-14 12:18:30 +01003399 " libxl will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00003400 QEMU_ARCH_ALL)
Paul Durrant1c599472017-03-22 09:39:15 +00003401DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3402 "-xen-domid-restrict restrict set of available xen operations\n"
3403 " to specified domain id. (Does not affect\n"
3404 " xenpv machine type).\n",
3405 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003406STEXI
3407@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003408@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01003409Specify xen guest domain @var{id} (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003410@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01003411@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01003412Attach to existing xen domain.
Anthony PERARD1077bca2018-09-14 12:18:30 +01003413libxl will use this when starting QEMU (XEN only).
Paul Durrant1c599472017-03-22 09:39:15 +00003414@findex -xen-domid-restrict
3415Restrict set of available xen operations to specified domain id (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003416ETEXI
aliguorie37630c2009-04-22 15:19:10 +00003417
blueswir15824d652009-03-28 06:44:27 +00003418DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00003419 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003420STEXI
3421@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01003422@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00003423Exit instead of rebooting.
3424ETEXI
3425
3426DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00003427 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003428STEXI
3429@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01003430@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00003431Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3432This allows for instance switching to monitor to commit changes to the
3433disk image.
3434ETEXI
3435
3436DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3437 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003438 " start right away with a saved state (loadvm in monitor)\n",
3439 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003440STEXI
3441@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003442@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00003443Start right away with a saved state (@code{loadvm} in monitor)
3444ETEXI
3445
3446#ifndef _WIN32
3447DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00003448 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003449#endif
3450STEXI
3451@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01003452@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00003453Daemonize the QEMU process after initialization. QEMU will not detach from
3454standard IO until it is ready to receive connections on any of its devices.
3455This option is a useful way for external programs to launch QEMU without having
3456to cope with initialization race conditions.
3457ETEXI
3458
3459DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00003460 "-option-rom rom load a file, rom, into the option ROM space\n",
3461 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003462STEXI
3463@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003464@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003465Load the contents of @var{file} as an option ROM.
3466This option is useful to load things like EtherBoot.
3467ETEXI
3468
Markus Armbrustere2180522014-10-06 16:19:07 +02003469HXCOMM Silently ignored for compatibility
3470DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003471
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003472DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Artem Pisarenko238d1242018-10-18 13:12:52 +06003473 "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003474 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3475 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003476
blueswir15824d652009-03-28 06:44:27 +00003477STEXI
3478
Artem Pisarenko238d1242018-10-18 13:12:52 +06003479@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003480@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003481Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3482UTC or local time, respectively. @code{localtime} is required for correct date in
Artem Pisarenko238d1242018-10-18 13:12:52 +06003483MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003484format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3485
Michael Tokarev9d85d552014-04-07 13:34:58 +04003486By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003487RTC as accurate reference clock inside the guest, specifically if the host
3488time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003489If you want to isolate the guest time from the host, you can set @option{clock}
Artem Pisarenko238d1242018-10-18 13:12:52 +06003490to @code{rt} instead, which provides a host monotonic clock if host support it.
3491To even prevent the RTC from progressing during suspension, you can set @option{clock}
3492to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in
3493icount mode in order to preserve determinism; however, note that in icount mode
3494the speed of the virtual clock is variable and can in general differ from the
3495host clock.
Jan Kiszka68752042009-09-15 13:36:04 +02003496
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003497Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3498specifically with Windows' ACPI HAL. This option will try to figure out how
3499many timer interrupts were not processed by the Windows guest and will
3500re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003501ETEXI
3502
3503DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003504 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003505 " enable virtual instruction counter with 2^N clock ticks per\n" \
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003506 " instruction, enable aligning the host and virtual clocks\n" \
3507 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003508STEXI
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003509@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003510@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003511Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003512instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003513then the virtual cpu speed will be automatically adjusted to keep virtual
3514time within a few seconds of real time.
3515
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003516When the virtual cpu is sleeping, the virtual time will advance at default
Pranith Kumar778d9f92016-02-26 10:16:51 -05003517speed unless @option{sleep=on|off} is specified.
3518With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003519instantly whenever the virtual cpu goes to sleep mode and will not advance
3520if no timer is enabled. This behavior give deterministic execution times from
3521the guest point of view.
3522
blueswir15824d652009-03-28 06:44:27 +00003523Note that while this option can give deterministic behavior, it does not
3524provide cycle accurate emulation. Modern CPUs contain superscalar out of
3525order cores with complex cache hierarchies. The number of instructions
3526executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003527
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01003528@option{align=on} will activate the delay algorithm which will try
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003529to synchronise the host clock and the virtual clock. The goal is to
3530have a guest running at the real frequency imposed by the shift option.
3531Whenever the guest clock is behind the host clock and if
Michael Tokarev82597612015-04-27 11:12:49 +03003532@option{align=on} is specified then we print a message to the user
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003533to inform about the delay.
3534Currently this option does not work when @option{shift} is @code{auto}.
3535Note: The sync algorithm will work for those shift values for which
3536the guest clock runs ahead of the host clock. Typically this happens
3537when the shift value is high (how high depends on the host machine).
Pavel Dovgalyuk4c27b852015-09-17 19:25:18 +03003538
3539When @option{rr} option is specified deterministic record/replay is enabled.
3540Replay log is written into @var{filename} file in record mode and
3541read from this file in replay mode.
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003542
3543Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3544at the start of execution recording. In replay mode this option is used
3545to load the initial VM state.
blueswir15824d652009-03-28 06:44:27 +00003546ETEXI
3547
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003548DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
Xu Wangd7933ef2015-06-11 17:32:05 +02003549 "-watchdog model\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003550 " enable virtual hardware watchdog [default=none]\n",
3551 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003552STEXI
3553@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003554@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003555Create a virtual hardware watchdog device. Once enabled (by a guest
3556action), the watchdog must be periodically polled by an agent inside
Xu Wangd7933ef2015-06-11 17:32:05 +02003557the guest or else the guest will be restarted. Choose a model for
3558which your guest has drivers.
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003559
Xu Wangd7933ef2015-06-11 17:32:05 +02003560The @var{model} is the model of hardware watchdog to emulate. Use
3561@code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003562watchdog can be enabled for a guest.
Xu Wangd7933ef2015-06-11 17:32:05 +02003563
3564The following models may be available:
3565@table @option
3566@item ib700
3567iBASE 700 is a very simple ISA watchdog with a single timer.
3568@item i6300esb
3569Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3570dual-timer watchdog.
Xu Wang188f24c2015-02-05 18:28:32 +08003571@item diag288
3572A virtual watchdog for s390x backed by the diagnose 288 hypercall
3573(currently KVM only).
Xu Wangd7933ef2015-06-11 17:32:05 +02003574@end table
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003575ETEXI
3576
3577DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
Markus Armbruster7ad92702017-10-02 16:03:07 +02003578 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003579 " action when watchdog fires [default=reset]\n",
3580 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003581STEXI
3582@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003583@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003584
3585The @var{action} controls what QEMU will do when the watchdog timer
3586expires.
3587The default is
3588@code{reset} (forcefully reset the guest).
3589Other possible actions are:
3590@code{shutdown} (attempt to gracefully shutdown the guest),
3591@code{poweroff} (forcefully poweroff the guest),
Markus Armbruster7ad92702017-10-02 16:03:07 +02003592@code{inject-nmi} (inject a NMI into the guest),
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003593@code{pause} (pause the guest),
3594@code{debug} (print a debug message and continue), or
3595@code{none} (do nothing).
3596
3597Note that the @code{shutdown} action requires that the guest responds
3598to ACPI signals, which it may not be able to do in the sort of
3599situations where the watchdog would have expired, and thus
3600@code{-watchdog-action shutdown} is not recommended for production use.
3601
3602Examples:
3603
3604@table @code
3605@item -watchdog i6300esb -watchdog-action pause
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003606@itemx -watchdog ib700
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003607@end table
3608ETEXI
3609
blueswir15824d652009-03-28 06:44:27 +00003610DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003611 "-echr chr set terminal escape character instead of ctrl-a\n",
3612 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003613STEXI
3614
Kevin Wolf4e257e52009-10-09 10:58:36 +02003615@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003616@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003617Change the escape character used for switching to the monitor when using
3618monitor and serial sharing. The default is @code{0x01} when using the
3619@code{-nographic} option. @code{0x01} is equal to pressing
3620@code{Control-a}. You can select a different character from the ascii
3621control keys where 1 through 26 map to Control-a through Control-z. For
3622instance you could use the either of the following to change the escape
3623character to Control-t.
3624@table @code
3625@item -echr 0x14
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003626@itemx -echr 20
blueswir15824d652009-03-28 06:44:27 +00003627@end table
3628ETEXI
3629
3630DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3631 "-virtioconsole c\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003632 " set virtio console\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003633STEXI
3634@item -virtioconsole @var{c}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003635@findex -virtioconsole
blueswir15824d652009-03-28 06:44:27 +00003636Set virtio console.
Thomas Huth45401292018-05-04 17:13:10 +02003637This option is deprecated, please use @option{-device virtconsole} instead.
blueswir15824d652009-03-28 06:44:27 +00003638ETEXI
3639
3640DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003641 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003642STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003643@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003644@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003645Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003646ETEXI
3647
3648DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003649 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003650STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003651@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003652@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003653Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003654ETEXI
3655
3656DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Michael Tokarev7c601802015-02-10 22:40:47 +03003657 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3658 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3659 "-incoming unix:socketpath\n" \
3660 " prepare for incoming migration, listen on\n" \
3661 " specified protocol and socket address\n" \
3662 "-incoming fd:fd\n" \
3663 "-incoming exec:cmdline\n" \
3664 " accept incoming migration on given file descriptor\n" \
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003665 " or from given external command\n" \
3666 "-incoming defer\n" \
3667 " wait for the URI to be specified via migrate_incoming\n",
Blue Swirlad960902010-03-29 19:23:52 +00003668 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003669STEXI
Michael Tokarev7c601802015-02-10 22:40:47 +03003670@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003671@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003672@findex -incoming
Michael Tokarev7c601802015-02-10 22:40:47 +03003673Prepare for incoming migration, listen on a given tcp port.
3674
3675@item -incoming unix:@var{socketpath}
3676Prepare for incoming migration, listen on a given unix socket.
3677
3678@item -incoming fd:@var{fd}
3679Accept incoming migration from a given filedescriptor.
3680
3681@item -incoming exec:@var{cmdline}
3682Accept incoming migration as an output from specified external command.
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003683
3684@item -incoming defer
3685Wait for the URI to be specified via migrate_incoming. The monitor can
3686be used to change settings (such as migration parameters) prior to issuing
3687the migrate_incoming to allow the migration to begin.
blueswir15824d652009-03-28 06:44:27 +00003688ETEXI
3689
Ashijeet Acharyad15c05f2017-01-16 17:01:51 +05303690DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3691 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3692STEXI
3693@item -only-migratable
3694@findex -only-migratable
3695Only allow migratable devices. Devices will not be allowed to enter an
3696unmigratable state.
3697ETEXI
3698
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003699DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003700 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003701STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003702@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003703@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003704Don't create default devices. Normally, QEMU sets the default devices like serial
3705port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3706CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3707default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003708ETEXI
3709
blueswir15824d652009-03-28 06:44:27 +00003710#ifndef _WIN32
3711DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003712 "-chroot dir chroot to dir just before starting the VM\n",
3713 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003714#endif
3715STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003716@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003717@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003718Immediately before starting guest execution, chroot to the specified
3719directory. Especially useful in combination with -runas.
3720ETEXI
3721
3722#ifndef _WIN32
3723DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Ian Jackson2c42f1e2017-09-15 18:10:44 +01003724 "-runas user change to user id user just before starting the VM\n" \
3725 " user can be numeric uid:gid instead\n",
Blue Swirlad960902010-03-29 19:23:52 +00003726 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003727#endif
3728STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003729@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003730@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003731Immediately before starting guest execution, drop root privileges, switching
3732to the specified user.
3733ETEXI
3734
blueswir15824d652009-03-28 06:44:27 +00003735DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3736 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003737 " set OpenBIOS nvram variables\n",
3738 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003739STEXI
3740@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003741@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003742Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3743ETEXI
blueswir15824d652009-03-28 06:44:27 +00003744DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003745 "-semihosting semihosting mode\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003746 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3747 QEMU_ARCH_MIPS)
Stefan Weil95d5f082010-01-20 22:25:27 +01003748STEXI
3749@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003750@findex -semihosting
Leon Alrae3b3c1692015-06-19 11:08:43 +01003751Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
Liviu Ionescua38bb072014-12-11 12:07:48 +00003752ETEXI
3753DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
Leon Alraea59d31a2015-06-19 14:17:45 +01003754 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3755 " semihosting configuration\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003756QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3757QEMU_ARCH_MIPS)
Liviu Ionescua38bb072014-12-11 12:07:48 +00003758STEXI
Leon Alraea59d31a2015-06-19 14:17:45 +01003759@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
Liviu Ionescua38bb072014-12-11 12:07:48 +00003760@findex -semihosting-config
Leon Alrae3b3c1692015-06-19 11:08:43 +01003761Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
Leon Alraea59d31a2015-06-19 14:17:45 +01003762@table @option
3763@item target=@code{native|gdb|auto}
3764Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3765or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3766during debug sessions and @code{native} otherwise.
3767@item arg=@var{str1},arg=@var{str2},...
3768Allows the user to pass input arguments, and can be used multiple times to build
3769up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3770command line is still supported for backward compatibility. If both the
3771@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3772specified, the former is passed to semihosting as it always takes precedence.
3773@end table
Stefan Weil95d5f082010-01-20 22:25:27 +01003774ETEXI
blueswir15824d652009-03-28 06:44:27 +00003775DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00003776 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003777STEXI
3778@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01003779@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003780Old param mode (ARM only).
3781ETEXI
3782
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003783DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003784 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003785 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003786 " Enable seccomp mode 2 system call filter (default 'off').\n" \
3787 " use 'obsolete' to allow obsolete system calls that are provided\n" \
3788 " by the kernel, but typically no longer used by modern\n" \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003789 " C library implementations.\n" \
3790 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \
3791 " its privileges by blacklisting all set*uid|gid system calls.\n" \
3792 " The value 'children' will deny set*uid|gid system calls for\n" \
Eduardo Otubo995a2262017-03-13 22:16:01 +01003793 " main QEMU process but will allow forks and execves to run unprivileged\n" \
3794 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003795 " blacklisting *fork and execve\n" \
3796 " use 'resourcecontrol' to disable process affinity and schedular priority\n",
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003797 QEMU_ARCH_ALL)
3798STEXI
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003799@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003800@findex -sandbox
3801Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3802disable it. The default is 'off'.
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003803@table @option
3804@item obsolete=@var{string}
3805Enable Obsolete system calls
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003806@item elevateprivileges=@var{string}
3807Disable set*uid|gid system calls
Eduardo Otubo995a2262017-03-13 22:16:01 +01003808@item spawn=@var{string}
3809Disable *fork and execve
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003810@item resourcecontrol=@var{string}
3811Disable process affinity and schedular priority
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003812@end table
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003813ETEXI
3814
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003815DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00003816 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003817STEXI
3818@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003819@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003820Read device configuration from @var{file}. This approach is useful when you want to spawn
3821QEMU process with many command line options but you don't want to exceed the command line
3822character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003823ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003824DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3825 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00003826 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003827STEXI
3828@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003829@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003830Write device configuration to @var{file}. The @var{file} can be either filename to save
3831command line and device configuration into file or dash @code{-}) character to print the
3832output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003833ETEXI
Thomas Huth2feac452018-08-21 12:59:56 +02003834
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003835DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3836 "-no-user-config\n"
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003837 " do not load default user-provided config files at startup\n",
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003838 QEMU_ARCH_ALL)
3839STEXI
3840@item -no-user-config
3841@findex -no-user-config
3842The @code{-no-user-config} option makes QEMU not load any of the user-provided
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003843config files on @var{sysconfdir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06003844ETEXI
Thomas Huth2feac452018-08-21 12:59:56 +02003845
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003846DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Paolo Bonzini10578a22016-01-07 16:55:26 +03003847 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
Lluís23d15e82011-08-31 20:31:31 +02003848 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003849 QEMU_ARCH_ALL)
3850STEXI
Lluís23d15e82011-08-31 20:31:31 +02003851HXCOMM This line is not accurate, as some sub-options are backend-specific but
3852HXCOMM HX does not support conditional compilation of text.
Denis V. Luneve370ad92016-06-17 17:44:08 +03003853@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003854@findex -trace
Denis V. Luneveeb2b8f2016-06-17 17:44:09 +03003855@include qemu-option-trace.texi
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003856ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003857
Markus Armbruster31e70d62013-02-13 19:49:37 +01003858HXCOMM Internal use
3859DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3860DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02003861
Paul Moore0f669982012-08-03 14:39:21 -04003862#ifdef __linux__
3863DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3864 "-enable-fips enable FIPS 140-2 compliance\n",
3865 QEMU_ARCH_ALL)
3866#endif
3867STEXI
3868@item -enable-fips
3869@findex -enable-fips
3870Enable FIPS 140-2 compliance mode.
3871ETEXI
3872
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003873HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003874DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003875
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04003876DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3877 "-msg timestamp[=on|off]\n"
3878 " change the format of messages\n"
3879 " on|off controls leading timestamps (default:on)\n",
3880 QEMU_ARCH_ALL)
3881STEXI
3882@item -msg timestamp[=on|off]
3883@findex -msg
3884prepend a timestamp to each log message.(default:on)
3885ETEXI
3886
Amit Shahabfd9ce2014-06-20 18:56:08 +05303887DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3888 "-dump-vmstate <file>\n"
3889 " Output vmstate information in JSON format to file.\n"
3890 " Use the scripts/vmstate-static-checker.py file to\n"
3891 " check for possible regressions in migration code\n"
Laurent Vivier23820532015-09-04 21:30:04 +02003892 " by comparing two such vmstate dumps.\n",
Amit Shahabfd9ce2014-06-20 18:56:08 +05303893 QEMU_ARCH_ALL)
3894STEXI
3895@item -dump-vmstate @var{file}
3896@findex -dump-vmstate
3897Dump json-encoded vmstate information for current machine type to file
3898in @var{file}
3899ETEXI
3900
Emilio G. Cota12df1892018-08-15 11:42:49 -04003901DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile,
3902 "-enable-sync-profile\n"
3903 " enable synchronization profiling\n",
3904 QEMU_ARCH_ALL)
3905STEXI
3906@item -enable-sync-profile
3907@findex -enable-sync-profile
3908Enable synchronization profiling.
3909ETEXI
3910
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003911STEXI
3912@end table
3913ETEXI
3914DEFHEADING()
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003915
3916DEFHEADING(Generic object creation:)
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003917STEXI
3918@table @option
3919ETEXI
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003920
3921DEF("object", HAS_ARG, QEMU_OPTION_object,
3922 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3923 " create a new object of type TYPENAME setting properties\n"
3924 " in the order they are specified. Note that the 'id'\n"
3925 " property must be set. These objects are placed in the\n"
3926 " '/objects' path.\n",
3927 QEMU_ARCH_ALL)
3928STEXI
3929@item -object @var{typename}[,@var{prop1}=@var{value1},...]
3930@findex -object
3931Create a new object of type @var{typename} setting properties
3932in the order they are specified. Note that the 'id'
3933property must be set. These objects are placed in the
3934'/objects' path.
3935
3936@table @option
3937
Haozhong Zhang98376842017-12-11 15:28:04 +08003938@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 +01003939
3940Creates a memory file backend object, which can be used to back
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003941the guest RAM with huge pages.
3942
3943The @option{id} parameter is a unique ID that will be used to reference this
3944memory region when configuring the @option{-numa} argument.
3945
3946The @option{size} option provides the size of the memory region, and accepts
3947common suffixes, eg @option{500M}.
3948
3949The @option{mem-path} provides the path to either a shared memory or huge page
3950filesystem mount.
3951
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003952The @option{share} boolean option determines whether the memory
3953region is marked as private to QEMU, or shared. The latter allows
3954a co-operating external process to access the QEMU memory region.
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003955
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02003956The @option{share} is also required for pvrdma devices due to
3957limitations in the RDMA API provided by Linux.
3958
3959Setting share=on might affect the ability to configure NUMA
3960bindings for the memory backend under some circumstances, see
3961Documentation/vm/numa_memory_policy.txt on the Linux kernel
3962source tree for additional details.
3963
Eduardo Habkost11ae6ed2017-08-24 16:23:15 -03003964Setting the @option{discard-data} boolean option to @var{on}
3965indicates that file contents can be destroyed when QEMU exits,
3966to avoid unnecessarily flushing data to the backing file. Note
3967that @option{discard-data} is only an optimization, and QEMU
3968might not discard file contents if it aborts unexpectedly or is
3969terminated using SIGKILL.
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003970
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003971The @option{merge} boolean option enables memory merge, also known as
3972MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
3973memory deduplication.
3974
3975Setting the @option{dump} boolean option to @var{off} excludes the memory from
3976core dumps. This feature is also known as MADV_DONTDUMP.
3977
3978The @option{prealloc} boolean option enables memory preallocation.
3979
3980The @option{host-nodes} option binds the memory range to a list of NUMA host
3981nodes.
3982
3983The @option{policy} option sets the NUMA policy to one of the following values:
3984
3985@table @option
3986@item @var{default}
3987default host policy
3988
3989@item @var{preferred}
3990prefer the given host node list for allocation
3991
3992@item @var{bind}
3993restrict memory allocation to the given host node list
3994
3995@item @var{interleave}
3996interleave memory allocations across the given host node list
3997@end table
3998
Haozhong Zhang98376842017-12-11 15:28:04 +08003999The @option{align} option specifies the base address alignment when
4000QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg
4001@option{2M}. Some backend store specified by @option{mem-path}
4002requires an alignment different than the default one used by QEMU, eg
4003the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
4004such cases, users can specify the required alignment via this option.
4005
Junyan Hea4de8552018-07-18 15:48:00 +08004006The @option{pmem} option specifies whether the backing file specified
4007by @option{mem-path} is in host persistent memory that can be accessed
4008using the SNIA NVM programming model (e.g. Intel NVDIMM).
4009If @option{pmem} is set to 'on', QEMU will take necessary operations to
4010guarantee the persistence of its own writes to @option{mem-path}
4011(e.g. in vNVDIMM label emulation and live migration).
4012
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02004013@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 +00004014
4015Creates a memory backend object, which can be used to back the guest RAM.
4016Memory backend objects offer more control than the @option{-m} option that is
4017traditionally used to define guest RAM. Please refer to
4018@option{memory-backend-file} for a description of the options.
4019
Marc-André Lureau36ea3972018-08-28 17:38:40 +02004020@item -object memory-backend-memfd,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},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size}
Marc-André Lureaudbb9e0f2018-02-01 14:27:54 +01004021
4022Creates an anonymous memory file backend object, which allows QEMU to
4023share the memory with an external process (e.g. when using
4024vhost-user). The memory is allocated with memfd and optional
4025sealing. (Linux only)
4026
4027The @option{seal} option creates a sealed-file, that will block
4028further resizing the memory ('on' by default).
4029
4030The @option{hugetlb} option specify the file to be created resides in
4031the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with
4032the @option{hugetlb} option, the @option{hugetlbsize} option specify
4033the hugetlb page size on systems that support multiple hugetlb page
4034sizes (it must be a power of 2 value supported by the system).
4035
4036In some versions of Linux, the @option{hugetlb} option is incompatible
4037with the @option{seal} option (requires at least Linux 4.16).
4038
4039Please refer to @option{memory-backend-file} for a description of the
4040other options.
4041
Marc-André Lureau36ea3972018-08-28 17:38:40 +02004042The @option{share} boolean option is @var{on} by default with memfd.
4043
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004044@item -object rng-random,id=@var{id},filename=@var{/dev/random}
4045
4046Creates a random number generator backend which obtains entropy from
4047a device on the host. The @option{id} parameter is a unique ID that
4048will be used to reference this entropy backend from the @option{virtio-rng}
4049device. The @option{filename} parameter specifies which file to obtain
4050entropy from and if omitted defaults to @option{/dev/random}.
4051
4052@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4053
4054Creates a random number generator backend which obtains entropy from
4055an external daemon running on the host. The @option{id} parameter is
4056a unique ID that will be used to reference this entropy backend from
4057the @option{virtio-rng} device. The @option{chardev} parameter is
4058the unique ID of a character device backend that provides the connection
4059to the RNG daemon.
4060
Daniel P. Berrangee00adf62015-03-13 17:39:26 +00004061@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4062
4063Creates a TLS anonymous credentials object, which can be used to provide
4064TLS support on network backends. The @option{id} parameter is a unique
4065ID which network backends will use to access the credentials. The
4066@option{endpoint} is either @option{server} or @option{client} depending
4067on whether the QEMU network backend that uses the credentials will be
4068acting as a client or as a server. If @option{verify-peer} is enabled
4069(the default) then once the handshake is completed, the peer credentials
4070will be verified, though this is a no-op for anonymous credentials.
4071
4072The @var{dir} parameter tells QEMU where to find the credential
4073files. For server endpoints, this directory may contain a file
4074@var{dh-params.pem} providing diffie-hellman parameters to use
4075for the TLS server. If the file is missing, QEMU will generate
4076a set of DH parameters at startup. This is a computationally
4077expensive operation that consumes random pool entropy, so it is
4078recommended that a persistent set of parameters be generated
4079upfront and saved.
4080
Richard W.M. Jonese1a6dc92018-07-03 09:03:03 +01004081@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}]
4082
4083Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide
4084TLS support on network backends. The @option{id} parameter is a unique
4085ID which network backends will use to access the credentials. The
4086@option{endpoint} is either @option{server} or @option{client} depending
4087on whether the QEMU network backend that uses the credentials will be
4088acting as a client or as a server. For clients only, @option{username}
4089is the username which will be sent to the server. If omitted
4090it defaults to ``qemu''.
4091
4092The @var{dir} parameter tells QEMU where to find the keys file.
4093It is called ``@var{dir}/keys.psk'' and contains ``username:key''
4094pairs. This file can most easily be created using the GnuTLS
4095@code{psktool} program.
4096
4097For server endpoints, @var{dir} may also contain a file
4098@var{dh-params.pem} providing diffie-hellman parameters to use
4099for the TLS server. If the file is missing, QEMU will generate
4100a set of DH parameters at startup. This is a computationally
4101expensive operation that consumes random pool entropy, so it is
4102recommended that a persistent set of parameters be generated
4103up front and saved.
4104
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004105@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 +00004106
4107Creates a TLS anonymous credentials object, which can be used to provide
4108TLS support on network backends. The @option{id} parameter is a unique
4109ID which network backends will use to access the credentials. The
4110@option{endpoint} is either @option{server} or @option{client} depending
4111on whether the QEMU network backend that uses the credentials will be
4112acting as a client or as a server. If @option{verify-peer} is enabled
4113(the default) then once the handshake is completed, the peer credentials
4114will be verified. With x509 certificates, this implies that the clients
4115must be provided with valid client certificates too.
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
4126For x509 certificate credentials the directory will contain further files
4127providing the x509 certificates. The certificates must be stored
4128in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4129@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4130@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4131
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004132For the @var{server-key.pem} and @var{client-key.pem} files which
4133contain sensitive private keys, it is possible to use an encrypted
4134version by providing the @var{passwordid} parameter. This provides
4135the ID of a previously created @code{secret} object containing the
4136password for decryption.
4137
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004138The @var{priority} parameter allows to override the global default
4139priority used by gnutls. This can be useful if the system administrator
4140needs to use a weaker set of crypto priorities for QEMU without
4141potentially forcing the weakness onto all applications. Or conversely
4142if one wants wants a stronger default for QEMU than for all other
4143applications, they can do this through this parameter. Its format is
4144a gnutls priority string as described at
4145@url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
4146
zhanghailiang338d3f42016-03-01 13:37:02 +08004147@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 +08004148
4149Interval @var{t} can't be 0, this filter batches the packet delivery: all
4150packets arriving in a given interval on netdev @var{netdevid} are delayed
4151until the end of the interval. Interval is in microseconds.
zhanghailiang338d3f42016-03-01 13:37:02 +08004152@option{status} is optional that indicate whether the netfilter is
4153on (enabled) or off (disabled), the default status for netfilter will be 'on'.
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004154
4155queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4156
4157@option{all}: the filter is attached both to the receive and the transmit
4158 queue of the netdev (default).
4159
4160@option{rx}: the filter is attached to the receive queue of the netdev,
4161 where it will receive packets sent to the netdev.
4162
4163@option{tx}: the filter is attached to the transmit queue of the netdev,
4164 where it will receive packets sent by the netdev.
4165
Zhang Chene2521f02017-07-04 14:53:48 +08004166@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 +08004167
Zhang Chene2521f02017-07-04 14:53:48 +08004168filter-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 +08004169
Zhang Chen00d5c242017-07-04 14:53:49 +08004170@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 +08004171
4172filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
Zhang Chen00d5c242017-07-04 14:53:49 +08004173@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4174filter-redirector will redirect packet with vnet_hdr_len.
Zhang Chend46f75b2016-03-17 16:16:26 +08004175Create a filter-redirector we need to differ outdev id from indev id, id can not
4176be the same. we can just use indev or outdev, but at least one of indev or outdev
4177need to be specified.
4178
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004179@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 +08004180
4181Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4182secondary from primary to keep secondary tcp connection,and rewrite
4183tcp packet to primary from secondary make tcp packet can be handled by
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004184client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
Zhang Chene6eee8a2016-09-27 10:22:32 +08004185
4186usage:
4187colo secondary:
4188-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4189-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4190-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4191
Changlong Xiec551cd52016-10-11 13:28:32 +08004192@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
Thomas Huthd3e0c032015-10-13 12:40:02 +02004193
4194Dump the network traffic on netdev @var{dev} to the file specified by
4195@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4196The file format is libpcap, so it can be analyzed with tools such as tcpdump
4197or Wireshark.
4198
Zhang Chenaa3a7032017-07-04 14:53:52 +08004199@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 +08004200
4201Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4202secondary packet. If the packets are same, we will output primary
4203packet to outdev@var{chardevid}, else we will notify colo-frame
4204do checkpoint and send primary packet to outdev@var{chardevid}.
Zhang Chenaa3a7032017-07-04 14:53:52 +08004205if it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len.
Zhang Chen7dce4e62016-09-27 10:22:26 +08004206
4207we must use it with the help of filter-mirror and filter-redirector.
4208
4209@example
4210
4211primary:
4212-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4213-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4214-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4215-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4216-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4217-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4218-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4219-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4220-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4221-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4222-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4223-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4224
4225secondary:
4226-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4227-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4228-chardev socket,id=red0,host=3.3.3.3,port=9003
4229-chardev socket,id=red1,host=3.3.3.3,port=9004
4230-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4231-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4232
4233@end example
4234
4235If you want to know the detail of above command line, you can read
4236the colo-compare git log.
4237
Gonglei1653a5f2016-10-28 16:33:23 +08004238@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4239
4240Creates a cryptodev backend which executes crypto opreation from
4241the QEMU cipher APIS. The @var{id} parameter is
4242a unique ID that will be used to reference this cryptodev backend from
4243the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4244which specify the queue number of cryptodev backend, the default of
4245@var{queues} is 1.
4246
4247@example
4248
4249 # qemu-system-x86_64 \
4250 [...] \
4251 -object cryptodev-backend-builtin,id=cryptodev0 \
4252 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4253 [...]
4254@end example
4255
Gonglei042cea22018-03-01 21:46:28 +08004256@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}]
4257
4258Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}.
4259The @var{id} parameter is a unique ID that will be used to reference this
4260cryptodev backend from the @option{virtio-crypto} device.
4261The chardev should be a unix domain socket backed one. The vhost-user uses
4262a specifically defined protocol to pass vhost ioctl replacement messages
4263to an application on the other end of the socket.
4264The @var{queues} parameter is optional, which specify the queue number
4265of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1.
4266
4267@example
4268
4269 # qemu-system-x86_64 \
4270 [...] \
4271 -chardev socket,id=chardev0,path=/path/to/socket \
4272 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4273 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4274 [...]
4275@end example
4276
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004277@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4278@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4279
4280Defines a secret to store a password, encryption key, or some other sensitive
4281data. The sensitive data can either be passed directly via the @var{data}
4282parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4283parameter is insecure unless the sensitive data is encrypted.
4284
4285The sensitive data can be provided in raw format (the default), or base64.
4286When encoded as JSON, the raw format only supports valid UTF-8 characters,
4287so base64 is recommended for sending binary data. QEMU will convert from
4288which ever format is provided to the format it needs internally. eg, an
4289RBD password can be provided in raw format, even though it will be base64
4290encoded when passed onto the RBD sever.
4291
4292For added protection, it is possible to encrypt the data associated with
4293a secret using the AES-256-CBC cipher. Use of encryption is indicated
4294by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4295parameter provides the ID of a previously defined secret that contains
4296the AES-256 decryption key. This key should be 32-bytes long and be
4297base64 encoded. The @var{iv} parameter provides the random initialization
4298vector used for encryption of this particular secret and should be a
Daniel P. Berrange69c0b272016-04-04 10:33:55 +01004299base64 encrypted string of the 16-byte IV.
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004300
4301The simplest (insecure) usage is to provide the secret inline
4302
4303@example
4304
4305 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4306
4307@end example
4308
4309The simplest secure usage is to provide the secret via a file
4310
Eric Blakeb43671f2017-07-03 13:09:50 -05004311 # printf "letmein" > mypasswd.txt
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004312 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4313
4314For greater security, AES-256-CBC should be used. To illustrate usage,
4315consider the openssl command line tool which can encrypt the data. Note
4316that when encrypting, the plaintext must be padded to the cipher block
4317size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4318
4319First a master key needs to be created in base64 encoding:
4320
4321@example
4322 # openssl rand -base64 32 > key.b64
4323 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4324@end example
4325
4326Each secret to be encrypted needs to have a random initialization vector
4327generated. These do not need to be kept secret
4328
4329@example
4330 # openssl rand -base64 16 > iv.b64
4331 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4332@end example
4333
4334The secret to be defined can now be encrypted, in this case we're
4335telling openssl to base64 encode the result, but it could be left
4336as raw bytes if desired.
4337
4338@example
Eric Blakeb43671f2017-07-03 13:09:50 -05004339 # SECRET=$(printf "letmein" |
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004340 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4341@end example
4342
4343When launching QEMU, create a master secret pointing to @code{key.b64}
4344and specify that to be used to decrypt the user password. Pass the
4345contents of @code{iv.b64} to the second secret
4346
4347@example
4348 # $QEMU \
4349 -object secret,id=secmaster0,format=base64,file=key.b64 \
4350 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4351 data=$SECRET,iv=$(<iv.b64)
4352@end example
4353
Brijesh Singha9b49422018-03-08 06:48:41 -06004354@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}]
4355
4356Create a Secure Encrypted Virtualization (SEV) guest object, which can be used
4357to provide the guest memory encryption support on AMD processors.
4358
4359When memory encryption is enabled, one of the physical address bit (aka the
4360C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos}
4361is used to provide the C-bit position. The C-bit position is Host family dependent
4362hence user must provide this value. On EPYC, the value should be 47.
4363
4364When memory encryption is enabled, we loose certain bits in physical address space.
4365The @option{reduced-phys-bits} is used to provide the number of bits we loose in
4366physical address space. Similar to C-bit, the value is Host family dependent.
4367On EPYC, the value should be 5.
4368
4369The @option{sev-device} provides the device file to use for communicating with
4370the SEV firmware running inside AMD Secure Processor. The default device is
4371'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are
4372created by CCP driver.
4373
4374The @option{policy} provides the guest policy to be enforced by the SEV firmware
4375and restrict what configuration and operational commands can be performed on this
4376guest by the hypervisor. The policy should be provided by the guest owner and is
4377bound to the guest and cannot be changed throughout the lifetime of the guest.
4378The default is 0.
4379
4380If guest @option{policy} allows sharing the key with another SEV guest then
4381@option{handle} can be use to provide handle of the guest from which to share
4382the key.
4383
4384The @option{dh-cert-file} and @option{session-file} provides the guest owner's
4385Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters
4386are used for establishing a cryptographic session with the guest owner to
4387negotiate keys used for attestation. The file must be encoded in base64.
4388
4389e.g to launch a SEV guest
4390@example
4391 # $QEMU \
4392 ......
4393 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4394 -machine ...,memory-encryption=sev0
4395 .....
4396
4397@end example
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004398@end table
4399
4400ETEXI
4401
4402
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004403HXCOMM This is the last statement. Insert new options before this line!
4404STEXI
4405@end table
4406ETEXI