blob: d4f3564b788428e39854fc7e3e1c9d068d129954 [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-create", 0, QEMU_OPTION_xen_create,
3398 "-xen-create create domain using xen hypercalls, bypassing xend\n"
Blue Swirlad960902010-03-29 19:23:52 +00003399 " warning: should not be used when xend is in use\n",
3400 QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003401DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3402 "-xen-attach attach to existing xen domain\n"
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003403 " xend will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00003404 QEMU_ARCH_ALL)
Paul Durrant1c599472017-03-22 09:39:15 +00003405DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3406 "-xen-domid-restrict restrict set of available xen operations\n"
3407 " to specified domain id. (Does not affect\n"
3408 " xenpv machine type).\n",
3409 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003410STEXI
3411@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003412@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01003413Specify xen guest domain @var{id} (XEN only).
3414@item -xen-create
Stefan Weil6616b2a2010-02-05 23:52:05 +01003415@findex -xen-create
Stefan Weil95d5f082010-01-20 22:25:27 +01003416Create domain using xen hypercalls, bypassing xend.
3417Warning: should not be used when xend is in use (XEN only).
3418@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01003419@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01003420Attach to existing xen domain.
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003421xend will use this when starting QEMU (XEN only).
Paul Durrant1c599472017-03-22 09:39:15 +00003422@findex -xen-domid-restrict
3423Restrict set of available xen operations to specified domain id (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003424ETEXI
aliguorie37630c2009-04-22 15:19:10 +00003425
blueswir15824d652009-03-28 06:44:27 +00003426DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00003427 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003428STEXI
3429@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01003430@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00003431Exit instead of rebooting.
3432ETEXI
3433
3434DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00003435 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003436STEXI
3437@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01003438@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00003439Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3440This allows for instance switching to monitor to commit changes to the
3441disk image.
3442ETEXI
3443
3444DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3445 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003446 " start right away with a saved state (loadvm in monitor)\n",
3447 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003448STEXI
3449@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003450@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00003451Start right away with a saved state (@code{loadvm} in monitor)
3452ETEXI
3453
3454#ifndef _WIN32
3455DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00003456 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003457#endif
3458STEXI
3459@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01003460@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00003461Daemonize the QEMU process after initialization. QEMU will not detach from
3462standard IO until it is ready to receive connections on any of its devices.
3463This option is a useful way for external programs to launch QEMU without having
3464to cope with initialization race conditions.
3465ETEXI
3466
3467DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00003468 "-option-rom rom load a file, rom, into the option ROM space\n",
3469 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003470STEXI
3471@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003472@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003473Load the contents of @var{file} as an option ROM.
3474This option is useful to load things like EtherBoot.
3475ETEXI
3476
Markus Armbrustere2180522014-10-06 16:19:07 +02003477HXCOMM Silently ignored for compatibility
3478DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003479
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003480DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Artem Pisarenko238d1242018-10-18 13:12:52 +06003481 "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003482 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3483 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003484
blueswir15824d652009-03-28 06:44:27 +00003485STEXI
3486
Artem Pisarenko238d1242018-10-18 13:12:52 +06003487@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003488@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003489Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3490UTC or local time, respectively. @code{localtime} is required for correct date in
Artem Pisarenko238d1242018-10-18 13:12:52 +06003491MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003492format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3493
Michael Tokarev9d85d552014-04-07 13:34:58 +04003494By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003495RTC as accurate reference clock inside the guest, specifically if the host
3496time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003497If you want to isolate the guest time from the host, you can set @option{clock}
Artem Pisarenko238d1242018-10-18 13:12:52 +06003498to @code{rt} instead, which provides a host monotonic clock if host support it.
3499To even prevent the RTC from progressing during suspension, you can set @option{clock}
3500to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in
3501icount mode in order to preserve determinism; however, note that in icount mode
3502the speed of the virtual clock is variable and can in general differ from the
3503host clock.
Jan Kiszka68752042009-09-15 13:36:04 +02003504
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003505Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3506specifically with Windows' ACPI HAL. This option will try to figure out how
3507many timer interrupts were not processed by the Windows guest and will
3508re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003509ETEXI
3510
3511DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003512 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003513 " enable virtual instruction counter with 2^N clock ticks per\n" \
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003514 " instruction, enable aligning the host and virtual clocks\n" \
3515 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003516STEXI
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003517@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003518@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003519Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003520instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003521then the virtual cpu speed will be automatically adjusted to keep virtual
3522time within a few seconds of real time.
3523
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003524When the virtual cpu is sleeping, the virtual time will advance at default
Pranith Kumar778d9f92016-02-26 10:16:51 -05003525speed unless @option{sleep=on|off} is specified.
3526With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003527instantly whenever the virtual cpu goes to sleep mode and will not advance
3528if no timer is enabled. This behavior give deterministic execution times from
3529the guest point of view.
3530
blueswir15824d652009-03-28 06:44:27 +00003531Note that while this option can give deterministic behavior, it does not
3532provide cycle accurate emulation. Modern CPUs contain superscalar out of
3533order cores with complex cache hierarchies. The number of instructions
3534executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003535
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01003536@option{align=on} will activate the delay algorithm which will try
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003537to synchronise the host clock and the virtual clock. The goal is to
3538have a guest running at the real frequency imposed by the shift option.
3539Whenever the guest clock is behind the host clock and if
Michael Tokarev82597612015-04-27 11:12:49 +03003540@option{align=on} is specified then we print a message to the user
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003541to inform about the delay.
3542Currently this option does not work when @option{shift} is @code{auto}.
3543Note: The sync algorithm will work for those shift values for which
3544the guest clock runs ahead of the host clock. Typically this happens
3545when the shift value is high (how high depends on the host machine).
Pavel Dovgalyuk4c27b852015-09-17 19:25:18 +03003546
3547When @option{rr} option is specified deterministic record/replay is enabled.
3548Replay log is written into @var{filename} file in record mode and
3549read from this file in replay mode.
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003550
3551Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3552at the start of execution recording. In replay mode this option is used
3553to load the initial VM state.
blueswir15824d652009-03-28 06:44:27 +00003554ETEXI
3555
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003556DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
Xu Wangd7933ef2015-06-11 17:32:05 +02003557 "-watchdog model\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003558 " enable virtual hardware watchdog [default=none]\n",
3559 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003560STEXI
3561@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003562@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003563Create a virtual hardware watchdog device. Once enabled (by a guest
3564action), the watchdog must be periodically polled by an agent inside
Xu Wangd7933ef2015-06-11 17:32:05 +02003565the guest or else the guest will be restarted. Choose a model for
3566which your guest has drivers.
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003567
Xu Wangd7933ef2015-06-11 17:32:05 +02003568The @var{model} is the model of hardware watchdog to emulate. Use
3569@code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003570watchdog can be enabled for a guest.
Xu Wangd7933ef2015-06-11 17:32:05 +02003571
3572The following models may be available:
3573@table @option
3574@item ib700
3575iBASE 700 is a very simple ISA watchdog with a single timer.
3576@item i6300esb
3577Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3578dual-timer watchdog.
Xu Wang188f24c2015-02-05 18:28:32 +08003579@item diag288
3580A virtual watchdog for s390x backed by the diagnose 288 hypercall
3581(currently KVM only).
Xu Wangd7933ef2015-06-11 17:32:05 +02003582@end table
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003583ETEXI
3584
3585DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
Markus Armbruster7ad92702017-10-02 16:03:07 +02003586 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003587 " action when watchdog fires [default=reset]\n",
3588 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003589STEXI
3590@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003591@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003592
3593The @var{action} controls what QEMU will do when the watchdog timer
3594expires.
3595The default is
3596@code{reset} (forcefully reset the guest).
3597Other possible actions are:
3598@code{shutdown} (attempt to gracefully shutdown the guest),
3599@code{poweroff} (forcefully poweroff the guest),
Markus Armbruster7ad92702017-10-02 16:03:07 +02003600@code{inject-nmi} (inject a NMI into the guest),
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003601@code{pause} (pause the guest),
3602@code{debug} (print a debug message and continue), or
3603@code{none} (do nothing).
3604
3605Note that the @code{shutdown} action requires that the guest responds
3606to ACPI signals, which it may not be able to do in the sort of
3607situations where the watchdog would have expired, and thus
3608@code{-watchdog-action shutdown} is not recommended for production use.
3609
3610Examples:
3611
3612@table @code
3613@item -watchdog i6300esb -watchdog-action pause
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003614@itemx -watchdog ib700
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003615@end table
3616ETEXI
3617
blueswir15824d652009-03-28 06:44:27 +00003618DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003619 "-echr chr set terminal escape character instead of ctrl-a\n",
3620 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003621STEXI
3622
Kevin Wolf4e257e52009-10-09 10:58:36 +02003623@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003624@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003625Change the escape character used for switching to the monitor when using
3626monitor and serial sharing. The default is @code{0x01} when using the
3627@code{-nographic} option. @code{0x01} is equal to pressing
3628@code{Control-a}. You can select a different character from the ascii
3629control keys where 1 through 26 map to Control-a through Control-z. For
3630instance you could use the either of the following to change the escape
3631character to Control-t.
3632@table @code
3633@item -echr 0x14
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003634@itemx -echr 20
blueswir15824d652009-03-28 06:44:27 +00003635@end table
3636ETEXI
3637
3638DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3639 "-virtioconsole c\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003640 " set virtio console\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003641STEXI
3642@item -virtioconsole @var{c}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003643@findex -virtioconsole
blueswir15824d652009-03-28 06:44:27 +00003644Set virtio console.
Thomas Huth45401292018-05-04 17:13:10 +02003645This option is deprecated, please use @option{-device virtconsole} instead.
blueswir15824d652009-03-28 06:44:27 +00003646ETEXI
3647
3648DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003649 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003650STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003651@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003652@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003653Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003654ETEXI
3655
3656DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003657 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003658STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003659@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003660@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003661Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003662ETEXI
3663
3664DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Michael Tokarev7c601802015-02-10 22:40:47 +03003665 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3666 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3667 "-incoming unix:socketpath\n" \
3668 " prepare for incoming migration, listen on\n" \
3669 " specified protocol and socket address\n" \
3670 "-incoming fd:fd\n" \
3671 "-incoming exec:cmdline\n" \
3672 " accept incoming migration on given file descriptor\n" \
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003673 " or from given external command\n" \
3674 "-incoming defer\n" \
3675 " wait for the URI to be specified via migrate_incoming\n",
Blue Swirlad960902010-03-29 19:23:52 +00003676 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003677STEXI
Michael Tokarev7c601802015-02-10 22:40:47 +03003678@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003679@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003680@findex -incoming
Michael Tokarev7c601802015-02-10 22:40:47 +03003681Prepare for incoming migration, listen on a given tcp port.
3682
3683@item -incoming unix:@var{socketpath}
3684Prepare for incoming migration, listen on a given unix socket.
3685
3686@item -incoming fd:@var{fd}
3687Accept incoming migration from a given filedescriptor.
3688
3689@item -incoming exec:@var{cmdline}
3690Accept incoming migration as an output from specified external command.
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003691
3692@item -incoming defer
3693Wait for the URI to be specified via migrate_incoming. The monitor can
3694be used to change settings (such as migration parameters) prior to issuing
3695the migrate_incoming to allow the migration to begin.
blueswir15824d652009-03-28 06:44:27 +00003696ETEXI
3697
Ashijeet Acharyad15c05f2017-01-16 17:01:51 +05303698DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3699 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3700STEXI
3701@item -only-migratable
3702@findex -only-migratable
3703Only allow migratable devices. Devices will not be allowed to enter an
3704unmigratable state.
3705ETEXI
3706
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003707DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003708 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003709STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003710@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003711@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003712Don't create default devices. Normally, QEMU sets the default devices like serial
3713port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3714CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3715default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003716ETEXI
3717
blueswir15824d652009-03-28 06:44:27 +00003718#ifndef _WIN32
3719DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003720 "-chroot dir chroot to dir just before starting the VM\n",
3721 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003722#endif
3723STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003724@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003725@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003726Immediately before starting guest execution, chroot to the specified
3727directory. Especially useful in combination with -runas.
3728ETEXI
3729
3730#ifndef _WIN32
3731DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Ian Jackson2c42f1e2017-09-15 18:10:44 +01003732 "-runas user change to user id user just before starting the VM\n" \
3733 " user can be numeric uid:gid instead\n",
Blue Swirlad960902010-03-29 19:23:52 +00003734 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003735#endif
3736STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003737@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003738@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003739Immediately before starting guest execution, drop root privileges, switching
3740to the specified user.
3741ETEXI
3742
blueswir15824d652009-03-28 06:44:27 +00003743DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3744 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003745 " set OpenBIOS nvram variables\n",
3746 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003747STEXI
3748@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003749@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003750Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3751ETEXI
blueswir15824d652009-03-28 06:44:27 +00003752DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003753 "-semihosting semihosting mode\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003754 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3755 QEMU_ARCH_MIPS)
Stefan Weil95d5f082010-01-20 22:25:27 +01003756STEXI
3757@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003758@findex -semihosting
Leon Alrae3b3c1692015-06-19 11:08:43 +01003759Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
Liviu Ionescua38bb072014-12-11 12:07:48 +00003760ETEXI
3761DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
Leon Alraea59d31a2015-06-19 14:17:45 +01003762 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3763 " semihosting configuration\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003764QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3765QEMU_ARCH_MIPS)
Liviu Ionescua38bb072014-12-11 12:07:48 +00003766STEXI
Leon Alraea59d31a2015-06-19 14:17:45 +01003767@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
Liviu Ionescua38bb072014-12-11 12:07:48 +00003768@findex -semihosting-config
Leon Alrae3b3c1692015-06-19 11:08:43 +01003769Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
Leon Alraea59d31a2015-06-19 14:17:45 +01003770@table @option
3771@item target=@code{native|gdb|auto}
3772Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3773or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3774during debug sessions and @code{native} otherwise.
3775@item arg=@var{str1},arg=@var{str2},...
3776Allows the user to pass input arguments, and can be used multiple times to build
3777up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3778command line is still supported for backward compatibility. If both the
3779@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3780specified, the former is passed to semihosting as it always takes precedence.
3781@end table
Stefan Weil95d5f082010-01-20 22:25:27 +01003782ETEXI
blueswir15824d652009-03-28 06:44:27 +00003783DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00003784 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003785STEXI
3786@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01003787@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003788Old param mode (ARM only).
3789ETEXI
3790
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003791DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003792 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003793 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003794 " Enable seccomp mode 2 system call filter (default 'off').\n" \
3795 " use 'obsolete' to allow obsolete system calls that are provided\n" \
3796 " by the kernel, but typically no longer used by modern\n" \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003797 " C library implementations.\n" \
3798 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \
3799 " its privileges by blacklisting all set*uid|gid system calls.\n" \
3800 " The value 'children' will deny set*uid|gid system calls for\n" \
Eduardo Otubo995a2262017-03-13 22:16:01 +01003801 " main QEMU process but will allow forks and execves to run unprivileged\n" \
3802 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003803 " blacklisting *fork and execve\n" \
3804 " use 'resourcecontrol' to disable process affinity and schedular priority\n",
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003805 QEMU_ARCH_ALL)
3806STEXI
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003807@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003808@findex -sandbox
3809Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3810disable it. The default is 'off'.
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003811@table @option
3812@item obsolete=@var{string}
3813Enable Obsolete system calls
Eduardo Otubo73a1e642017-03-13 22:13:27 +01003814@item elevateprivileges=@var{string}
3815Disable set*uid|gid system calls
Eduardo Otubo995a2262017-03-13 22:16:01 +01003816@item spawn=@var{string}
3817Disable *fork and execve
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01003818@item resourcecontrol=@var{string}
3819Disable process affinity and schedular priority
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01003820@end table
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003821ETEXI
3822
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003823DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00003824 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003825STEXI
3826@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003827@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003828Read device configuration from @var{file}. This approach is useful when you want to spawn
3829QEMU process with many command line options but you don't want to exceed the command line
3830character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003831ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003832DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3833 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00003834 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003835STEXI
3836@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003837@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003838Write device configuration to @var{file}. The @var{file} can be either filename to save
3839command line and device configuration into file or dash @code{-}) character to print the
3840output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003841ETEXI
Thomas Huth2feac452018-08-21 12:59:56 +02003842
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003843DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3844 "-no-user-config\n"
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003845 " do not load default user-provided config files at startup\n",
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003846 QEMU_ARCH_ALL)
3847STEXI
3848@item -no-user-config
3849@findex -no-user-config
3850The @code{-no-user-config} option makes QEMU not load any of the user-provided
Eduardo Habkost3478eae2017-10-04 00:00:25 -03003851config files on @var{sysconfdir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06003852ETEXI
Thomas Huth2feac452018-08-21 12:59:56 +02003853
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003854DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Paolo Bonzini10578a22016-01-07 16:55:26 +03003855 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
Lluís23d15e82011-08-31 20:31:31 +02003856 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003857 QEMU_ARCH_ALL)
3858STEXI
Lluís23d15e82011-08-31 20:31:31 +02003859HXCOMM This line is not accurate, as some sub-options are backend-specific but
3860HXCOMM HX does not support conditional compilation of text.
Denis V. Luneve370ad92016-06-17 17:44:08 +03003861@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003862@findex -trace
Denis V. Luneveeb2b8f2016-06-17 17:44:09 +03003863@include qemu-option-trace.texi
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003864ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003865
Markus Armbruster31e70d62013-02-13 19:49:37 +01003866HXCOMM Internal use
3867DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3868DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02003869
Paul Moore0f669982012-08-03 14:39:21 -04003870#ifdef __linux__
3871DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3872 "-enable-fips enable FIPS 140-2 compliance\n",
3873 QEMU_ARCH_ALL)
3874#endif
3875STEXI
3876@item -enable-fips
3877@findex -enable-fips
3878Enable FIPS 140-2 compliance mode.
3879ETEXI
3880
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003881HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003882DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003883
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04003884DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3885 "-msg timestamp[=on|off]\n"
3886 " change the format of messages\n"
3887 " on|off controls leading timestamps (default:on)\n",
3888 QEMU_ARCH_ALL)
3889STEXI
3890@item -msg timestamp[=on|off]
3891@findex -msg
3892prepend a timestamp to each log message.(default:on)
3893ETEXI
3894
Amit Shahabfd9ce2014-06-20 18:56:08 +05303895DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3896 "-dump-vmstate <file>\n"
3897 " Output vmstate information in JSON format to file.\n"
3898 " Use the scripts/vmstate-static-checker.py file to\n"
3899 " check for possible regressions in migration code\n"
Laurent Vivier23820532015-09-04 21:30:04 +02003900 " by comparing two such vmstate dumps.\n",
Amit Shahabfd9ce2014-06-20 18:56:08 +05303901 QEMU_ARCH_ALL)
3902STEXI
3903@item -dump-vmstate @var{file}
3904@findex -dump-vmstate
3905Dump json-encoded vmstate information for current machine type to file
3906in @var{file}
3907ETEXI
3908
Emilio G. Cota12df1892018-08-15 11:42:49 -04003909DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile,
3910 "-enable-sync-profile\n"
3911 " enable synchronization profiling\n",
3912 QEMU_ARCH_ALL)
3913STEXI
3914@item -enable-sync-profile
3915@findex -enable-sync-profile
3916Enable synchronization profiling.
3917ETEXI
3918
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003919STEXI
3920@end table
3921ETEXI
3922DEFHEADING()
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003923
3924DEFHEADING(Generic object creation:)
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003925STEXI
3926@table @option
3927ETEXI
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003928
3929DEF("object", HAS_ARG, QEMU_OPTION_object,
3930 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3931 " create a new object of type TYPENAME setting properties\n"
3932 " in the order they are specified. Note that the 'id'\n"
3933 " property must be set. These objects are placed in the\n"
3934 " '/objects' path.\n",
3935 QEMU_ARCH_ALL)
3936STEXI
3937@item -object @var{typename}[,@var{prop1}=@var{value1},...]
3938@findex -object
3939Create a new object of type @var{typename} setting properties
3940in the order they are specified. Note that the 'id'
3941property must be set. These objects are placed in the
3942'/objects' path.
3943
3944@table @option
3945
Haozhong Zhang98376842017-12-11 15:28:04 +08003946@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 +01003947
3948Creates a memory file backend object, which can be used to back
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003949the guest RAM with huge pages.
3950
3951The @option{id} parameter is a unique ID that will be used to reference this
3952memory region when configuring the @option{-numa} argument.
3953
3954The @option{size} option provides the size of the memory region, and accepts
3955common suffixes, eg @option{500M}.
3956
3957The @option{mem-path} provides the path to either a shared memory or huge page
3958filesystem mount.
3959
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003960The @option{share} boolean option determines whether the memory
3961region is marked as private to QEMU, or shared. The latter allows
3962a co-operating external process to access the QEMU memory region.
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003963
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02003964The @option{share} is also required for pvrdma devices due to
3965limitations in the RDMA API provided by Linux.
3966
3967Setting share=on might affect the ability to configure NUMA
3968bindings for the memory backend under some circumstances, see
3969Documentation/vm/numa_memory_policy.txt on the Linux kernel
3970source tree for additional details.
3971
Eduardo Habkost11ae6ed2017-08-24 16:23:15 -03003972Setting the @option{discard-data} boolean option to @var{on}
3973indicates that file contents can be destroyed when QEMU exits,
3974to avoid unnecessarily flushing data to the backing file. Note
3975that @option{discard-data} is only an optimization, and QEMU
3976might not discard file contents if it aborts unexpectedly or is
3977terminated using SIGKILL.
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003978
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00003979The @option{merge} boolean option enables memory merge, also known as
3980MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
3981memory deduplication.
3982
3983Setting the @option{dump} boolean option to @var{off} excludes the memory from
3984core dumps. This feature is also known as MADV_DONTDUMP.
3985
3986The @option{prealloc} boolean option enables memory preallocation.
3987
3988The @option{host-nodes} option binds the memory range to a list of NUMA host
3989nodes.
3990
3991The @option{policy} option sets the NUMA policy to one of the following values:
3992
3993@table @option
3994@item @var{default}
3995default host policy
3996
3997@item @var{preferred}
3998prefer the given host node list for allocation
3999
4000@item @var{bind}
4001restrict memory allocation to the given host node list
4002
4003@item @var{interleave}
4004interleave memory allocations across the given host node list
4005@end table
4006
Haozhong Zhang98376842017-12-11 15:28:04 +08004007The @option{align} option specifies the base address alignment when
4008QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg
4009@option{2M}. Some backend store specified by @option{mem-path}
4010requires an alignment different than the default one used by QEMU, eg
4011the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
4012such cases, users can specify the required alignment via this option.
4013
Junyan Hea4de8552018-07-18 15:48:00 +08004014The @option{pmem} option specifies whether the backing file specified
4015by @option{mem-path} is in host persistent memory that can be accessed
4016using the SNIA NVM programming model (e.g. Intel NVDIMM).
4017If @option{pmem} is set to 'on', QEMU will take necessary operations to
4018guarantee the persistence of its own writes to @option{mem-path}
4019(e.g. in vNVDIMM label emulation and live migration).
4020
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02004021@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 +00004022
4023Creates a memory backend object, which can be used to back the guest RAM.
4024Memory backend objects offer more control than the @option{-m} option that is
4025traditionally used to define guest RAM. Please refer to
4026@option{memory-backend-file} for a description of the options.
4027
Marc-André Lureau36ea3972018-08-28 17:38:40 +02004028@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 +01004029
4030Creates an anonymous memory file backend object, which allows QEMU to
4031share the memory with an external process (e.g. when using
4032vhost-user). The memory is allocated with memfd and optional
4033sealing. (Linux only)
4034
4035The @option{seal} option creates a sealed-file, that will block
4036further resizing the memory ('on' by default).
4037
4038The @option{hugetlb} option specify the file to be created resides in
4039the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with
4040the @option{hugetlb} option, the @option{hugetlbsize} option specify
4041the hugetlb page size on systems that support multiple hugetlb page
4042sizes (it must be a power of 2 value supported by the system).
4043
4044In some versions of Linux, the @option{hugetlb} option is incompatible
4045with the @option{seal} option (requires at least Linux 4.16).
4046
4047Please refer to @option{memory-backend-file} for a description of the
4048other options.
4049
Marc-André Lureau36ea3972018-08-28 17:38:40 +02004050The @option{share} boolean option is @var{on} by default with memfd.
4051
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004052@item -object rng-random,id=@var{id},filename=@var{/dev/random}
4053
4054Creates a random number generator backend which obtains entropy from
4055a device on the host. The @option{id} parameter is a unique ID that
4056will be used to reference this entropy backend from the @option{virtio-rng}
4057device. The @option{filename} parameter specifies which file to obtain
4058entropy from and if omitted defaults to @option{/dev/random}.
4059
4060@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4061
4062Creates a random number generator backend which obtains entropy from
4063an external daemon running on the host. The @option{id} parameter is
4064a unique ID that will be used to reference this entropy backend from
4065the @option{virtio-rng} device. The @option{chardev} parameter is
4066the unique ID of a character device backend that provides the connection
4067to the RNG daemon.
4068
Daniel P. Berrangee00adf62015-03-13 17:39:26 +00004069@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4070
4071Creates a TLS anonymous credentials object, which can be used to provide
4072TLS support on network backends. The @option{id} parameter is a unique
4073ID which network backends will use to access the credentials. The
4074@option{endpoint} is either @option{server} or @option{client} depending
4075on whether the QEMU network backend that uses the credentials will be
4076acting as a client or as a server. If @option{verify-peer} is enabled
4077(the default) then once the handshake is completed, the peer credentials
4078will be verified, though this is a no-op for anonymous credentials.
4079
4080The @var{dir} parameter tells QEMU where to find the credential
4081files. For server endpoints, this directory may contain a file
4082@var{dh-params.pem} providing diffie-hellman parameters to use
4083for the TLS server. If the file is missing, QEMU will generate
4084a set of DH parameters at startup. This is a computationally
4085expensive operation that consumes random pool entropy, so it is
4086recommended that a persistent set of parameters be generated
4087upfront and saved.
4088
Richard W.M. Jonese1a6dc92018-07-03 09:03:03 +01004089@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}]
4090
4091Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide
4092TLS support on network backends. The @option{id} parameter is a unique
4093ID which network backends will use to access the credentials. The
4094@option{endpoint} is either @option{server} or @option{client} depending
4095on whether the QEMU network backend that uses the credentials will be
4096acting as a client or as a server. For clients only, @option{username}
4097is the username which will be sent to the server. If omitted
4098it defaults to ``qemu''.
4099
4100The @var{dir} parameter tells QEMU where to find the keys file.
4101It is called ``@var{dir}/keys.psk'' and contains ``username:key''
4102pairs. This file can most easily be created using the GnuTLS
4103@code{psktool} program.
4104
4105For server endpoints, @var{dir} may also contain a file
4106@var{dh-params.pem} providing diffie-hellman parameters to use
4107for the TLS server. If the file is missing, QEMU will generate
4108a set of DH parameters at startup. This is a computationally
4109expensive operation that consumes random pool entropy, so it is
4110recommended that a persistent set of parameters be generated
4111up front and saved.
4112
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004113@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 +00004114
4115Creates a TLS anonymous credentials object, which can be used to provide
4116TLS support on network backends. The @option{id} parameter is a unique
4117ID which network backends will use to access the credentials. The
4118@option{endpoint} is either @option{server} or @option{client} depending
4119on whether the QEMU network backend that uses the credentials will be
4120acting as a client or as a server. If @option{verify-peer} is enabled
4121(the default) then once the handshake is completed, the peer credentials
4122will be verified. With x509 certificates, this implies that the clients
4123must be provided with valid client certificates too.
4124
4125The @var{dir} parameter tells QEMU where to find the credential
4126files. For server endpoints, this directory may contain a file
4127@var{dh-params.pem} providing diffie-hellman parameters to use
4128for the TLS server. If the file is missing, QEMU will generate
4129a set of DH parameters at startup. This is a computationally
4130expensive operation that consumes random pool entropy, so it is
4131recommended that a persistent set of parameters be generated
4132upfront and saved.
4133
4134For x509 certificate credentials the directory will contain further files
4135providing the x509 certificates. The certificates must be stored
4136in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4137@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4138@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4139
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004140For the @var{server-key.pem} and @var{client-key.pem} files which
4141contain sensitive private keys, it is possible to use an encrypted
4142version by providing the @var{passwordid} parameter. This provides
4143the ID of a previously created @code{secret} object containing the
4144password for decryption.
4145
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004146The @var{priority} parameter allows to override the global default
4147priority used by gnutls. This can be useful if the system administrator
4148needs to use a weaker set of crypto priorities for QEMU without
4149potentially forcing the weakness onto all applications. Or conversely
4150if one wants wants a stronger default for QEMU than for all other
4151applications, they can do this through this parameter. Its format is
4152a gnutls priority string as described at
4153@url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
4154
zhanghailiang338d3f42016-03-01 13:37:02 +08004155@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 +08004156
4157Interval @var{t} can't be 0, this filter batches the packet delivery: all
4158packets arriving in a given interval on netdev @var{netdevid} are delayed
4159until the end of the interval. Interval is in microseconds.
zhanghailiang338d3f42016-03-01 13:37:02 +08004160@option{status} is optional that indicate whether the netfilter is
4161on (enabled) or off (disabled), the default status for netfilter will be 'on'.
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004162
4163queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4164
4165@option{all}: the filter is attached both to the receive and the transmit
4166 queue of the netdev (default).
4167
4168@option{rx}: the filter is attached to the receive queue of the netdev,
4169 where it will receive packets sent to the netdev.
4170
4171@option{tx}: the filter is attached to the transmit queue of the netdev,
4172 where it will receive packets sent by the netdev.
4173
Zhang Chene2521f02017-07-04 14:53:48 +08004174@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 +08004175
Zhang Chene2521f02017-07-04 14:53:48 +08004176filter-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 +08004177
Zhang Chen00d5c242017-07-04 14:53:49 +08004178@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 +08004179
4180filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
Zhang Chen00d5c242017-07-04 14:53:49 +08004181@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4182filter-redirector will redirect packet with vnet_hdr_len.
Zhang Chend46f75b2016-03-17 16:16:26 +08004183Create a filter-redirector we need to differ outdev id from indev id, id can not
4184be the same. we can just use indev or outdev, but at least one of indev or outdev
4185need to be specified.
4186
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004187@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 +08004188
4189Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4190secondary from primary to keep secondary tcp connection,and rewrite
4191tcp packet to primary from secondary make tcp packet can be handled by
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004192client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
Zhang Chene6eee8a2016-09-27 10:22:32 +08004193
4194usage:
4195colo secondary:
4196-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4197-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4198-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4199
Changlong Xiec551cd52016-10-11 13:28:32 +08004200@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
Thomas Huthd3e0c032015-10-13 12:40:02 +02004201
4202Dump the network traffic on netdev @var{dev} to the file specified by
4203@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4204The file format is libpcap, so it can be analyzed with tools such as tcpdump
4205or Wireshark.
4206
Zhang Chenaa3a7032017-07-04 14:53:52 +08004207@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 +08004208
4209Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4210secondary packet. If the packets are same, we will output primary
4211packet to outdev@var{chardevid}, else we will notify colo-frame
4212do checkpoint and send primary packet to outdev@var{chardevid}.
Zhang Chenaa3a7032017-07-04 14:53:52 +08004213if it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len.
Zhang Chen7dce4e62016-09-27 10:22:26 +08004214
4215we must use it with the help of filter-mirror and filter-redirector.
4216
4217@example
4218
4219primary:
4220-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4221-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4222-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4223-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4224-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4225-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4226-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4227-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4228-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4229-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4230-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4231-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4232
4233secondary:
4234-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4235-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4236-chardev socket,id=red0,host=3.3.3.3,port=9003
4237-chardev socket,id=red1,host=3.3.3.3,port=9004
4238-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4239-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4240
4241@end example
4242
4243If you want to know the detail of above command line, you can read
4244the colo-compare git log.
4245
Gonglei1653a5f2016-10-28 16:33:23 +08004246@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4247
4248Creates a cryptodev backend which executes crypto opreation from
4249the QEMU cipher APIS. The @var{id} parameter is
4250a unique ID that will be used to reference this cryptodev backend from
4251the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4252which specify the queue number of cryptodev backend, the default of
4253@var{queues} is 1.
4254
4255@example
4256
4257 # qemu-system-x86_64 \
4258 [...] \
4259 -object cryptodev-backend-builtin,id=cryptodev0 \
4260 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4261 [...]
4262@end example
4263
Gonglei042cea22018-03-01 21:46:28 +08004264@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}]
4265
4266Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}.
4267The @var{id} parameter is a unique ID that will be used to reference this
4268cryptodev backend from the @option{virtio-crypto} device.
4269The chardev should be a unix domain socket backed one. The vhost-user uses
4270a specifically defined protocol to pass vhost ioctl replacement messages
4271to an application on the other end of the socket.
4272The @var{queues} parameter is optional, which specify the queue number
4273of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1.
4274
4275@example
4276
4277 # qemu-system-x86_64 \
4278 [...] \
4279 -chardev socket,id=chardev0,path=/path/to/socket \
4280 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4281 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4282 [...]
4283@end example
4284
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004285@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4286@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4287
4288Defines a secret to store a password, encryption key, or some other sensitive
4289data. The sensitive data can either be passed directly via the @var{data}
4290parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4291parameter is insecure unless the sensitive data is encrypted.
4292
4293The sensitive data can be provided in raw format (the default), or base64.
4294When encoded as JSON, the raw format only supports valid UTF-8 characters,
4295so base64 is recommended for sending binary data. QEMU will convert from
4296which ever format is provided to the format it needs internally. eg, an
4297RBD password can be provided in raw format, even though it will be base64
4298encoded when passed onto the RBD sever.
4299
4300For added protection, it is possible to encrypt the data associated with
4301a secret using the AES-256-CBC cipher. Use of encryption is indicated
4302by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4303parameter provides the ID of a previously defined secret that contains
4304the AES-256 decryption key. This key should be 32-bytes long and be
4305base64 encoded. The @var{iv} parameter provides the random initialization
4306vector used for encryption of this particular secret and should be a
Daniel P. Berrange69c0b272016-04-04 10:33:55 +01004307base64 encrypted string of the 16-byte IV.
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004308
4309The simplest (insecure) usage is to provide the secret inline
4310
4311@example
4312
4313 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4314
4315@end example
4316
4317The simplest secure usage is to provide the secret via a file
4318
Eric Blakeb43671f2017-07-03 13:09:50 -05004319 # printf "letmein" > mypasswd.txt
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004320 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4321
4322For greater security, AES-256-CBC should be used. To illustrate usage,
4323consider the openssl command line tool which can encrypt the data. Note
4324that when encrypting, the plaintext must be padded to the cipher block
4325size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4326
4327First a master key needs to be created in base64 encoding:
4328
4329@example
4330 # openssl rand -base64 32 > key.b64
4331 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4332@end example
4333
4334Each secret to be encrypted needs to have a random initialization vector
4335generated. These do not need to be kept secret
4336
4337@example
4338 # openssl rand -base64 16 > iv.b64
4339 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4340@end example
4341
4342The secret to be defined can now be encrypted, in this case we're
4343telling openssl to base64 encode the result, but it could be left
4344as raw bytes if desired.
4345
4346@example
Eric Blakeb43671f2017-07-03 13:09:50 -05004347 # SECRET=$(printf "letmein" |
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004348 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4349@end example
4350
4351When launching QEMU, create a master secret pointing to @code{key.b64}
4352and specify that to be used to decrypt the user password. Pass the
4353contents of @code{iv.b64} to the second secret
4354
4355@example
4356 # $QEMU \
4357 -object secret,id=secmaster0,format=base64,file=key.b64 \
4358 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4359 data=$SECRET,iv=$(<iv.b64)
4360@end example
4361
Brijesh Singha9b49422018-03-08 06:48:41 -06004362@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}]
4363
4364Create a Secure Encrypted Virtualization (SEV) guest object, which can be used
4365to provide the guest memory encryption support on AMD processors.
4366
4367When memory encryption is enabled, one of the physical address bit (aka the
4368C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos}
4369is used to provide the C-bit position. The C-bit position is Host family dependent
4370hence user must provide this value. On EPYC, the value should be 47.
4371
4372When memory encryption is enabled, we loose certain bits in physical address space.
4373The @option{reduced-phys-bits} is used to provide the number of bits we loose in
4374physical address space. Similar to C-bit, the value is Host family dependent.
4375On EPYC, the value should be 5.
4376
4377The @option{sev-device} provides the device file to use for communicating with
4378the SEV firmware running inside AMD Secure Processor. The default device is
4379'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are
4380created by CCP driver.
4381
4382The @option{policy} provides the guest policy to be enforced by the SEV firmware
4383and restrict what configuration and operational commands can be performed on this
4384guest by the hypervisor. The policy should be provided by the guest owner and is
4385bound to the guest and cannot be changed throughout the lifetime of the guest.
4386The default is 0.
4387
4388If guest @option{policy} allows sharing the key with another SEV guest then
4389@option{handle} can be use to provide handle of the guest from which to share
4390the key.
4391
4392The @option{dh-cert-file} and @option{session-file} provides the guest owner's
4393Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters
4394are used for establishing a cryptographic session with the guest owner to
4395negotiate keys used for attestation. The file must be encoded in base64.
4396
4397e.g to launch a SEV guest
4398@example
4399 # $QEMU \
4400 ......
4401 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4402 -machine ...,memory-encryption=sev0
4403 .....
4404
4405@end example
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004406@end table
4407
4408ETEXI
4409
4410
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004411HXCOMM This is the last statement. Insert new options before this line!
4412STEXI
4413@end table
4414ETEXI